Blob de Cópia Incremental
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:
- Ação RBAC do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write (para gravar em um blob existente) ou Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action (para gravar um novo blob no destino)
- Função interna com privilégios mínimos:Colaborador de Dados do Blob 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 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 Blob
e 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