# CopyObject (API SOAP)
<a name="SOAPCopyObject"></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. 

## Descrição
<a name="SOAPCopyObject_Description"></a>

A operação `CopyObject` cria uma cópia de um objeto quando você especifica a chave e o bucket de um objeto de origem e a chave e o bucket de um destino. 

Ao copiar um objeto, você pode preservar todos os metadados (padrão) ou especificar novos metadados. No entanto, a ACL não é preservada e está definida como `private` para o usuário que faz a solicitação. Para substituir a configuração de ACL padrão, especifique uma nova ACL ao gerar uma solicitação de cópia. Para obter mais informações, consulte [Usar ACLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/S3_ACLs_UsingACLs.html).

Todas as solicitações de cópia devem ser autenticadas. Além disso, você deve ter acesso de *leitura* ao objeto de origem e acesso de *gravação* ao bucket de destino. Para obter mais informações, consulte [Uso de acesso de autenticação](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html). 

Para copiar um objeto somente sob determinadas condições, como se o Etag corresponde ou se o objeto foi modificado antes ou depois de uma data especificada, use os parâmetros de solicitação `CopySourceIfUnmodifiedSince`, `CopyIfUnmodifiedSince`, `CopySourceIfMatch` ou `CopySourceIfNoneMatch`. 

**nota**  
 Talvez seja necessário configurar o tempo limite do soquete da pilha SOAP para copiar objetos grandes. 

## Sintaxe da solicitação
<a name="SOAPCopyObject_RequestSyntax"></a>

```
 1. <CopyObject xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
 2.   <SourceBucket>source_bucket</SourceBucket>
 3.   <SourceObject>source_object</SourceObject>
 4.   <DestinationBucket>destination_bucket</DestinationBucket>
 5.   <DestinationObject>destination_object</DestinationObject>
 6.   <MetadataDirective>{REPLACE | COPY}</MetadataDirective>
 7.   <Metadata>
 8.     <Name>metadata_name</Name>
 9.     <Value>metadata_value</Value>
10.   </Metadata>
11.   ...
12.   <AccessControlList>
13.     <Grant>
14.       <Grantee xsi:type="user_type">
15.         <ID>user_id</ID>
16.         <DisplayName>display_name</DisplayName>
17.       </Grantee>
18.       <Permission>permission</Permission>
19.     </Grant>
20.     ...
21.   </AccessControlList>
22.   <CopySourceIfMatch>etag</CopySourceIfMatch>
23.   <CopySourceIfNoneMatch>etag</CopySourceIfNoneMatch>
24.   <CopySourceIfModifiedSince>date_time</CopySourceIfModifiedSince>
25.   <CopySourceIfUnmodifiedSince>date_time</CopySourceIfUnmodifiedSince>
26.   <AWSAccessKeyId>AWSAccessKeyId</AWSAccessKeyId>
27.   <Timestamp>TimeStamp</Timestamp>
28.   <Signature>Signature</Signature>
29. </CopyObject>
```

## Parâmetros da solicitação
<a name="SOAPCopyObject_RequestParameters"></a>


|  Name (Nome)  |  Descrição  |  Obrigatório  | 
| --- | --- | --- | 
|  SourceBucket  | O nome do bucket de origem.<br />Tipo: string<br />Padrão: nenhum<br />Restrições: um bucket de origem válido. |  Sim  | 
|  SourceKey  | O nome da chave do objeto de origem.<br />Tipo: string<br />Padrão: nenhum<br />Restrições: a chave de um objeto de origem válido ao qual você tem acesso READ. |  Sim  | 
|  DestinationBucket  | O nome do bucket do de destino.<br />Tipo: string<br />Padrão: nenhum<br />Restrições: você deve ter acesso WRITE ao bucket de destino. |  Sim  | 
|  DestinationKey  |  A chave do objeto de destino.<br />Tipo: string<br />Padrão: nenhum<br />Restrições: você deve ter acesso WRITE ao bucket de destino. |  Sim  | 
|  MetadataDirective  |  Especifica se os metadados são copiados do objeto de origem ou substituídos pelos metadados fornecidos na solicitação.<br />Tipo: string<br />Padrão: COPY<br />Valores válidos: COPY \| REPLACE<br />Restrições: valores diferentes de `COPY` ou `REPLACE` resultarão em um erro imediato. Você não pode copiar um objeto para si mesmo, a menos que o cabeçalho MetadataDirective seja especificado e seu valor definido como `REPLACE`. |  Não  | 
|  Metadata  |  Especifica os pares de nome-valor dos metadados a serem definidos para o objeto. Se MetadataDirective estiver definido como `COPY`, todos os metadados serão ignorados.<br />Tipo: string<br />Padrão: nenhum<br />Restrições: nenhuma. |  Não  | 
|  AccessControlList  | Concede acesso aos usuários por endereços de e-mail ou ID de usuário canônico.<br />Tipo: string<br />Padrão: nenhum<br />Restrições: nenhuma |  Não  | 
|  CopySourceIfMatch  | Copiará o objeto se o ETag (identificador de entidade) corresponder à tag especificada; caso contrário, retornará um PreconditionFailed.<br />Tipo: string<br />Padrão: nenhum<br />Restrições: nenhuma. Se o Etag não corresponder, o objeto não será copiado. |  Não  | 
|  CopySourceIfNoneMatch  | Copiará o objeto se o ETag (identificador de entidade) for diferente do Etag especificado; caso contrário, retornará um erro.<br />Tipo: string<br />Padrão: nenhum<br />Restrições: nenhuma.  |  Não  | 
|  CopySourceIfUnmodifiedSince  |  Copiará o objeto se ele não tiver sido modificado desde o horário especificado; caso contrário, retornará um PreconditionFailed.<br />Tipo: dateTime<br />Padrão: nenhum |  Não  | 
|  CopySourceIfModifiedSince  | Copiará o objeto se ele tiver sido modificado desde o horário especificado; caso contrário, retornará um erro.<br />Tipo: dateTime<br />Padrão: nenhum |  Não  | 

