Blob de instantâneo

A operação Snapshot Blob cria um instantâneo somente leitura de um blob.

Solicitação

A solicitação Snapshot Blob pode ser criada da seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento:

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

URI de serviço de armazenamento emulado

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

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

Para obter mais informações, consulte Usando o Armazenamento Emulator do Azure para Desenvolvimento e Teste.

Parâmetros de URI

Os seguintes parâmetros adicionais podem ser especificados 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 serviço blob.

Cabeçalhos de 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 obter mais informações, consulte Autorizar solicitações ao Armazenamento do Azure.
Date ou x-ms-date Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para obter mais informações, consulte Autorizar solicitações ao Armazenamento do Azure.
x-ms-version Necessário para todas as solicitações autorizadas. 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.
x-ms-meta-name:value Opcional. Especifica um par de nome-valor definido pelo usuário associado ao blob. Se nenhum par de nome-valor for especificado, a operação copiará os metadados do blob de base no instantâneo. Se um ou mais pares de nome-valor forem especificados, o instantâneo será criado com os metadados especificados, e os metadados não serão copiados do blob de base.

Observe que, a partir da versão 2009-09-19, os nomes de metadados devem aderir às regras de nomenclatura para identificadores C#. Consulte Contêineres de Nomenclatura e Referência, Blobs e Metadados para obter mais informações.
If-Modified-Since Opcional. Um valor DateTime. Especifique esse cabeçalho condicional para obter um instantâneo do blob somente se o blob tiver sido modificado desde a data/hora especificada. Se o blob de base não tiver sido modificado, o serviço Blob retornará o código de status 412 (Falha na Pré-condição).
If-Unmodified-Since Opcional. Um valor DateTime. Especifique esse cabeçalho condicional para obter um instantâneo do blob somente se o blob não tiver sido modificado desde a data/hora especificada. Se o blob de base tiver sido modificado, o serviço Blob retornará o código de status 412 (Falha na Pré-condição).
If-Match Opcional. Um valor de ETag. Especifique um valor ETag para esse cabeçalho condicional obter um instantâneo do blob somente se o seu valor ETag corresponder ao valor especificado. Se os valores não coincidirem, o serviço Blob retornará o código de status 412 (Falha na Pré-condição).
If-None-Match Opcional. Um valor de ETag.

Especifique um valor ETag para esse cabeçalho condicional para obter um instantâneo do blob somente se o seu valor ETag não corresponder ao valor especificado. Se os valores forem idênticos, o serviço Blob retornará o código de status 412 (Falha na Pré-condição).
x-ms-encryption-scope Opcional. Indica o escopo de criptografia a ser usado para criptografar o conteúdo da solicitação. Esse cabeçalho tem suporte nas versões 2019-02-02 ou posterior.
x-ms-lease-id:<ID> Opcional. Se esse cabeçalho for especificado, a operação será executada apenas se as seguintes condições forem atendidas:

- A concessão do blob está ativa no momento.
- A ID de concessão especificada na solicitação corresponde à do blob.

Se esse cabeçalho for especificado e nenhuma dessas condições for atendida, a solicitação não será feita e ocorrerá uma falha na operação Snapshot Blob com o código de status 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 de análise quando o log de análise de armazenamento está habilitado. O uso desse cabeçalho é altamente recomendável para correlacionar as atividades do lado do cliente com as solicitações recebidas pelo servidor. Para obter mais informações, consulte Sobre Análise de Armazenamento registro em log e log do Azure: usando logs para acompanhar solicitações de Armazenamento.

Essa operação também oferece suporte ao uso de cabeçalhos condicionais para executar a operação somente se uma determinada condição for atendida. Para obter mais informações, confira Como especificar cabeçalhos condicionais para operações de serviço Blob.

Cabeçalhos de solicitação (chaves de criptografia fornecidas pelo cliente)

