16 min de lecture

Objectifs d'apprentissage

À la fin de ce module, vous serez en mesure de:

  • Configurer boto3 pour un point d'accès régional IONOS Cloud Object Storage à l'aide d'une Access Key et d'une Secret Key
  • Mettre en œuvre des URL présignées pour le téléversement et le téléchargement afin que les navigateurs transfèrent directement les pièces jointes de TaskBoard
  • Téléverser de grands fichiers avec un téléversement multipart et diffuser les téléchargements avec les types de contenu corrects
  • Automatiser les règles de cycle de vie via l'API S3 pour expirer les objets temporaires et les téléversements abandonnés
  • Vérifier la prise en charge des fonctionnalités S3 avant d'utiliser une API spécifique à AWS dans votre code

Unité 4.2 : Intégration d'Object Storage

Introduction

Les utilisateurs de TaskBoard souhaitent joindre des captures d'écran, des journaux et des documents à leurs tâches. Acheminer ces données par les pods de l'API coûterait en mémoire, en bande passante et en temps de requête. À la place, le navigateur téléverse directement dans le bucket de l'unité 2.4 à l'aide d'une URL présignée à durée limitée, et l'API ne stocke que la clé de l'objet dans PostgreSQL.

IONOS Cloud Object Storage utilise le protocole S3, vous utilisez donc des SDK S3 standard. Cependant, il ne s'agit pas d'AWS : vous définissez explicitement le point de terminaison, vous vous authentifiez avec une Access Key et une Secret Key, et vous vérifiez quelles fonctionnalités S3 existent avant de les appeler. Dans cette unité, vous construisez le service de pièces jointes avec boto3 : configuration du client, URLs présignées, téléversements multipart, téléchargements en flux et règles de cycle de vie. Le Code Lab exécute le flux complet de téléversement et de téléchargement.

1. Le client boto3

import os
import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.eu-central-3.ionoscloud.com",
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],       # terraform output uploads_access_key
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],   # terraform output uploads_secret_key
    region_name="eu-central-3",
    config=Config(signature_version="s3v4"),
)
print([b["Name"] for b in s3.list_buckets()["Buckets"]])

Sans endpoint_url, boto3 communique avec AWS et vos clés échouent. Les identifiants sont une paire de clé d'accès et de clé secrète : Object Storage n'accepte pas le jeton de porteur de l'API Cloud, et les rôles IAM ainsi que le Security Token Service (STS) ne sont pas pris en charge. Vos identifiants ne sont liés à aucune région ou à aucun bucket spécifique, de sorte qu'une seule paire de clés fonctionne avec chaque point d'accès.

1.1 Points d'accès par région

Le point d'accès dépend du type de bucket et de la région. Le tableau suivant répertorie les points d'accès pour les buckets appartenant au contrat :

Centre de données Région Point d'accès Point d'accès du site statique
Francfort, Allemagne eu-central-4 s3.eu-central-4.ionoscloud.com s3-website.eu-central-4.ionoscloud.com
Berlin, Allemagne eu-central-3 s3.eu-central-3.ionoscloud.com s3-website.eu-central-3.ionoscloud.com
Lenexa, États-Unis us-central-1 s3.us-central-1.ionoscloud.com s3-website.us-central-1.ionoscloud.com

Les buckets appartenant à l'utilisateur utilisent d'autres régions, par exemple s3.eu-central-2.ionoscloud.com pour Berlin. Le bucket de TaskBoard appartient au contrat dans eu-central-3. Les points d'accès répondent sur HTTP et HTTPS ; utilisez toujours https://. Le chiffrement en transit utilise TLS 1.2 ou 1.3.

1.2 La modification des sommes de contrôle dans boto3 1.36

À partir de boto3 1.36.0, PutObject envoie de nouvelles bandes de sommes de contrôle que Object Storage ne prend pas encore en charge. Les appels échouent alors avec InvalidTrailer : « Invalid trailing header names in x-amz-trailer ». Soit fixez boto3<=1.35.99, soit définissez ces variables pour votre processus :

export AWS_REQUEST_CHECKSUM_CALCULATION=when_required
export AWS_RESPONSE_CHECKSUM_VALIDATION=when_required

Placez-les dans le ConfigMap de l'API de l'Unité 3.2 afin que chaque pod y accède.

2. Bacs, accès et URL pré-signées

2.1 Opérations sur les bacs

Terraform gère le bac à durée de vie longue de TaskBoard (Unité 2.4). Les tests et les outils peuvent toujours créer et lister des bacs dans le code :

