Copiar Blob da URL

A Copy Blob From URL operação copia um blob para um destino dentro da conta de armazenamento de forma síncrona para tamanhos de blob de origem de até 256 mebibytes (MiB). Essa API está disponível a partir da versão 2018-03-28.

A origem de uma Copy Blob From URL operação pode ser qualquer blob de bloco confirmado em qualquer conta de armazenamento do Azure que seja pública ou autorizada com uma assinatura de acesso compartilhado.

Solicitação

Você pode construir a solicitação da Copy Blob From URL seguinte maneira. Recomendamos HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento, mycontainer pelo nome do contêiner e myblob pelo nome do blob de destino.

URI de solicitação de método PUT Versão HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob HTTP/1.1

URI para o serviço de armazenamento emulado

Ao fazer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e Armazenamento de Blobs do Azure porta como 127.0.0.1:10000, seguido pelo nome da conta de armazenamento emulada:

URI de solicitação de método PUT Versão HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob HTTP/1.1

Para obter mais informações, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no URI da solicitação:

Parâmetro Descrição
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de Armazenamento de Blobs.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais:

Cabeçalho da solicitação Descrição
Authorization Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Necessário para todas as solicitações autorizadas. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure.
x-ms-meta-name:value Opcional. Especifica um par nome/valor definido pelo usuário associado ao blob. Se nenhum par nome/valor for especificado, a operação copiará os metadados do blob ou arquivo de origem para o blob de destino. Se um ou mais pares nome/valor forem especificados, o blob de destino será criado com os metadados especificados e os metadados não serão copiados do blob ou arquivo de origem.

A partir da versão 2009-09-19, os nomes de metadados devem seguir as regras de nomenclatura para identificadores C#. Para obter mais informações, consulte Nomenclatura e referência a contêineres, blobs e metadados.
x-ms-encryption-scope Opcional. Indica o escopo de criptografia para criptografar o conteúdo da solicitação. Esse cabeçalho tem suporte na versão 2020-12-06 e posterior.
x-ms-tags Opcional. Define marcas codificadas em cadeia de caracteres de consulta no blob. As marcas não são copiadas da origem da cópia. Para obter mais informações, consulte Comentários. Com suporte na versão 2019-12-12 e posterior.
x-ms-copy-source-tag-option Opcional. Os valores possíveis são REPLACE e COPY (diferencia maiúsculas de minúsculas). O valor padrão é REPLACE.

Se COPY for especificado, as marcas do blob de origem serão copiadas para o blob de destino. O blob de origem deve ser privado e a solicitação deve ter permissão para a operação Obter Marcas de Blob no blob de origem e a operação Definir Marcas de Blob no blob de destino. Isso incorre em uma chamada extra para a Get Blob Tags operação na conta de origem.

REPLACE definirá marcas que o x-ms-tags cabeçalho especifica no blob de destino. Se x-ms-tags especificar REPLACE e nenhuma marca, nenhuma marca será definida no blob de destino. Especificar COPY e x-ms-tags resultará em um erro 409 (Conflito).

