API PutObject d'Object Storage Service - Object Storage Service

Syntaxe de la requête

PUT /ObjectName HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Notes d'utilisation

La taille maximale d'un fichier pouvant être chargé en une seule opération est de 5 Go. Pour charger un fichier supérieur à 5 Go, utilisez la fonctionnalité de chargement multipartie.
Lorsque vous chargez un fichier portant le même nom qu'un fichier existant, ce dernier est écrasé par défaut et un code d'état 200 OK est renvoyé. Définissez un paramètre pour empêcher les écrasements et éviter de remplacer accidentellement des fichiers importants.
OSS utilise une structure de stockage à plat et ne dispose pas de répertoires comme un système de fichiers traditionnel. Vous pouvez simuler une structure de dossiers en créant un objet vide se terminant par une barre oblique (/).

Autorisations

Un compte Alibaba Cloud dispose de toutes les autorisations par défaut. Toutefois, un utilisateur RAM ou un rôle RAM associé au compte ne possède aucune autorisation tant que celles-ci ne lui ont pas été accordées par le compte Alibaba Cloud ou un administrateur via une politique RAM ou une politique de compartiment.

API	Action	Description
PutObject	`oss:PutObject`	Charge un objet.
	`oss:PutObjectTagging`	Requis si vous spécifiez des tags d'objet à l'aide de l'en-tête `x-oss-tagging` lors du chargement d'un objet.
	`kms:GenerateDataKey`	Requis si l'en-tête `X-Oss-Server-Side-Encryption: KMS` est défini sur `KMS` lors du chargement d'un objet.
	`kms:Decrypt`

Gestion des versions

Dans un compartiment avec gestion des versions activée, OSS génère automatiquement un ID de version unique pour chaque nouvel objet. Cet ID est renvoyé dans l'en-tête de réponse x-oss-version-id.

Dans un compartiment avec gestion des versions suspendue, l'ID de version d'un nouvel objet est null. OSS garantit qu'une seule version null d'un objet existe.

Paramètres de la requête

OSS prend en charge les en-têtes de requête HTTP standard tels que Cache-Control, Expires, Content-Encoding, Content-Disposition et Content-Type. Si vous définissez ces en-têtes de requête, leurs valeurs sont automatiquement appliquées lors du téléchargement du fichier.

