Interface GetObject d'Object Storage Service - Object Storage Service

Syntaxe de la requête

GET /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Range: bytes=ByteRange (Optional)

Pour savoir comment calculer la signature de l'en-tête Authorization, consultez En-tête de requête Authorization.

Lors du téléchargement d'objets volumineux (supérieurs à 100 Mo) depuis OSS, le transfert peut échouer en raison de problèmes réseau. Utilisez les requêtes HTTP Range pour récupérer un objet volumineux par parties. Cette méthode permet des téléchargements reprenables et simultanés, et améliore la fiabilité du transfert. Pour plus d'informations, consultez Comment obtenir des ressources OSS par segments à l'aide de requêtes HTTP Range.

Notes d'utilisation

Par défaut, l'opération GetObject prend en charge l'accès via HTTP et HTTPS. Elle prend également en charge les téléchargements multi-plages. Spécifiez plusieurs plages d'octets dans une seule requête pour améliorer l'efficacité du téléchargement.

Pour n'autoriser l'accès que via HTTPS, utilisez une politique de bucket afin d'accorder l'accès.
Si l'objet appartient à la classe de stockage Archive, envoyez d'abord une requête RestoreObject ou activez l'accès en temps réel aux objets Archive pour le bucket où l'objet est stocké.

Autorisations

Par défaut, un compte Alibaba Cloud dispose de toutes les autorisations sur toutes les ressources du compte. Toutefois, les utilisateurs RAM et les rôles RAM ne disposent d'aucune autorisation par défaut. Le propriétaire du compte Alibaba Cloud ou un administrateur doit accorder des autorisations aux utilisateurs ou rôles RAM à l'aide d'une politique RAM ou d'une politique de bucket.

API	Action	Description
GetObject	`oss:GetObject`	Télécharge un objet.
	`oss:GetObjectVersion`	Cette autorisation est requise lors du téléchargement d'un objet si vous spécifiez la version de l'objet via versionId.
	`kms:Decrypt`	Cette autorisation est requise lors du téléchargement d'un objet si les métadonnées de l'objet contiennent X-Oss-Server-Side-Encryption: KMS.

Gestion des versions

Par défaut, un appel à l'opération GetObject renvoie uniquement la version actuelle d'un objet. Si vous spécifiez le versionId d'un objet dans les paramètres de requête, l'opération renvoie la version spécifiée. Si vous définissez versionId sur null, l'opération renvoie la version dont le versionId est null.

Comportement de l'API

L'opération GetObject est compatible avec les protocoles RFC standard.
Le téléchargement multi-plages est pris en charge. Vous pouvez télécharger plusieurs plages d'un objet en une seule fois.
- Une requête de téléchargement multi-plages n'est déclenchée que si la requête inclut l'en-tête x-oss-multi-range-behavior: multi-range.
- Le nombre maximal d'intervalles de plage est de 50.

Facturation et limitation du débit

Lorsque vous utilisez la fonctionnalité multi-plages, le nombre d'appels API GetObject facturés est calculé en multipliant le nombre d'appels API par le nombre de segments de plage d'octets par appel.
La même logique s'applique à la limitation du débit. Le nombre d'appels API GetObject pris en compte pour la limitation est calculé en multipliant le nombre d'appels API par le nombre de segments de plage d'octets par appel.

Paramètres de la requête

En-têtes de requête

OSS prend en charge les en-têtes de réponse personnalisés dans les requêtes GET. Les valeurs des en-têtes de réponse sont définies selon les valeurs que vous spécifiez dans les en-têtes de la requête GET uniquement si la requête aboutit et que le code de retour est 200 OK.

OSS ne prend pas en charge les en-têtes de réponse personnalisés dans les requêtes GET pour l'accès anonyme.