A partir da versão 2019-02-02, os cabeçalhos a seguir podem ser especificados na solicitação para criptografar um blob com uma chave fornecida pelo cliente. A criptografia com uma chave fornecida pelo cliente (e o conjunto correspondente de cabeçalhos) é opcional. Se um blob tiver sido criptografado anteriormente com uma chave fornecida pelo cliente, esses cabeçalhos deverão ser incluídos na solicitação para concluir a operação de leitura com êxito.

Cabeçalho da solicitação Descrição
x-ms-encryption-key Obrigatórios. A chave de criptografia AES-256 codificada em Base64.
x-ms-encryption-key-sha256 Obrigatórios. O hash SHA256 codificado em Base64 da chave de criptografia.
x-ms-encryption-algorithm: AES256 Obrigatórios. Especifica o algoritmo a ser usado para criptografia. O valor deste cabeçalho deve ser AES256.

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 201 (Criado).

Para obter informações sobre códigos de status, consulte Status e Códigos 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 padrão HTTP adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação de protocolo HTTP/1.1.

Sintaxe Descrição
x-ms-snapshot: <DateTime> Esse cabeçalho retorna um valor DateTime que identifica o instantâneo de forma exclusiva. O valor desse cabeçalho indica a versão do instantâneo e pode ser usado em solicitações subsequentes para acessar o instantâneo. Observe que esse valor é opaco.
ETag A ETag do instantâneo. Se a versão da solicitação for a 2011-08-18 ou mais recente, o valor de ETag será exibido entre aspas. Observe que um instantâneo não pode ser gravado, portanto, a ETag de um instantâneo específico nunca será alterado. No entanto, a ETag do instantâneo diferirá da do blob de base se novos metadados tiverem sido fornecidos à solicitação Snaphot Blob. Se não forem especificados metadados com a solicitação, a ETag do instantâneo será idêntica à do blob de base no momento em que o instantâneo foi obtido.
Last-Modified A hora da última modificação do instantâneo. O formato da data segue RFC 1123. Para obter mais informações, consulte Representação de valores de Date-Time em cabeçalhos.

Observe que um instantâneo não pode ser gravado, portanto, a hora da última modificação um instantâneo específico nunca será alterada. No entanto, a hora da última modificação do instantâneo diferirá da do blob de base se novos metadados tiverem sido fornecidos à solicitação Snaphot Blob. Se não forem especificados metadados com a solicitação, a hora da última modificação do instantâneo será idêntica à do blob de base no momento em que o instantâneo foi obtido.
x-ms-request-id Esse cabeçalho identifica a solicitação que foi feita de forma exclusiva e pode ser usado para solucionar problemas na 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 serviço Blob usado para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente.
Date Um valor de data/hora UTC gerado pelo serviço que indica a hora em que a resposta foi iniciada.
x-ms-request-server-encrypted: true/false Versão 2019-02-02 ou mais recente. O valor desse cabeçalho será definido para true se o conteúdo da solicitação for criptografado com êxito usando o algoritmo especificado e false de outra forma.
x-ms-encryption-key-sha256 Versão 2019-02-02 ou mais recente. Esse cabeçalho será retornado se a solicitação tiver usado uma chave fornecida pelo cliente para criptografia, para que o cliente possa garantir que o conteúdo da solicitação seja criptografado com êxito usando a chave fornecida.
x-ms-encryption-scope Versão 2019-02-02 ou mais recente. Esse cabeçalho será retornado se a solicitação tiver usado um escopo de criptografia, para que o cliente possa garantir que o conteúdo da solicitação seja criptografado com êxito usando o escopo de criptografia.
x-ms-version-id: <DateTime> Versão 2019-12-12 e mais recente. Esse cabeçalho retorna um valor datetime opaco que identifica exclusivamente o blob. O valor desse cabeçalho indica a versão do blob e pode ser usado em solicitações subsequentes para acessar o blob.
x-ms-client-request-id Esse cabeçalho pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho será igual ao valor do x-ms-client-request-id cabeçalho se ele estiver presente na solicitação e o valor estiver no máximo 1024 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.

