Blob de Cópia Incremental

  • Artigo

A Incremental Copy Blob operação copia um instantâneo do blob de página de origem para um blob de página de destino. Somente as diferenças dos instantâneo copiados anteriormente são transferidas para o destino. Os instantâneos copiados são cópias completas do instantâneo original e você pode ler ou copiar deles como de costume. Essa API tem suporte desde a versão REST 2016-05-31.

Solicitação

Você pode construir a solicitação da Incremental Copy Blob seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento, mycontainer pelo nome do contêiner e myblob pelo nome do blob de destino. O comp parâmetro de consulta, com valor de incrementalcopy, indica que essa solicitação deve criar um instantâneo incremental.

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

URI do serviço de armazenamento emulado

Quando você fizer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e Armazenamento de Blobs do Azure porta de serviço como 127.0.0.1:10000, seguido pelo nome da conta de armazenamento emulada. Também indique que essa solicitação é para cópia incremental, definindo o comp parâmetro de consulta como incrementalcopy.

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

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

Parâmetros do URI

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

Parâmetro Descrição
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Configurando 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 e opcional para solicitações anônimas. Especifica a versão da operação a ser usada para esta solicitação. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento 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 o ETag para o blob de destino não corresponder ao especificado para If-Match, o ETag 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 o nome do blob de página de origem instantâneo.

Esse valor é uma URL de até 2 kibibytes (KiB) de comprimento que especifica um blob de página instantâneo. O valor deve ser codificado em URL tal como apareceria em um pedido URI. O URI do blob de origem pode ser autorizado de duas maneiras:

O URI do blob de origem pode referenciar um blob de página instantâneo, mas deve incluir um token SAS (assinatura de acesso compartilhado) que foi criado no blob base do instantâneo. O campo de recurso assinado (sr) da SAS deve ser definido como b. Por exemplo: https://<account-name>.blob.core.windows.net/<container-name>/<page-blob-name>?snapshot=2022-07-23T00:14:45.3964054Z&sp=r&st=2022-07-23T00:15:38Z&se=2022-07-23T08:15:38Z&spr=https&sv=2021-06-08&sr=b&sig=<signature>.

O URI do blob de origem pode fazer referência a um blob de página pública instantâneo; por exemplo, https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>.
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. Para obter mais informações, consulte Monitorar Armazenamento de Blobs do Azure.

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.

Sintaxe Descrição
ETag Contém um valor que você pode usar para executar operações condicionalmente. O valor está entre aspas.
Last-Modified A data e hora da última modificação do blob. Para obter mais informações, consulte Representação de valores de data/hora em cabeçalhos.

Qualquer operação de gravação no blob (incluindo atualizações nos metadados ou propriedades do blob) altera a hora da última modificação do blob.
x-ms-request-id Identifica exclusivamente a solicitação que foi feita e pode ser usada para solucionar problemas da solicitação. Para obter mais informações, consulte Solução de 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 a resposta foi iniciada. O serviço gera esse valor.
x-ms-copy-id: <id> O identificador de cadeia de caracteres para esta operação de cópia. Use com Get Blob Properties para marcar o status desta operação de cópia ou passe para Abort Copy Blob para interromper uma cópia pendente.
x-ms-copy-status: pending O estado da operação de cópia. Isso está sempre pendente, para indicar que a cópia foi iniciada e está em andamento.
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. O valor é 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, ele não estará presente na resposta.

Corpo da resposta

Nenhum.

Resposta de exemplo

Veja a seguir uma resposta de exemplo para uma solicitação para executar uma cópia incremental:

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: 2016-05-31
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-copy-status: pending
Date: <date>

Autorização

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. A seção a seguir descreve como o objeto de destino da Incremental Copy Blob operação pode ser autorizado. O acesso ao blob ou arquivo de origem é autorizado separadamente, conforme descrito nos detalhes do cabeçalho da solicitação x-ms-copy-source .

Importante

A Microsoft recomenda usar Microsoft Entra ID com identidades gerenciadas para autorizar solicitações ao Armazenamento do Azure. Microsoft Entra ID fornece segurança superior e facilidade de uso em comparação com a autorização de Chave Compartilhada.

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, grupo, entidade de serviço de aplicativo ou 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 um usuário Microsoft Entra, grupo, identidade gerenciada ou entidade de serviço para chamar a Incremental Copy Blob operação e a função RBAC interna do Azure com menos privilégios que inclui esta ação:

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 destino de uma cópia incremental não deve existir ou deve ter sido criado com uma cópia incremental anterior do mesmo blob de origem. Depois de criá-lo, o blob de destino é permanentemente associado à origem e só pode ser usado para cópias incrementais. As Get Blob Properties APIs e List Blobs indicam se o blob é um blob de cópia incremental criado dessa forma.

Você não pode baixar diretamente blobs de cópia incrementais. As únicas operações com suporte são Get Blob Properties, Incremental Copy Blobe Delete Blob. Você pode ler e excluir os instantâneos copiados como de costume.

Você executa uma cópia incremental de forma assíncrona no serviço e deve sondar para conclusão. Consulte a Copy Blob API para obter detalhes sobre como sondar uma cópia pendente. Quando a cópia for concluída, o blob de destino conterá uma nova instantâneo. A Get Blob Properties API retorna a instantâneo hora do instantâneo recém-criado.

Na primeira vez que você executa uma cópia incremental em um blob de destino, um novo blob é criado, com um instantâneo totalmente copiado da origem. Cada chamada subsequente para Incremental Copy Blob criar um novo instantâneo, copiando apenas as alterações diferenciais do instantâneo copiado anteriormente.

As alterações diferenciais são computadas no servidor emitindo uma Get Page Ranges chamada no blob de origem instantâneo. Defina prevsnapshot como o instantâneo copiado mais recentemente. Portanto, as mesmas restrições em Get Page Ranges se aplicam a Incremental Copy Blob. Especificamente, você deve copiar instantâneos em ordem crescente e, se o blob de origem for recriado usando Put Blob ou Copy Blob, Incremental Copy Blob os novos instantâneos falharão.

O espaço de armazenamento adicional consumido pelo instantâneo copiado é o tamanho dos dados diferenciais transferidos durante a cópia. Você pode determinar esse tamanho executando uma chamada à API diferencial Get Page Ranges no instantâneo para compará-la com o instantâneo anterior.

Confira também

Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Definindo tempos limite para operações de Armazenamento de Blobs