# Tema 2 · 1 · Tu primer bucket de S3: subir, listar y compartir datos

Presentación del Tema 2: «Laboratorio almacenamiento de objetos - 1» y «Laboratorio de objetos 1 · paso a paso». Duración: unos 30 minutos. Coste: céntimos (unos 26 MB almacenados un rato).

> **¿Dudas con un script?** Todos los scripts de esta carpeta traen su propia ayuda: `./descargar-datos.sh --ayuda` (también vale `--help` o `-h`) explica los pasos y las opciones. Este `README.md` es el paso a paso de la actividad: tenlo a mano y consúltalo antes de preguntar.

> **Etiquetas de lo que creas.** Todo recurso que crees a mano (máquina, volumen, bucket, base de datos, tabla, función...) ponle estas etiquetas, al crearlo (apartado *Tags* / *Etiquetas*) o después desde su pestaña de etiquetas: `curso` = `G214`, `universidad` = `CUNEF` y `actividad` = `02.01-s3primerbucket`. Si algún día hay que borrar recursos a mano, se localizan todos de golpe con `aws resourcegroupstaggingapi get-resources --region eu-north-1 --tag-filters Key=actividad,Values=02.01-s3primerbucket`. Más detalle (cómo etiquetar con la CLI, cómo buscar y qué hacer en una emergencia): [README principal](../../README.md), sección «Etiquetas».

## Qué vas a hacer

Crear un bucket de S3 (almacenamiento de objetos) en tu cuenta, subir un conjunto de **datos abiertos reales** (el padrón municipal del INE, 26 MB) y otros ficheros de tres maneras distintas, comprobar el inventario y compartir un fichero **sin abrir el bucket** con una URL firmada.

```
 tu CloudShell ──aws s3 cp──►  s3://g214-<apellido>-objetos/
                                 ├─ dataset.csv                (padrón INE, raíz del bucket)
                                 ├─ galeria/naturaleza/bosque.jpg   (prefijo, no carpeta)
                                 └─ lote/…                      (carpeta entera con --recursive)
```

## Qué se crea en AWS

Un bucket `g214-<apellido>-objetos` en `eu-north-1`. Nada más.

## Qué contiene esta carpeta

| Fichero | Para qué sirve | Se usa en |
|---|---|---|
| `descargar-datos.sh` | Descarga el padrón del INE (`dataset.csv`, 26 MB) y la calidad del aire de Madrid (`aire.csv`, unos 20 MB), comprobando que lo bajado es el CSV y no una página de error. Tiene también `estado` (qué hay y si es válido) y `eliminar` (borra lo descargado). Si el portal cambió la dirección, te dice dónde buscarla | Paso 2 (solo `padron`) |
| `bosque.jpg`, `bosque2.jpg` | Dos imágenes de ejemplo pequeñas (generadas, 30 KB cada una) | Paso 4 (`bosque.jpg`) |
| `carpeta/` | Cinco ficheros pequeños (uno en `carpeta/sub/`) | Paso 5 (`--recursive`) |

## Antes de empezar

- [ ] Cuenta de AWS con sesión iniciada y región **eu-north-1 (Estocolmo)**.
- [ ] **Recomendado: AWS CloudShell** (icono `>_` arriba a la derecha de la consola). Ya trae la CLI de AWS, tus credenciales, `curl` y Python 3: **no hay que ejecutar `aws configure` ni crear claves de acceso**. Comprueba quién eres con `aws sts get-caller-identity`.
- [ ] Opción local (PC con la CLI instalada): instala AWS CLI v2 y configúrala con un **usuario IAM** (no con las claves del usuario raíz), como explica el anexo del Tema 0. Los scripts `.sh` necesitan Git Bash en Windows. Con Git Bash los comandos son idénticos a los de CloudShell; si Git Bash convierte una ruta que empieza por `/` (por ejemplo, en un `--key`), ejecuta antes `export MSYS_NO_PATHCONV=1`.
- [ ] Nombre de bucket: es único en **todo el mundo**. Usa `g214-<apellido>-objetos`; si ya existe, añade un sufijo (`-2`, tus iniciales...). En esta guía se escribe `g214-apellido-objetos`: cámbialo por el tuyo en todos los comandos.

## Cómo llevar los ficheros a CloudShell

1. En tu PC, comprime **esta carpeta** (`02.01-s3primerbucket`) en un zip: clic derecho > *Comprimir en archivo ZIP* (Windows 11), *Enviar a > Carpeta comprimida en zip* (Windows 10) o *Comprimir* (Mac).
2. En CloudShell: **Actions → Upload file** y elige el zip. No lo descomprimas en tu PC.
3. Descomprime y entra en la carpeta:

```bash
unzip -o 02.01-s3primerbucket.zip
cd 02.01-s3primerbucket
chmod -R u+rwX . && chmod +x *.sh
```

> Si ya subiste `g214-materiales.zip` (README principal), no necesitas este zip: entra con `cd ~/g214-materiales/tema2/02.01-s3primerbucket` y, si algún fichero da `Permission denied`, ejecuta allí `chmod -R u+rwX . && chmod +x *.sh`.

Los datos grandes **no se suben desde tu PC**: se descargan directamente en CloudShell con `./descargar-datos.sh`.

## Paso a paso

### Paso 1 · Comprueba quién eres

```bash
aws sts get-caller-identity
```

**Qué verás:** tu cuenta y tu usuario (nunca las claves).

### Paso 2 · Descarga el padrón del INE

```bash
./descargar-datos.sh padron                       # dataset.csv (26 MB, separador ";")
```