Corpo da resposta

Nenhum.

Autorização

Somente o proprietário da conta pode chamar essa operação.

Comentários

Os instantâneos fornecem versões somente leitura de blobs. Quando um instantâneo tiver sido criado, ele pode ser lido, copiado ou excluído, mas não modificado.

Um instantâneo proporciona um modo conveniente de fazer backup de dados de blob. Você pode usar um instantâneo para restaurar um blob para uma versão anterior chamando Copiar Blob para substituir um blob base com seu instantâneo.

Quando você cria um instantâneo, o serviço Blob retorna um valor DateTime que identifica, de forma exclusiva, o instantâneo em relação a seu blob de base. Esse valor pode ser usado para executar operações adicionais no instantâneo. Observe que você deve tratar esse valor DateTime como opaco.

O valor DateTime identifica o instantâneo no URI. Por exemplo, um blob de base e seus instantâneos têm URIs semelhantes ao seguinte:

  • Blob de base:http://myaccount.blob.core.windows.net/mycontainer/myblob

  • Instantâneo:http://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>

Observe que sempre que você chama a operação Snapshot Blob, um novo instantâneo é criado, com um valor DateTime exclusivo. Um blob pode dar suporte a qualquer quantidade de instantâneos. Os instantâneos existentes nunca são substituídos, mas devem ser excluídos explicitamente chamando o Blob de Exclusão e definindo o x-ms-include-snapshots cabeçalho como o valor apropriado.

Lendo, copiando e excluindo instantâneos

Uma chamada bem-sucedida para Snapshot Blob retorna um valor DateTime no cabeçalho de resposta x-ms-snapshot. Você pode usar esse valor DateTime para executar operações de leitura, exclusão ou cópia em uma versão de instantâneo específica. Qualquer operação de serviço Blob que seja válida para um instantâneo pode ser chamada especificando ?snapshot=<DateTime> depois do nome do blob.

Copiando propriedades e metadados de blob

Quando você cria um instantâneo de um blob, as propriedades do sistema a seguir são copiadas no instantâneo com os mesmos valores:

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-Length

  • Cache-Control

  • Content-MD5

  • x-ms-blob-sequence-number (for page blobs only)

  • x-ms-blob-committed-block-count (for append blobs only)

  • x-ms-copy-id (versão 2012-02-12 e mais recente)

  • x-ms-copy-status (versão 2012-02-12 e mais recente)

  • x-ms-copy-source (versão 2012-02-12 e mais recente)

  • x-ms-copy-progress (versão 2012-02-12 e mais recente)

  • x-ms-copy-completion-time (versão 2012-02-12 e mais recente)

  • x-ms-copy-status-description (versão 2012-02-12 e mais recente)

A lista de blocos confirmados do blob de base também será copiada no instantâneo, se o blob for de blocos. Todos os blocos não confirmados não são copiados.

O blob de instantâneo é sempre do mesmo tamanho que o blob de base no momento em que o instantâneo é criado, portanto, o valor do cabeçalho Content-Length para o blob do instantâneo será equivalente ao valor do blob de base.

Você pode especificar um ou mais novos valores de metadados para o instantâneo especificando o cabeçalho x-ms-meta-name:value na solicitação. Se esse cabeçalho não for especificado, os metadados associados ao blob de base serão copiados no instantâneo.

Todas as marcas associadas ao blob base são copiadas para o instantâneo. Não é possível definir novos valores de marca para o instantâneo.

Especificando cabeçalhos condicionais

Você poderá especificar cabeçalhos condicionais na solicitação para obter um instantâneo do blob somente se a condição for atendida. Se a condição especificada não for atendida, o instantâneo não será criado, e o serviço Blob retornará o código de status 412 (Falha na Pré-condição), juntamente com informações adicionais sobre o erro relativas à condição não atendida.

