Partilhar via


Colocar Página

A Put Page operação escreve um intervalo de páginas num blob de páginas.

Pedir

Pode construir o pedido da Put Page seguinte forma. Recomendamos que utilize HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento:

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

Pedido de serviço de armazenamento emulado

Quando estiver a fazer um pedido relativamente ao serviço de armazenamento emulado, especifique o nome do anfitrião do emulador e a porta do serviço Blob como 127.0.0.1:10000, seguido do nome da conta de armazenamento emulada:

URI do pedido 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, veja Utilizar o emulador do Azurite para o desenvolvimento local do Armazenamento do Azure.

Parâmetros do URI

Pode especificar os seguintes parâmetros adicionais no URI do pedido:

Parâmetro Description
timeout Opcional. O timeout parâmetro é expresso em segundos. Para obter mais informações, veja Set time-outs for Blob service operations (Definir tempos limite para operações do serviço Blob).

Cabeçalhos do pedido

Os cabeçalhos de pedido obrigatórios e opcionais estão descritos na tabela seguinte:

Cabeçalho do pedido Description
Authorization Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
Date ou x-ms-date Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
x-ms-version Necessário para todos os pedidos autorizados. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
Range x-ms-range Ou Range é necessário.

Especifica o intervalo de bytes a escrever como uma página. O início e o fim do intervalo têm de ser especificados. Este cabeçalho é definido pela especificação do protocolo HTTP/1.1.

Para uma operação de atualização de páginas , o intervalo de páginas pode ter até 4 MiB. Para uma operação de limpar páginas , o intervalo de páginas pode ser tão grande quanto o valor do tamanho total do blob.

Uma vez que as páginas têm de estar alinhadas com limites de 512 bytes, o desvio inicial tem de ser um módulo de 512 e o desvio final tem de ser um módulo de 512 –1. Os exemplos de intervalos de bytes válidos são 0-511, 512-1023, etc.

O Armazenamento de Blobs aceita apenas um intervalo de bytes único para o Range cabeçalho e o intervalo de bytes tem de ser especificado no seguinte formato: bytes=startByte-endByte.

Se e Rangex-ms-range forem especificados, o serviço utiliza o valor de x-ms-range. Para obter mais informações, veja Especificar o cabeçalho de intervalo para operações do serviço Blob.
x-ms-range x-ms-range Ou Range é necessário.

Especifica o intervalo de bytes a escrever como uma página. O início e o fim do intervalo têm de ser especificados. Este cabeçalho é definido pela especificação do protocolo HTTP/1.1.

Para uma operação de atualização de páginas, o intervalo de páginas pode ter um tamanho tão grande como 4 MiB. Para uma operação de limpeza de páginas, o intervalo de páginas pode ser até ao valor do tamanho total do blob.

Uma vez que as páginas têm de estar alinhadas com limites de 512 bytes, o desvio inicial tem de ser um módulo de 512 e o desvio final tem de ser um módulo de 512 – 1. Exemplos de intervalos de bytes válidos são 0-511, 512-1023, etc.

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

Se e Rangex-ms-range forem especificados, o serviço utiliza o valor de x-ms-range. Veja Especificar o cabeçalho do intervalo para operações do serviço Blob para obter mais informações.
Content-Length Obrigatório. Especifica o número de bytes que estão a ser transmitidos no corpo do pedido. Quando o x-ms-page-write cabeçalho está definido como clear, o valor deste cabeçalho tem de ser definido como 0.
Content-MD5 Opcional. Um Hash MD5 do conteúdo da página. Este Hash é utilizado para verificar a integridade da página durante o transporte. Quando este cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que chegou com este valor do cabeçalho.
<br / >Nota: este hash MD5 não está armazenado com o blob.

Se os dois hashes não corresponderem, a operação falha com o código de erro 400 (Pedido Incorreto).
x-ms-content-crc64 Opcional. Um Hash CRC64 do conteúdo da página. Este Hash é utilizado para verificar a integridade da página durante o transporte. Quando este cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que chegou com este valor do cabeçalho.

Nota: este hash CRC64 não está armazenado com o blob.

Se os dois hashes não corresponderem, a operação falha com o código de erro 400 (Pedido Incorreto).

Se os Content-MD5 cabeçalhos e x-ms-content-crc64 estiverem presentes, o pedido falha com um 400 (Pedido Incorreto).

Este cabeçalho é suportado na versão 2019-02-02 e posterior.
x-ms-page-write: {update ¦ clear} Obrigatório. Pode especificar uma das seguintes opções:

