Todos los productos
Search

Este producto

    Object Storage Service:GetObject

    Centro de documentos

    Object Storage Service:GetObject

    Última actualización: Sep 23, 2026

    La operación GetObject recupera un objeto de un bucket. Para llamar a esta operación, debe contar con permisos de lectura sobre el objeto.

    Sintaxis de la solicitud

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

    • Para obtener información sobre cómo calcular la firma del encabezado Authorization, consulte Authorization request header.

    • Al descargar objetos grandes (de más de 100 MB) desde OSS, la transferencia puede fallar debido a problemas de red. Utilice solicitudes HTTP Range para recuperar un objeto grande por partes. Este método permite descargas reanudables y concurrentes, lo que mejora la confiabilidad de la transferencia. Para obtener más información, consulte How to obtain OSS resources in segments using HTTP Range requests.

    Notas de uso

    De forma predeterminada, la operación GetObject admite el acceso mediante HTTP y HTTPS. También es compatible con descargas de múltiples rangos. Especifique varios intervalos de bytes en una sola solicitud para mejorar la eficiencia de la descarga.

    • Para permitir el acceso únicamente mediante HTTPS, utilice una bucket policy.

    • Si el objeto pertenece a la clase de almacenamiento Archive, primero debe enviar una solicitud RestoreObject o habilitar el acceso en tiempo real a los objetos Archive en el bucket donde se almacena el objeto.

    Permisos

    De forma predeterminada, una cuenta de Alibaba Cloud tiene permisos completos sobre todos los recursos de dicha cuenta. Sin embargo, los usuarios y roles de Resource Access Management (RAM) no cuentan con ningún permiso de manera predeterminada. El propietario de la cuenta de Alibaba Cloud o un administrador deben otorgar permisos a los usuarios o roles de RAM mediante una RAM Policy o un bucket policy.

    API

    Action

    Descripción

    GetObject

    oss:GetObject

    Descarga un objeto.

    oss:GetObjectVersion

    Este permiso es obligatorio cuando se especifica la versión del objeto mediante versionId durante la descarga.

    kms:Decrypt

    Este permiso es obligatorio si los metadatos del objeto contienen X-Oss-Server-Side-Encryption: KMS durante la descarga.

    Control de versiones

    De forma predeterminada, una llamada a la operación GetObject devuelve únicamente la versión actual de un objeto. Si especifica el versionId del objeto en los parámetros de consulta, la operación devuelve la versión indicada. Si establece versionId en null, la operación devuelve la versión cuyo versionId es null.

    Comportamiento de la API

    • La operación GetObject es compatible con los protocolos estándar RFC.

    • Se admiten las descargas de múltiples rangos. Descargue varios rangos de un objeto al mismo tiempo.

      • Una solicitud de descarga de múltiples rangos se activa solo cuando incluye el encabezado x-oss-multi-range-behavior: multi-range.

      • El número máximo de intervalos de rango es 50.

    Facturación y limitación de velocidad

    • Cuando utiliza la función de múltiples rangos, el número de llamadas a la API GetObject para efectos de facturación se calcula al multiplicar la cantidad de llamadas a la API por el número de segmentos de intervalo de bytes en cada llamada.

    • La misma lógica aplica para la limitación de velocidad. El número de llamadas a la API GetObject para este fin se calcula al multiplicar la cantidad de llamadas a la API por el número de segmentos de intervalo de bytes en cada llamada.

    Parámetros de la solicitud

    Encabezados de la solicitud

    OSS admite encabezados de respuesta personalizados en las solicitudes GET. Los valores de estos encabezados se establecen según lo indicado en la solicitud GET únicamente si esta se completa correctamente y el código de retorno es 200 OK.

    OSS no admite encabezados de respuesta personalizados en las solicitudes GET con acceso anónimo.

    Nombre

    Tipo

    Obligatorio

    Descripción

    Range

    String

    No

    Intervalo del objeto que se va a transferir.

    • Si el intervalo especificado es válido, el mensaje de respuesta incluye el tamaño total del objeto y el rango devuelto para la solicitud actual. Por ejemplo, Content-Range: bytes 0-9/44 indica que el tamaño total del objeto es de 44 bytes y que el rango devuelto es de 0 a 9.

    • Si el intervalo especificado no es válido, se transfiere el objeto completo y la respuesta no incluye Content-Range.

    • Cuando establece x-oss-multi-range-behavior en multi-range, especifique varios rangos. Por ejemplo: Range: bytes=0-1,3-4,5-6,7-8. Se admiten como máximo 50 intervalos de rango.

    Valor predeterminado: Ninguna

    x-oss-multi-range-behavior

    String

    No

    Habilita la función de descarga de múltiples rangos.

    • Si establece este encabezado en multi-range, especifique varios intervalos de bytes en el encabezado Range para la descarga.

    • Si el intervalo especificado no es válido, se transfiere el objeto completo.

    • Cuando utiliza la descarga de múltiples rangos, el número de llamadas a la API para la facturación y la limitación de velocidad se calcula de la siguiente manera: Número real de llamadas × Número de segmentos de intervalo de bytes.

    Valor predeterminado: Ninguna

    If-Modified-Since

    String

    No

    Si la hora especificada es anterior a la hora de modificación real del objeto, o bien no es válida, el objeto se devuelve con el estado 200 OK. Si la hora especificada es igual o posterior a la hora de modificación real, se devuelve 304 Not Modified.

    Formato: GMT. Ejemplo: Fri, 13 Nov 2015 14:47:53 GMT

    Valor predeterminado: Ninguna

    If-Unmodified-Since

    String

    No

    Si la hora especificada es igual o posterior a la hora de modificación real del objeto, este se transfiere y se devuelve 200 OK. Si la hora especificada es anterior a la hora de modificación real, se devuelve 412 Precondition Failed.

    Formato: GMT. Ejemplo: Fri, 13 Nov 2015 14:47:53 GMT

    Utilice If-Modified-Since y If-Unmodified-Since de manera simultánea.

    Valor predeterminado: Ninguna

    If-Match

    String

    No

    Si el ETag proporcionado coincide con el ETag del objeto, este se transfiere y se devuelve 200 OK. Si el ETag proporcionado no coincide con el ETag del objeto, se devuelve 412 Precondition Failed.

    El ETag de un objeto sirve para comprobar si los datos han cambiado. Utilice el valor de ETag para verificar la integridad de los datos.

    Valor predeterminado: Ninguna

    If-None-Match

    String

    No

    Si el ETag proporcionado no coincide con el ETag del objeto, este se transfiere y se devuelve 200 OK. Si el ETag proporcionado coincide con el ETag del objeto, se devuelve 304 Not Modified.

    Utilice If-Match y If-None-Match de manera simultánea.

    Valor predeterminado: Ninguna

    Accept-Encoding

    String

    No

    Tipo de codificación del cliente.

    Para transferir el contenido devuelto en formato comprimido Gzip, agregue de forma explícita Accept-Encoding:gzip al encabezado de la solicitud.

    OSS determina si comprime los datos con Gzip durante la transferencia según el Content-Type y el tamaño del objeto (como mínimo 1 KB). Si se cumplen estas condiciones, los datos se transfieren en formato comprimido; de lo contrario, se transfieren en su formato original.

    • Si se utiliza la compresión Gzip y surte efecto, no se incluye la información de ETag ni de Content-Length.

    • OSS admite la compresión Gzip para datos con los siguientes tipos de Content-Type: text/cache-manifest, text/xml, text/css, text/html, text/plain, application/javascript, application/x-javascript, application/rss+xml, application/json, text/json.

    Valor predeterminado: Ninguna

    Parámetros de consulta

    Nombre

    Tipo

    Obligatorio

    Descripción

    response-content-language

    String

    No

    Especifica el encabezado content-language que OSS devuelve para la solicitud.

    Valor predeterminado: Ninguna

    response-expires

    String

    No

    Especifica el encabezado expires que OSS devuelve para la solicitud.

    Valor predeterminado: Ninguna

    response-cache-control

    String

    No

    Especifica el encabezado cache-control que OSS devuelve para la solicitud.

    Valor predeterminado: Ninguna

    response-content-disposition

    String

    No

    Especifica el encabezado content-disposition que OSS devuelve para la solicitud.

    Valor predeterminado: Ninguna

    response-content-encoding

    String

    No

    Especifica el encabezado content-encoding que OSS devuelve para la solicitud.

    Valor predeterminado: Ninguna

    Parámetros de la respuesta

    Encabezados de la respuesta

    Si el objeto es un enlace simbólico, se devuelve el contenido del objeto de destino. En los encabezados de respuesta, Content-Length, ETag y Content-Md5 corresponden a los metadatos del objeto de destino. Last-Modified refleja la hora de modificación más reciente entre el objeto de destino y el enlace simbólico. Los demás encabezados contienen los metadatos del enlace simbólico.

    Nombre

    Tipo

    Descripción

    x-oss-server-side-encryption

    String

    Si el objeto se almacenó con cifrado del lado del servidor, se descifra automáticamente y se devuelve al enviar una solicitud GET. El encabezado x-oss-server-side-encryption se incluye en la respuesta para indicar el algoritmo de cifrado del lado del servidor utilizado en el objeto.

    x-oss-sealed-time

    String

    Si el objeto es de tipo appendable y se le aplicó la operación Seal, se devuelve este encabezado para indicar la hora en que se ejecutó dicha operación en el archivo. El valor tiene un formato similar a Sat, 11 Oct 2025 06:41:42 GMT.

    x-oss-tagging-count

    String

    Número de etiquetas asociadas al objeto. Este encabezado se devuelve únicamente si cuenta con permisos para leer etiquetas.

    x-oss-expiration

    String

    Fecha de caducidad de un objeto en un bucket con una regla de ciclo de vida configurada.

    • El bucket tiene habilitado el control de versiones

      • Se envía una solicitud sin versionId

        Si el objeto solicitado coincide con una regla de eliminación del ciclo de vida, se devuelve el encabezado x-oss-expiration en la respuesta para indicar la fecha de caducidad de la versión actual del objeto.

      • Se envía una solicitud con versionId

        No se devuelve el encabezado x-oss-expiration en la respuesta, sin importar si el objeto solicitado coincide con una regla de eliminación del ciclo de vida.

    • El bucket no tiene habilitado el control de versiones

      • Si el objeto solicitado coincide con una regla de eliminación del ciclo de vida, se devuelve el encabezado x-oss-expiration en la respuesta.

      • Si el objeto solicitado no coincide con ninguna regla de eliminación del ciclo de vida, no se devuelve el encabezado x-oss-expiration en la respuesta.

    Ejemplos

    Descarga básica

    • Solicitud de ejemplo

      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

    • Respuesta de ejemplo (cuando el objeto es un archivo)

      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]

    • Respuesta de ejemplo (cuando el objeto es un directorio)

      Cuando el objeto es un directorio, se ignoran los encabezados de respuesta personalizados de la solicitud, como Range.

      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

    Descarga por rangos

    • Solicitud de ejemplo

      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

    • Respuestas de ejemplo

      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]

    Descarga de múltiples rangos

    • Solicitud de ejemplo

      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

    • Respuesta de ejemplo

      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--

    Encabezados de respuesta personalizados

    • Solicitud de ejemplo

      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

    • Respuesta de ejemplo

      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]

    Objeto de enlace simbólico

    • Solicitud de ejemplo

      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

    • Respuesta de ejemplo

      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****

    Objeto Archive (restaurado)

    • Solicitud de ejemplo

      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

    • Respuesta de ejemplo

      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]

    Escenarios de control de versiones

    • Especificar un identificador de versión

      • Solicitud de ejemplo

        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

      • Respuesta de ejemplo

        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 versión actual es un marcador de eliminación

      • Solicitud de ejemplo

        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

      • Respuesta de ejemplo

        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>

    • Especificar el identificador de versión de un marcador de eliminación

      • Solicitud de ejemplo

        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

      • Respuesta de ejemplo

        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>

    Códigos de error

    Si una solicitud falla, OSS devuelve un cuerpo de respuesta que contiene un código de error. A continuación se muestran los códigos de error de esta operación.

    Código de error

    Código de estado HTTP

    Descripción

    NoSuchKey

    404

    El objeto de destino no existe.

    SymlinkTargetNotExist

    404

    El objeto es un enlace simbólico y el objeto de destino no existe.

    InvalidTargetType

    400

    El objeto es un enlace simbólico y el objeto de destino también lo es.

    InvalidObjectState

    403

    Este error ocurre al descargar un objeto de la clase de almacenamiento Archive:

    • No se envió una solicitud RestoreObject o la última solicitud enviada expiró.

    • Se envió una solicitud RestoreObject, pero la restauración aún no ha finalizado.

    Not Modified

    304

    Este error se devuelve por los siguientes motivos:

    • Se especificó el encabezado de solicitud If-Modified-Since, pero el objeto solicitado no se modificó después de la hora indicada.

    • Se especificó el encabezado de solicitud If-None-Match y el ETag del objeto solicitado es igual al ETag proporcionado.

    Precondition Failed

    412

    Este error se devuelve por los siguientes motivos:

    • Se especificó el encabezado If-Unmodified-Since, pero la hora indicada es anterior a la hora de modificación real del objeto.

    • Se especificó el encabezado If-Match, pero el ETag del objeto solicitado no coincide con el ETag proporcionado.

    Not Found

    404

    Este error se devuelve si no se especifica el versionId del objeto en la solicitud y la versión actual del objeto es un marcador de eliminación.

    Method Not Allowed

    405

    Este error se devuelve si se especifica el versionId del objeto en la solicitud y dicho versionId corresponde a un marcador de eliminación.

    Métodos de integración