Com suporte na versão 2021-04-10 e posterior.
x-ms-source-if-modified-since Opcional. Um valor DateTime. Especifique esse cabeçalho condicional para copiar o blob somente se o blob de origem tiver sido modificado desde a data/hora especificada. Se o blob de origem não tiver sido modificado, o Armazenamento de Blobs retornará status código 412 (Falha na pré-condição). Você não poderá especificar esse cabeçalho se a origem for um arquivo do Azure.
x-ms-source-if-unmodified-since Opcional. Um valor DateTime. Especifique esse cabeçalho condicional para copiar o blob somente se o blob de origem não tiver sido modificado desde a data/hora especificada. Se o blob de origem tiver sido modificado, o Armazenamento de Blobs retornará status código 412 (Falha na pré-condição). Você não poderá especificar esse cabeçalho se a origem for um arquivo do Azure.
x-ms-source-if-match Opcional. Um valor ETag. Especifique esse cabeçalho condicional para copiar o blob de origem somente se o ETag valor corresponder ao valor especificado. Se os valores não corresponderem, o Armazenamento de Blobs retornará status código 412 (Falha na pré-condição). Você não poderá especificar esse cabeçalho se a origem for um arquivo do Azure.
x-ms-source-if-none-match Opcional. Um valor ETag. Especifique esse cabeçalho condicional para copiar o blob somente se o ETag valor não corresponder ao valor especificado. Se os valores forem idênticos, o Armazenamento de Blobs retornará status código 412 (Falha na pré-condição). Você não poderá especificar esse cabeçalho se a origem for um arquivo do Azure.
If-Modified-Since Opcional. Um valor DateTime. Especifique esse cabeçalho condicional para copiar o blob somente se o blob de destino tiver sido modificado desde a data/hora especificada. Se o blob de destino não tiver sido modificado, o Armazenamento de Blobs retornará status código 412 (Falha na pré-condição).
If-Unmodified-Since Opcional. Um valor DateTime. Especifique esse cabeçalho condicional para copiar o blob somente se o blob de destino não tiver sido modificado desde a data/hora especificada. Se o blob de destino tiver sido modificado, o Armazenamento de Blobs retornará status código 412 (Falha na pré-condição).
If-Match Opcional. Um valor ETag. Especifique um ETag valor para esse cabeçalho condicional para copiar o blob somente se o valor especificado ETag corresponder ao ETag valor de um blob de destino existente. Se os valores não corresponderem, o Armazenamento de Blobs retornará status código 412 (Falha na pré-condição).
If-None-Match Opcional. Um ETag valor ou o caractere curinga (*).

Especifique um ETag valor para esse cabeçalho condicional para copiar o blob somente se o valor especificado ETag não corresponder ao ETag valor do blob de destino.

Especifique o caractere curinga (*) para executar a operação somente se o blob de destino não existir.

Se a condição especificada não for atendida, o Armazenamento de Blobs retornará status código 412 (Falha na pré-condição).
x-ms-copy-source:name Obrigatórios. Especifica a URL do blob de origem. O valor pode ser uma URL de até 2 kibibytes (KiB) de comprimento que especifica um blob. O valor deve ser codificado em URL tal como apareceria em um pedido URI. O blob de origem deve ser público ou ser autorizado por meio de uma assinatura de acesso compartilhado. Se o blob de origem for público, nenhuma autorização será necessária para executar a operação. Se o tamanho do blob de origem for maior que 256 MiB, a solicitação falhará com um erro 409 (Conflito). O tipo de blob do blob de origem precisa ser blob de blocos. Aqui estão alguns exemplos de URLs de objeto de origem:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> Opcional. Especifica o esquema de autorização e a assinatura para a origem da cópia. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
Somente o portador do esquema tem suporte para o Azure Active Directory.
Esse cabeçalho tem suporte na versão 2020-10-02 e posterior.
x-ms-requires-sync:true Obrigatórios. Indica que essa é uma operação síncrona Copy Blob From URL em vez de uma operação assíncrona Copy Blob .
x-ms-source-content-md5 Opcional. Especifica um hash MD5 do conteúdo do blob do URI. Esse hash é usado para verificar a integridade do blob durante o transporte dos dados do URI. Quando esse cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que chegou da fonte de cópia com esse valor de cabeçalho.

O hash MD5 não é armazenado com o blob.

Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação inválida).
x-ms-lease-id:<ID> Obrigatório se o blob de destino tiver uma concessão ativa. A ID da concessão especificada para esse cabeçalho deve corresponder à ID de concessão do blob de destino. Se a solicitação não incluir a ID de concessão ou não for válida, a operação falhará com status código 412 (Falha na pré-condição).

Se esse cabeçalho for especificado e o blob de destino não tiver uma concessão ativa no momento, a operação falhará com status código 412 (Falha na pré-condição).

Na versão 2012-02-12 e posterior, esse valor deve especificar uma concessão ativa e infinita para um blob alugado. Uma ID de concessão de duração finita falha com status código 412 (Falha na pré-condição).
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres de 1 KiB que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor.
x-ms-access-tier Opcional. Especifica a camada a ser definida no blob de destino. Esse cabeçalho é para blobs de páginas em uma conta premium somente com a versão 2017-04-17 e posterior. Para obter uma lista completa de camadas com suporte, consulte Armazenamento premium de alto desempenho e discos gerenciados para VMs. Esse cabeçalho tem suporte na versão 2018-11-09 e posterior para blobs de blocos. Há suporte para camadas de blob de blocos no Armazenamento de Blobs ou contas Uso Geral v2. Os valores válidos são Hot, Cool, Cold e Archive. Nota:Cold A camada tem suporte para a versão 2021-12-02 e posterior. Para obter informações detalhadas sobre camadas de blob de blocos, consulte Camadas de armazenamento frequente, esporádico e de arquivos.