from botocore.exceptions import ClientError

try:
    s3.create_bucket(Bucket="taskboard-ci-4711",
                     CreateBucketConfiguration={"LocationConstraint": "eu-central-3"})
except ClientError as e:
    if e.response["Error"]["Code"] != "BucketAlreadyOwnedByYou":
        raise
print(s3.get_bucket_acl(Bucket="taskboard-ci-4711")["Grants"])

Les objets sont privés par défaut ; seul le propriétaire du bucket peut y accéder. Maintenez cette configuration. Pour un bucket appartenant à un contrat, une ACL ne partage l'accès qu'avec les bénéficiaires issus d'autres contrats ; pour accorder l'accès aux utilisateurs de votre propre contrat, utilisez une Bucket Policy. TaskBoard n'a besoin d'aucun des deux, car les URL présignées accordent un accès temporaire à des objets individuels.

2.2 URL présignées pour le téléversement

import uuid

BUCKET = "taskboard-uploads-dev-7f3a"

def create_upload(task_id: int, filename: str, content_type: str) -> dict:
    key = f"tasks/{task_id}/{uuid.uuid4()}/{filename}"
    url = s3.generate_presigned_url(
        "put_object",
        Params={"Bucket": BUCKET, "Key": key, "ContentType": content_type},
        ExpiresIn=900,
    )
    return {"key": key, "url": url, "headers": {"Content-Type": content_type}}

Les URL présignées sont générées localement par un algorithme de signature à l'aide de vos identifiants ; aucun appel à l'API n'est effectué. Les types de signature v2 et v4 sont pris en charge. Le navigateur envoie ensuite le fichier lui-même :

const { key, url, headers } = await (await fetch(`/api/tasks/${id}/attachments`, { method: "POST",
  body: JSON.stringify({ filename: file.name, contentType: file.type }) })).json();
await fetch(url, { method: "PUT", headers, body: file });
await fetch(`/api/tasks/${id}/attachments/${encodeURIComponent(key)}/confirm`, { method: "POST" });

Étant donné que ContentType fait partie de la signature, le navigateur doit envoyer exactement cet en-tête. L'appel confirm permet à l'API de vérifier l'objet avec head_object avant d'écrire la clé dans PostgreSQL.

Seul le propriétaire du bucket peut générer une URL présignée valide ; pour un bucket appartenant à un contrat, un administrateur peut également le faire. La clé utilisée pour la signature doit appartenir à l'un d'eux.

2.3 CORS pour les téléversements par navigateur

Un navigateur sur https://taskboard.example.com ne peut effectuer que PUT vers le bucket si la configuration CORS du bucket le permet :

resource "ionoscloud_s3_bucket_cors_configuration" "uploads" {
  bucket = ionoscloud_s3_bucket.uploads.name
  cors_rule {
    allowed_methods = ["PUT", "GET"]
    allowed_origins = ["https://taskboard.example.com"]
    allowed_headers = ["Content-Type"]
    expose_headers  = ["ETag"]
    max_age_seconds = 3000
  }
}

allowed_methods accepte GET, PUT, HEAD, POST et DELETE.

3. Modèles de téléversement et de téléchargement

3.1 Téléversement multipart pour les fichiers volumineux

Une requête de téléversement unique est limitée à 5 Go pour les buckets appartenant au contrat et à 4,65 Go pour les buckets appartenant à l'utilisateur. Au-delà de cette limite, utilisez le téléversement multipart, jusqu'à la taille maximale d'objet de 5 To. Le transfert géré de boto3 fractionne les fichiers pour vous :

from boto3.s3.transfer import TransferConfig

cfg = TransferConfig(multipart_threshold=64 * 1024**2,
                     multipart_chunksize=64 * 1024**2,
                     max_concurrency=4)
s3.upload_file("export.tar.gz", BUCKET, "exports/2026-11/export.tar.gz",
               ExtraArgs={"ContentType": "application/gzip"}, Config=cfg)

Les tâches côté serveur, telles que les exports du worker, utilisent ce schéma. Pour les téléversements de plusieurs gigaoctets depuis le navigateur, l'API appelle create_multipart_upload, présigne une URL upload_part par partie, et termine avec complete_multipart_upload en utilisant les ETags renvoyés. Un téléversement multipart abandonné conserve ses parties, que la règle de cycle de vie de la section 4 supprime.

3.2 Téléchargements en flux

