View a markdown version of this page

GetObject (API SOAP) - Amazon Simple Storage Service
ElementosElementos retornadosControle de acessoDownloads de SOAP fragmentados e retomáveis

GetObject (API SOAP)

nota

As APIs SOAP para o Amazon S3 não estão disponíveis para novos clientes e chegam ao fim da vida útil (EOL) em 31 de agosto de 2025. Recomendamos usar a API REST ou os AWS SDKs.

A operação GetObject retorna a versão atual de um objeto. Se você tentar executar GetObject em um objeto que tenha um marcador de exclusão como a versão atual, o S3 retornará um erro 404. Você não pode usar a API SOAP para recuperar uma versão especificada de um objeto. Para fazer isso, use a API REST. Para obter mais informações, consulte Versionamento. Para obter mais opções, use a operação GetObjectExtended (API SOAP).

nota

Os nomes de chave de objeto com o valor “soap” não são compatíveis com solicitações de estilo de hospedagem virtual. Quanto a valores de nome de chave de objeto em que se usa “soap”, deve-se usar, em vez disso, um URL de estilo de caminho.

exemplo

Este exemplo obtém o objeto "Nelson" do bucket "quotes".

Sample Request

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>quotes</Bucket>
  <Key>Nelson</Key>
  <GetMetadata>true</GetMetadata>
  <GetData>true</GetData>
  <InlineData>true</InlineData>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Sample Response

<GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
  <GetObjectResponse>
    <Status>
      <Code>200</Code>
      <Description>OK</Description>
    </Status>
    <Metadata>
      <Name>Content-Type</Name>
      <Value>text/plain</Value>
    </Metadata>
    <Metadata>
      <Name>family</Name>
      <Value>Muntz</Value>
    </Metadata>
    <Data>aGEtaGE=</Data>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
  </GetObjectResponse>
</GetObjectResponse>

Elementos

  • Bucket: O bucket do qual recuperar o objeto.

  • Key: A chave que identifica o objeto.

  • GetMetadata: Os metadados serão retornados com o objeto se for verdadeiro.

  • GetData: Os dados do objeto serão retornados se for verdadeiro.

  • InlineData: Se for verdadeiro, os dados serão retornados, com codificação base 64, como parte do corpo SOAP da resposta. Se for falso, os dados serão retornados como um anexo SOAP. A opção InlineData não é adequada para uso com objetos grandes. O sistema limita essa operação a trabalhar com 1 MB de dados ou menos. Uma solicitação GetObject com o sinalizador InlineData definido falhará com o código de status InlineDataTooLargeError se o parâmetro Data resultante tiver codificado mais de 1 MB. Para baixar objetos grandes, considere chamar GetObject sem definir o sinalizador InlineData ou use a API REST.

Elementos retornados

  • Metadata: Os metadados em pares de nome-valor armazenados com o objeto.

  • Data: Se InlineData for verdadeiro na solicitação, o elemento conterá os dados do objeto codificados em base 64.

  • LastModified: A hora em que o objeto foi armazenado no Amazon S3.

  • ETag: O ETag (identificador de entidade) do objeto. Trata-se de um hash do objeto que pode ser usado para obter dados condicionais. O ETag reflete apenas as alterações no conteúdo de um objeto, não nos metadados.

Controle de acesso

Você poderá ler um objeto somente se tiver recebido acesso READ ao objeto.

Downloads de SOAP fragmentados e retomáveis

Para oferecer flexibilidade a operações GET, o Amazon S3 oferece suporte a downloads fragmentados e retomáveis.

Escolha entre as seguintes opções:

  • Para downloads de objetos grandes, divida-os em partes menores. Para obter mais informações, consulte . Operações GET de intervalo

  • Para operações GET que falham, você pode criar seu aplicativo para baixar o restante em vez do arquivo inteiro. Para obter mais informações, consulte . Recuperação de erros REST GET

Operações GET de intervalo

Para alguns clientes, você talvez queira dividir downloads grandes em downloads menores. Para dividir um GET em unidades menores, use Range.

