Tous les produits
Search

Ce produit

    Object Storage Service:PostObject

    Centre de documentation

    Object Storage Service:PostObject

    Dernière mise à jour :Sep 22, 2026

    Appelez l'opération PostObject pour télécharger un objet dans un compartiment à l'aide d'un formulaire HTML.

    Notes d'utilisation

    • Le téléchargement via un formulaire HTML nécessite l'autorisation oss:PutObject. Attachez une stratégie personnalisée à un utilisateur RAM.

    • La taille des objets téléchargés via PostObject ne doit pas dépasser 5 Go.

    • Une requête PostObject requiert des autorisations d'écriture sur le compartiment. Si la liste de contrôle d'accès (ACL) du compartiment est définie sur public-read-write, aucune information de signature n'est nécessaire. Dans le cas contraire, OSS authentifie la signature incluse dans la requête.

    • Contrairement à PutObject, PostObject utilise une clé secrète AccessKey pour signer la stratégie. La chaîne de signature résultante correspond à la valeur du champ de formulaire Signature, qu'OSS authentifie.

    • L'URL du formulaire correspond au nom de domaine du compartiment, sans le nom de l'objet. La ligne de requête est POST / HTTP/1.1, et non POST /ObjectName HTTP/1.1.

    • Si une requête POST contient des informations de signature dans l'en-tête ou l'URL, OSS ne vérifie pas ces informations.

    Gestion des versions

    Si la gestion des versions est activée sur le compartiment, OSS génère un ID de version unique pour l'objet téléchargé et le renvoie dans l'en-tête de réponse x-oss-version-id.

    Si la gestion des versions est suspendue, OSS génère un ID de version nul pour l'objet téléchargé et le renvoie dans l'en-tête de réponse x-oss-version-id. Un seul ID de version nul est autorisé par objet.

    Syntaxe de la requête

    POST / HTTP/1.1 
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
User-Agent: browser_data
Content-Length: ContentLength
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
key
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
attachment;filename=oss_download.jpg
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
myuuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
mytag
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
access-key-id
--9431149156168
Content-Disposition: form-data; name="policy"
encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"
signature
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg
file_content
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    En-têtes de requête

    Important

    • Le corps de la requête PostObject utilise l'encodage multipart/form-data. Contrairement à PutObject, qui transmet les paramètres dans les en-têtes HTTP, PostObject les transmet sous forme de champs de formulaire dans le corps de la requête.

    • PostObject ne prend pas en charge l'en-tête x-oss-tagging. Une fois l'opération PostObject terminée, appelez PutObjectTagging pour ajouter des tags à l'objet.

    Nom

    Type

    Obligatoire

    Description

    Content-Type

    Chaîne

    Non

    Le type de fichier et l'encodage de la page web, qui déterminent la manière dont les navigateurs lisent le fichier.

    Le formulaire soumis lors d'une opération Post doit être encodé au format multipart/form-data. Cela signifie que l'en-tête Content-Type est au format multipart/form-data;boundary=xxxxxx.

    La limite (boundary) est une chaîne aléatoire générée par le formulaire. Vous n'avez pas besoin de la spécifier. Les SDK génèrent cette valeur automatiquement.

    Cette opération utilise également des en-têtes de requête communs tels que Host et Date.

    Éléments de formulaire

    Le tableau suivant décrit les éléments de formulaire communs aux signatures V1 et V4. Pour plus d'informations sur les éléments de formulaire spécifiques aux signatures V4, consultez la rubrique Formulaire de signature V4. Pour plus d'informations sur les éléments de formulaire spécifiques aux signatures V1, consultez la rubrique Formulaire de signature V1.

    Important

    • Le champ file doit être le dernier champ du formulaire. Les autres champs peuvent apparaître dans n'importe quel ordre.

    • La clé d'un champ de formulaire ne doit pas dépasser 8 Ko et sa valeur ne doit pas dépasser 2 Mo.

    Nom

    Type

    Obligatoire

    Description

    Cache-Control

    String

    Non

    Comportement de mise en cache lors du téléchargement de l'objet, tel que défini dans la norme RFC 2616.

    Valeur par défaut : aucune.

    Content-Disposition

    String

    Non

    Nom de fichier utilisé lors du téléchargement de l'objet, tel que défini dans la norme RFC 2616.

    Valeur par défaut : aucune.

    Content-Encoding

    String

    Non

    Encodage du contenu de l'objet lors du téléchargement, tel que défini dans la norme RFC 2616.

    Valeur par défaut : aucune.

    Expires

    String

    Non

    Date d'expiration du cache, telle que définie dans la norme RFC 2616.

    Valeur par défaut : aucune.

    policy

    String

    Oui, sous condition

    Spécifie la validité des champs du formulaire de requête. Une requête dépourvue du champ policy est traitée comme anonyme et ne peut accéder qu'aux buckets en lecture-écriture publique.

    Valeur par défaut : aucune.

    Contrainte : obligatoire si le bucket n'est pas en lecture-écriture publique, ou si les champs OSSAccessKeyId ou Signature sont fournis.

    Important

    Le formulaire et la politique (policy) doivent être encodés en UTF-8. Le champ de formulaire policy doit également être encodé en Base64.

    x-oss-server-side-encryption-key-id

    String

    Non

    Clé maître client (CMK) gérée par KMS. Valide uniquement lorsque le paramètre x-oss-server-side-encryption est défini sur KMS.

    x-oss-content-type

    String

    Non

    Remplace le Content-Type ajouté automatiquement par les navigateurs au champ de formulaire file. Cet élément possède la priorité la plus élevée pour la spécification du Content-Type.

    Ordre de priorité : x-oss-content-type > Content-Type du champ de formulaire file

    Valeur par défaut : aucune.

    x-oss-forbid-overwrite

    String

    Non

    Indique s'il faut écraser un objet portant le même nom lors d'une opération PostObject.

    Lorsque le versioning est activé ou suspendu, le paramètre x-oss-forbid-overwrite est ignoré et les objets portant le même nom peuvent être écrasés.

    • Si le paramètre x-oss-forbid-overwrite n'est pas spécifié ou s'il est défini sur false, les objets portant le même nom peuvent être écrasés.

    • Si le paramètre x-oss-forbid-overwrite est défini sur true, les objets portant le même nom ne peuvent pas être écrasés.

    L'en-tête x-oss-forbid-overwrite réduit le nombre de requêtes par seconde (QPS). Si votre utilisation de x-oss-forbid-overwrite dépasse 1 000 QPS, contactez le support technique.

    x-oss-object-acl

    String

    Non

    Autorisations d'accès pour l'objet téléchargé.

    Valeurs possibles :

    • default (par défaut) : hérite de la liste de contrôle d'accès (ACL) du bucket.

    • private : seul le propriétaire et les utilisateurs autorisés peuvent lire et écrire l'objet.

    • public-read : tous les utilisateurs peuvent lire l'objet. Seul le propriétaire et les utilisateurs autorisés peuvent l'écrire. À utiliser avec prudence.

    • public-read-write : tous les utilisateurs peuvent lire et écrire l'objet. À utiliser avec prudence.

    Les autorisations d'accès sont décrites dans la rubrique ACL des objets.

    x-oss-storage-class

    String

    Non

    Spécifie la classe de stockage de l'objet.

    Quelle que soit la classe de stockage du bucket, l'objet téléchargé utilise la classe que vous spécifiez. Par exemple, si vous spécifiez x-oss-storage-class sur Standard pour un bucket IA, l'objet sera stocké en tant que Standard.

    Valeurs possibles :

    • Standard : Standard

    • IA : Infrequent Access

    • Archive : Archive Storage

    • ColdArchive : Cold Archive

    • DeepColdArchive : Deep Cold Archive

      Important

      Si vous souhaitez télécharger un grand nombre d'objets, la spécification directe de la classe de stockage Deep Cold Archive pour les objets à télécharger entraîne des frais de requête PUT élevés. Nous vous recommandons de spécifier d'abord la classe de stockage Standard pour les objets lors de leur téléchargement, puis d'utiliser les règles de cycle de vie pour les convertir en classe de stockage Deep Cold Archive afin de réduire les frais de requête PUT.

    Classes de stockage.

    key

    String

    Oui

    Nom de l'objet à télécharger. N'encodez pas le nom. Si le nom inclut un chemin d'accès, tel que destfolder/example.jpg, OSS crée automatiquement le dossier correspondant.

    Valeur par défaut : aucune.

    success_action_redirect

    String

    Non

    URL vers laquelle le client est redirigé après un téléchargement réussi. Si ce champ n'est pas spécifié, le comportement de la réponse est déterminé par success_action_status. En cas d'échec, OSS renvoie une erreur sans redirection.

    Valeur par défaut : aucune.

    success_action_status

    String

    Non

    Code d'état HTTP renvoyé après un téléchargement réussi lorsque success_action_redirect n'est pas spécifié.

    Valeurs possibles : 200, 201 et 204 (par défaut).

    • Si ce champ est défini sur 200 ou 204, OSS renvoie un document vide et le code d'état correspondant.

    • Si ce champ est défini sur 201, OSS renvoie un fichier XML et le code d'état 201.

    • Si ce champ n'est pas défini ou s'il est défini sur une valeur non valide, OSS renvoie un document vide et le code d'état 204.

    x-oss-meta-*

    String

    Non

    Métadonnées définies par l'utilisateur.

    Valeur par défaut : aucune.

    Les champs de formulaire préfixés par x-oss-meta- sont stockés en tant que métadonnées utilisateur. Exemple : x-oss-meta-location.

    Remarque

    Un objet peut comporter plusieurs paramètres de ce type, mais la taille totale de toutes les métadonnées utilisateur ne doit pas dépasser 8 Ko.

    x-oss-security-token

    String

    Non

    Jeton de sécurité STS. Requis uniquement lors de l'utilisation de STS pour construire une URL signée. Obtenez un jeton en appelant l'opération AssumeRole.

    Valeur par défaut : aucune.

    file

    String

    Oui

    Contenu du fichier ou du texte. N'encodez pas le contenu. Le navigateur définit le Content-Type en fonction du type de fichier, ce qui écrase vos paramètres. Un seul fichier peut être téléchargé par requête.

    Valeur par défaut : aucune.

    Important

    Le champ file doit être le dernier champ du formulaire.

    En-têtes de réponse

    Nom

    Type

    Exemple

    Description

    x-oss-server-side-encryption

    String

    KMS

    Renvoyé si x-oss-server-side-encryption est spécifié dans la requête. Indique l'algorithme de chiffrement utilisé.

    Content-MD5

    String

    1B2M2Y8AsgTpgAmY7PhC****

    Le hachage MD5 du fichier.

    Important

    Il s'agit du hachage MD5 du fichier téléchargé, et non du hachage MD5 du corps de la réponse.

    x-oss-hash-crc64ecma

    String

    316181249502703****

    La valeur CRC-64 du fichier.

    x-oss-version-id

    String

    CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

    L'ID de version de l'objet téléchargé. Renvoyé uniquement pour les buckets avec contrôle de version activé.

    Cette opération renvoie également En-têtes de réponse courants tels que Date et x-oss-request-id.

    Éléments de réponse

    Nom

    Type

    Description

    PostResponse

    Container

    Conteneur qui stocke le résultat de la requête Post.

    Nœuds enfants : Bucket, ETag, Key et Location

    Bucket

    String

    Nom du bucket.

    Nœud parent : PostResponse

    ETag

    String

    ETag de l'objet téléchargé. Pour les téléchargements PostObject, l'ETag est un identifiant unique mais ne correspond pas au hachage MD5 du contenu. Utilisez-le pour vérifier si le contenu a changé.

    Nœud parent : PostResponse

    Location

    String

    URL de l'objet nouvellement créé.

    Nœud parent : PostResponse

    Exemples

    • Exemple de requête :

      POST / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 344606
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
/user/a/objectName.txt
--9431149156168
Content-Disposition: form-data; name="success_action_status"
200
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
content_disposition
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
uuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
44CF9590006BF252****
--9431149156168
Content-Disposition: form-data; name="policy"
eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
--9431149156168
Content-Disposition: form-data; name="Signature"
kZoYNv66bsmc10+dcGKw5x2P****
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.txt"
Content-Type: text/plain
abcdefg
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    • Exemple de réponse :

      HTTP/1.1 200 OK