Pour les téléchargements, l'API renvoie généralement une redirection vers une URL présignée GET. Lorsqu'elle doit traiter le fichier elle-même, transmettez-le en flux au lieu de le charger en mémoire :

from fastapi.responses import StreamingResponse

def download(key: str):
    obj = s3.get_object(Bucket=BUCKET, Key=key)
    return StreamingResponse(obj["Body"].iter_chunks(chunk_size=1024 * 1024),
                             media_type=obj["ContentType"])

Conservez le type de contenu au moment de la mise en charge ; get_object le renvoie. Les métadonnées définies par l'utilisateur pour chaque objet sont limitées à 2 Ko, et le nom d'un objet, y compris son chemin de dossier, peut comporter jusqu'à 1024 caractères.

3.3 Limites de débit pour l'énumération et la suppression

Sur les buckets appartenant à un contrat, l'utilisation intensive des ressources des opérations List Objects et Delete Objects déclenche une limitation de débit, appliquée par contrat. La réponse est 429 Too Many Requests avec un en-tête Retry-After :

import time

def list_all(prefix: str):
    kwargs = {"Bucket": BUCKET, "Prefix": prefix}
    while True:
        try:
            page = s3.list_objects_v2(**kwargs)
        except ClientError as e:
            if e.response["ResponseMetadata"]["HTTPStatusCode"] != 429:
                raise
            time.sleep(int(e.response["ResponseMetadata"]["HTTPHeaders"].get("retry-after", "1")))
            continue
        yield from page.get("Contents", [])
        if not page.get("IsTruncated"):
            return
        kwargs["ContinuationToken"] = page["NextContinuationToken"]

N'effectuez pas d'appels List Objects à intervalle fixe ; conservez la liste des pièces jointes dans PostgreSQL.

4. Règles de cycle de vie via l'API

Les règles de cycle de vie automatisent la suppression des objets et de leurs versions. Appliquez-les à l'aide de l'API S3 :

s3.put_bucket_lifecycle_configuration(
    Bucket=BUCKET,
    LifecycleConfiguration={"Rules": [
        {"ID": "expire-tmp", "Status": "Enabled",
         "Filter": {"Prefix": "tmp/"}, "Expiration": {"Days": 7}},
        {"ID": "abort-multipart", "Status": "Enabled", "Filter": {},
         "AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 5}},
    ]},
)
print(s3.get_bucket_lifecycle_configuration(Bucket=BUCKET)["Rules"])

Une règle prend en charge quatre actions : expirer les versions actuelles, supprimer définitivement les versions non actuelles, supprimer les marqueurs de suppression expirés des objets, et supprimer les téléchargements multipart incomplets. Une configuration peut contenir jusqu'à 1000 règles. Terraform gère la même configuration avec ionoscloud_s3_bucket_lifecycle_configuration.

Les règles de transition n'existent pas ici. Seule la classe de stockage STANDARD est disponible, de sorte que les règles de cycle de vie ne peuvent pas déplacer les objets vers une autre classe de stockage. La gestion des coûts sur IONOS Cloud Object Storage consiste à supprimer ce dont vous n'avez plus besoin.

5. Vérifications de compatibilité S3

IONOS Cloud Object Storage prend en charge la plupart des API S3, mais pas toutes. Le tableau suivant présente le niveau de prise en charge par fonctionnalité :

Fonctionnalité Prise en charge Remarques
CRUD des buckets Oui
CRUD des objets Oui
Copie d'objets Oui La copie inter-régions n'est pas prise en charge
Téléversements multipart Oui
URL pré-signées Oui Les types de signature v2 et v4 sont pris en charge
ACL de bucket Oui
ACL d'objet Oui
Blocage d'accès public Oui Uniquement via l'API
Stratégies de bucket Oui
Stratégies d'objet Oui
Configuration CORS Oui
Versioning de bucket Oui
Réplication de bucket Oui La réplication intra-région et inter-régions est prise en charge
Balisage de bucket Oui Uniquement via l'API
Balisage d'objet Oui Uniquement via l'API
Cycle de vie de bucket Oui
Journalisation d'accès au bucket Oui
Configuration du chiffrement de bucket Oui Le chiffrement côté serveur est utilisé par défaut dans l'interface web. Le chiffrement avec des clés de chiffrement gérées par le client est disponible via l'API.
Chiffrement d'objet Oui Uniquement via l'API
Sites web de bucket Oui
Inventaire de bucket Oui Uniquement via l'API
Object Lock Oui
Mise sous scellé légale Oui
Gestion des identités et des accès (IAM) Non
Service de jetons de sécurité (STS) Non
Authentification multifacteur Non
Notifications de bucket Non
Paiement des requêtes Non
Métriques de bucket Non
Analytique de bucket Non
Accélération de bucket Non
S3 Select Non

Comme le montre le tableau, le chemin de données est largement compatible, tandis que les fonctionnalités liées au compte AWS sont absentes. Deux conséquences pour TaskBoard : sans les notifications de bucket, l'appel de confirmation de l'API (section 2.2) remplace un événement « objet créé », et sans STS, chaque service dispose de sa propre paire de clés à durée de vie prolongée. Les types de buckets diffèrent également : la journalisation d'accès au bucket n'est pas prise en charge pour les buckets appartenant au contrat, par exemple. Vérifiez le type de bucket avant de vous appuyer sur une fonctionnalité.

Fiche de référence rapide de l'API

Opérations S3 clés derrière le code de cette unité :

Méthode Point de terminaison Description
PUT /{Bucket}/{Key} Téléversement d'un objet (cible d'une URL de téléversement présignée)
GET /{Bucket}/{Key} Téléchargement d'un objet (cible d'une URL de téléchargement présignée)
GET /{Bucket}?list-type=2 Liste des objets (ListObjectsV2, limité en débit sur les buckets appartenant au contrat)
POST /{Bucket}/{Key}?uploads Début d'un téléversement multipart
PUT /{Bucket}?lifecycle Définition de la configuration du cycle de vie