Nom	Type	Obligatoire	Description
Range	String	Non	Plage de l'objet à transférer. Si la plage spécifiée est valide, le message de réponse inclut la taille totale de l'objet et la plage de l'objet renvoyée pour la requête actuelle. Par exemple, Content-Range: bytes 0-9/44 indique que la taille totale de l'objet est de 44 octets et que la plage renvoyée est 0-9. Si la plage spécifiée n'est pas valide, l'intégralité de l'objet est transférée et la réponse n'inclut pas Content-Range. Lorsque vous définissez x-oss-multi-range-behavior sur multi-range, vous pouvez spécifier plusieurs plages. Par exemple : Range: bytes=0-1,3-4,5-6,7-8. Un maximum de 50 intervalles de plage est pris en charge. Valeur par défaut : aucune
x-oss-multi-range-behavior	String	Non	Active la fonctionnalité de téléchargement multi-plages. Si vous définissez cet en-tête sur multi-range, vous pouvez spécifier plusieurs plages d'octets dans l'en-tête Range pour le téléchargement. Si la plage spécifiée n'est pas valide, l'intégralité de l'objet est transférée. Lorsque vous utilisez le téléchargement multi-plages, le nombre d'appels API pour la facturation et la limitation du débit est calculé comme suit : Nombre réel d'appels × Nombre de segments de plage d'octets. Valeur par défaut : aucune
If-Modified-Since	String	Non	Si l'heure spécifiée est antérieure à l'heure réelle de modification de l'objet ou si l'heure spécifiée n'est pas valide, l'objet est renvoyé avec un statut 200 OK. Si l'heure spécifiée est identique ou postérieure à l'heure réelle de modification, le code 304 Not Modified est renvoyé. Format : GMT. Exemple : `Fri, 13 Nov 2015 14:47:53 GMT` Valeur par défaut : aucune
If-Unmodified-Since	String	Non	Si l'heure spécifiée est identique ou postérieure à l'heure réelle de modification de l'objet, l'objet est transféré et le code 200 OK est renvoyé. Si l'heure spécifiée est antérieure à l'heure réelle de modification, le code 412 Precondition Failed est renvoyé. Format : GMT. Exemple : `Fri, 13 Nov 2015 14:47:53 GMT` Vous pouvez utiliser If-Modified-Since et If-Unmodified-Since simultanément. Valeur par défaut : aucune
If-Match	String	Non	Si l'ETag que vous fournissez correspond à l'ETag de l'objet, l'objet est transféré et le code 200 OK est renvoyé. Si l'ETag que vous fournissez ne correspond pas à l'ETag de l'objet, le code 412 Precondition Failed est renvoyé. L'ETag d'un objet sert à vérifier si les données ont changé. Vous pouvez utiliser la valeur ETag pour vérifier l'intégrité des données. Valeur par défaut : aucune
If-None-Match	String	Non	Si l'ETag que vous fournissez ne correspond pas à l'ETag de l'objet, l'objet est transféré et le code 200 OK est renvoyé. Si l'ETag que vous fournissez correspond à l'ETag de l'objet, le code 304 Not Modified est renvoyé. Vous pouvez utiliser If-Match et If-None-Match simultanément. Valeur par défaut : aucune
Accept-Encoding	String	Non	Type d'encodage du client. Pour transférer le contenu renvoyé au format compressé Gzip, ajoutez explicitement Accept-Encoding:gzip à l'en-tête de la requête. OSS détermine s'il faut compresser les données à l'aide de Gzip pendant le transfert en fonction du Content-Type et de la taille (au moins 1 Ko) de l'objet. Si les conditions sont remplies, les données sont transférées au format compressé. Sinon, les données sont transférées dans leur format d'origine. Si la compression Gzip est utilisée et prend effet, les informations ETag et Content-Length ne sont pas incluses. OSS prend en charge la compression Gzip pour les données des types Content-Type suivants : text/cache-manifest, text/xml, text/css, text/html, text/plain, application/javascript, application/x-javascript, application/rss+xml, application/json, text/json. Valeur par défaut : aucune

Paramètres de requête

Nom

Type

Obligatoire

Description

response-content-language

String

Non

Spécifie l'en-tête content-language qu'OSS renvoie pour la requête.

Valeur par défaut : aucune