**Qué verás:** `[OK] dataset.csv: 27348525 bytes (27.3 MB). Primeras líneas:` y las dos primeras líneas del CSV. El script descarga a un fichero temporal, reintenta si falla y solo lo deja como `dataset.csv` si es válido (si no, te explica el motivo). Repetirlo no vuelve a descargar un fichero ya válido (`--forzar` lo obliga). `./descargar-datos.sh estado` te dice qué tienes y si es válido.

### Paso 3 · Crea el bucket y sube el CSV a la raíz

```bash
aws s3 mb s3://g214-apellido-objetos --region eu-north-1
aws s3 cp dataset.csv s3://g214-apellido-objetos/ --content-type text/csv
```

**Qué verás:** `make_bucket: g214-apellido-objetos` y una barra de progreso de la subida. En Windows, `aws s3 cp` sube los CSV con tipo `application/vnd.ms-excel` (lo toma del registro del sistema); por eso el comando lleva `--content-type text/csv`.

### Paso 4 · Sube una imagen a un «prefijo»

```bash
aws s3 cp bosque.jpg s3://g214-apellido-objetos/galeria/naturaleza/
aws s3 ls s3://g214-apellido-objetos/galeria/
```

**Qué verás:** `PRE naturaleza/`. Las carpetas de S3 **no existen**: son prefijos dentro de la clave del objeto (`galeria/naturaleza/bosque.jpg`), por eso no hay que crearlas antes.

### Paso 5 · Sube una carpeta entera

```bash
aws s3 cp ./carpeta s3://g214-apellido-objetos/lote/ --recursive
```

**Qué verás:** cinco líneas `upload: carpeta/...`, una por fichero, incluida la que está en `carpeta/sub/`.

### Paso 6 · Comprueba el inventario

```bash
aws s3 ls s3://g214-apellido-objetos --recursive --summarize --human-readable
```

**Qué verás:** el listado termina con `Total Objects: 7` y `Total Size: 26.1 MiB` (el CSV son 27.348.525 bytes, es decir, 26,1 MiB; la imagen y la carpeta suman unos 32 KiB y no cambian el redondeo).

### Paso 7 · Comparte el CSV sin abrir el bucket (URL firmada)

```bash
aws s3 presign s3://g214-apellido-objetos/dataset.csv --expires-in 600
```

**Qué verás:** una URL larga (`...amazonaws.com/dataset.csv?X-Amz-Algorithm=...`). Ábrela en el navegador (o `curl -o prueba.csv "URL"`, entre comillas): se descarga **sin credenciales**. Sin firmar, la misma dirección da `403`. Caduca a los 600 segundos.

### Paso 8 · Lee los datos desde tres clientes

1. **Consola web:** S3 → tu bucket → el objeto → *Open* o *Download*.
2. **Visual Studio Code** con la extensión de AWS (Anexo Tema 0: *Configuración Visual Studio Code*).
3. **Excel:** *Datos → Desde texto/CSV*, pega la URL firmada y elige **delimitador punto y coma** y **codificación UTF-8** (el INE usa `;` y UTF-8).

### Paso 9 (opcional) · Lo básico por consola, con ficheros tuyos

Para ver lo mismo desde el navegador: *Create bucket* (tipo de propósito general, nombre único, **deja marcado el bloqueo de acceso público**), *Upload* y arrastra un fichero. Para la CLI: `aws s3 cp fichero.txt s3://g214-apellido-objetos/`, `aws s3 ls`, `aws s3 cp s3://g214-apellido-objetos/fichero.txt ./`, `aws s3 rm s3://g214-apellido-objetos/fichero.txt`. Guía con capturas: `Anexo - Tema 2 - Guías de creación de recursos.docx`.

## Errores frecuentes

| Qué ves | Causa | Solución |
|---|---|---|
| `BucketAlreadyExists` / `BucketAlreadyOwnedByYou` | El nombre de bucket es global y ya existe | Cambia el nombre (sufijo propio) |
| `Unable to locate credentials` | Estás en un terminal sin credenciales (una VM, o la CLI sin configurar) | Usa CloudShell; en local, `aws configure` con un usuario IAM |
| `dataset.csv` no es válido o no se descarga | El portal devolvió una página de error o cambió la dirección | `./descargar-datos.sh estado` dice el motivo; repite con `./descargar-datos.sh padron --forzar`. Si el portal cambió la URL, el propio script indica dónde buscar la nueva |
| La URL firmada da `403` | Caducó, o la copiaste sin las comillas / cortada | Genera otra y pégala entera |

## Limpieza

- Si vas a hacer [`02.02-s3versionadoysync`](../02.02-s3versionadoysync/README.md), **no borres todavía** el bucket ni el CSV.
- Si **no** vas a hacerlo: `aws s3 rb s3://g214-apellido-objetos --force` borra el bucket con su contenido. Comprueba con `aws s3 ls | grep g214` (no debe salir ningún bucket tuyo). Si activaste el versionado, usa `python3 vaciar-bucket.py` (carpeta 02.02).
- Los ficheros descargados de tu CloudShell: `./descargar-datos.sh eliminar` (pide confirmación; `--si` no pregunta).

## Cómo sabes que has terminado

- [ ] `ls --summarize` muestra `Total Objects: 7` y `Total Size: 26.1 MiB`.
- [ ] Has abierto el CSV con la URL firmada sin credenciales, y sabes por qué la dirección sin firmar da `403`.
- [ ] Sabes explicar por qué `galeria/naturaleza/` no es una carpeta.
- [ ] Has borrado el bucket (o sigues con el 02.02 y lo borrarás al final).

Siguiente: [`02.02-s3versionadoysync`](../02.02-s3versionadoysync/README.md)