URL de base : https://s3.eu-central-3.ionoscloud.com (un point de terminaison par région) Authentification : Signature AWS (v4 ou v2) avec clé d'accès et clé secrète, et non un jeton bearer

Atelier de code

Objectif : Téléverser et récupérer des pièces jointes de TaskBoard avec boto3 : une URL de téléversement présignée, un téléversement multipart et un téléchargement présigné, le tout authentifié avec une Access Key et une Secret Key.

Prérequis :

  • Le bucket et la clé d'accès de l'Unité 2.4, appliqués, ainsi que la ressource CORS de la section 2.3
  • Python 3.12 avec boto3 et requests
  • curl et un fichier de test de 100 Mo : head -c 100M /dev/urandom > big.bin

Étape 1 : Configurer les informations d'identification

export S3_ACCESS_KEY=$(terraform output -raw uploads_access_key)
export S3_SECRET_KEY=$(terraform output -raw uploads_secret_key)
export AWS_REQUEST_CHECKSUM_CALCULATION=when_required
export AWS_RESPONSE_CHECKSUM_VALIDATION=when_required
python -c "import boto3; print(boto3.__version__)"

Sortie attendue :

1.x.y

Étape 2 : Démontrer le modèle d'authentification

curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $IONOS_TOKEN" \
  https://s3.eu-central-3.ionoscloud.com/taskboard-uploads-dev-7f3a

Sortie attendue :

4xx status code (not 200)

Le jeton Cloud API n'est pas une référence S3, la requête est donc rejetée. Énumérez maintenant le bucket à l'aide du client de la section 1 :

print(s3.list_objects_v2(Bucket=BUCKET).get("KeyCount"))

Sortie attendue :

0

Étape 3 : Créer une URL de téléversement présignée

up = create_upload(42, "screenshot.png", "image/png")
print(up["key"]); print(up["url"][:60], "...")

Sortie attendue :

tasks/42/<uuid>/screenshot.png
https://s3.eu-central-3.ionoscloud.com/taskboard-uploads-dev ...

Étape 4 : Téléverser comme le navigateur

curl -s -o /dev/null -w "%{http_code}\n" -X PUT -H "Content-Type: image/png" \
  --upload-file screenshot.png "<url from Step 3>"

Sortie attendue :

200

Étape 5 : Téléverser un fichier volumineux par parties

s3.upload_file("big.bin", BUCKET, "tmp/big.bin", Config=cfg)
print(s3.head_object(Bucket=BUCKET, Key="tmp/big.bin")["ETag"])

Sortie attendue :

"<hash>-2"

Le suffixe -2 indique un objet multipart composé de deux parties : 64 Mo et les 36 Mo restants.

Étape 6 : Téléchargement via une URL présignée

url = s3.generate_presigned_url("get_object", Params={"Bucket": BUCKET, "Key": up["key"]}, ExpiresIn=300)
import requests; r = requests.get(url); print(r.status_code, r.headers["Content-Type"])

Sortie attendue :

200 image/png

