View a markdown version of this page

CopyObject (API SOAP) - Amazon Simple Storage Service
DescriçãoSintaxe da solicitaçãoParâmetros da solicitaçãoSintaxe da respostaElementos de respostaErros especiaisExemplosRecursos relacionados

CopyObject (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.

Descrição

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.

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.

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


<CopyObject xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
  <SourceBucket>source_bucket</SourceBucket>
  <SourceObject>source_object</SourceObject>
  <DestinationBucket>destination_bucket</DestinationBucket>
  <DestinationObject>destination_object</DestinationObject>
  <MetadataDirective>{REPLACE | COPY}</MetadataDirective>
  <Metadata>
    <Name>metadata_name</Name>
    <Value>metadata_value</Value>
  </Metadata>
  ...
  <AccessControlList>
    <Grant>
      <Grantee xsi:type="user_type">
        <ID>user_id</ID>
        <DisplayName>display_name</DisplayName>
      </Grantee>
      <Permission>permission</Permission>
    </Grant>
    ...
  </AccessControlList>
  <CopySourceIfMatch>etag</CopySourceIfMatch>
  <CopySourceIfNoneMatch>etag</CopySourceIfNoneMatch>
  <CopySourceIfModifiedSince>date_time</CopySourceIfModifiedSince>
  <CopySourceIfUnmodifiedSince>date_time</CopySourceIfUnmodifiedSince>
  <AWSAccessKeyId>AWSAccessKeyId</AWSAccessKeyId>
  <Timestamp>TimeStamp</Timestamp>
  <Signature>Signature</Signature>
</CopyObject>

Parâmetros da solicitação

Name (Nome) Descrição Obrigatório
SourceBucket

O nome do bucket de origem.

Tipo: string

Padrão: nenhum

Restrições: um bucket de origem válido.

 Sim
SourceKey

O nome da chave do objeto de origem.

Tipo: string

Padrão: nenhum

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.

Tipo: string

Padrão: nenhum

Restrições: você deve ter acesso WRITE ao bucket de destino.

 Sim
DestinationKey

A chave do objeto de destino.

Tipo: string

Padrão: nenhum

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.

Tipo: string

Padrão: COPY

Valores válidos: COPY | REPLACE

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.

Tipo: string

Padrão: nenhum

Restrições: nenhuma.

 Não
AccessControlList

Concede acesso aos usuários por endereços de e-mail ou ID de usuário canônico.

Tipo: string

Padrão: nenhum

Restrições: nenhuma

 Não
CopySourceIfMatch

Copiará o objeto se o ETag (identificador de entidade) corresponder à tag especificada; caso contrário, retornará um PreconditionFailed.

Tipo: string

Padrão: nenhum

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.

Tipo: string

Padrão: nenhum

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.

Tipo: dateTime

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.

Tipo: dateTime

Padrão: nenhum

 Não

Sintaxe da resposta

<CopyObjectResponse xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
  <CopyObjectResponse>
    <ETag>"etag"</ETag>
    <LastModified>timestamp</LastModified>
  </CopyObjectResponse>
</CopyObjectResponse>

Elementos de resposta

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.

Tipo: string

Antepassado: CopyObjectResult
LastModified

Retorna a data em que o objeto foi modificado pela última vez.

Tipo: string

Antepassado: CopyObjectResult

Para obter informações sobre elementos de resposta gerais, consulte Uso de cabeçalhos de resposta de erro REST.

Erros especiais

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.

Exemplos

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

Exemplo de solicitação

<CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
  <SourceBucket>pacific</SourceBucket>
  <SourceObject>flotsam</SourceObject>
  <DestinationBucket>atlantic</DestinationBucket>
  <DestinationObject>jetsam</DestinationObject>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
</CopyObject>

Resposta da amostra

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

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

Exemplo de solicitação

<CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
  <SourceBucket>wonderland</SourceBucket>
  <SourceObject>tweedledee</SourceObject>
  <DestinationBucket>wonderland</DestinationBucket>
  <DestinationObject>tweedledum</DestinationObject>
  <MetadataDirective >REPLACE</MetadataDirective >
  <Metadata>
    <Name>Content-Type</Name>
    <Value>text/plain</Value>
  </Metadata>
  <Metadata>
    <Name>relationship</Name>
    <Value>twins</Value>
  </Metadata>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
</CopyObject>

Resposta da amostra

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

Recursos relacionados