Exportar (0) Imprimir
Expandir Tudo

Colocar Página

Atualizado: janeiro de 2014

A operação Put Page grava um intervalo de páginas em um blob de páginas.

A solicitação Put Page pode ser criada da seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento:

 

  URI de solicitação do método PUT Versão de HTTP

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page

HTTP/1.1

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

 

  URI de solicitação do método PUT Versão de HTTP

http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page

HTTP/1.1

Para obter mais informações, consulte Uso do Azure Storage Emulator para desenvolvimento e testes.

Os seguintes parâmetros adicionais podem ser especificados no URI de solicitação.

 

Parâmetro Descrição

timeout

Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definição de tempos limite para operações de serviço Blob.

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

 

Cabeçalho de solicitação Descrição

Authorization

Obrigatória. Especifica o esquema de autenticação, o nome da conta e a assinatura. Para obter mais informações, consulte Autenticação federada para os Serviços de Armazenamento do Azure.

Date ou x-ms-date

Obrigatória. Especifica o Tempo Universal Coordenado (UTC) para a solicitação. Para obter mais informações, consulte Autenticação federada para os Serviços de Armazenamento do Azure.

x-ms-version

Obrigatório para todas as solicitações autenticadas. 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 do protocolo HTTP/1.1.

Para uma operação de atualização de página, o intervalo de páginas pode ter até 4 MB. Para uma operação de limpeza de página, o intervalo de páginas pode ter até o valor do tamanho total do blob.

Considerando que 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, etc.

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. Consulte Especificando o cabeçalho de intervalo para operações do serviço Blob para obter mais informações.

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 do protocolo HTTP/1.1.

Para uma operação de atualização de página, o intervalo de páginas pode ter até 4 MB. Para uma operação de limpeza de página, o intervalo de páginas pode ter até o valor do tamanho total do blob.

Considerando que 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, etc.

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. Consulte Especificando o cabeçalho de intervalo para operações do serviço Blob para obter mais informações.

Content-Length

Obrigatória. Especifica o número de bytes que estão sendo transmitidos no corpo da solicitação. Quando o cabeçalho x-ms-page-write é definido como clear, o valor desse cabeçalho deve ser definido como zero.

Content-MD5

Opcional. Um hash MD5 do conteúdo da página. O hash é usado para verificar a integridade da página durante o transporte. Quando esse cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que foi recebido com o valor do cabeçalho que foi enviado. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação Incorreta).

O cabeçalho Content-MD5 não é permitido quando o cabeçalho x-ms-page-write é definido como clear. Se for incluído na solicitação, o serviço Blob retornará o código de status 400 (Solicitação Incorreta).

x-ms-page-write: {update | clear}

Obrigatória. Você pode especificar uma das seguintes opções:

  • Update: grava os bytes especificados pelo corpo da solicitação no intervalo especificado. Os cabeçalhos Range e Content-Length devem corresponder para executar a atualização.

  • Clear: limpa o intervalo especificado e libera o espaço usado no armazenamento para esse intervalo. Para limpar um intervalo, defina o cabeçalho Content-Length como zero e o cabeçalho Range com um valor que indique o intervalo a ser limpo, até atingir o tamanho máximo do blob.

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 da sequência de blob for menor ou igual ao valor especificado, a solicitação continuará; de outra forma, falhará com o erro SequenceNumberConditionNotMet (código de status HTTP 412 – Falha na Precondição).

x-ms-if-sequence-number-lt: <num>

Opcional. Se o número da sequência de blob for menor do que o valor especificado, a solicitação continuará; de outra forma, falhará com o erro SequenceNumberConditionNotMet (código de status HTTP 412 – Falha na Precondição).

x-ms-if-sequence-number-eq: <num>