Criando um instantâneo de um blob concedido

Se o blob de base tiver uma concessão ativa, você poderá obter um instantâneo do blob desde que as seguintes condições sejam verdadeiras para a solicitação:

  • O cabeçalho condicional x-ms-lease-id está especificado, e a ID da concessão ativa para o blob de base está incluída na solicitação. Essa condição especifica que o instantâneo seja criado apenas se a concessão estiver ativa e a ID de concessão especificada corresponder à associada ao blob.

  • O cabeçalho x-ms-lease-id não está especificado, caso em que a concessão de gravação exclusiva é ignorada.

Observe que uma concessão associada ao blob básico não é copiada no instantâneo. Os instantâneos não podem ser concedidos.

Copiando instantâneos

Quando um blob base é copiado usando a operação Copiar Blob , todos os instantâneos do blob base não são copiados para o blob de destino. Quando um blob de destino é substituído por uma cópia, todos os instantâneos associados ao blob de destino permanecem intactos sob o seu nome.

Você pode copiar um blob de instantâneo sobre o blob de base para restaurar uma versão anterior de um blob. O instantâneo permanece, mas o blob de base é substituído por uma cópia que pode ser lida e gravada.

Observação

Promover um instantâneo não incorre em uma cobrança adicional para recursos de armazenamento, pois blocos ou páginas são compartilhados entre o instantâneo e o blob base.
A configuração de uma camada de blob em um instantâneo é permitida iniciando a versão REST 2019-12-12. Se uma camada for definida em um blob raiz, todos os instantâneos herdarão a camada do blob base. A captura de um instantâneo em um blob arquivado falhará. Definir explicitamente a camada em um objeto resultará na cobrança do tamanho total do objeto. Tirar um instantâneo de um blob que tem conjunto de camadas resultaria na cobrança de cópia completa do blob raiz e do instantâneo. Para obter informações detalhadas sobre camadas de nível de blob de blocos, consulte camadas de armazenamento frequentes, esporádicas e arquivadas.

Instantâneos nas contas de Armazenamento Premium

Há algumas diferenças entre contas de Armazenamento Premium do Azure e as contas de armazenamento padrão em termos de instantâneos:

  • O número de instantâneos por blob de página em uma conta de Armazenamento Premium é limitado a 100. Se esse limite for excedido, a operação retornará o Snapshot Blob código de erro 409 (SnapshotCountExceeded).

  • Um instantâneo de um blob de página em uma conta de Armazenamento Premium pode ser retirado uma vez a cada dez minutos. Se essa taxa for excedida, a operação do Snapshot Blob retorna o código de erro 409 (SnaphotOperationRateExceeded).

  • Não há suporte para a leitura de um instantâneo de um blob de página em uma conta de Armazenamento Premium por meio do Get Blob. Chamar Get Blob em um instantâneo em uma conta de Armazenamento Premium retornará o código de erro 400 (Operação Inválida). No entanto, há suporte para chamar Obter Propriedades do Blob e Obter Metadados de Blob em um instantâneo.

    Para ler um instantâneo, você pode usar a operação Copiar Blob para copiar um instantâneo para outro blob de página na conta. O blob de destino da operação de cópia não deve ter todos os instantâneos existentes. Se o blob de destino tiver instantâneos, Copy Blob retornará o código de erro 409 (SnapshotsPresent).

Para obter mais informações sobre como chamar operações REST em recursos de Armazenamento Premium do Azure, consulte Como usar operações de serviço de blob com Armazenamento Premium do Azure.

Instantâneos com controle de versão habilitado

Quando o controle de versão está habilitado, a criação de um instantâneo de um blob também gera uma nova versão e salva a versão anterior do blob base. O x-ms-version-id parâmetro retorna um valor datetime opaco para a nova versão do blob.

Confira também

Criando um instantâneo de um Blob
Autorizar solicitações ao Azure Armazenamento
Status e códigos de erro
Códigos de erro do serviço Blob