Colocar página de URL

Artigo
09/22/2022
16 minutos para ler

A Put Page From URL operação escreve uma série de páginas para uma bolha de página 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

O Put Page From URL pedido pode ser construído da seguinte forma. HTTPS é recomendado. Substitua a minha conta pelo nome da sua conta de armazenamento:

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

Serviço de Armazenamento emulado URI

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

PUT Método Request URI	Versão HTTP
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page`	HTTP/1.1

Para obter mais informações, consulte a Utilização do Armazenamento Emulator Azure para Desenvolvimento e Testes.

Parâmetros do URI

Os seguintes parâmetros adicionais podem ser especificados no pedido URI.

Parâmetro	Descrição
`timeout`	Opcional. O `timeout` parâmetro é expresso em segundos. Para obter mais informações, consulte a definição de intervalos para operações de serviço de blob.

Pedido cabeçalhos

A tabela seguinte descreve os cabeçalhos de pedido necessários e opcionais.

Cabeçalho do Pedido	Description
`Authorization`	Obrigatório. Especifica o esquema de autorização, nome da conta e assinatura. Para mais informações, consulte Os pedidos autorizados à Azure Armazenamento.
`Date` ou `x-ms-date`	Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para mais informações, consulte Os pedidos autorizados à Azure Armazenamento.
`x-ms-version`	Requerido para todos os pedidos autorizados. Especifica a versão da operação a utilizar para este pedido. Para mais informações, consulte a versão para os Serviços Azure Armazenamento.
`Range`	`x-ms-range` Ou `Range` é necessário. Especifica o intervalo de bytes a ser escrito como uma página. Tanto o início como o fim do intervalo devem 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ágina pode ser de até 4 MiB de tamanho. Dado que as páginas devem ser alinhadas com os limites de 512 byte, o offset inicial deve ser um módulo de 512 e o offset final deve ser um módulo de 512 - 1. Exemplos de gamas byte válidas são 0-511, 512-1023, etc. O serviço Blob aceita apenas uma gama de bytes para o `Range` cabeçalho, e a gama byte deve ser especificada no seguinte formato: `bytes=startByte-endByte`. Se ambos `Range` e `x-ms-range` forem especificados, o serviço utiliza o valor de `x-ms-range`. Consulte especificar o cabeçalho de alcance para operações de serviço de blob para obter mais informações.
`x-ms-range`	`x-ms-range` Ou `Range` é necessário. Especifica o intervalo de bytes a ser escrito como uma página. Tanto o início como o fim do intervalo devem ser especificados. Este cabeçalho é definido pela especificação do protocolo HTTP/1.1. A gama de páginas pode ter até 4 MiB de tamanho. Dado que as páginas devem ser alinhadas com os limites de 512 byte, o offset inicial deve ser um módulo de 512 e o offset final deve ser um módulo de 512 - 1. Exemplos de gamas byte válidas são 0-511, 512-1023, etc. O serviço Blob aceita apenas uma gama de bytes para o `x-ms-range` cabeçalho, e a gama byte deve ser especificada no seguinte formato: `bytes=startByte-endByte`. Se ambos `Range` e `x-ms-range` forem especificados, o serviço utiliza o valor de `x-ms-range`. Consulte especificar o cabeçalho de alcance para operações de serviço de blob para obter mais informações.
`Content-Length`	Obrigatório. Especifica o número de bytes transmitidos no organismo de pedido. O valor deste cabeçalho deve ser definido para zero. Quando o comprimento não for zero, a operação falhará com o código de estado 400 (Mau Pedido).
`x-ms-copy-source:name`	Obrigatório. Especifica o URL da bolha de origem. O valor pode ser um URL de até 2 KiB de comprimento que especifica uma bolha. O valor deve ser codificado por URL, tal como aparece num pedido URI. A bolha de origem deve ser pública ou deve ser autorizada através de uma assinatura de acesso partilhado. Se a bolha de origem for pública, não é necessária autorização para a realização da 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 regime de autorização e a assinatura para a fonte de cópia. Para mais informações, consulte Os pedidos autorizados à Azure Armazenamento. Apenas o portador do regime é apoiado para Azure Ative Directory. Este cabeçalho é suportado nas versões 2020-10-02 e posteriormente.
`x-ms-source-range`	Carrega os bytes da bolha no URL de origem na gama especificada. Tanto o início como o fim do intervalo devem ser especificados. Este cabeçalho é definido pela especificação do protocolo HTTP/1.1. A gama de páginas pode ter até 4 MiB de tamanho. O serviço Blob aceita apenas uma gama de bytes para o `x-ms-source-range` cabeçalho, e a gama byte deve ser especificada no seguinte formato: `bytes=startByte-endByte`. Consulte especificar o cabeçalho de alcance para operações de serviço de 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. Note que este hash md5 não está armazenado com a bolha. Se os dois hashes não coincidirem, a operação falhará com o código de erro 400 (Mau Pedido).
`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. Note que este Hash CRC64 não é armazenado com a bolha. Se os dois hashes não coincidirem, a operação falhará com o código de erro 400 (Mau Pedido). Se ambos e `x-ms-source-content-crc64` cabeçalhos `x-ms-source-content-md5` estiverem presentes, o pedido falhará com um 400 (Mau Pedido). Este cabeçalho é suportado nas versões 2019-02-02 ou posterior.
`x-ms-lease-id:<ID>`	Requerido se a bolha tiver um arrendamento ativo. Para realizar esta operação numa bolha com um arrendamento ativo, especifique o ID de locaçã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 inferior ou igual ao valor especificado, o pedido prossegue; caso contrário, falha com o erro SequenceNumberConditionNotMet (código de estado HTTP 412 – Pré-condição falhada).
`x-ms-if-sequence-number-lt: <num>`	Opcional. Se o número de sequência do blob for inferior ao valor especificado, o pedido prossegue; caso contrário, falha com o erro SequenceNumberConditionNotMet (código de estado HTTP 412 – Pré-condição falhada).
`x-ms-if-sequence-number-eq: <num>`	Opcional. Se o número de sequência do blob for igual ao valor especificado, o pedido prossegue; caso contrário, falha com o erro SequenceNumberConditionNotMet (código de estado HTTP 412 – Pré-condição falhada).
`If-Modified-Since`	Opcional. Um `DateTime` valor. Especifique este cabeçalho condicional para escrever a página apenas se a bolha tiver sido modificada desde a data/hora especificada. Se a bolha não tiver sido modificada, o serviço Blob devolve o código de estado 412 (Pré-condição Falhada).
`If-Unmodified-Since`	Opcional. Um `DateTime` valor. Especifique este cabeçalho condicional para escrever a página apenas se a bolha não tiver sido modificada desde a data/hora especificada. Se a bolha tiver sido modificada, o serviço Blob devolve o código de estado 412 (Pré-condição Falhada).
`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 da bolha corresponder ao valor especificado. Se os valores não coincidirem, o serviço Blob devolve o código de estado 412 (Pré-condição Falhada).
`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 da bolha não corresponder ao valor especificado. Se os valores forem idênticos, o serviço Blob devolve o código de estado 412 (Pré-condição Falhada).
`x-ms-encryption-scope`	Opcional. Indica o âmbito de encriptação a utilizar para encriptar o conteúdo da origem. Este cabeçalho é suportado nas versões 2019-02-02 ou posterior.
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres de 1 KiB que é gravado nos registos de análise quando o registo de análise de armazenamento está ativado. Recomenda-se a utilização deste cabeçalho para correlacionar as atividades do lado do cliente com os pedidos recebidos pelo servidor. Para obter mais informações, consulte Sobre Análise de Armazenamento registo de registos e registos Azure: Utilizar registos para rastrear pedidos de Armazenamento.