Opcional. Se o número da sequência de blob for igual ao valor especificado, a solicitação continuará; de outra forma, falhará com o erro SequenceNumberConditionNotMet (código de status HTTP 412 – Falha na Precondiçã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á o código de status 412 (Falha na Precondiçã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 coincidirem, o serviço Blob retornará o código de status 412 (Falha na Pré-condição).

If-None-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 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-client-request-id

Opcional. Fornece um valor opaco, gerado pelo cliente, com um limite de caracteres de 1 KB que é registrado nos logs de análise quando o log de análise de armazenamento está habilitado. É altamente recomendável usar esse cabeçalho para correlacionar atividades do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Sobre o registro em log da Análise de Armazenamento e Log do Windows Azure: Usando logs para rastrear solicitações de armazenamento.

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 Especificando cabeçalhos condicionais para operações do serviço Blob.

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


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


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=

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

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

Para obter informações sobre códigos de status, consulte Status e códigos de erro.

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 obedecem à especificação de protocolo HTTP/1.1.

 

Sintaxe Descrição

ETag

A ETag do blob. Se a versão da solicitação for a 2011-08-18 ou mais recente, o valor de ETag será exibido entre aspas. É possível usar ETag para executar uma operação condicional Put Page especificando seu valor para o cabeçalho de solicitação If-Match ou If-None-Match.

Last-Modified

A data e a hora da última modificação no blob. O formato da data segue a RFC 1123. Para obter mais informações, consulte Representação de 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

Esse cabeçalho é retornado para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor desse cabeçalho é computado pelo serviço Blob; ele não é necessariamente o mesmo valor que pode ter sido especificado nos cabeçalhos de solicitação.

x-ms-blob-sequence-number

O número de sequência atual do blob da página.

x-ms-request-id

Esse cabeçalho identifica a solicitação que foi feita de forma exclusiva e pode ser usado para solucionar problemas na solicitação. Para obter mais informações, consulte Solucionando problemas de operações de API.

x-ms-version

Indica a versão do serviço Blob usado para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente.

Date

Um valor de data/hora UTC gerado pelo serviço que indica a hora em que a resposta foi iniciada.

Response Status:
HTTP/1.1 201 Created

Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
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

Essa operação poderá ser chamada pelo proprietário da conta e por qualquer pessoa com uma assinatura de acesso compartilhado que tenha permissão para gravar nesse blob ou em seu contêiner.

A operação Put Page 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. Não é possível chamá-la para criar um novo blob de páginas, nem em um blob de blocos. Chamar Put Page com um nome de blob que não exista atualmente retorna o erro BlobNotFound (código de status HTTP 404 – Não Encontrado).

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é 1 TB.

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 com a opção Update executa uma gravação no local no blob de páginas especificado. Todo o conteúdo na página especificada é substituído pela atualização.

ImportantImportante
Se o servidor atingir o tempo limite ou a conexão for fechada durante Put Page, 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 enviado com Put Page para uma operação de atualização poderá ter até 4 MB. 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 MB, o serviço retornará o código de status 413 (Entidade de Solicitação Muito Grande).

Operações de limpeza de página

Chamar Put Page com a opção Clear libera o espaço de armazenamento usado pela página especificada. As páginas que foram limpas não são mais rastreadas como parte do blob de páginas.

As páginas que já foram limpas não incorrem mais em um encargo na conta de armazenamento, pois seus recursos de armazenamento foram liberados. A única exceção a isso ocorrerá se houver instantâneos existentes do blob de páginas; as páginas em instantâneos incorrerão em um encargo se essas mesmas páginas não existirem mais como parte do blob de origem.

Gerenciando problemas de simultaneidade

O serviço de Blob lida com as gravações simultâneas com sobreposição de páginas sequencialmente: 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. 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 Blob de concessão para bloquear o blob em outras gravações por um período de um minuto, ou mais longo, se a concessão for renovada.

  • Você pode usar o número de sequência do blob para assegurar 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 poderá ser melhor para os clientes que exijam alta taxa de transferência para gravações de página. Ela é descrita com detalhes na próxima seção.

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

Quando uma chamada para Put Page atingir o tempo limite ou não retornar uma resposta, não haverá nenhuma forma de 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 Windows Azure, talvez a solicitação original seja processada depois que a solicitação repetida for bem-sucedida. A solicitação original atrasada poderá substituir outras atualizações e gerar um resultado inesperado. A sequência a seguir mostra como isso pode acontecer:

  1. Uma solicitação de Put Page 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 de 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, use o número de sequência do blob de páginas para assegurar que quando uma solicitação for repetida, a solicitação original não tenha êxito depois. Para fazer isso, você deve incrementar o número de sequência antes de repetir a solicitação original. Assim, você poderá usar os cabeçalhos do número de sequência condicional para assegurar que a solicitação falhe, caso seu número de sequência não corresponda ao esperado. A sequência a seguir mostra essa abordagem:

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

  2. Uma solicitação de Put Page para gravar o valor "X" na página 0 com o cabeçalho if-sequence-number-lt 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 if-sequence-number-lt definido como 2 é bem-sucedida.

  5. Uma solicitação repetida para gravar o valor "Y" na página 0 com if-sequence-number-lt definido como 2 é bem-sucedida.

  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 cabeçalho if-sequence-num-lt é definido como 1). 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".

Mostrar:
© 2014 Microsoft