Étape 7 : Appliquer les règles de cycle de vie

Exécutez le code de la section 4. Sortie attendue :

[{'ID': 'expire-tmp', ...}, {'ID': 'abort-multipart', ...}]

Liste de contrôle de validation :

  • [ ] Le jeton bearer est rejeté, la paire de clés obtient l'accès
  • [ ] Les téléversements présignés PUT s'effectuent sans identifiants dans la requête
  • [ ] L'ETag multipart se termine par un nombre de parties
  • [ ] L'objet téléchargé a le type de contenu défini lors du téléversement

Nettoyage :

for k in [up["key"], "tmp/big.bin"]:
    s3.delete_object(Bucket=BUCKET, Key=k)

Erreurs courantes

Erreurs de développement à éviter concernant le sujet de cette unité :

  1. InvalidTrailer lors de chaque téléversement

    • Problème : put_object et upload_file échouent après une mise à jour de dépendance avec « Invalid trailing header names in x-amz-trailer ».
    • Pourquoi cela se produit : boto3 1.36.0 et les versions ultérieures envoient des en-têtes de contrôle de somme que Object Storage ne prend pas encore en charge.
    • Correction : Définissez AWS_REQUEST_CHECKSUM_CALCULATION=when_required et AWS_RESPONSE_CHECKSUM_VALIDATION=when_required, ou verrouillez boto3<=1.35.99 (section 1.2).
  2. SignatureDoesNotMatch lors des téléversements présignés

    • Problème : Le PUT du navigateur renvoie 403 avec SignatureDoesNotMatch.
    • Pourquoi cela se produit : Le navigateur envoie un Content-Type différent de celui qui a été signé, ou l'URL a été signée pour un autre point de terminaison ou une autre région.
    • Correction : Renvoyez les en-têtes signés avec l'URL et envoyez-les sans modification ; signez avec le point de terminaison régional du bucket.
  3. Attente d'une fonctionnalité AWS qui n'existe pas

    • Problème : Le code qui appelle put_bucket_notification_configuration, ou une règle de cycle de vie avec Transitions, échoue.
    • Pourquoi cela se produit : Les notifications de bucket ne sont pas prises en charge, et seule la classe de stockage STANDARD existe.
    • Correction : Consultez d'abord le tableau de compatibilité (section 5) ; utilisez un appel de confirmation explicite au lieu d'événements, et une expiration au lieu de transitions.

Résumé

Vous pouvez désormais intégrer IONOS Cloud Object Storage dans TaskBoard à la manière S3, avec les spécificités d'IONOS CLOUD. Le client boto3 reçoit un point d'accès régional explicite ainsi qu'une Access Key et une Secret Key. Les navigateurs effectuent les téléversements et les téléchargements via des URL pré-signées, de sorte que l'API ne fait jamais de proxy pour les octets, et les fichiers volumineux utilisent le téléversement multipart. Les règles de cycle de vie suppriment les fichiers temporaires et les téléversements abandonnés, et vous consultez le tableau de compatibilité avant d'utiliser une fonctionnalité exclusive à AWS.

Points clés :

  • Définissez toujours endpoint_url ; authentifiez-vous avec une Access Key et une Secret Key, jamais avec un jeton bearer
  • Définissez les deux variables de somme de contrôle, ou fixez boto3 à une version antérieure à 1.36.0
  • Les URL pré-signées sont signées localement ; la clé de signature doit appartenir au propriétaire du bucket ou à un administrateur
  • Utilisez le téléversement multipart au-delà de la limite d'une seule requête ; ajoutez une règle qui interrompt les téléversements incomplets
  • Les règles de cycle de vie expirent et suppriment les objets ; il n'existe pas de règles de transition

Terminologie importante :

  • Access Key et Secret Key : La paire d'identifiants qui signe chaque requête S3 ; non liée à une région ou à un bucket
  • URL pré-signée : Une URL qui porte une signature à durée limitée pour une opération sur un objet donné
  • Bucket appartenant au contrat : Un bucket appartenant au propriétaire du contrat, situé dans eu-central-3, eu-central-4 ou us-central-1
  • Téléversement multipart : Un téléversement découpé en parties qui sont envoyées séparément puis combinées en un seul objet
  • Règle de cycle de vie : Une règle de bucket qui expire les objets, les versions non actuelles ou les téléversements incomplets après un délai défini

Prochaines étapes

Continuer l'apprentissage : Unité 4.3 : Intégration du streaming d'événements

Sujets connexes :