## Sintaxe da resposta
<a name="SOAPCopyObject_ResponseSyntax"></a>

```
1. <CopyObjectResponse xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
2.   <CopyObjectResponse>
3.     <ETag>"etag"</ETag>
4.     <LastModified>timestamp</LastModified>
5.   </CopyObjectResponse>
6. </CopyObjectResponse>
```

## Elementos de resposta
<a name="SOAPCopyObject_CommonResponseElements"></a>

Confira a seguir uma lista de elementos de resposta.

**nota**  
 A API SOAP não retorna espaços em branco extras. O espaço em branco extra só é retornado pela API REST. 


|  Name (Nome)  |  Descrição  | 
| --- | --- | 
|  Etag  | Retorna o Etag do novo objeto. O ETag reflete apenas as alterações no conteúdo de um objeto, não nos metadados.<br />Tipo: string<br />Antepassado: CopyObjectResult | 
|  LastModified  | Retorna a data em que o objeto foi modificado pela última vez.<br />Tipo: string<br />Antepassado: CopyObjectResult | 

Para obter informações sobre elementos de resposta gerais, consulte [Uso de cabeçalhos de resposta de erro REST](https://docs.aws.amazon.com/AmazonS3/latest/userguide/HandlingErrors.html#UsingRESTErrorResponseHeaders).

## Erros especiais
<a name="SOAPCopyObject_SpecialErrors"></a>

Não há erros especiais para essa operação. Para obter informações sobre erros gerais do Amazon S3, consulte [Lista de códigos de erro](ErrorResponses.md#ErrorCodeList).

## Exemplos
<a name="SOAPCopyObject_Examples"></a>

Este exemplo copia o objeto `flotsam` do bucket `pacific` para o objeto `jetsam` do bucket `atlantic`, preservando seus metadados.

### Exemplo de solicitação
<a name="SOAPCopyObject_Examples_Request1"></a>

```
1. <CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <SourceBucket>pacific</SourceBucket>
3.   <SourceObject>flotsam</SourceObject>
4.   <DestinationBucket>atlantic</DestinationBucket>
5.   <DestinationObject>jetsam</DestinationObject>
6.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
7.   <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
8.   <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
9. </CopyObject>
```

### Resposta da amostra
<a name="SOAPCopyObject_Examples_Response1"></a>

```
1. <CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <CopyObjectResponse>
3.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
4.     <LastModified>2008-02-18T13:54:10.183Z</LastModified>
5.   </CopyObjectResponse>
6. </CopyObjectResponse>
```

Este exemplo copia o objeto "tweedledee" do bucket wonderland para o objeto "tweedledum" do bucket wonderland, substituindo os metadados.

### Exemplo de solicitação
<a name="SOAPCopyObject_Examples_Request2"></a>

```
 1. <CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2.   <SourceBucket>wonderland</SourceBucket>
 3.   <SourceObject>tweedledee</SourceObject>
 4.   <DestinationBucket>wonderland</DestinationBucket>
 5.   <DestinationObject>tweedledum</DestinationObject>
 6.   <MetadataDirective >REPLACE</MetadataDirective >
 7.   <Metadata>
 8.     <Name>Content-Type</Name>
 9.     <Value>text/plain</Value>
10.   </Metadata>
11.   <Metadata>
12.     <Name>relationship</Name>
13.     <Value>twins</Value>
14.   </Metadata>
15.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
16.   <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
17.   <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
18. </CopyObject>
```

### Resposta da amostra
<a name="SOAPCopyObject_Examples_Response2"></a>

```
1. <CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <CopyObjectResponse>
3.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
4.     <LastModified>2008-02-18T13:54:10.183Z</LastModified>
5.   </CopyObjectResponse>
6. </CopyObjectResponse>
```

## Recursos relacionados
<a name="SOAPCopyObject_RelatedResources"></a>
+  [PutObject (API SOAP)](SOAPPutObject.md) 
+  [PutObjectInline (API SOAP)](SOAPPutObjectInline.md)