- Update: escreve os bytes especificados pelo corpo do pedido no intervalo especificado. Os Range cabeçalhos e Content-Length têm de corresponder para efetuar a atualização.
- Clear: limpa o intervalo especificado e liberta o espaço utilizado no armazenamento para esse intervalo. Para limpar um intervalo, defina o Content-Length cabeçalho como 0e defina o Range cabeçalho para um valor que indica o intervalo a limpar, até ao tamanho máximo do blob.
x-ms-encryption-scope Opcional. Indica o âmbito de encriptação a utilizar para encriptar o conteúdo do pedido. Este cabeçalho é suportado na versão 2019-02-02 e posterior.
x-ms-lease-id:<ID> Necessário se o blob tiver uma concessão ativa. Para executar esta operação num blob com uma concessão ativa, especifique o ID de concessão válido para este 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, o pedido prossegue. Caso contrário, falha com o erro SequenceNumberConditionNotMet (código de estado HTTP 412 – Falha na Pré-condição).
x-ms-if-sequence-number-lt: <num> Opcional. Se o número de sequência do blob for inferior ao valor especificado, o pedido continua. Caso contrário, falha com o erro SequenceNumberConditionNotMet (código de estado HTTP 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, o pedido continua. Caso contrário, falha com o erro SequenceNumberConditionNotMet (código de estado HTTP 412 – Falha na Pré-condição).
If-Modified-Since Opcional. Um DateTime valor. Especifique este cabeçalho condicional para escrever a página apenas se o blob tiver sido modificado desde a data/hora especificada. Se o blob não tiver sido modificado, o Armazenamento de Blobs devolve o código de estado 412 (Falha na Pré-condição).
If-Unmodified-Since Opcional. Um DateTime valor. Especifique este cabeçalho condicional para escrever a página apenas se o blob não tiver sido modificado desde a data/hora especificada. Se o blob tiver sido modificado, o Armazenamento de Blobs devolve o código de estado 412 (Falha na Pré-condição).
If-Match Opcional. Um valor ETag. Especifique um valor ETag para este cabeçalho condicional para escrever a página apenas se o valor ETag do blob corresponder ao valor especificado. Se os valores não corresponderem, o Armazenamento de Blobs devolve o código de estado 412 (Falha na Pré-condição).
If-None-Match Opcional. Um valor ETag.

Especifique um valor ETag para este cabeçalho condicional para escrever a página apenas se o valor ETag do blob não corresponder ao valor especificado. Se os valores forem idênticos, o Armazenamento de Blobs devolve o código de estado 412 (Falha na Pré-condição).
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Armazenamento de Blobs do Azure.

Esta operação também suporta a utilização de cabeçalhos condicionais para executar a operação apenas se uma condição especificada for cumprida. Para obter mais informações, veja Especificar cabeçalhos condicionais para operações do serviço Blob.

Cabeçalhos de pedido (chaves de encriptação fornecidas pelo cliente)

A partir da versão 2019-02-02, pode especificar os seguintes cabeçalhos no pedido para encriptar um blob com uma chave fornecida pelo cliente. A encriptação com uma chave fornecida pelo cliente (e o conjunto de cabeçalhos correspondente) é opcional.

Cabeçalho do pedido Description
x-ms-encryption-key Obrigatório. A chave de encriptação AES-256 codificada com Base64.
x-ms-encryption-key-sha256 Obrigatório. O hash SHA256 codificado com Base64 da chave de encriptação.
x-ms-encryption-algorithm: AES256 Obrigatório. Especifica o algoritmo a utilizar para encriptação. O valor deste cabeçalho tem de ser AES256.

Corpo do pedido

O corpo do pedido contém o conteúdo da página.

Pedido de exemplo: Atualizar o intervalo de bytes

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

Pedido de exemplo: Limpar intervalo de bytes

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:  
Range: bytes=1024-2048  
x-ms-page-write: clear  
x-ms-date: Sun, 25 Sep 2011 23:37:35 GMT  
x-ms-version: 2011-08-18  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
  

Resposta

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

Código de estado

Uma operação bem-sucedida devolve o código de estado 201 (Criado).

Para obter mais informações sobre códigos de estado, veja Códigos de estado e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os seguintes cabeçalhos. 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.

Syntax Descrição
ETag A ETag do blob. Se a versão do pedido for 2011-08-18 e posterior, o valor ETag estará entre aspas. A ETag pode ser utilizada para executar uma operação condicional Put Page ao especificar o respetivo valor para o cabeçalho ou If-MatchIf-None-Match do pedido.
Last-Modified A data e hora em que o blob foi modificado pela última vez. O formato de data segue RFC 1123. Para obter mais informações, veja Representar valores de data/hora em cabeçalhos.

Qualquer operação de escrita no blob, incluindo atualizações aos metadados ou propriedades do blob, altera a hora da última modificação do blob.
Content-MD5 Este cabeçalho é devolvido para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor deste cabeçalho é calculado pelo Armazenamento de Blobs. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos do pedido. Para a versão 2019-02-02 e posterior, este cabeçalho só é devolvido quando o pedido tiver este cabeçalho.
x-ms-content-crc64 Para a versão 2019-02-02 ou posterior, este cabeçalho é devolvido para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor deste cabeçalho é calculado pelo Armazenamento de Blobs. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos do pedido.

Este cabeçalho é devolvido quando Content-MD5 o cabeçalho não está presente no pedido.
x-ms-blob-sequence-number O número de sequência atual do blob de páginas.
x-ms-request-id Identifica exclusivamente o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
x-ms-version Indica a versão do serviço Blob que foi utilizada para executar o pedido. Este cabeçalho é devolvido para pedidos efetuados 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 deste cabeçalho é definido como true se os conteúdos do pedido forem encriptados com êxito através do algoritmo especificado. Caso contrário, o valor está definido como false.
x-ms-encryption-key-sha256 Versão 2019-02-02 e posterior. Devolvido se o pedido utilizou uma chave fornecida pelo cliente para encriptação, para que o cliente possa garantir que os conteúdos do pedido são encriptados com êxito com a chave fornecida.
x-ms-encryption-scope Versão 2019-02-02 e posterior. Devolvido se o pedido utilizou um âmbito de encriptação, para que o cliente possa garantir que os conteúdos do pedido são encriptados com êxito através do âmbito de encriptação.
x-ms-client-request-id Pode ser utilizado para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho se estiver presente no pedido e o valor não contiver mais de 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, não estará presente na resposta.

Corpo da resposta

Nenhum.

Resposta de amostra

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
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. Pode autorizar a Put Page operação conforme descrito abaixo.

Importante

A Microsoft recomenda a utilização de Microsoft Entra ID com identidades geridas para autorizar pedidos para o Armazenamento do Azure. Microsoft Entra ID fornece segurança superior e facilidade de utilização em comparação com a autorização de Chave Partilhada.

O Armazenamento do Azure suporta a utilização de Microsoft Entra ID para autorizar pedidos a dados de blobs. Com Microsoft Entra ID, pode utilizar o controlo de acesso baseado em funções do Azure (RBAC do Azure) para conceder permissões a um principal de segurança. O principal de segurança pode ser um utilizador, grupo, principal de serviço de aplicação ou identidade gerida do Azure. O principal de segurança é autenticado por Microsoft Entra ID para devolver um token OAuth 2.0. Em seguida, o token pode ser utilizado para autorizar um pedido contra o serviço Blob.

Para saber mais sobre a autorização através de Microsoft Entra ID, veja Autorizar o acesso a blobs com Microsoft Entra ID.

Permissões

Abaixo estão listadas as ações RBAC necessárias para que um utilizador Microsoft Entra, grupo, identidade gerida ou principal de serviço chame a Put Page operação e a função RBAC do Azure com menos privilégios que inclua esta ação:

Para saber mais sobre como atribuir funções com o RBAC do Azure, veja Atribuir uma função do Azure para acesso a dados de blobs.

Observações

A Put Page operação escreve um intervalo de páginas num blob de páginas. Esta operação só pode ser chamada num blob de página existente. Não pode ser chamado para criar um novo blob de página, nem pode ser chamado num blob de blocos. Chamar Put Page com um nome de blob que não existe atualmente devolve o código de estado HTTP 404 (Não Encontrado).

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

Se o blob tiver uma concessão ativa, o cliente tem de especificar um ID de concessão válido no pedido para escrever uma página.

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

A Put Page chamada com a opção Update efetua uma escrita no local no blob de páginas especificado. Qualquer conteúdo na página especificada é substituído pela atualização.

Importante

Se o servidor exceder o limite de tempo ou a ligação estiver fechada durante uma Put Page operação, a página poderá ou não ter sido atualizada. Por conseguinte, deve continuar a repetir a atualização até receber uma resposta que indique êxito.

Cada intervalo de páginas submetidas Put Page para uma operação de atualização pode ter até 4 MiB de tamanho. O intervalo de início e de fim da página tem de estar alinhado com limites de 512 bytes. Se tentar carregar um intervalo de páginas com mais de 4 MiB, o serviço devolve o código de estado 413 (Entidade de Pedido Demasiado Grande).

Operações de limpeza de páginas

Chamar Put Page com a opção Clear liberta o espaço de armazenamento utilizado pela página especificada. As páginas que foram desmarcadas já não são controladas como parte do blob de páginas.

As páginas que foram desmarcadas já não incorrem numa cobrança relativamente à conta de armazenamento, porque os respetivos recursos de armazenamento foram libertados. A única exceção é se existirem instantâneos do blob de página. As páginas nos instantâneos incorrem num custo se essas mesmas páginas já não existirem como parte do blob de origem.

Gerir problemas de simultaneidade

O Armazenamento de Blobs processa escritas simultâneas em páginas sobrepostas sequencialmente. Ou seja, a última página processada pelo serviço determina o conteúdo do blob. Por conseguinte, para garantir a integridade do conteúdo do blob, o cliente deve processar as escritas em páginas sobrepostas através de uma ou mais das seguintes abordagens:

  • Pode verificar o valor do cabeçalho de Last-Modified resposta para cada chamada bem-sucedida para Put Page. A ordem das respostas devolvidas a partir do Armazenamento de Blobs não corresponde necessariamente à ordem pela qual foram executadas pelo serviço. Mas o valor de Last-Modified indica sempre a ordem pela qual o serviço processou os pedidos.

  • Pode efetuar atualizações condicionalmente com base no ETag do blob ou na última modificação com a simultaneidade otimista. Esta abordagem funciona bem se o número de escritas simultâneas for relativamente baixo. Utilize os cabeçalhos If-Matchde pedido condicional , If-None-Match, If-Modified-Sincee If-Unmodified-Since para esta finalidade.

  • Pode chamar o Blob de Concessão para bloquear o blob em relação a outras escritas durante um período de um minuto ou mais se a concessão for renovada.

  • Pode utilizar o número de sequência do blob para garantir que repetir um pedido para o qual não houve resposta não resulta em atualizações simultâneas. Esta abordagem pode ser a melhor para clientes que necessitam de débito elevado para escritas de páginas. Isto é descrito em detalhe na secção seguinte.

Utilizar o número de sequência de blobs de páginas para repetir pedidos

Quando uma chamada para Put Page exceder o limite de tempo ou não devolver uma resposta, não há como saber ao certo se o pedido foi efetuado com êxito. Por conseguinte, tem de repetir o pedido, mas, devido à natureza distribuída dos serviços de armazenamento do Azure, é possível que o pedido original possa ser processado após o pedido repetido ter sido executado com êxito. O pedido original atrasado pode substituir outras atualizações e gerar um resultado inesperado. A sequência seguinte ilustra como isto pode acontecer:

  1. Um Put Page pedido para escrever o valor "X" na página 0 excede o limite de tempo ou não devolve uma resposta.

  2. Um pedido repetido para escrever o valor "X" na página 0 é bem-sucedido.

  3. Um pedido para escrever o valor "Y" na página 0 é bem-sucedido.

  4. O pedido original é bem-sucedido ao escrever o valor "X" na página 0.

  5. Ler a página 0 devolve o valor "X", quando o cliente estava neste momento à espera do valor "Y".

Este tipo de conflito pode ocorrer quando o pedido original não devolve um código de estado de 100 a 499 ou 503 (Servidor Ocupado). Se um destes códigos de estado for devolvido, pode ter a certeza se o pedido foi efetuado com êxito ou falhou. No entanto, se o serviço devolver um código de estado fora deste intervalo, não há forma de saber o estado do pedido original.

Para evitar este tipo de conflito, pode utilizar o número de sequência do blob de página para garantir que, quando repetir um pedido, o pedido original não será bem-sucedido. Para tal, deve incrementar o número de sequência antes de repetir o pedido original. Em seguida, pode utilizar os cabeçalhos de número de sequência condicional para garantir que o pedido falha se o número de sequência não corresponder ao número de sequência esperado. A seguinte sequência ilustra esta abordagem:

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

  2. Um Put Page pedido para escrever o valor "X" na página 0 com o cabeçalho definido para 1 exceder o if-sequence-number-lt limite de tempo ou não devolve uma resposta.

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

  4. Um pedido repetido para escrever o valor "X" na página 0 com if-sequence-number-lt definido como 2 com êxito.

  5. Um pedido para escrever o valor "Y" na página 0 com if-sequence-number-lt o conjunto definido como 2 com êxito.

  6. O pedido original é finalmente processado, mas falha porque especifica a condição de que o número de sequência tem de ser inferior a 1 (ou seja, o if-sequence-num-lt cabeçalho está definido como 1). O erro é SequenceNumberConditionNotMet (código de estado HTTP 412 – Falha na Pré-condição).

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

Ver também

Autorizar pedidos para o Armazenamento do Azure
Códigos de estado e de erro
Definir tempos limite para operações do serviço Blob