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
boto3etrequests curlet 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
PUTs'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é :
-
InvalidTrailer lors de chaque téléversement
- Problème :
put_objectetupload_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_requiredetAWS_RESPONSE_CHECKSUM_VALIDATION=when_required, ou verrouillezboto3<=1.35.99(section 1.2).
- Problème :
-
SignatureDoesNotMatch lors des téléversements présignés
- Problème : Le
PUTdu navigateur renvoie403avecSignatureDoesNotMatch. - Pourquoi cela se produit : Le navigateur envoie un
Content-Typediffé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.
- Problème : Le
-
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 avecTransitions, échoue. - Pourquoi cela se produit : Les notifications de bucket ne sont pas prises en charge, et seule la classe de stockage
STANDARDexiste. - 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.
- Problème : Le code qui appelle
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-4ouus-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 :