Colocar Página a Partir do URL

A Put Page From URL operação escreve um intervalo de páginas num blob de páginas onde os conteúdos são lidos a partir de um URL. Esta API está disponível a partir da versão 2018-11-09.

Pedir

Pode construir o pedido da Put Page From URL 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

URI do 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ágina, o intervalo de páginas pode ter até 4 MiB de tamanho.

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 serviço Blob 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.

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

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 serviço Blob 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. Para obter mais informações, veja Especificar o cabeçalho de intervalo para operações do serviço Blob.
Content-Length Obrigatório. Especifica o número de bytes que estão a ser transmitidos no corpo do pedido. O valor deste cabeçalho tem de ser definido como zero. Quando o comprimento não é zero, a operação falha com o código de estado 400 (Pedido Incorreto).
x-ms-copy-source:name Obrigatório. Especifica o URL do blob de origem. O valor pode ser um URL de até 2 KiB de comprimento que especifica um blob. O valor deve ser codificado com URL, tal como apareceria num URI de pedido. O blob de origem tem de ser público ou tem de ser autorizado através de uma assinatura de acesso partilhado. Se o blob de origem for público, não é necessária autorização para efetuar a operação. Eis alguns exemplos de URLs de objetos 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 da origem de cópia. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
Apenas um portador do esquema é suportado para o Azure Active Directory.
Este cabeçalho é suportado na versão 2020-10-02 e posterior.
x-ms-source-range Carrega os bytes do blob no URL de origem no intervalo especificado. 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.

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

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

Veja Especificar o cabeçalho do 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. Este Hash é utilizado para verificar a integridade da página durante o transporte dos dados do URI. Quando este cabeçalho é especificado, o serviço de armazenamento compara o Hash do conteúdo que chegou da fonte de cópia com este valor do cabeçalho.

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-source-content-crc64 Opcional. Um hash CRC64 do conteúdo da página do URI. Este Hash é utilizado para verificar a integridade da página durante o transporte dos dados do URI. Quando este cabeçalho é especificado, o serviço de armazenamento compara o Hash do conteúdo que chegou da fonte de cópia 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 cabeçalhos x-ms-source-content-md5 e x-ms-source-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-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 serviço Blob 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 serviço Blob 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 serviço Blob 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 serviço Blob devolve o código de estado 412 (Falha na Pré-condição).
x-ms-encryption-scope Opcional. Indica o âmbito de encriptação a utilizar para encriptar o conteúdo de origem. Este cabeçalho é suportado 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 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, podem ser especificados os seguintes cabeçalhos no pedido para encriptar um blob encriptado 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

  
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 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 From URL 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 Devolvido para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor deste cabeçalho é calculado pelo serviço Blob. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos do pedido. Para a versão 2019-02-02 ou 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. Devolvido para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor deste cabeçalho é calculado pelo serviço Blob. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos do pedido.

Este cabeçalho é devolvido quando x-ms-source-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 e false caso contrário.
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:  
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. Pode autorizar a Put Page From URL operação conforme descrito abaixo.

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, grupo ou principal de serviço Microsoft Entra chame a Put Page From URL 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 From URL 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 From URL com um nome de blob que não existe atualmente devolve o erro BlobNotFound (código de estado HTTP 404 – Não Encontrado).

Na versão 2020-10-02 e posterior, a autorização do Azure Active Directory é suportada 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 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 chamada Put Page From URL 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 um Put Page From URL, 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 para Put Page From URL 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).

Gerir problemas de simultaneidade

O serviço Blob 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 escritas em páginas sobrepostas com 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 From URL. A ordem das respostas devolvidas pelo serviço Blob 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 os clientes que necessitam de débito elevado para escritas de páginas. é 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 From URL 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 seja 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 From URL 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 entre 100-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á posteriormente 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 Put Blob e define o respetivo número de sequência para 0.

  2. Um Put Page From URL 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 Definir Propriedades do Blob 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