Corpo da solicitação

Nenhum.

Resposta

A resposta inclui um código de status HTTP e um conjunto de cabeçalhos de resposta.

Código de status

Uma operação bem-sucedida retorna o código de status 202 (Aceito).

Para obter informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta Descrição
ETag Se a cópia for concluída, conterá o ETag valor do blob de destino. Se a cópia não estiver concluída, conterá o ETag valor do blob vazio criado no início da cópia.

O ETag valor está entre aspas.
Last-Modified Retorna a data/hora em que a operação de cópia para o blob de destino foi concluída.
x-ms-request-id Identifica exclusivamente a solicitação que foi feita. Você pode usá-lo para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API.
x-ms-version Indica a versão do Armazenamento de Blobs usada para executar a solicitação.
Date Um valor de data/hora UTC que indica a hora em que o serviço enviou a resposta.
x-ms-copy-id: <id> Identificador de cadeia de caracteres para essa operação de cópia.
x-ms-copy-status: <success> Indica o estado da operação de cópia. Um valor de success significa que a operação foi concluída com êxito.
x-ms-client-request-id Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho, se ele estiver presente na solicitação e o valor for no máximo 1.024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.
x-ms-request-server-encrypted: true/false Defina como true se o conteúdo da solicitação for criptografado com êxito por meio do algoritmo especificado. Caso contrário, o valor é false.
x-ms-encryption-scope Retornado se a solicitação usou um escopo de criptografia, para que o cliente possa garantir que o conteúdo da solicitação seja criptografado com êxito por meio do escopo de criptografia.

Corpo da resposta

Nenhum.

Resposta de exemplo

Veja a seguir uma resposta de exemplo de uma solicitação para copiar um blob:

Response Status:  
HTTP/1.1 202 Accepted  
  
Response Headers:   
Last-Modified: <date>   
ETag: "0x8CEB669D794AFE2"  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2018-03-28  
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-copy-status: success  
Date: <date>  
  

Autorização

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. A tabela a seguir descreve como os objetos de destino e de origem de uma Copy Blob From URL operação podem ser autorizados:

Tipo de objeto autorização Microsoft Entra ID Autorização de SAS (Assinatura de Acesso Compartilhado) Autorização de chave compartilhada (ou Chave Compartilhada Lite)
Blob de blocos de destino Yes Yes Yes
Blob de bloco de origem na mesma conta de armazenamento Yes Yes Yes
Blob de bloco de origem em outra conta de armazenamento No Yes No

Se uma solicitação especificar marcas no cabeçalho da x-ms-tags solicitação, o chamador deverá atender aos requisitos de autorização da operação Definir Marcas de Blob .

Você pode autorizar a Copy Blob From URL operação, conforme descrito abaixo. Observe que um blob de origem em uma conta de armazenamento diferente deve ser autorizado separadamente por meio do token SAS com a permissão Leitura (r ). Para obter mais informações sobre a autorização do blob de origem, consulte os detalhes do cabeçalho x-ms-copy-sourceda solicitação .

O Armazenamento do Azure dá suporte ao uso de Microsoft Entra ID para autorizar solicitações para dados de blob. Com Microsoft Entra ID, você pode usar o RBAC (controle de acesso baseado em função) do Azure para conceder permissões a uma entidade de segurança. A entidade de segurança pode ser um usuário, um grupo, uma entidade de serviço de aplicativo ou uma identidade gerenciada do Azure. A entidade de segurança é autenticada por Microsoft Entra ID para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço de Blob.

Para saber mais sobre a autorização usando Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.

Permissões

Veja abaixo a ação RBAC necessária para que um usuário, grupo ou entidade de serviço Microsoft Entra chame a Copy Blob From URL operação e a função rbac interna do Azure com privilégios mínimos que inclua esta ação:

Blob de destino

Blob de origem na mesma conta de armazenamento

Para saber mais sobre como atribuir funções usando o RBAC do Azure, confira Atribuir uma função do Azure para acesso aos dados de blob.

Comentários

O blob de origem e de destino de uma Copy Blob From URL operação deve ser um blob de blocos.

Na versão 2020-10-02 e posterior, há suporte para a autorização do Azure Active Directory para a origem da operação de cópia.

A operação Copy Blob From URL sempre copia o blob de origem inteiro. Não há suporte para a cópia de um intervalo de bytes ou um conjunto de blocos.

Você pode copiar um blob de origem para um blob de destino que tenha um nome diferente. O blob de destino pode ser um blob de blocos existente ou pode ser um novo blob que a operação de cópia cria.

Quando você está copiando de um blob de blocos, todos os blocos confirmados e suas IDs de bloco são copiados. Os blocos não confirmados não são copiados. No final da operação de cópia, o blob de destino terá a mesma contagem de blocos confirmada que a origem.

O ETag valor de um blob de blocos é alterado quando a Copy Blob From URL operação é iniciada e quando a operação é concluída.

Copiar propriedades e metadados de blob

Quando um blob de blocos é copiado, as seguintes propriedades do sistema são copiadas para o blob de destino com os mesmos valores:

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-Length

  • Cache-Control

  • Content-MD5

  • Content-Disposition

A lista de blocos confirmados do blob de origem também é copiada para o blob de destino. Todos os blocos não confirmados não são copiados.

O blob de destino sempre tem o mesmo tamanho que o blob de origem, portanto, o valor do Content-Length cabeçalho do blob de destino corresponde ao valor desse cabeçalho para o blob de origem.

Se o x-ms-tags cabeçalho fornecer marcas para o blob de destino, elas deverão ser codificadas em cadeia de caracteres de consulta. As chaves de marca e os valores devem estar em conformidade com os requisitos de nomenclatura e comprimento especificados na operação Definir Marcas de Blob .

O x-ms-tags cabeçalho pode conter até 2 quilobits de marcas. Se você precisar de mais marcas, use a Set Blob Tags operação .

Se o x-ms-tags cabeçalho não fornecer marcas, as marcas não serão copiadas do blob de origem.

Copiando um blob alugado

A Copy Blob From URL operação lê apenas do blob de origem, portanto, o estado de concessão do blob de origem não importa.

Cobrança

As solicitações de preços podem ser originadas de clientes que usam APIs de Armazenamento de Blobs, diretamente por meio da API REST do Armazenamento de Blobs ou de uma biblioteca de clientes do Armazenamento do Azure. Essas solicitações acumulam encargos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura se acumulam em uma categoria de cobrança diferente das transações de gravação. A tabela a seguir mostra a categoria de cobrança para Copy Blob From URL solicitações com base no tipo de conta de armazenamento:

Operação Tipo de conta de armazenamento Categoria de cobrança
Copiar Blob da URL (conta de destino1) Blob de blocos Premium
Uso geral v2 Standard
Uso geral v1 Standard
Operações de gravação
Copiar Blob da URL (conta de origem2) Blob de blocos Premium
Uso geral v2 Standard
Uso geral v1 Standard
Operações de leitura

1A conta de destino é cobrada por uma transação para iniciar a gravação.
2A conta de origem incorre em uma transação para cada solicitação de leitura para o objeto de origem.

Para saber mais sobre os preços das categorias de cobrança especificadas, consulte Armazenamento de Blobs do Azure Preços.

Além disso, se as contas de origem e destino residirem em regiões diferentes (por exemplo, Norte dos EUA e Sul dos EUA), a largura de banda usada para transferir a solicitação será cobrada para a conta de armazenamento de origem como saída. A saída entre contas na mesma região é gratuita.

Quando você copia um blob de origem para um blob de destino que tem um nome diferente na mesma conta, você usa recursos de armazenamento adicionais para o novo blob. Em seguida, a operação de cópia resulta em uma cobrança em relação ao uso da capacidade da conta de armazenamento para esses recursos adicionais.

Confira também

Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Códigos de erro do Armazenamento de Blobs
Noções básicas sobre como os instantâneos acumulam encargos