x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e 
Date: Fri, 24 Feb 2014 06:03:28 GMT
ETag: "5B3C1A2E053D763E1B002CC607C5****"
Connection: keep-alive
Content-Length: 0
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
Server: AliyunOSS

    SDK

    SDK pris en charge :

    Codes d'erreur

    Code d'erreur

    Code d'état HTTP

    Description

    FieldItemTooLong

    400

    La taille de la clé du champ de formulaire ne peut pas dépasser 8 Ko et la taille de la valeur du champ de formulaire ne peut pas dépasser 2 Mo.

    InvalidArgument

    400

    Indépendamment de l'ACL du bucket, si l'un des éléments OSSAccessKeyId, policy ou Signature est fourni, les trois sont obligatoires. L'absence de l'un d'eux renvoie cette erreur.

    InvalidDigest

    400

    Le Content-MD5 de la requête ne correspond pas au hachage MD5 calculé par OSS pour le corps de la requête.

    EntityTooLarge

    400

    Le corps de la requête dépasse la limite de taille de 5 Go.

    InvalidEncryptionAlgorithmError

    400

    La valeur x-oss-server-side-encryption n'est pas AES256 ou KMS.

    IncorrectNumberOfFilesInPOSTRequest

    400

    Une requête PostObject ne peut contenir qu'un seul champ de formulaire de type fichier.

    FileAlreadyExists

    409

    Un objet portant le même nom existe et x-oss-forbid-overwrite est défini sur true.

    KmsServiceNotEnabled

    403

    x-oss-server-side-encryption est défini sur KMS, mais vous n'avez pas souscrit à une suite KMS au préalable.

    FileImmutable

    409

    Le bucket est protégé et les données ne peuvent pas être supprimées ni modifiées.

    MethodNotAllowed

    405

    La méthode de requête HTTP n'est pas prise en charge. Vérifiez que la méthode de requête, les en-têtes, le protocole URL, le nom de domaine et le chemin d'accès sont corrects.

    Politique POST

    Le champ de formulaire policy est une politique de sécurité au format JSON qui spécifie les contraintes pour les téléchargements via formulaires HTML, y compris le nom du bucket, le préfixe de l'objet, la période de validité, les méthodes HTTP autorisées, les limites de taille de téléchargement et les types de contenu.

    Signature POST

    Chaque requête PostObject doit inclure une signature à des fins d'authentification.

    FAQ

    Que faire si l'erreur « Your proposed upload exceeds the maximum allowed size » s'affiche ?

    • Cause : la taille du fichier téléchargé ne respecte pas la plage spécifiée par le paramètre content-length-range.

    • Solution : utilisez le paramètre content-length-range pour spécifier les tailles minimale et maximale autorisées pour le fichier téléchargé, en octets. Par exemple, pour télécharger un fichier de 1 Go, vous pouvez définir content-length-range sur ["content-length-range", 1, 1073741824].

    Références