Paramètre	Type	Obligatoire	Exemple	Description
Authorization	String	Non	OSS qn6q:77Dv**	Indique que la requête a été authentifiée et autorisée. Pour plus d'informations sur le calcul de la valeur Authorization, consultez Inclure une signature dans l'en-tête. L'en-tête Authorization est généralement requis. Toutefois, vous n'avez pas besoin d'inclure cet en-tête si vous incluez la signature dans l'URL. Pour plus d'informations, consultez Inclure une signature dans l'URL. Valeur par défaut : aucune
Cache-Control	String	Non	no-cache	Spécifie le comportement de mise en cache lors du téléchargement d'un objet. Valeurs valides : no-cache : Le cache doit revalider auprès du serveur d'origine avant de servir le contenu. no-store : Aucune mise en cache de l'objet. public : L'objet peut être mis en cache par n'importe quel cache. private : L'objet est mis en cache uniquement sur le client. max-age=<seconds> : Période de validité du cache en secondes. Disponible uniquement dans HTTP 1.1. Valeur par défaut : aucune
Content-Disposition	String	Non	attachment	Spécifie la manière dont l'objet est affiché. Valeurs valides : Content-Disposition:inline : Affiche l'objet dans le navigateur. Content-Disposition:attachment : Télécharge l'objet avec son nom d'origine. Content-Disposition:attachment; filename="yourFileName" : Télécharge l'objet avec un nom de fichier personnalisé. yourFileName est le nom de fichier personnalisé, par exemple example.jpg. Lors du téléchargement d'objets en tant que pièces jointes, tenez compte des points suivants : Remarque Si le nom de l'objet contient des caractères spéciaux tels que des astérisques () ou des barres obliques (/), le nom du fichier téléchargé peut être échappé. Par exemple, si vous téléchargez `example`.jpg sur votre ordinateur local, `example*.jpg` peut être échappé en `example_.jpg`. Pour éviter les noms de fichiers corrompus pour les caractères non ASCII, encodez-les en URL. Par exemple, pour télécharger l'objet `Test.txt` avec son nom d'origine `Test.txt`, définissez l'en-tête Content-Disposition sur `attachment;filename=%E6%B5%8B%E8%AF%95.txt;filename=UTF-8''%E6%B5%8B%E8%AF%95.txt`, qui dérive de `"attachment;filename="+URLEncoder.encode("Test","UTF-8")+".txt;filename=UTF-8''"+URLEncoder.encode("Test","UTF-8")+".txt"`. Le fait qu'un objet soit prévisualisé ou téléchargé en tant que pièce jointe dépend de l'heure de création du compartiment, de l'heure d'activation d'OSS et du type de nom de domaine. Pour plus d'informations, consultez Que faire si un objet image est téléchargé en tant que pièce jointe mais ne peut pas être prévisualisé lorsque j'accède à l'objet image via son URL ? Valeur par défaut : aucune
Content-Encoding	String	Non	identity	Déclare le codec de l'objet. Spécifiez le codec réel de l'objet. Sinon, des erreurs d'analyse ou de téléchargement peuvent se produire sur le client. Si l'objet n'est pas encodé, laissez cet en-tête vide. Valeurs valides : identity (par défaut) : Aucune compression ni encodage. gzip : Encodé avec l'algorithme LZ77 et CRC 32 bits. compress : Encodé avec l'algorithme LZW. deflate : Encodé avec zlib et l'algorithme deflate. br : Encodé avec l'algorithme Brotli. Valeur par défaut : aucune
Content-MD5	String	Non	eB5eJF1ptWaXm4bijSPyxw==	Utilisé pour vérifier l'intégrité du contenu du message. Content-MD5 est une valeur générée par l'algorithme MD5. Si vous définissez cet en-tête, OSS calcule le hachage Content-MD5 du corps du message et vérifie la cohérence. Pour plus d'informations, consultez Comment calculer Content-MD5. Pour garantir l'intégrité des données, OSS propose plusieurs méthodes pour vérifier le hachage MD5 des données. Pour effectuer une vérification MD5 à l'aide de Content-MD5, ajoutez l'en-tête Content-MD5 à la requête. Valeur par défaut : aucune
Content-Length	String	Non	344606	La taille du corps du message HTTP à transférer, en octets. Si la valeur de l'en-tête Content-Length est inférieure à la taille réelle des données transférées dans le corps de la requête, OSS crée toujours l'objet. Toutefois, la taille de l'objet sera égale à la taille définie dans Content-Length, et les données excédentaires sont ignorées.
Expires	String	Non	Wed, 08 Jul 2015 16:57:01 GMT	Spécifie l'heure d'expiration de l'objet. Pour plus d'informations, consultez RFC2616. Valeur par défaut : aucune
x-oss-forbid-overwrite	String	Non	false	Spécifie s'il faut écraser un objet portant le même nom lors d'une opération PutObject. Si le compartiment de destination a la gestion des versions activée ou suspendue, l'en-tête de requête x-oss-forbid-overwrite est invalide. Cela signifie qu'un objet portant le même nom peut être écrasé. Si vous ne spécifiez pas x-oss-forbid-overwrite ou si vous définissez x-oss-forbid-overwrite sur false, un objet portant le même nom peut être écrasé. Si vous définissez x-oss-forbid-overwrite sur true, un objet portant le même nom ne peut pas être écrasé. La définition de l'en-tête de requête x-oss-forbid-overwrite affecte les performances QPS. Si de nombreuses opérations (QPS>1000) nécessitent l'en-tête de requête x-oss-forbid-overwrite, contactez le support technique pour éviter tout impact sur vos opérations commerciales. Valeur par défaut : false
x-oss-server-side-encryption	String	Non	AES256	Spécifie la méthode de chiffrement côté serveur lors de la création d'un objet. Valeurs valides : AES256, KMS, Si vous spécifiez cet en-tête, il est renvoyé dans l'en-tête de réponse. OSS chiffre et stocke l'objet chargé. Lorsque vous téléchargez l'objet, l'en-tête de réponse inclut x-oss-server-side-encryption, et sa valeur est définie sur l'algorithme de chiffrement de l'objet.
x-oss-server-side-encryption-key-id	String	Non	9468da86-3509-4f8d-a61e-6eab1eac****	L'ID de la clé maître client (CMK) gérée par KMS. Cet en-tête n'est valide que lorsque x-oss-server-side-encryption est défini sur KMS.
x-oss-object-acl	String	Non	default	Spécifie les autorisations d'accès de l'objet lors de sa création dans OSS. Valeurs valides : default : L'objet hérite des autorisations d'accès du compartiment. private : L'objet est une ressource privée. Seul le propriétaire de l'objet et les utilisateurs autorisés disposent des autorisations de lecture et d'écriture sur l'objet. Les autres utilisateurs ne peuvent pas accéder à l'objet. public-read : L'objet est une ressource en lecture publique. Seul le propriétaire de l'objet et les utilisateurs autorisés disposent des autorisations de lecture et d'écriture sur l'objet. Les autres utilisateurs disposent uniquement des autorisations de lecture. Utilisez cette autorisation avec prudence. public-read-write : L'objet est une ressource en lecture-écriture publique. Tous les utilisateurs disposent des autorisations de lecture et d'écriture sur l'objet. Utilisez cette autorisation avec prudence. Pour plus d'informations sur les autorisations d'accès, consultez ACL d'objet.
x-oss-storage-class	String	Non	Standard	Spécifie la classe de stockage de l'objet. Pour un compartiment de n'importe quelle classe de stockage, si vous spécifiez ce paramètre lors du chargement d'un objet, l'objet est stocké dans la classe spécifiée. Par exemple, si vous définissez x-oss-storage-class sur Standard lors du chargement d'un objet dans un compartiment Infrequent Access (IA), l'objet est stocké en tant qu'objet Standard. Valeurs valides : Standard : Standard IA : Infrequent Access Archive : Archive Storage ColdArchive : Cold Archive DeepColdArchive : Deep Cold Archive Important Si vous souhaitez charger un grand nombre d'objets, la spécification directe de la classe de stockage Deep Cold Archive pour les objets à 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 chargement, puis d'utiliser des 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. Pour plus d'informations, consultez Classes de stockage.
x-oss-meta-*	String	Non	x-oss-meta-location	Lorsque vous utilisez l'API PutObject, les paramètres préfixés par x-oss-meta- sont considérés comme des métadonnées définies par l'utilisateur, telles que `x-oss-meta-location`. Un objet peut avoir plusieurs paramètres de ce type, mais la taille totale de toutes les métadonnées ne peut pas dépasser 8 Ko. Les métadonnées prennent en charge les traits d'union (-), les chiffres et les lettres minuscules (a-z). Les lettres majuscules sont converties en minuscules. Les autres caractères, y compris les traits de soulignement (_), ne sont pas pris en charge.
x-oss-tagging	String	Non	TagA=A&TagB=B	Spécifie des tags pour l'objet au format clé-valeur. Vous pouvez définir plusieurs tags simultanément, par exemple `TagA=A&TagB=B`. Remarque La clé et la valeur doivent être encodées en URL. La clé est obligatoire, mais la valeur est facultative. Par exemple, vous pouvez définir les tags de l'objet sur `TagA&TagB=B`.

