Objetos en S3: claves, prefijos y carpetas

Un acta entre miles de archivos

Una federación de fútbol sala guarda en un bucket de S3 un acta por partido, durante años. Hoy solo quieres las actas del 4 de octubre. Abrir miles de archivos es impensable.

S3 te deja pedir la lista de los archivos cuyo nombre empieza de cierta forma. Esta lección enseña a listar un bucket de S3 por prefijo.

Al final de esta lección

Nota

Puedo encontrar archivos de un bucket por su prefijo.

Palabras clave

Palabra	Qué significa	Ejemplo
Objeto	un archivo guardado con sus datos
Clave	el nombre completo de un objeto en un bucket	actas/2026-10-04/liga.txt
Prefijo	el comienzo de una clave
Delimitador	un carácter que parte una clave en niveles	/
Prefijo común	un comienzo parecido a una carpeta que comparten varias claves

Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.

Un bucket guarda objetos con clave

Un bucket guarda objetos. Un objeto son los bytes de un archivo más datos como su tamaño. Cada objeto tiene una clave, su nombre completo, y con ella lo encuentras.

Dentro no hay un árbol de carpetas. El bucket es una lista plana de claves. Una clave como actas/2026-10-04/liga.txt es solo un nombre largo que contiene barras.

Leer un listado

Código: python

answer = {
    "Name": "federacion-actas",
    "Prefix": "",
    "KeyCount": 4,
    "IsTruncated": False,
    "Contents": [
        {"Key": "actas/2026-10-04/liga.txt", "Size": 21, "StorageClass": "STANDARD"},
        {"Key": "actas/2026-10-11/liga.txt", "Size": 8, "StorageClass": "STANDARD"},
        {"Key": "escudos/rayo.png", "Size": 6, "StorageClass": "STANDARD"},
        {"Key": "reglas.txt", "Size": 9, "StorageClass": "STANDARD"},
    ],
}
for item in answer["Contents"]:
    print(item["Key"], item["Size"])
# Suma el Size de todos los objetos y muestra el total.

Un error frecuente

Advertencia

Mucha gente cree que un bucket de S3 tiene carpetas de verdad. No las tiene. La barra es solo un carácter de la clave. Una carpeta aparece en un listado porque varias claves empiezan igual, y desaparece cuando se borra su último objeto.

Un prefijo lista las claves que empiezan así

Al listar un bucket puedes pasar un prefijo. S3 devuelve entonces solo las claves que empiezan con él. El prefijo actas/2026-10-04/ encuentra un día de actas y nada más.

Filtra S3, así que tu código nunca tiene que leer todo el bucket. La respuesta repite el prefijo que enviaste y cuenta las claves halladas en KeyCount.

Filtrar claves por prefijo

Código: python

keys = [
    "actas/2026-10-04/liga.txt",
    "actas/2026-10-04/copa.txt",
    "actas/2026-10-11/liga.txt",
    "escudos/rayo.png",
    "reglas.txt",
]
prefix = "actas/2026-10-04/"
found = []
for key in keys:
    if key.startswith(prefix):
        found.append(key)
print("KeyCount:", len(found))
print(found)
# Cambia prefix a "actas/" y pulsa Run. ¿Cuántas claves salen ahora?

Un delimitador agrupa claves en carpetas

Imagina que quieres las carpetas que hay justo debajo de actas/, no todos los archivos. Pasa el delimitador / además del prefijo. S3 corta cada clave en la primera barra que sigue al prefijo.

Las claves con el mismo corte salen una sola vez, como un prefijo común, en CommonPrefixes. Las claves sin barra después del prefijo vuelven en Contents como antes.

Buscar las carpetas bajo actas/

Código: python

keys = [
    "actas/2026-10-04/liga.txt",
    "actas/2026-10-04/copa.txt",
    "actas/2026-10-11/liga.txt",
]
prefix = "actas/"
common = []
for key in keys:
    rest = key[len(prefix):]
    slash = rest.find("/")
    if slash != -1:
        folder = prefix + rest[:slash + 1]
        if folder not in common:
            common.append(folder)
prefixes = []
for one in common:
    prefixes.append({"Prefix": one})
answer = {"Prefix": prefix, "Delimiter": "/", "CommonPrefixes": prefixes}
print(answer)
# Añade a keys la clave "actas/2026-10-18/liga.txt". Ejecuta otra vez.

Una clave ausente responde de dos formas

Pedir un objeto que no está es un error. Pero las dos llamadas se distinguen. get_object responde con el Code NoSuchKey. head_object, que solo pide los datos, no tiene cuerpo donde poner un nombre, así que su Code es "404".

Las dos tienen el estado 404. Comprueba el estado cuando quieras cubrir las dos.

Pruébalo en el laboratorio de nube

El laboratorio de nube es una copia de práctica de S3, SQS y DynamoDB. Pulsa Iniciar el laboratorio en la barra y luego Ejecutar en cada orden de abajo. Usan la línea de comandos real de AWS, así que las mismas palabras sirven en una cuenta real. Las dos últimas órdenes muestran un listado con la carpeta logs/2026-10-01/ en CommonPrefixes, y luego el error NoSuchKey. Este paso es para practicar. La tarea de abajo sigue siendo Python simple, así que puedes hacerla sin el laboratorio.