# GetObject (API SOAP)
<a name="SOAPGetObject"></a>

**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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html). Para obter mais opções, use a operação [GetObjectExtended (API SOAP)](SOAPGetObjectExtended.md).

**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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access). 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access).

**Example**  
Este exemplo obtém o objeto "Nelson" do bucket "quotes".  
`Sample Request`  

```
 1. <GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>quotes</Bucket>
 3.   <Key>Nelson</Key>
 4.   <GetMetadata>true</GetMetadata>
 5.   <GetData>true</GetData>
 6.   <InlineData>true</InlineData>
 7.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
 8.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
 9.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
10. </GetObject>
```
`Sample Response`  

```
 1. <GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
 2.   <GetObjectResponse>
 3.     <Status>
 4.       <Code>200</Code>
 5.       <Description>OK</Description>
 6.     </Status>
 7.     <Metadata>
 8.       <Name>Content-Type</Name>
 9.       <Value>text/plain</Value>
10.     </Metadata>
11.     <Metadata>
12.       <Name>family</Name>
13.       <Value>Muntz</Value>
14.     </Metadata>
15.     <Data>aGEtaGE=</Data>
16.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
18.   </GetObjectResponse>
19. </GetObjectResponse>
```

## Elementos
<a name="SOAPGetObjectElements"></a>
+ `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
<a name="SOAPGetObjectReturnedElements"></a>
+ `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
<a name="SOAPGetObjectAccessControl"></a>

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

## Downloads de SOAP fragmentados e retomáveis
<a name="SOAPResumableDownloads"></a>

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](#SOAPRangeGETs) 
+ 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](#SOAPGETErrorRecovery)

### Operações GET de intervalo
<a name="SOAPRangeGETs"></a>

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. 

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

O Amazon S3 retorna a seguinte resposta.

```
 1. <ListBucketResult xmlns="https://s3.amazonaws.com/doc/2006-03-01">
 2.   <Name>quotes</Name>
 3.   <Prefix>N</Prefix>
 4.   <MaxKeys>1</MaxKeys>
 5.   <IsTruncated>false</IsTruncated>
 6.   <Contents>
 7.     <Key>bigfile</Key>
 8.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
 9.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
10.     <Size>2023276</Size>
11.     <StorageClass>STANDARD</StorageClass>
12.     <Owner>
13.       <ID>bcaf1ffd86f41161ca5fb16fd081034f</ID>
14.       <DisplayName>bigfile</DisplayName>
15.      </Owner>
16.   </Contents>
17. </ListBucketResult>
```

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

```
 1. <GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>bigbucket</Bucket>
 3.   <Key>bigfile</Key>
 4.   <GetMetadata>true</GetMetadata>
 5.   <GetData>true</GetData>
 6.   <InlineData>true</InlineData>
 7.   <ByteRangeStart>0</ByteRangeStart>
 8.   <ByteRangeEnd>1048576</ByteRangeEnd>
 9.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
10.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
11.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
12. </GetObject>
```

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

```
 1. <GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 2.   <GetObjectResponse>
 3.     <Status>
 4.       <Code>200</Code>
 5.       <Description>OK</Description>
 6.     </Status>
 7.     <Metadata>
 8.       <Name>Content-Type</Name>
 9.       <Value>text/plain</Value>
10.     </Metadata>
11.     <Metadata>
12.       <Name>family</Name>
13.       <Value>Muntz</Value>
14.     </Metadata>
15.     <Data>--first megabyte of bigfile--</Data>
16.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
18.   </GetObjectResponse>
19. </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.

```
 1. <GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>bigbucket</Bucket>
 3.   <Key>bigfile</Key>
 4.   <GetMetadata>true</GetMetadata>
 5.   <GetData>true</GetData>
 6.   <InlineData>true</InlineData>
 7.   <ByteRangeStart>10485761</ByteRangeStart>
 8.   <ByteRangeEnd>2023276</ByteRangeEnd>
 9.   <IfMatch>"828ef3fdfa96f00ad9f27c383fc9ac7f"</IfMatch>
10.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
11.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
12.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
13. </GetObject>
```

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

```
 1. <GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 2.   <GetObjectResponse>
 3.     <Status>
 4.       <Code>200</Code>
 5.       <Description>OK</Description>
 6.     </Status>
 7.     <Metadata>
 8.       <Name>Content-Type</Name>
 9.       <Value>text/plain</Value>
10.     </Metadata>
11.     <Metadata>
12.       <Name>family</Name>
13.       <Value>>Muntz</Value>
14.     </Metadata>
15.     <Data>--remainder of bigfile--</Data>
16.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
18.   </GetObjectResponse>
19. </GetObjectResponse>
```

### GetObject com versão
<a name="SOAPResumableDownloads-versioned-getobject"></a>

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

```
 1. <GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
 2. <Bucket>quotes</Bucket>
 3. <Key>Nelson</Key>
 4. <GetMetadata>true</GetMetadata>
 5. <GetData>true</GetData>
 6. <InlineData>true</InlineData>
 7. <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
 8. <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
 9. <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
10. </GetObject>
```

Resposta da amostra

```
 1. <GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
 2. <GetObjectResponse>
 3. <Status>
 4. <Code>200</Code>
 5. <Description>OK</Description>
 6. </Status>
 7. <Metadata>
 8. <Name>Content-Type</Name>
 9. <Value>text/plain</Value>
10. </Metadata>
11. <Metadata>
12. <Name>family</Name>
13. <Value>Muntz</Value>
14. </Metadata>
15. <Data>aGEtaGE=</Data>
16. <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17. <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
18. </GetObjectResponse>
19. </GetObjectResponse>
```

### Recuperação de erros REST GET
<a name="SOAPGETErrorRecovery"></a>

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)](SOAPGetObjectExtended.md).

### Recursos relacionados
<a name="SOAPGettingObjectsRelatedTopics"></a>

[Operações em objetos (API SOAP)](SOAPObjectsOps.md)