Pour plus d'informations, consultez En-têtes de réponse courants.

Paramètres de la réponse

Paramètre	Type	Exemple	Description
Content-MD5	String	1B2M2Y8AsgTpgAmY7PhC****	Le hachage MD5 du fichier chargé. Important Le hachage MD5 est le hachage du fichier obtenu après que le client a terminé le chargement, et non le hachage MD5 du corps de la réponse.
x-oss-hash-crc64ecma	String	316181249502703****	La valeur CRC-64 du fichier chargé.
x-oss-version-id	String	CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****	L'ID de version du fichier. Cet en-tête de réponse est renvoyé uniquement lorsque le fichier est chargé dans un compartiment avec gestion des versions activée.

Pour plus d'informations, consultez En-têtes de réponse courants.

Exemples

Chargement simple

Exemple de requête

PUT /test.txt HTTP/1.1
Host: test.oss-cn-zhangjiakou.aliyuncs.com
User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
Accept: */*
Connection: keep-alive
Content-Type: text/plain
Date: Tue, 04 Dec 2018 15:56:37 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Transfer-Encoding: chunked

Exemple de réponse

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 04 Dec 2018 15:56:38 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5C06A3B67B8B5A3DA422299D
ETag: "D41D8CD98F00B204E9800998ECF8****"
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
x-oss-server-time: 7

Définir la classe de stockage

Exemple de requête

PUT /oss.jpg HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Cache-control: no-cache 
Expires: Fri, 28 Feb 2012 05:38:42 GMT 
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Fri, 24 Feb 2012 06:03:28 GMT 
Content-Type: image/jpg 
Content-Length: 344606 
x-oss-storage-class: Archive
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e 
[344606 bytes of object data]

Exemple de réponse

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Sat, 21 Nov 2015 18:52:34 GMT
Content-Type: image/jpg
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5650BD72207FB30443962F9A
ETag: "A797938C31D59EDD08D86188F6D5B872"

Activer la gestion des versions

Exemple de requête

PUT /test HTTP/1.1
Content-Length: 362149
Content-Type: text/html
Host: versioning-put.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 02:53:24 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemple de réponse

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 09 Apr 2019 02:53:24 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5CAC0A3DB7AEADE01700****
x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****
ETag: "4F345B1F066DB1444775AA97D5D2****"

Codes d'erreur

Code d'erreur	Code d'état HTTP	Description
MissingContentLength	411	L'en-tête de la requête n'utilise pas l'encodage chunked ou le paramètre Content-Length n'est pas défini.
InvalidEncryptionAlgorithmError	400	La valeur spécifiée pour x-oss-server-side-encryption est invalide. Valeurs valides : AES256, KMS, .
AccessDenied	403	L'utilisateur ne dispose pas des autorisations d'accès requises pour le compartiment spécifié lors de l'ajout de l'objet.
NoSuchBucket	404	Le compartiment spécifié n'existe pas lors de l'ajout de l'objet.
InvalidObjectName	400	Le nom de l'objet est invalide. Cela peut être dû au fait que le nom de l'objet n'est pas spécifié, dépasse la limite de longueur ou est invalide.
InvalidArgument	400	Cette erreur peut être renvoyée pour les raisons suivantes : La taille de l'objet à ajouter dépasse 5 Go. La valeur d'un paramètre tel que x-oss-storage-class est invalide.
RequestTimeout	400	Content-Length est spécifié, mais aucun corps de message n'est envoyé, ou le corps de message envoyé est inférieur à la taille spécifiée. Dans ce cas, le serveur attend jusqu'à l'expiration du délai de la requête.
Bad Request	400	Si vous spécifiez Content-MD5 dans la requête, OSS calcule le hachage MD5 des données envoyées et le compare à la valeur de Content-MD5 dans la requête. Si les deux valeurs ne correspondent pas, cette erreur est renvoyée.
KmsServiceNotEnabled	403	Vous avez spécifié KMS pour x-oss-server-side-encryption mais n'avez pas acheté de suite KMS au préalable.
FileAlreadyExists	409	Causes possibles : L'en-tête de requête inclut `x-oss-forbid-overwrite=true` pour empêcher l'écrasement d'un fichier portant le même nom, mais un fichier portant le même nom existe déjà dans le compartiment. La fonctionnalité d'espace de noms hiérarchique est activée pour le compartiment et un répertoire portant le même nom existe déjà au niveau du répertoire actuel.
FileImmutable	409	Cette erreur est renvoyée si vous tentez de supprimer ou de modifier des données dans un compartiment qui est dans un état protégé.

Méthodes d'intégration

SDK

Les SDK pour l'API PutObject dans différents langages sont les suivants :

Interface de ligne de commande ossutil

Pour la commande ossutil correspondant à l'API PutObject, consultez put-object.

FAQ

Comment modifier les métadonnées d'un fichier chargé ?

Modifiez les métadonnées du fichier à l'aide de la console OSS, d'ossbrowser, des SDK pour différents langages, de l'interface de ligne de commande ossutil ou de l'API REST. Par exemple, vous pouvez changer le Content-Type de application/octet-stream en image/jpeg. Pour plus d'informations, consultez Gérer les métadonnées des objets.

Pourquoi l'en-tête Expires que j'ai défini ne fonctionne-t-il pas ?

Priorité des en-têtes de cache

Si vous définissez à la fois Expires et Cache-Control, Cache-Control a une priorité plus élevée. Si Cache-Control inclut une directive de mise en cache, telle que max-age=3600, l'en-tête Expires peut être ignoré.

Configuration incorrecte d'Expires

La valeur de l'en-tête Expires doit être une heure future au format GMT. Le code suivant fournit un exemple de configuration de cet en-tête à l'aide du SDK Node.js :

const OSS = require('ali-oss');

// Create an OSS client instance.
const client = new OSS({
  // Replace yourregion with the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before running this example, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the bucket name.
  bucket: 'examplebucket',
});

async function setExpires(objectName, expiresDate) {
  try {
    const result = await client.copy(objectName, objectName, {
      meta: {
        'Expires': expiresDate.toGMTString()
      }
    });
    console.log('Expires header set successfully.');
  } catch (error) {
    console.error('Error setting Expires header:', error);
  }
}

// Set the absolute expiration time for the cached content.
const expiresDate = new Date('2024-10-12T00:00:00.000Z');
setExpires('your-object-name', expiresDate);