Todos os produtos
Search

Este produto

    Object Storage Service:GetObject

    Central de documentação

    Object Storage Service:GetObject

    Última atualização: Jul 03, 2026

    A operação GetObject recupera um objeto de um bucket. Para chamar esta operação, é necessário ter permissões de leitura no objeto.

    Sintaxe da requisição

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

    Notas de uso

    Por padrão, a operação GetObject suporta acesso via HTTP e HTTPS, além de downloads multi-range. É possível especificar vários intervalos de bytes em uma única requisição para aumentar a eficiência do download.

    • Para permitir acesso exclusivamente via HTTPS, utilize uma política de bucket para conceder o acesso.

    • Caso o objeto esteja na classe de armazenamento Archive, envie primeiro uma requisição RestoreObject ou ative o acesso em tempo real para objetos Archive no bucket onde o objeto está armazenado.

    Permissões

    Por padrão, uma conta Alibaba Cloud possui permissões totais sobre todos os recursos da conta. No entanto, usuários do Resource Access Management (RAM) e funções RAM não possuem nenhuma permissão por padrão. O proprietário da conta Alibaba Cloud ou um administrador deve conceder permissões aos usuários ou funções RAM usando uma Política RAM ou uma política de bucket.

    API

    Action

    Descrição

    GetObject

    oss:GetObject

    Baixa um objeto.

    oss:GetObjectVersion

    Necessária ao baixar um objeto especificando sua versão por meio do versionId.

    kms:Decrypt

    Exigida quando os metadados do objeto contêm X-Oss-Server-Side-Encryption: KMS durante o download.

    Controle de versão

    Por padrão, uma chamada à operação GetObject retorna apenas a versão atual de um objeto. Se você especificar o versionId de um objeto nos parâmetros de consulta, a operação retornará a versão especificada. Caso defina o versionId como null, a operação retornará a versão que possui um versionId nulo.

    Comportamento da API

    • A operação GetObject é compatível com protocolos RFC padrão.

    • Há suporte para download multi-range, permitindo baixar vários intervalos de um objeto simultaneamente.

      • Uma requisição de download multi-range é acionada somente quando a requisição inclui o cabeçalho x-oss-multi-range-behavior: multi-range.

      • O número máximo de intervalos de range é 50.

    Faturamento e limitação de taxa

    • Ao utilizar o recurso multi-range, o número de chamadas de API GetObject para faturamento é calculado multiplicando-se o número de chamadas de API pelo número de segmentos de intervalo de bytes por chamada.

    • A mesma lógica se aplica à limitação de taxa. O número de chamadas de API GetObject para limitação é calculado multiplicando-se o número de chamadas de API pelo número de segmentos de intervalo de bytes por chamada.

    Parâmetros da requisição

    Cabeçalhos da requisição

    O OSS suporta cabeçalhos de resposta personalizados em requisições GET. Os valores dos cabeçalhos de resposta são definidos com os valores especificados nos cabeçalhos da requisição GET apenas se a requisição for bem-sucedida e o código de retorno for 200 OK.

    O OSS não suporta cabeçalhos de resposta personalizados em requisições GET para acesso anônimo.

    Nome

    Tipo

    Obrigatório

    Descrição

    Range

    String

    Não

    Intervalo do objeto a ser transferido.

    • Se o intervalo especificado for válido, a mensagem de resposta incluirá o tamanho total do objeto e o intervalo retornado para a requisição atual. Por exemplo, Content-Range: bytes 0-9/44 indica que o tamanho total do objeto é 44 bytes e o intervalo retornado é 0-9.

    • Se o intervalo especificado for inválido, o objeto inteiro será transferido e a resposta não incluirá Content-Range.

    • Ao definir x-oss-multi-range-behavior como multi-range, é possível especificar vários intervalos. Exemplo: Range: bytes=0-1,3-4,5-6,7-8. São suportados no máximo 50 intervalos.

    Valor padrão: nenhum

    x-oss-multi-range-behavior

    String

    Não

    Ativa o recurso de download multi-range.

    • Ao definir este cabeçalho como multi-range, é possível especificar vários intervalos de bytes no cabeçalho Range para download.

    • Caso o intervalo especificado seja inválido, o objeto inteiro será transferido.

    • No download multi-range, o número de chamadas de API para faturamento e limitação de taxa é calculado como: Número real de chamadas × Número de segmentos de intervalo de bytes.

    Valor padrão: nenhum

    If-Modified-Since

    String

    Não

    Retorna o objeto com status 200 OK se o horário especificado for anterior ao horário de modificação real do objeto ou se o horário for inválido. Retorna 304 Not Modified se o horário especificado for igual ou posterior ao horário de modificação real.

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

    Valor padrão: nenhum

    If-Unmodified-Since

    String

    Não

    Transfere o objeto e retorna 200 OK se o horário especificado for igual ou posterior ao horário de modificação real do objeto. Retorna 412 Precondition Failed se o horário especificado for anterior ao horário de modificação real.

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

    É possível usar If-Modified-Since e If-Unmodified-Since simultaneamente.

    Valor padrão: nenhum

    If-Match

    String

    Não

    Transfere o objeto e retorna 200 OK se o ETag fornecido corresponder ao ETag do objeto. Retorna 412 Precondition Failed se o ETag fornecido não corresponder ao ETag do objeto.

    O ETag de um objeto serve para verificar se os dados foram alterados. Use o valor do ETag para validar a integridade dos dados.

    Valor padrão: nenhum

    If-None-Match

    String

    Não

    Transfere o objeto e retorna 200 OK se o ETag fornecido não corresponder ao ETag do objeto. Retorna 304 Not Modified se o ETag fornecido corresponder ao ETag do objeto.

    É possível usar If-Match e If-None-Match simultaneamente.

    Valor padrão: nenhum

    Accept-Encoding

    String

    Não

    Tipo de codificação do cliente.

    Para transferir o conteúdo retornado no formato compactado Gzip, adicione explicitamente Accept-Encoding:gzip ao cabeçalho da requisição.

    O OSS determina se deve compactar os dados usando Gzip durante a transferência com base no Content-Type e no tamanho (mínimo de 1 KB) do objeto. Se as condições forem atendidas, os dados serão transferidos no formato compactado; caso contrário, serão transferidos no formato original.

    • Se a compactação Gzip for utilizada e entrar em vigor, as informações de ETag e Content-Length não serão incluídas.

    • O OSS suporta compactação Gzip para dados dos seguintes 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 padrão: nenhum

    Parâmetros de consulta

    Nome

    Tipo

    Obrigatório

    Descrição

    response-content-language

    String

    Não

    Especifica o cabeçalho content-language que o OSS retorna para a requisição.

    Valor padrão: nenhum

    response-expires

    String

    Não

    Especifica o cabeçalho expires que o OSS retorna para a requisição.

    Valor padrão: nenhum

    response-cache-control

    String

    Não

    Especifica o cabeçalho cache-control que o OSS retorna para a requisição.

    Valor padrão: nenhum

    response-content-disposition

    String

    Não

    Especifica o cabeçalho content-disposition que o OSS retorna para a requisição.

    Valor padrão: nenhum

    response-content-encoding

    String

    Não

    Especifica o cabeçalho content-encoding que o OSS retorna para a requisição.

    Valor padrão: nenhum

    Parâmetros da resposta

    Cabeçalhos da resposta

    Se o objeto for um link simbólico, o conteúdo do objeto de destino será retornado. Nos cabeçalhos de resposta, Content-Length, ETag e Content-Md5 referem-se aos metadados do objeto de destino. Last-Modified corresponde ao horário de modificação mais recente entre o objeto de destino e o link simbólico. Os demais cabeçalhos contêm os metadados do link simbólico.

    Nome

    Tipo

    Descrição

    x-oss-server-side-encryption

    String

    Se o objeto estiver armazenado com criptografia no lado do servidor, ele será descriptografado automaticamente e retornado ao enviar uma requisição GET. O cabeçalho x-oss-server-side-encryption é retornado na resposta para indicar o algoritmo de criptografia no lado do servidor do objeto.

    x-oss-sealed-time

    String

    Se o objeto for um objeto anexável no qual a operação Seal foi executada, este cabeçalho será retornado para indicar o momento em que a operação Seal foi realizada no arquivo. O valor é semelhante a Sat, 11 Oct 2025 06:41:42 GMT.

    x-oss-tagging-count

    String

    Número de tags associadas ao objeto. Este cabeçalho é retornado apenas se você tiver permissões para ler tags.

    x-oss-expiration

    String

    Data de expiração de um objeto em um bucket com regra de ciclo de vida configurada.

    • Bucket com controle de versão ativado

      • Requisição enviada sem versionId

        Se o objeto solicitado atingir uma regra de exclusão no ciclo de vida, o cabeçalho x-oss-expiration será retornado na resposta para indicar a data de expiração da versão atual do objeto.

      • Requisição enviada com versionId

        O cabeçalho x-oss-expiration não será retornado na resposta, independentemente de o objeto solicitado atingir ou não uma regra de exclusão no ciclo de vida.

    • Bucket sem controle de versão ativado

      • O cabeçalho x-oss-expiration será retornado na resposta se o objeto solicitado atingir uma regra de exclusão no ciclo de vida.

      • O cabeçalho x-oss-expiration não será retornado na resposta se o objeto solicitado não atingir uma regra de exclusão no ciclo de vida.

    Exemplos

    Download básico

    • Exemplo de requisição

      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

    • Exemplo de resposta (quando o objeto é um arquivo)

      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]

    • Exemplo de resposta (quando o objeto é uma pasta)

      Quando o objeto é uma pasta, cabeçalhos de resposta personalizados como Range na requisição são ignorados.

      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

    Download por intervalo

    • Exemplo de requisição

      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

    • Exemplo de resposta

      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]

    Download multi-range

    • Exemplo de requisição

      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

    • Exemplo de resposta

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

    Cabeçalhos de resposta personalizados

    • Exemplo de requisição

      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

    • Exemplo de resposta

      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 link simbólico

    • Exemplo de requisição

      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

    • Exemplo de resposta

      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)

    • Exemplo de requisição

      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

    • Exemplo de resposta

      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]

    Cenários de controle de versão

    • Especificar um ID de versão

      • Exemplo de requisição

        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

      • Exemplo de resposta

        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]

    • A versão atual é um marcador de exclusão

      • Exemplo de requisição

        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

      • Exemplo de resposta

        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 o ID de versão de um marcador de exclusão

      • Exemplo de requisição

        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

      • Exemplo de resposta

        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 erro

    Se uma requisição falhar, o OSS retorna um corpo de resposta contendo um código de erro. A tabela a seguir lista os códigos de erro para esta operação.

    Código de erro

    Código de status HTTP

    Descrição

    NoSuchKey

    404

    O objeto de destino não existe.

    SymlinkTargetNotExist

    404

    O objeto é um link simbólico e o objeto de destino não existe.

    InvalidTargetType

    400

    O objeto é um link simbólico e o objeto de destino também é um link simbólico.

    InvalidObjectState

    403

    Ao baixar um objeto da classe de armazenamento Archive:

    • Nenhuma requisição RestoreObject foi enviada ou a última requisição RestoreObject enviada expirou.

    • Uma requisição RestoreObject foi enviada, mas a operação de restauração ainda não foi concluída.

    Not Modified

    304

    Este erro é retornado pelos seguintes motivos:

    • O cabeçalho de requisição If-Modified-Since foi especificado, mas o objeto solicitado não foi modificado após o horário especificado.

    • O cabeçalho de requisição If-None-Match foi especificado e o ETag do objeto solicitado é igual ao ETag fornecido.

    Precondition Failed

    412

    Este erro é retornado pelos seguintes motivos:

    • O cabeçalho If-Unmodified-Since foi especificado, mas o horário especificado é anterior ao horário de modificação real do objeto.

    • O cabeçalho If-Match foi especificado, mas o ETag do objeto solicitado não é igual ao ETag fornecido.

    Not Found

    404

    Este erro é retornado se o versionId de um objeto não for especificado na requisição e a versão atual do objeto for um marcador de exclusão.

    Method Not Allowed

    405

    Este erro é retornado se o versionId de um objeto for especificado na requisição e o versionId corresponder a um marcador de exclusão.

    Métodos de integração