Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
A Put Page From URL
operação grava um intervalo de páginas em um blob de página onde o conteúdo é lido a partir de uma URL. Esta API está disponível a partir da versão 2018-11-09.
Solicitação
Você pode construir a solicitação Put Page From URL
da seguinte maneira. Recomendamos que você use HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento:
URI de solicitação de 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 você estiver fazendo uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e a porta do serviço de Blob como 127.0.0.1:10000
, seguido pelo nome da conta de armazenamento emulada:
URI de solicitação de 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 o desenvolvimento local do Armazenamento do Azure.
Parâmetros de URI
Você pode especificar os seguintes parâmetros adicionais no URI de 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 de serviço de Blob. |
Cabeçalhos da requisiçã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ório Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure. |
Date ou x-ms-date |
Obrigatório Especifica o Tempo Universal Coordenado (UTC) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure. |
x-ms-version |
Obrigatório para todos os pedidos autorizados. Especifica a versão da operação a ser usada para essa solicitação. Para obter mais informações, consulte Controle de versão para os serviços de Armazenamento do Azure. |
Range |
Ou Range x-ms-range é obrigatório.Especifica o intervalo de bytes a ser escrito como uma página. O início e 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áginas pode ter até 4 MiB de tamanho. Como as páginas devem estar 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 único intervalo de bytes para o Range cabeçalho 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 do intervalo para operações de serviço de Blob. |
x-ms-range |
Ou Range x-ms-range é obrigatório.Especifica o intervalo de bytes a ser escrito como uma página. O início e o fim do intervalo devem 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. Como as páginas devem estar 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 único intervalo de bytes para o x-ms-range cabeçalho 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 do intervalo para operações de serviço de Blob. |
Content-Length |
Obrigatório Especifica o número de bytes que estão sendo transmitidos no corpo da solicitação. O valor deste cabeçalho deve ser definido como zero. Quando o comprimento não é zero, a operação falha com o código de status 400 (Solicitação incorreta). |
x-ms-copy-source:name |
Obrigatório 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 por URL como apareceria em um URI de solicitação. 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 da fonte de cópia. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure. Apenas um portador de esquema é suportado para o Microsoft Entra. 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 devem 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 único intervalo de bytes para o x-ms-source-range cabeçalho e o intervalo de bytes deve ser especificado no seguinte formato: bytes=startByte-endByte .Consulte Especificar o cabeçalho do intervalo 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. 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. Nota: Este 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 incorreta). |
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. Nota: Este 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 incorreta). Se ambos os x-ms-source-content-md5 cabeçalhos estiverem x-ms-source-content-crc64 presentes, a solicitação falhará com um 400 (Solicitação incorreta).Este cabeçalho é suportado 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 (código de status HTTP 412 – Precondition Failed). |
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 (código de status HTTP 412 – Precondition Failed). |
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 (código de status HTTP 412 – Precondition Failed). |
If-Modified-Since |
Opcional. Um valor de DateTime . Especifique esse cabeçalho condicional para escrever 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á o código de status 412 (Falha na pré-condição). |
If-Unmodified-Since |
Opcional. Um valor de DateTime . Especifique esse cabeçalho condicional para escrever 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 pré-condição). |
If-Match |
Opcional. Um valor 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á o código de status 412 (Falha na pré-condição). |
If-None-Match |
Opcional. Um valor ETag. Especifique um valor ETag para esse cabeçalho condicional para 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. 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 caracteres de 1 kibibyte (KiB) que é registrado nos logs quando o log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações que o servidor recebe. Para obter mais informações, consulte Monitor Azure Blob Storage. |
x-ms-file-request-intent |
Obrigatório se x-ms-copy-source header for uma URL de arquivo do Azure e x-ms-copy-source-authorization o cabeçalho especificar um token OAuth. O valor aceitável é backup . Este cabeçalho especifica que os Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action devem ser concedidos se forem incluídos na política RBAC atribuída à identidade autorizada usando o cabeçalho x-ms-copy-source-authorization . Disponível para a versão 2025-07-05 e posterior. |
Esta operação também suporta o uso de cabeçalhos condicionais para executar a operação somente se uma condição especificada for atendida. Para obter mais informações, consulte Especificar cabeçalhos condicionais para operações de serviço de 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ório A chave de criptografia AES-256 codificada em Base64. |
x-ms-encryption-key-sha256 |
Obrigatório O hash SHA256 codificado em Base64 da chave de criptografia. |
x-ms-encryption-algorithm: AES256 |
Obrigatório Especifica o algoritmo a ser usado para criptografia. O valor deste cabeçalho deve ser AES256 . |
Corpo de solicitação
O corpo da solicitação 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 status HTTP e um conjunto de cabeçalhos de resposta.
Código de estado
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 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.
Sintaxe | Descrição |
---|---|
ETag |
O ETag para o blob. Se a versão da solicitação for 2011-08-18 e posterior, o valor ETag será colocado entre aspas. O ETag pode ser usado para executar uma operação condicional Put Page From URL , especificando seu valor para o If-Match cabeçalho ou If-None-Match solicitação. |
Last-Modified |
A data e a hora em que o blob foi modificado pela última vez. O formato de data segue o 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 propriedades do blob, altera a hora da última modificação do blob. |
Content-MD5 |
Retornado para que o cliente possa verificar a 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 da 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 verificar a 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 da 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 para o blob de página. |
x-ms-request-id |
Identifica exclusivamente a solicitação que foi feita e pode ser usada para solucionar a 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. Este 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 é definido como true 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 é igual ao valor do cabeçalho x-ms-client-request-id se ele estiver presente na solicitação e o valor não contiver mais de 1.024 caracteres ASCII visíveis. Se o cabeçalho x-ms-client-request-id não estiver presente na solicitação, ele não estará presente na resposta. |
Corpo da resposta
Nenhum.
Resposta da 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. Você pode autorizar a operação Put Page From URL
conforme descrito abaixo.
Importante
A Microsoft recomenda o uso do Microsoft Entra ID com identidades gerenciadas para autorizar solicitações ao Armazenamento do Azure. O Microsoft Entra ID oferece segurança superior e facilidade de uso em comparação com a autorização de chave compartilhada.
O Armazenamento do Azure dá suporte ao uso do Microsoft Entra ID para autorizar solicitações para dados de blob. Com o Microsoft Entra ID, você pode usar o controle de acesso baseado em função do Azure (Azure RBAC) 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 pelo Microsoft Entra ID para retornar um token OAuth 2.0. O token pode ser usado para autorizar uma solicitação contra o serviço Blob.
Para saber mais sobre a autorização usando o Microsoft Entra ID, consulte Autorizar o acesso a blobs usando o Microsoft Entra ID.
Permissões
Abaixo estão listadas a ação RBAC necessária para que um usuário, grupo, identidade gerenciada ou entidade de serviço do Microsoft Entra chame a operação Put Page From URL
e a função interna menos privilegiada do RBAC do Azure que inclui essa ação:
- ação RBAC do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- Função interna menos privilegiada:Contribuidor de Dados de Blob de Armazenamento
Para saber mais sobre como atribuir funções usando o RBAC do Azure, consulte Atribuir uma função do Azure para acesso a dados de blob.
Observações
A Put Page From URL
operação grava um intervalo de páginas em um blob de página. Esta operação só pode ser chamada em um blob de página existente. Ele não pode ser chamado para criar um novo blob de página, nem pode ser chamado em um blob de bloco. Chamar Put Page From URL
com um nome de blob que não existe atualmente retorna o erro BlobNotFound (código de status HTTP 404 – Não encontrado).
Na versão 2020-10-02 e posterior, a autorização do Microsoft Entra é suportada para a origem da operação de cópia.
Para criar um novo blob de página, chame Put Blob e especifique o tipo de blob a ser criado como um blob de página. Um blob de página pode ter até 8 TiB de tamanho.
Se o blob tiver uma concessão ativa, o cliente deverá especificar um ID de concessão válido na solicitação para escrever uma página.
Operações de atualização de página
A chamada Put Page From URL
executa uma gravação in-loco no blob de página especificado. Qualquer conteúdo na página especificada é substituído pela atualização.
Importante
Se o servidor expirar ou se a sua ligação for fechada durante um Put Page From URL
, a página poderá ou não ter sido atualizada. Portanto, você deve continuar a tentar novamente a atualização até receber uma resposta indicando sucesso.
Cada intervalo de páginas enviadas para Put Page From URL
uma operação de atualização pode ter até 4 MiB de tamanho. O intervalo inicial e final da página deve estar alinhado com limites de 512 bytes. Se você tentar carregar um intervalo de páginas maior que 4 MiB, o serviço retornará o código de status 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. Portanto, para garantir a integridade do conteúdo do blob, o cliente deve lidar com gravações em páginas sobrepostas usando uma ou mais das seguintes abordagens:
Você pode verificar o
Last-Modified
valor do cabeçalho de resposta para cada chamada bem-sucedida paraPut Page From URL
. A ordem das respostas retornadas do serviço Blob não corresponde necessariamente à ordem em que foram executadas pelo serviço. Mas o valor deLast-Modified
sempre indica a ordem em que o serviço processou as solicitações.Você pode executar atualizações condicionalmente com base no ETag do blob ou no tempo da última modificação usando simultaneidade otimista. Essa abordagem funciona bem se o número de gravações simultâneas for relativamente baixo. Use os cabeçalhos de
If-Match
solicitação condicional , ,If-None-Match
If-Modified-Since
eIf-Unmodified-Since
para essa finalidade.Você pode chamar o Blob de Locação para bloquear o blob contra 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 a repetição de uma solicitação para a qual não houve resposta não resulte em atualizações simultâneas. Essa abordagem pode ser melhor para clientes que exigem alta taxa de transferência para gravações de página. é descrito em detalhes na seção a seguir.
Use o número de sequência de blob de página para repetir solicitações
Quando uma chamada expira Put Page From URL
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 depois que a solicitação repetida for bem-sucedida. A solicitação original atrasada pode substituir outras atualizações e gerar um resultado inesperado. A sequência a seguir ilustra como isso pode acontecer:
Uma
Put Page From URL
solicitação para gravar o valor "X" na página 0 expira ou não retorna uma resposta.Uma solicitação repetida para gravar o valor "X" na página 0 é bem-sucedida.
Uma solicitação para escrever o valor "Y" na página 0 é bem-sucedida.
A solicitação original é bem-sucedida, escrevendo o valor "X" na página 0.
A leitura da página 0 retorna o valor "X", quando o cliente estava neste momento esperando o valor "Y".
Esse tipo de conflito pode ocorrer quando a solicitação original não retorna um código de status entre 100-499 ou 503 (Servidor ocupado). Se um desses códigos de status for retornado, você pode ter certeza se a solicitação foi bem-sucedida ou falhou. Mas se o serviço retornar um código de status fora desse intervalo, não há 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ágina para garantir que, quando você repetir uma solicitação, a solicitação original não seja bem-sucedida posteriormente. Para fazer isso, você deve incrementar o número de sequência antes de tentar novamente 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 seu número de sequência não corresponder ao número de sequência esperado. A sequência a seguir ilustra essa abordagem:
O cliente cria um blob de página com Put Blob e define seu número de sequência como 0.
Uma
Put Page From URL
solicitação para gravar o valor "X" na página 0 com oif-sequence-number-lt
cabeçalho definido como1
tempo limite ou não retorna uma resposta.O cliente chama set Blob Properties para atualizar o número de sequência para 1.
Uma solicitação repetida para gravar o valor "X" na página 0 com
if-sequence-number-lt
definido para2
êxito.Uma solicitação para escrever o valor "Y" na página 0 com
if-sequence-number-lt
definido para2
êxito.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 como1
). O erro é SequenceNumberConditionNotMet (código de status HTTP 412 – Precondition Failed).A leitura da página 0 retorna o valor esperado de "Y".
Ver também
Autorizar solicitações ao de Armazenamento do Azure
Códigos de status e de erro
Definir tempos limite para operações de serviço de Blob