Antes de dividir um GET em unidades menores, você deve determinar seu tamanho. Por exemplo, a solicitação a seguir obtém o tamanho do objeto bigfile. 

<ListBucket xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>bigbucket</Bucket>
  <Prefix>bigfile</Prefix>
  <MaxKeys>1</MaxKeys>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</ListBucket>

O Amazon S3 retorna a seguinte resposta.

<ListBucketResult xmlns="https://s3.amazonaws.com/doc/2006-03-01">
  <Name>quotes</Name>
  <Prefix>N</Prefix>
  <MaxKeys>1</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>bigfile</Key>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
    <Size>2023276</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>bcaf1ffd86f41161ca5fb16fd081034f</ID>
      <DisplayName>bigfile</DisplayName>
     </Owner>
  </Contents>
</ListBucketResult>

Confira abaixo uma solicitação que baixa o primeiro megabyte do objeto bigfile. 

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>bigbucket</Bucket>
  <Key>bigfile</Key>
  <GetMetadata>true</GetMetadata>
  <GetData>true</GetData>
  <InlineData>true</InlineData>
  <ByteRangeStart>0</ByteRangeStart>
  <ByteRangeEnd>1048576</ByteRangeEnd>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

O Amazon S3 retorna o primeiro megabyte do arquivo e o Etag do arquivo.

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <GetObjectResponse>
    <Status>
      <Code>200</Code>
      <Description>OK</Description>
    </Status>
    <Metadata>
      <Name>Content-Type</Name>
      <Value>text/plain</Value>
    </Metadata>
    <Metadata>
      <Name>family</Name>
      <Value>Muntz</Value>
    </Metadata>
    <Data>--first megabyte of bigfile--</Data>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
  </GetObjectResponse>
</GetObjectResponse>

Para garantir que o arquivo não tenha sido alterado desde o download da parte anterior, especifique o elemento IfMatch. Embora o elemento IfMatch não seja obrigatório, ele é recomendado para conteúdo que provavelmente mudará.

Confira abaixo uma solicitação que obtém o restante do arquivo, usando o cabeçalho da solicitação IfMatch.

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>bigbucket</Bucket>
  <Key>bigfile</Key>
  <GetMetadata>true</GetMetadata>
  <GetData>true</GetData>
  <InlineData>true</InlineData>
  <ByteRangeStart>10485761</ByteRangeStart>
  <ByteRangeEnd>2023276</ByteRangeEnd>
  <IfMatch>"828ef3fdfa96f00ad9f27c383fc9ac7f"</IfMatch>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

O Amazon S3 retorna a resposta a seguir e o restante do arquivo.

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <GetObjectResponse>
    <Status>
      <Code>200</Code>
      <Description>OK</Description>
    </Status>
    <Metadata>
      <Name>Content-Type</Name>
      <Value>text/plain</Value>
    </Metadata>
    <Metadata>
      <Name>family</Name>
      <Value>>Muntz</Value>
    </Metadata>
    <Data>--remainder of bigfile--</Data>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
  </GetObjectResponse>
</GetObjectResponse>

GetObject com versão

A solicitação a seguir retorna a versão especificada do objeto no bucket. 

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<Key>Nelson</Key>
<GetMetadata>true</GetMetadata>
<GetData>true</GetData>
<InlineData>true</InlineData>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Resposta da amostra

<GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
<GetObjectResponse>
<Status>
<Code>200</Code>
<Description>OK</Description>
</Status>
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>Muntz</Value>
</Metadata>
<Data>aGEtaGE=</Data>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
</GetObjectResponse>
</GetObjectResponse>

Recuperação de erros REST GET

Se um objeto GET falhar, você poderá obter o restante do arquivo especificando o intervalo a ser baixado. Para fazer isso, você deve obter o tamanho do objeto usando ListBucket e executar um GET de intervalo no restante do arquivo. Para obter mais informações, consulte GetObjectExtended (API SOAP).

Recursos relacionados

Operações em objetos (API SOAP)