response-expires

String

Non

Spécifie l'en-tête expires qu'OSS renvoie pour la requête.

Valeur par défaut : aucune

response-cache-control

String

Non

Spécifie l'en-tête cache-control qu'OSS renvoie pour la requête.

Valeur par défaut : aucune

response-content-disposition

String

Non

Spécifie l'en-tête content-disposition qu'OSS renvoie pour la requête.

Valeur par défaut : aucune

response-content-encoding

String

Non

Spécifie l'en-tête content-encoding qu'OSS renvoie pour la requête.

Valeur par défaut : aucune

Paramètres de la réponse

En-têtes de réponse

Si l'objet est un lien symbolique, le contenu de l'objet cible est renvoyé. Dans les en-têtes de réponse, Content-Length, ETag et Content-Md5 correspondent aux métadonnées de l'objet cible. Last-Modified correspond à la date de modification la plus récente entre l'objet cible et le lien symbolique. Les autres en-têtes contiennent les métadonnées du lien symbolique.

Nom	Type	Description
x-oss-server-side-encryption	String	Si l'objet est stocké avec un chiffrement côté serveur, il est automatiquement déchiffré et renvoyé lorsque vous envoyez une requête GET. L'en-tête x-oss-server-side-encryption est renvoyé dans la réponse pour indiquer l'algorithme de chiffrement côté serveur de l'objet.
x-oss-sealed-time	String	Si l'objet est un objet ajoutable sur lequel l'opération Seal a été effectuée, cet en-tête est renvoyé pour indiquer l'heure à laquelle l'opération Seal a été effectuée sur le fichier. La valeur est similaire à `Sat, 11 Oct 2025 06:41:42 GMT`.
x-oss-tagging-count	String	Nombre de tags associés à l'objet. Cet en-tête est renvoyé uniquement si vous disposez des autorisations de lecture des tags.
x-oss-expiration	String	Heure d'expiration d'un objet dans un bucket pour lequel une règle de cycle de vie est configurée. Le bucket a la gestion des versions activée Une requête est envoyée sans versionId Si l'objet demandé correspond à une règle de suppression dans le cycle de vie, l'en-tête x-oss-expiration est renvoyé dans la réponse pour indiquer l'heure d'expiration de la version actuelle de l'objet. Une requête est envoyée avec un versionId L'en-tête x-oss-expiration n'est pas renvoyé dans la réponse, que l'objet demandé corresponde ou non à une règle de suppression dans le cycle de vie. Le bucket n'a pas la gestion des versions activée Si l'objet demandé correspond à une règle de suppression dans le cycle de vie, l'en-tête x-oss-expiration est renvoyé dans la réponse. Si l'objet demandé ne correspond pas à une règle de suppression dans le cycle de vie, l'en-tête x-oss-expiration n'est pas renvoyé dans la réponse.

Téléchargement de base

Exemple de requête

