Colocar Página da URL

A Put Page From URL operação grava um intervalo de páginas em um blob de páginas em que o conteúdo é lido de uma URL. Essa API está disponível a partir da versão 2018-11-09.

Solicitação

Você pode construir a solicitação da Put Page From URL seguinte maneira. Recomendamos que você use HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento:

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

URI de serviço de armazenamento emulado

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

URI de solicitação do método PUT Versão HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page 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 do serviço Blob.

Cabeçalhos da solicitação

Os cabeçalhos de solicitação obrigatórios e opcionais são descritos na tabela a seguir:

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. 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.
Range Range or x-ms-range is required.

Especifica o intervalo de bytes a ser gravado como uma página. É necessário especificar o início e o fim do intervalo. Esse cabeçalho é definido pela especificação de protocolo HTTP/1.1.

Para uma operação de atualização de página, o intervalo de páginas pode ter até 4 MiB de tamanho.

Como as páginas devem ser alinhadas com limites de 512 bytes, o deslocamento inicial deve ser um módulo de 512 e o deslocamento final deve ser um módulo de 512 – 1. Exemplos de intervalos de bytes válidos são 0-511, 512-1023 e assim por diante.

O serviço Blob aceita apenas um intervalo de byte único para o cabeçalho Range e o intervalo de bytes deve ser especificado no seguinte formato: bytes=startByte-endByte.

Se Range e x-ms-range forem especificados, o serviço usará o valor de x-ms-range. Para obter mais informações, consulte Especificar o cabeçalho de intervalo para operações do serviço Blob.
x-ms-range Range or x-ms-range is required.

Especifica o intervalo de bytes a ser gravado como uma página. É necessário especificar o início e o fim do intervalo. Esse cabeçalho é definido pela especificação de protocolo HTTP/1.1.

O intervalo de páginas pode ter até 4 MiB de tamanho.

Como as páginas devem ser alinhadas com limites de 512 bytes, o deslocamento inicial deve ser um módulo de 512 e o deslocamento final deve ser um módulo de 512 – 1. Exemplos de intervalos de bytes válidos são 0-511, 512-1023 e assim por diante.

O serviço Blob aceita apenas um intervalo de byte único para o cabeçalho x-ms-range e o intervalo de bytes deve ser especificado no seguinte formato: bytes=startByte-endByte.

Se Range e x-ms-range forem especificados, o serviço usará o valor de x-ms-range. Para obter mais informações, consulte Especificar o cabeçalho de intervalo para operações do serviço Blob.
Content-Length Obrigatórios. Especifica o número de bytes que estão sendo transmitidos no corpo da solicitação. O valor desse cabeçalho deve ser definido como zero. Quando o comprimento não for zero, a operação falhará com o código status 400 (Solicitação Incorreta).
x-ms-copy-source:name Obrigatórios. Especifica a URL do blob de origem. O valor pode ser uma URL de até 2 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 deve 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. 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.
Há suporte apenas para um portador de esquema no Azure Active Directory.
Esse cabeçalho tem suporte na versão 2020-10-02 e posterior.
x-ms-source-range Carrega os bytes do blob na URL de origem no intervalo especificado. É necessário especificar o início e o fim do intervalo. Esse cabeçalho é definido pela especificação de protocolo HTTP/1.1.

O intervalo de páginas pode ter até 4 MiB de tamanho.

O serviço Blob aceita apenas um intervalo de byte único para o cabeçalho x-ms-source-range e o intervalo de bytes deve ser especificado no seguinte formato: bytes=startByte-endByte.

Consulte Especificar o cabeçalho de intervalo para operações do serviço Blob para obter mais informações.
x-ms-source-content-md5 Opcional. Um hash MD5 do conteúdo da página do URI. Esse hash é usado para verificar a integridade da página 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.

Observação: esse 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-source-content-crc64 Opcional. Um hash CRC64 do conteúdo da página do URI. Esse hash é usado para verificar a integridade da página 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.

Observação: esse hash CRC64 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).

Se os x-ms-source-content-md5 cabeçalhos e x-ms-source-content-crc64 estiverem presentes, a solicitação falhará com um 400 (Solicitação Incorreta).