Esta operação também suporta a utilização de cabeçalhos condicional para executar a operação apenas se uma condição especificada for satisfeita. Para obter mais informações, consulte especificar cabeçalhos condicional para operações de serviço de bolhas.

Pedido cabeçalhos (chaves de encriptação fornecidas pelo cliente)

Começando pela versão 2019-02-02, os seguintes cabeçalhos podem ser especificados no pedido de encriptação de uma bolha encriptada com uma chave fornecida pelo cliente. A encriptação com uma chave fornecida pelo cliente (e o conjunto correspondente de cabeçalhos) é opcional.

Cabeçalho do pedido	Description
`x-ms-encryption-key`	Obrigatório. A chave de encriptação AES-256 codificada pela Base64.
`x-ms-encryption-key-sha256`	Obrigatório. O hash SHA256 codificado pela 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 deve ser `AES256`.

Corpo do Pedido

O órgão de pedido contém o conteúdo da página.

Pedido de Amostra

  
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 informações sobre códigos de estado, consulte 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 standard estão de acordo com a especificação do protocolo HTTP/1.1.

Syntax	Descrição
`ETag`	O ETag para a bolha. Se a versão de pedido for 2011-08-18 ou mais recente, o valor ETag estará em aspas. O ETag pode ser utilizado para efetuar uma operação condicional `Put Page From URL` especificando o seu valor para o `If-Match` cabeçalho ou `If-None-Match` pedido.
`Last-Modified`	A data e a hora em que a bolha foi modificada pela última vez. O formato de data segue o RFC 1123. Para mais informações, consulte Representação de Valores Date-Time em Cabeçalhos. Qualquer operação de escrita na bolha, incluindo atualizações para os metadados ou propriedades do blob, altera o último tempo modificado da bolha.
`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 serviço Blob; não é necessariamente o mesmo valor especificado nos cabeçalhos de pedido. Para as versões 2019-02-02 ou posterior, este cabeçalho só é devolvido quando o pedido tiver este cabeçalho.
`x-ms-content-crc64`	Para as versões 2019-02-02 ou posterior, este cabeçalho é devolvido para que o cliente possa verificar se a integridade do conteúdo da mensagem é possível. O valor deste cabeçalho é calculado pelo serviço Blob; não é necessariamente o mesmo valor especificado nos cabeçalhos de 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 para a bolha da página.
`x-ms-request-id`	Este cabeçalho identifica exclusivamente o pedido que foi feito e pode ser usado para resolver problemas no pedido. Para mais informações, consulte operações de resolução de problemas da API.
`x-ms-version`	Indica a versão do serviço Blob utilizado para executar o pedido. Este cabeçalho é devolvido para pedidos feitos contra a versão 2009-09-19 e mais tarde.
`Date`	Uma data/valor de hora UTC gerado pelo serviço que indica o momento em que a resposta foi iniciada.
`x-ms-request-server-encrypted: true/false`	Versão 2015-12-11 ou mais recente. O valor deste cabeçalho é definido para `true` se o conteúdo do pedido for encriptado com sucesso usando o algoritmo especificado, e `false` de outra forma.
`x-ms-encryption-key-sha256`	Versão 2019-02-02 ou mais recente. Este cabeçalho é devolvido se o pedido utilizar uma chave fornecida pelo cliente para encriptação, para que o cliente possa garantir que o conteúdo do pedido seja encriptado com sucesso usando a chave fornecida.
`x-ms-encryption-scope`	Versão 2019-02-02 ou mais recente. Este cabeçalho é devolvido se o pedido utilizar um âmbito de encriptação, para que o cliente possa garantir que o conteúdo do pedido seja encriptado com sucesso usando o âmbito de encriptação.
`x-ms-client-request-id`	Este cabeçalho pode ser usado para resolver 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 for no máximo 1024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente no pedido, este cabeçalho não estará presente na resposta.

Corpo de 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

Esta operação pode ser chamada pelo proprietário da conta e por qualquer pessoa com uma Assinatura de Acesso Partilhado que tenha permissão para escrever a esta bolha ou ao seu recipiente.

Observações

A Put Page From URL operação escreve uma série de páginas para uma bolha de página. Esta operação só pode ser chamada numa bolha de página existente. Não pode ser chamado para criar uma nova bolha de página, nem pode ser chamado numa bolha de bloco. Chamar Put Page From URL com um nome 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 mais recente, Azure Ative Directory autorização é suportada para a origem da operação de cópia.

Para criar uma nova bolha de página, ligue para colocar Blob e especifique o tipo de bolha para criar como uma bolha de página. Uma mancha de página pode ter até 8 TiB de tamanho.

Se a bolha tiver um contrato de arrendamento ativo, o cliente deve especificar um ID de locação válido no pedido para escrever uma página.

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

A chamada Put Page From URL executa uma escrita no local na bolha de página especificada. Qualquer conteúdo na página especificada é substituído com a atualização.

Importante

Se o servidor esgotar ou a sua ligação estiver fechada durante um Put Page From URL, a página pode ou não ter sido atualizada. Portanto, deve continuar a tentar novamente a atualização até receber uma resposta que indique o sucesso.

Cada gama de páginas submetidas Put Page From URL para uma operação de atualização pode ter até 4 MiB de tamanho. A gama de início e de extremidade da página deve estar alinhada com os limites de 512 byte. Se tentar carregar uma série de páginas superiores a 4MB, o serviço devolve o código de estado 413 (Entidade de Pedido Demasiado Grande).

Gerir problemas de concurrency

O serviço Blob lida com escritos simultâneos para páginas sobrepostas sequencialmente: a última página processada pelo serviço determina o conteúdo da bolha. Portanto, para garantir a integridade do conteúdo do blob, o cliente deve lidar com escritas para páginas sobrepostas usando 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 de respostas devolvidas do serviço Blob não corresponde necessariamente à ordem em que foram executadas pelo serviço. Mas o valor de Last-Modified sempre indica a ordem em que o serviço processou os pedidos.
Pode executar atualizações condicionalmente com base no ETag da bolha ou no último tempo modificado utilizando a concordância otimista. Esta abordagem funciona bem se o número de escritos simultâneos for relativamente baixo. Utilize os cabeçalhos de pedido condicional If-Match, If-None-Match, If-Modified-Sincee If-Unmodified-Since para este fim.
Você pode ligar para Lease Blob para bloquear a bolha contra outras escritas por um período de um minuto, ou mais se o arrendamento for renovado.
Pode utilizar o número de sequência da bolha para garantir que a repetição de um pedido para o qual não houve resposta não resulte em atualizações simultâneas. Esta abordagem pode ser a melhor para os clientes que requerem alta produção para as escritas de página. É descrito em detalhe na secção seguinte.

Utilização do número de sequência de blob de página para retíria pedidos

Quando uma chamada para Put Page From URL o horário fora ou não devolve uma resposta, não há como saber ao certo se o pedido foi bem sucedido. Por isso, é necessário voltar a julgar o pedido, mas devido à natureza distribuída dos serviços de armazenamento Azure, é possível que o pedido original possa ser processado após o pedido re-experimentado ter sido bem sucedido. O pedido original atrasado pode substituir outras atualizações e produzir um resultado inesperado. A seguinte sequência ilustra como isto pode acontecer:

Um Put Page From URL pedido para escrever o valor "X" para a página 0 vezes fora ou não devolve uma resposta.
Um pedido de nova avaliação para escrever o valor "X" para a página 0 tem sucesso.
Um pedido para escrever valor "Y" para a página 0 tem sucesso.
O pedido original tem sucesso, escrevendo o valor "X" para a página 0.
Ler a página 0 devolve o valor "X", quando o cliente estava neste ponto à 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 (Server Busy). Se um destes códigos de estado for devolvido, pode ter a certeza se o pedido foi bem sucedido ou falhado. Mas se o serviço devolver um código de estado fora deste alcance, não há como saber o estado do pedido original.

Para evitar este tipo de conflito, pode utilizar o número de sequência da página blob para garantir que, quando voltar a tentar um pedido, o pedido original não será posteriormente bem sucedido. Para tal, deverá incrementar o número de sequência antes de voltar a tentar 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 da sequência não corresponder ao número de sequência esperado. A seguinte sequência ilustra esta abordagem:

O cliente cria uma bolha de página com Put Blob e define o seu número de sequência para 0.
Um Put Page From URL pedido para escrever o valor "X" para a página 0 com o if-sequence-number-lt cabeçalho definido para 1 o tempo fora ou não devolve uma resposta.
O cliente liga para definir propriedades blob para atualizar o número da sequência para 1.
Um pedido de nova tentação para escrever o valor "X" para a página 0 com if-sequence-number-lt definido para 2 ter sucesso.
Um pedido para escrever valor "Y" para a página 0 com if-sequence-number-lt definido para 2 ter sucesso.
O pedido original é finalmente processado, mas falha porque especifica a condição de que o número de sequência deve ser inferior a 1 (ou seja, o if-sequence-num-lt cabeçalho está definido para 1). O erro é SequenceNumberConditionNotMet (código de estado HTTP 412 – Pré-condição falhada).
Ler a página 0 devolve o valor esperado de "Y".

Consulte também

Autorizar pedidos à Azure Armazenamento
Códigos de Estado e erro
Definição de intervalos para operações de serviço de blob