GET /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 06:38:30 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemple de réponse (lorsque l'objet est un fichier)

HTTP/1.1 200 OK
x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
x-oss-object-type: Normal
Date: Fri, 24 Feb 2012 06:38:30 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E0563E1B002CC607C*****"
Content-Type: image/jpg
Content-Length: 344606
Server: AliyunOSS
[344606 bytes of object data]

Exemple de réponse (lorsque l'objet est un dossier)

Lorsque l'objet est un dossier, les en-têtes de réponse personnalisés tels que Range dans la requête sont ignorés.

HTTP/1.1 200 OK
x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
x-oss-object-type: Normal
Date: Wed, 31 Mar 2021 06:38:30 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "null"
Content-Type: application/x-directory
Content-Length: 0
Server: AliyunOSS

Téléchargement par plage

Exemple de requête

GET /oss.jpg HTTP/1.1
Host:oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Feb 2012 05:38:42 GMT
Range: bytes=100-900
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemples de réponses

HTTP/1.1 206 Partial Content
x-oss-request-id: 28f6-15ea-8224-234e-c0ce407*****
x-oss-object-type: Normal
Date: Fri, 28 Feb 2012 05:38:42 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E05E1B002CC607C*****"
Accept-Ranges: bytes
Content-Range: bytes 100-900/344606
Content-Type: image/jpg
Content-Length: 801
Server: AliyunOSS
[801 bytes of object data]

Téléchargement multi-plages

Exemple de requête

GET /oss.jpg HTTP/1.1
Host:oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Feb 2012 05:38:42 GMT
Range: bytes=0-1,3-4,5-6,7-8
x-oss-multi-range-behavior: multi-range
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemple de réponse

HTTP/1.1 206 Partial Content
x-oss-request-id: 28f6-15ea-8224-234e-c0ce407*****
x-oss-object-type: Normal
Date: Fri, 28 Feb 2012 05:38:42 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E05E1B002CC607C*****"
Accept-Ranges: bytes
Content-Type: multipart/byteranges;boundary=63ce7776-c104-417f-8a65-ccaa3b17f428
Content-Length: 446
Server: AliyunOSS

--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 0-1/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 3-4/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 5-6/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 7-8/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428--

En-têtes de réponse personnalisés

Exemple de requête

GET /oss.jpg?response-expires=Thu%2C%2001%20Feb%202012%2017%3A00%3A00%20GMT&response-cache-control=No-cache&response-content-disposition=attachment%253B%2520filename%253Dtesting.txt&response-content-encoding=utf-8&response-content-language=%E4%B8%AD%E6%96%87 HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com:
Date: Fri, 24 Feb 2012 06:09:48 GMT

Exemple de réponse

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC75A644*****
x-oss-object-type: Normal
Date: Fri, 24 Feb 2012 06:09:48 GMT 
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E053D1B002CC607*****"
Content-Length: 344606
Connection: keep-alive
Content-disposition: attachment; filename=testing.txt
Content-language: Chinese
Content-type: jpg
Cache-control: no-cache
Expires: Fri, 24 Feb 2012 17:00:00 GMT
Server: AliyunOSS
[344606 bytes of object data]

Objet lien symbolique

Exemple de requête

GET /link-to-oss.jpg HTTP/1.1
Accept-Encoding: identity
Date: Tue, 08 Nov 2016 03:17:58 GMT
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemple de réponse

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 08 Nov 2016 03:17:58 GMT
Content-Type: application/octet-stream
Content-Length: 20
Connection: keep-alive
x-oss-request-id: 582143E6A212AD*****
Accept-Ranges: bytes
ETag: "8086265EFC021F9A2F09BF4****"
Last-Modified: Tue, 08 Nov 2016 03:17:58 GMT
x-oss-object-type: Symlink
Content-MD5: gIYmXvwCEe0fmi8Jv0Y****

Objet Archive (restauré)

Exemple de requête

GET /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Sat, 15 Apr 2017 09:38:30 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemple de réponse

HTTP/1.1 200 OK
x-oss-request-id: 58F723829F29F18D7F00*****
x-oss-object-type: Normal
x-oss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"
Date: Sat, 15 Apr 2017 09:38:30 GMT
Last-Modified: Sat, 15 Apr 2017 06:07:48 GMT
ETag: "5B3C1A2E0763E1B002CC607C*****"
Content-Type: image/jpg
Content-Length: 344606
Server: AliyunOSS
[344606 bytes of object data]

Scénarios de gestion des versions

Spécification d'un ID de version

Exemple de requête

GET /example?versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** HTTP/1.1
Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 02:58:06 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemple de réponse

HTTP/1.1 200 OK
x-oss-request-id: 5CAC0A3EDE0170*****
x-oss-version-id: CAEQNhiBgM0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY*****
x-oss-object-type: Normal
Date: Tue, 17 Apr 2025 02:58:06 GMT
Last-Modified: Fri, 22 Mar 2018 08:07:50 GMT
ETag: "5B3C1A2E053D7002CC607C5A*****"
Content-Type: text/html
Content-Length: 362149
Server: AliyunOSS
[362149 bytes of object data]

La version actuelle est un marqueur de suppression

Exemple de requête

GET /example HTTP/1.1
Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 17 Apr 2025 03:22:33 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemple de réponse

HTTP/1.1 404 Not Found
x-oss-request-id: 5CAC0FEADE0170*****
x-oss-delete-marker: true
x-oss-version-id: CAEQNxiBgyA0BYiIDc4ZDdmNTA2MGViZTRiNjE5NzZlZWM4OWM5OT*****
Date: Tue, 17 Apr 2025 03:22:33 GMT
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
  <RequestId>5CAC0FEADE0170*****</RequestId>
  <HostId>versioning-get.oss-cn-hangzhou.aliyun*****</HostId>
  <Key>example</Key>
</Error>

Spécification de l'ID de version d'un marqueur de suppression

Exemple de requête

GET /example?versionId=CAEQMxiBgMCfqaWA0BYiIDliMWI4MGQ0MTVmMjQ3MmE5MDNlMmY4YmFkYTk3**** HTTP/1.1
Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 17 Apr 2025 03:09:44 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemple de réponse

HTTP/1.1 405 Method Not Allowed
x-oss-request-id: 5CAC0CF8DE01700*****
x-oss-delete-marker: true
x-oss-version-id: CAEQMxiBgMCfqaWADliMWI4MGQ0MTVmMjQ3MmE5MDNlMmY4YmFkYTk*****
Allow: DELETE
Date: Tue, 17 Apr 2025 03:09:44 GMT
Content-Type: application/xml
Content-Length: 318
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>MethodNotAllowed</Code>
  <Message>The specified method is not allowed against this resource.</Message>
  <RequestId>5CAC0CF8DE0170*****</RequestId>
  <HostId>versioning-get.oss-cn-hangzhou.aliyunc*****</HostId>
  <Method>GET</Method>
  <ResourceType>DeleteMarker</ResourceType>
</Error>

Codes d'erreur

Si une requête échoue, OSS renvoie un corps de réponse contenant un code d'erreur. Le tableau suivant répertorie les codes d'erreur pour cette opération.

Code d'erreur	Code d'état HTTP	Description
NoSuchKey	404	L'objet cible n'existe pas.
SymlinkTargetNotExist	404	L'objet est un lien symbolique et l'objet cible n'existe pas.
InvalidTargetType	400	L'objet est un lien symbolique et l'objet cible est également un lien symbolique.
InvalidObjectState	403	Lors du téléchargement d'un objet de la classe de stockage Archive : Aucune requête RestoreObject n'a été soumise, ou la dernière requête RestoreObject soumise a expiré. Une requête RestoreObject a été soumise, mais l'opération de restauration n'est pas encore terminée.
Not Modified	304	Cette erreur est renvoyée pour les raisons suivantes : L'en-tête de requête If-Modified-Since est spécifié, mais l'objet demandé n'a pas été modifié après l'heure spécifiée. L'en-tête de requête If-None-Match est spécifié et l'ETag de l'objet demandé est identique à l'ETag fourni.
Precondition Failed	412	Cette erreur est renvoyée pour les raisons suivantes : L'en-tête If-Unmodified-Since est spécifié, mais l'heure spécifiée est antérieure à l'heure réelle de modification de l'objet. L'en-tête If-Match est spécifié, mais l'ETag de l'objet demandé n'est pas identique à l'ETag fourni.
Not Found	404	Cette erreur est renvoyée si le versionId d'un objet n'est pas spécifié dans la requête et que la version actuelle de l'objet est un marqueur de suppression.
Method Not Allowed	405	Cette erreur est renvoyée si le versionId d'un objet est spécifié dans la requête et que le versionId correspond à un marqueur de suppression.

Méthodes d'intégration

SDK

Le tableau suivant répertorie les kits de développement logiciel (SDK) pour différents langages que vous pouvez utiliser pour appeler l'opération GetObject.

Interface de ligne de commande ossutil

Pour plus d'informations sur la commande ossutil correspondant à l'opération GetObject, consultez get-object.