Esse cabeçalho tem suporte na versão 2019-02-02 e posterior.
x-ms-lease-id:<ID> Obrigatório se o blob tiver uma concessão ativa. Para executar essa operação em um blob com uma concessão ativa, especifique a ID de concessão válida para esse cabeçalho.
x-ms-if-sequence-number-le: <num> Opcional. Se o número de sequência do blob for menor ou igual ao valor especificado, a solicitação continuará. Caso contrário, ele falhará com o erro SequenceNumberConditionNotMet (HTTP status código 412 – Falha na pré-condição).
x-ms-if-sequence-number-lt: <num> Opcional. Se o número de sequência do blob for menor que o valor especificado, a solicitação continuará. Caso contrário, ele falhará com o erro SequenceNumberConditionNotMet (HTTP status código 412 – Falha na pré-condição).
x-ms-if-sequence-number-eq: <num> Opcional. Se o número de sequência do blob for igual ao valor especificado, a solicitação continuará. Caso contrário, ele falhará com o erro SequenceNumberConditionNotMet (HTTP status código 412 – Falha na pré-condição).
If-Modified-Since Opcional. Um valor DateTime. Especifique esse cabeçalho condicional para gravar a página somente se o blob tiver sido modificado desde a data/hora especificada. Se o blob não tiver sido modificado, o serviço Blob retornará status código 412 (Falha na pré-condição).
If-Unmodified-Since Opcional. Um valor DateTime. Especifique esse cabeçalho condicional para gravar a página somente se o blob não tiver sido modificado desde a data/hora especificada. Se o blob tiver sido modificado, o serviço Blob retornará o código de status 412 (Falha na Precondição).
If-Match Opcional. Um valor de ETag. Especifique um valor ETag para esse cabeçalho condicional para gravar a página somente se o valor ETag do blob corresponder ao valor especificado. Se os valores não corresponderem, o serviço Blob retornará status código 412 (Falha na pré-condição).
If-None-Match Opcional. Um valor de ETag.

Especifique um valor ETag para esse cabeçalho condicional gravar a página somente se o valor ETag do blob 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 de origem. Esse cabeçalho tem suporte na versão 2019-02-02 e posterior.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres KiB (1 kibibyte) 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.

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, consulte 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 criptografado com uma chave fornecida pelo cliente. A criptografia com uma chave fornecida pelo cliente (e o conjunto correspondente de cabeçalhos) é opcional.

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

O corpo da solicitação contém o conteúdo da página.

Solicitação de exemplo

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:   
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT  
x-ms-version: 2018-11-09  
x-ms-range: bytes=0-65535  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0  
  

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 mais 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 padrão HTTP adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Sintaxe Descrição
ETag A ETag do blob. Se a versão da solicitação for 2011-08-18 e posterior, o valor ETag será colocado entre aspas. É possível usar ETag para executar uma operação condicional Put Page From URL especificando seu valor para o cabeçalho de solicitação If-Match ou If-None-Match.
Last-Modified A data e hora da última modificação do blob. O formato da data segue RFC 1123. Para obter mais informações, consulte Representar valores de data/hora em cabeçalhos.

Qualquer operação de gravação no blob, incluindo atualizações nos metadados ou nas propriedades do blob, altera a hora da última modificação do blob.
Content-MD5 Retornado para que o cliente possa marcar para integridade do conteúdo da mensagem. O valor desse cabeçalho é calculado pelo serviço Blob. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos de solicitação. Para a versão 2019-02-02 ou posterior, esse cabeçalho é retornado somente quando a solicitação tem esse cabeçalho.
x-ms-content-crc64 Para a versão 2019-02-02 ou posterior. Retornado para que o cliente possa marcar para integridade do conteúdo da mensagem. O valor desse cabeçalho é calculado pelo serviço Blob. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos de solicitação.

Esse cabeçalho é retornado quando x-ms-source-content-md5 o cabeçalho não está presente na solicitação.
x-ms-blob-sequence-number O número de sequência atual do blob da página.
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 Solucionar problemas de operações de API.
x-ms-version Indica a versão do serviço Blob que foi usada para executar a solicitação. Esse cabeçalho é retornado para solicitações que foram feitas na versão 2009-09-19 e posterior.
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 2015-12-11 e posterior. O valor desse cabeçalho será definido true como se o conteúdo da solicitação for criptografado com êxito usando o algoritmo especificado e false , caso contrário, .
x-ms-encryption-key-sha256 Versão 2019-02-02 e posterior. Retornado se a solicitação usou 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 e posterior. 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 usando o escopo de criptografia.
x-ms-client-request-id 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 não contiver mais de 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

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT  
x-ms-version: 2011-08-18  
x-ms-blob-sequence-number: 0  
Content-Length: 0  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
  

Autorização

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. Você pode autorizar a Put Page From URL operação, conforme descrito abaixo.

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 que um usuário, grupo ou entidade de serviço Microsoft Entra chame a Put Page From URL operação e a função rbac interna do Azure com privilégios mínimos que inclua 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

A operação Put Page From URL grava um intervalo de páginas em um blob de páginas. Essa operação só pode ser chamada em um blob de páginas existente. Ele não pode ser chamado para criar um novo blob de páginas, nem pode ser chamado em um blob de blocos. Chamar Put Page From URL com um nome de blob que não existe atualmente retorna o erro BlobNotFound (HTTP status código 404 – Não Encontrado).

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.

Para criar um novo blob de páginas, chame Colocar Blob e especifique o tipo de blob a ser criado como um blob de páginas. Um blob de páginas pode ter até 8 TiB de tamanho.

Se o blob tiver uma concessão ativa, o cliente deverá especificar uma ID de concessão válida na solicitação para gravar uma página.

Operações de atualização de página

Chamar Put Page From URL executa uma gravação in-loco no blob de páginas especificado. Todo o conteúdo na página especificada é substituído pela atualização.

Importante

Se o servidor atingir o tempo limite ou sua conexão estiver fechada durante um Put Page From URL, a página poderá ou não ter sido atualizada. Por isso, você deverá continuar repetindo a atualização até receber uma resposta que indique êxito.

Cada intervalo de páginas enviadas com Put Page From URL para uma operação de atualização pode ter até 4 MiB de tamanho. O intervalo de início e término da página deverá ser alinhado com limites de 512 bytes. Se você tentar carregar um intervalo de páginas com mais de 4 MiB, o serviço retornará status código 413 (Entidade de Solicitação Muito Grande).

Gerenciar problemas de simultaneidade

O serviço Blob lida com gravações simultâneas em páginas sobrepostas sequencialmente. Ou seja, a última página processada pelo serviço determina o conteúdo do blob. Assim, para assegurar a integridade do conteúdo do blob, o cliente deverá tratar gravações em páginas sobrepostas usando uma ou mais das seguintes abordagens:

  • Você pode verificar o valor do cabeçalho de resposta Last-Modified para cada chamada bem-sucedida para Put Page From URL. A ordem das respostas retornadas do serviço Blob não corresponde necessariamente à ordem em que foram executadas pelo serviço. Porém, o valor de Last-Modified sempre indica a ordem na qual o serviço processou as solicitações.

  • Você pode executar atualizações condicionalmente com base no ETag do blob ou na hora da última modificação usando a simultaneidade otimista. Essa abordagem funcionará bem se o número de gravações simultâneas for relativamente baixo. Use os cabeçalhos de solicitação condicional If-Match, If-None-Match, If-Modified-Since e If-Unmodified-Since para essa finalidade.

  • Você pode chamar o Blob de Concessão para bloquear o blob em relação a outras gravações por um período de um minuto ou mais se a concessão for renovada.

  • Você pode usar o número de sequência do blob para garantir que repetir uma solicitação para a qual não houve resposta não resulte em atualizações simultâneas. Essa abordagem poderá ser melhor para os clientes que exijam alta taxa de transferência para gravações de página. ele é descrito em detalhes na seção a seguir.

Usar o número de sequência de blob de páginas para repetir solicitações

Quando uma chamada para Put Page From URL atinge o tempo limite ou não retorna uma resposta, não há como saber com certeza se a solicitação foi bem-sucedida. Portanto, você precisa repetir a solicitação, mas devido à natureza distribuída dos serviços de armazenamento do Azure, é possível que a solicitação original seja processada após a solicitação repetida ter sido bem-sucedida. A solicitação original atrasada poderá substituir outras atualizações e gerar um resultado inesperado. A sequência a seguir ilustra como isso pode acontecer:

  1. Uma Put Page From URL solicitação para gravar o valor "X" na página 0 atinge o tempo limite ou não retorna uma resposta.

  2. Uma solicitação repetida para gravar o valor "X" na página 0 é bem-sucedida.

  3. Uma solicitação para gravar o valor "Y" na página 0 é bem-sucedida.

  4. A solicitação original é bem-sucedida, gravando o valor "X" na página 0.

  5. A leitura da página 0 retorna o valor "X", quando o cliente estava esperando o valor "Y" nesse momento.

Esse tipo de conflito pode ocorrer quando a solicitação original não retorna um código status entre 100 e 499 ou 503 (Servidor Ocupado). Se um desses códigos de status for retornado, você poderá ter certeza se a solicitação foi bem-sucedida ou falhou. Porém, se o serviço retornar um código de status fora desse intervalo, não haverá como saber o status da solicitação original.

Para evitar esse tipo de conflito, você pode usar o número de sequência do blob de páginas para garantir que, quando você tentar novamente uma solicitação, a solicitação original não terá êxito posteriormente. Para fazer isso, você deve incrementar o número de sequência antes de repetir a solicitação original. Em seguida, você pode usar os cabeçalhos de número de sequência condicional para garantir que a solicitação falhe se o número de sequência não corresponder ao número de sequência esperado. A sequência a seguir mostra essa abordagem:

  1. O cliente cria um blob de páginas com Put Blob e define seu número de sequência como 0.

  2. Uma Put Page From URL solicitação para gravar o valor "X" na página 0 com o if-sequence-number-lt cabeçalho definido como 1 atinge o tempo limite ou não retorna uma resposta.

  3. O cliente chama Definir Propriedades de Blob para atualizar o número de sequência para 1.

  4. Uma solicitação repetida para gravar o valor "X" na página 0 com definido como if-sequence-number-lt2 bem-sucedido.

  5. Uma solicitação para gravar o valor "Y" na página 0 com definido como if-sequence-number-lt2 bem-sucedido.

  6. A solicitação original é finalmente processada, mas falha porque especifica a condição de que o número de sequência deve ser menor que 1 (ou seja, o if-sequence-num-lt cabeçalho está definido 1como ). O erro é SequenceNumberConditionNotMet (código de status HTTP 412 – Falha na Precondição).

  7. A leitura da página 0 retorna o valor esperado de "Y".

Confira também

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