Especificar cabeçalhos condicionais para operações do serviço Blob

Várias operações do serviço Blob suportam a utilização de cabeçalhos condicionais. Pode especificar cabeçalhos condicionais para realizar uma operação apenas se uma condição especificada tiver sido cumprida.

O serviço Blob segue a especificação do protocolo HTTP/1.1 para cabeçalhos condicionais.

Cabeçalhos Condicionais Suportados

Os cabeçalhos condicionais suportados estão descritos na tabela seguinte.

Cabeçalho condicional	Description
If-Modified-Since	Um DateTime valor. O formato de data segue RFC 1123. Para obter mais informações, veja Representação de valores de data/hora em cabeçalhos. Especifique este cabeçalho para executar a operação apenas se o recurso tiver sido modificado desde a hora especificada.
If-Unmodified-Since	Um DateTime valor. O formato de data segue RFC 1123. Para obter mais informações, veja Representação de valores de data/hora em cabeçalhos. Especifique este cabeçalho para executar a operação apenas se o recurso não tiver sido modificado desde a data/hora especificada.
If-Match	Um valor ETag. Especifique este cabeçalho para executar a operação apenas se a ETag do recurso corresponder ao valor especificado. Para as versões 2011-08-18 e mais recentes, a ETag pode ser especificada entre aspas.
If-None-Match	Um valor ETag ou o caráter universal (*). Especifique este cabeçalho para executar a operação apenas se a ETag do recurso não corresponder ao valor especificado. Para as versões 2011-08-18 e mais recentes, a ETag pode ser especificada entre aspas. Especifique o caráter universal (*) para executar a operação apenas se o recurso não existir e falhe a operação se existir.

Especificar Cabeçalhos Condicionais para Operações de Leitura do Serviço Blob na Versão 2013-08-15 ou Posterior

A partir da versão 2013-08-15, as operações Obter Blob e Obter Propriedades do Blob suportam vários cabeçalhos condicionais. Pode especificar qualquer combinação de cabeçalhos condicionais suportados. O serviço Blob avaliará estas condições de acordo com a seguinte expressão:

If-Match && If-Unmodified-Since && (If-None-Match || If-Modified-Since)

Também pode fornecer vários valores separados por vírgulas para If-Match e If-None-Match. Se especificar vários valores para If-Match, o serviço Blob efetua uma operação lógica OR em todos os valores fornecidos antes de avaliar toda a expressão. Se especificar vários valores para if-None-Match, o serviço efetua uma operação lógica AND antes de avaliar toda a expressão. Especificar vários valores para If-Modified-Since e If-Unmodified-Since não é suportado e resulta no código de erro 400 (Bad Request).

Esta funcionalidade está ativada para cumprir a especificação HTTP/1.1 e atender a cenários em que uma Rede de Entrega de Conteúdos (CDN) ou um servidor proxy adiciona cabeçalhos condicionais adicionais a um pedido de verificação. Seguem-se alguns exemplos de diferentes combinações de cabeçalhos condicionais.

Exemplo 1:

Considere um pedido Get Blob que contém os If-Match cabeçalhos e If-Modified-Since . A tabela seguinte indica o resultado se os cabeçalhos forem avaliados individualmente e o resultado se forem avaliados em combinação.

Cabeçalhos condicionais	Resultado se for avaliado individualmente	Resultado se avaliado em combinação
If-Match	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Modified-Since	200 (OK)	412 (Falha na Pré-condição)
If-Match	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Modified-Since	304 (Não Modificado)	412 (Falha na Pré-condição)
If-Match	200 (OK)	200 (OK)
If-Modified-Since	200 (OK)	200 (OK)
If-Match	200 (OK)	304 (Não Modificado)
If-Modified-Since	304 (Não Modificado)	304 (Não Modificado)

Exemplo 2:

Considere um pedido que If-None-Match contém e cabeçalhos If-Modified-Since .

Cabeçalhos condicionais	Resultado se for avaliado individualmente	Resultado se avaliado em combinação
If-None-Match	304 (Não Modificado)	200 (OK)
If-Modified-Since	200 (OK)	200 (OK)
If-None-Match	200 (OK)	200 (OK)
If-Modified-Since	200 (OK)	200 (OK)
If-None-Match	200 (OK)	200 (OK)
If-Modified-Since	304 (Não Modificado)	200 (OK)
If-None-Match	304 (Não Modificado)	304 (Não Modificado)
If-Modified-Since	304 (Não Modificado)	304 (Não Modificado)

Exemplo 3:

Considere um pedido que If-Modified-Sincecontém , If-Match e If-Unmodified-Since cabeçalhos.

Cabeçalhos condicionais	Resultado se for avaliado individualmente	Resultado se avaliado em combinação
If-Modified-Since	200 (OK)	412 (Falha na Pré-condição)
If-Match	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Unmodified-Since	200 (OK)	412 (Falha na Pré-condição)
If-Modified-Since	200 (OK)	412 (Falha na Pré-condição)
If-Match	200 (OK)	412 (Falha na Pré-condição)
If-Unmodified-Since	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Modified-Since	304 (Não Modificado)	412 (Falha na Pré-condição)
If-Match	200 (OK)	412 (Falha na Pré-condição)
If-Unmodified-Since	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Modified-Since	304 (Não Modificado)	304 (Não Modificado)
If-Match	200 (OK)	304 (Não Modificado)
If-Unmodified-Since	200 (OK)	304 (Não Modificado)

Exemplo 4:

Considere um pedido que If-Modified-Sincecontém , If-Unmodified-SinceIf-None-Matche If-Match cabeçalhos.

Combinação	Código de estado http individual	Obter o resultado do estado do Blob
If-Modified-Since	200 (OK)	200 (OK)
If-None-Match	200 (OK)	200 (OK)
If-Unmodified-Since	200 (OK)	200 (OK)
If-Match	200 (OK)	200 (OK)
If-Modified-Since	200 (OK)	412 (Falha na Pré-condição)
If-None-Match	304 (Não Modificado)	412 (Falha na Pré-condição)
If-Unmodified-Since	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Match	200 (OK)	412 (Falha na Pré-condição)
If-Modified-Since	200 (OK)	200 (OK)
If-None-Match	304 (Não Modificado)	200 (OK)
If-Unmodified-Since	200 (OK)	200 (OK)
If-Match	200 (OK)	200 (OK)
If-Modified-Since	304 (Não Modificado)	412 (Falha na Pré-condição)
If-None-Match	200 (OK)	412 (Falha na Pré-condição)
If-Unmodified-Since	200 (OK)	412 (Falha na Pré-condição)
If-Match	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Modified-Since	304 (Não Modificado)	412 (Falha na Pré-condição)
If-None-Match	200 (OK)	412 (Falha na Pré-condição)
If-Unmodified-Since	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Match	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Modified-Since	304 (Não Modificado)	200 (OK)
If-None-Match	200 (OK)	200 (OK)
If-Unmodified-Since	200 (OK)	200 (OK)
If-Match	200 (OK)	200 (OK)
If-Modified-Since	304 (Não Modificado)	412 (Falha na Pré-condição)
If-None-Match	304 (Não Modificado)	412 (Falha na Pré-condição)
If-Unmodified-Since	412 (Falha na Pré-condição)	412 (Falha na Pré-condição)
If-Match	200 (OK)	412 (Falha na Pré-condição)

Especificar Cabeçalhos Condicionais para Operações de Leitura em Versões Anteriores a 2013-08-15 e para Operações de Escrita (Todas as Versões)

Ao chamar operações de leitura do serviço Blob (Obter Blob e Obter Propriedades do Blob) com versões anteriores a 2013-08-15 e ao chamar qualquer operação de escrita independentemente da versão, tenha em atenção o seguinte:

• Se um pedido especificar os If-None-Match cabeçalhos e If-Modified-Since , o pedido é avaliado com base nos critérios especificados em If-None-Match.

• Se um pedido especificar os If-Match cabeçalhos e If-Unmodified-Since , o pedido é avaliado com base nos critérios especificados em If-Match.

• Com exceção das duas combinações de cabeçalhos condicionais listadas acima, um pedido pode especificar apenas um único cabeçalho condicional. Especificar mais de um cabeçalho condicional resulta no código de estado 400 (Bad Request).

• Se uma resposta incluir uma ETag, verifique a versão do pedido e a resposta antes de processar a ETag. Por exemplo, a versão 2011-08-18 e posterior devolve uma ETag citada, mas as versões mais antigas não. Certifique-se de que a sua aplicação pode processar ambos os formatos de ETag antes de serem avaliados.

• O RFC 2616 permite vários valores de ETag num único cabeçalho, mas os pedidos ao serviço Blob só podem incluir um valor ETag. Especificar mais do que um valor de ETag resulta no código de estado 400 (Bad Request).

Operações que Suportam Cabeçalhos Condicionais

As operações que suportam cabeçalhos condicionais estão descritas na tabela seguinte.

Operação REST	Tipo de operação	Cabeçalhos condicionais suportados
Bloco de Acréscimo (versão 2015-02-21 e posterior)	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Anexar Bloco do URL (versão 2018-11-09 e posterior)	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Copiar Blob	Leitura e Escrita	Para condições no blob de destino: - If-Modified-Since - If-Unmodified-Since - If-Match - If-None-Match - x-ms-if-tags Para condições no blob de origem: - x-ms-source-if-modified-since - x-ms-source-if-unmodified-since - x-ms-source-if-match - x-ms-source-if-none-match - x-ms-source-if-tags
Eliminar Blob	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Eliminar Contentor	Escrita	If-Modified-Since If-Unmodified-Since
Obter Blob	Leitura	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Obter Metadados de Blobs	Leitura	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Get Blob Properties (Obter Propriedades do Blob)	Leitura	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Obter Etiquetas de Blobs (versão 2019-12-12 e posterior)	Leitura	x-ms-if-tags
Obter Lista de Blocos	Leitura	x-ms-if-tags
Obter Intervalos de Páginas	Leitura	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Blob de Concessão	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Contentor de Concessão	Escrita	If-Modified-Since If-Unmodified-Since
Colocar o Blob a partir do URL	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match Para condições no blob de origem: - x-ms-source-If-Modified-Since - x-ms-source-if-Unmodified-Since - x-ms-source-If-Match - x-ms-source-If-None-Match
Colocar o Blob	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Colocar Bloco a Partir do URL (versão 2018-03-28 e posterior)	Escrita	x-ms-source-If-Modified-Since x-ms-source-If-Unmodified-Since x-ms-source-If-Match x-ms-source-If-None-Match
Put Block List	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Colocar Página	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Colocar Página a Partir do URL (versão 2018-11-09 e posterior)	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Definir Metadados de Blobs	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Definir Propriedades do Blob	Escrita	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Definir ACL de Contentor	Escrita	If-Modified-Since If-Unmodified-Since
Definir Metadados de Contentor	Escrita	If-Modified-Since
Definir Etiquetas de Blobs (versão 2019-12-12 e posterior)	Escrita	x-ms-if-tags
Definir Camada de Blob	Ler ou Escrever	x-ms-if-tags
Blob de Instantâneo	Leitura	If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags
Definir Política de Imutabilidade de Blobs	Escrita	If-Unmodified-Since

As seguintes operações de dados do serviço Blob não suportam atualmente cabeçalhos condicionais:

• Abortar Blob de Cópia

• Criar Contentor

• Localizar Blobs por Etiquetas

• Obter ACL de Contentor

• Obter Metadados de Contentor

• Obter Propriedades do Contentor

• Listar Blobs

• Listar Contentores

• Colocar Bloco

• Anular eliminação do Blob

Códigos de Resposta HTTP para Operações que Suportam Cabeçalhos Condicionais

Se o pedido incluir um cabeçalho condicional e a condição especificada não for cumprida pelo recurso que está a ser pedido, o serviço Blob devolve um código de resposta HTTP. Os códigos de resposta devolvidos estão de acordo com a especificação do protocolo HTTP/1.1 (RFC 2616).

Os métodos na biblioteca de cliente .NET do Azure convertem estes códigos de resposta de erro num objeto StorageException.

Operações de Leitura

A tabela seguinte indica os códigos de resposta devolvidos para uma condição não cumprida para cada cabeçalho condicional quando a operação é uma operação de leitura. As operações de leitura utilizam os verbos GET ou HEAD.

Cabeçalho condicional	Código de resposta se a condição não tiver sido cumprida
If-Modified-Since	Não Modificado (304 (Não Modificado))
If-Unmodified-Since	Falha na Pré-condição (412 (Falha na Pré-condição))
If-Match	Falha na Pré-condição (412 (Falha na Pré-condição))
If-None-Match	Não Modificado (304 (Não Modificado))

Veja os exemplos acima para obter resultados ao utilizar vários cabeçalhos com as versões 2013-08-15 ou posterior.

Operações de Escrita

A tabela seguinte indica os códigos de resposta devolvidos para uma condição não cumprida para cada cabeçalho condicional quando a operação é uma operação de escrita. As operações de escrita utilizam os verbos PUT ou DELETE.

Cabeçalho condicional	Código de resposta se a condição não tiver sido cumprida
If-Modified-Since	Falha na Pré-condição (412 (Falha na Pré-condição))
If-Unmodified-Since	Falha na Pré-condição (412 (Falha na Pré-condição))
If-Match	Falha na Pré-condição (412 (Falha na Pré-condição))
If-None-Match	Falha na Pré-condição (412 (Falha na Pré-condição))

Operações de Cópia

A tabela seguinte indica os códigos de resposta devolvidos para uma condição não cumprida para cada cabeçalho condicional quando a operação é uma operação de cópia. A operação Copiar Blob utiliza os verbos PUT.

Cabeçalho condicional	Código de resposta se a condição não tiver sido cumprida
If-Modified-Since	Falha na Pré-condição (412 (Falha na Pré-condição))
If-Unmodified-Since	Falha na Pré-condição (412 (Falha na Pré-condição))
If-Match	Falha na Pré-condição (412 (Falha na Pré-condição))
If-None-Match	Falha na Pré-condição (412 (Falha na Pré-condição))
x-ms-source-if-modified-since	Precondition Failed (412 (Precondition Failed))
x-ms-source-if-unmodified-since	Precondition Failed (412 (Precondition Failed))
x-ms-source-if-match	Precondition Failed (412 (Precondition Failed))
x-ms-source-if-none-match	Precondition Failed (412 (Precondition Failed))

Operações Condicionais de Etiquetas

Além dos cabeçalhos condicionais HTTP padrão suportados pelo serviço Blob, várias operações também suportam condições em relação às etiquetas num recurso de blob.

Cabeçalho condicional	Description
x-ms-if-tags	Versão 2019-12-12 e mais recente. Um TagsPredicate valor. Especifique este cabeçalho para executar a operação apenas se o predicado for avaliado em relação às true etiquetas do blob.
x-ms-source-if-tags	Versão 2019-12-12 e mais recente. Aplica-se apenas a Copiar Blob. Um TagsPredicate valor. Especifique este cabeçalho para executar a operação apenas se o predicado for avaliado em relação às true etiquetas do blob de origem.

Se o x-ms-if-tags cabeçalho condicional ou x-ms-source-if-tags estiver presente num pedido e o TagsPredicate for avaliado como false, o serviço Blob devolverá o código de erro 412 (Falha de Pré-condição) para a operação.

O autor da chamada tem de ter permissão para ler as etiquetas num blob para utilizar os x-ms-if-tags cabeçalhos condicionais ou x-ms-source-if-tags .

Sintaxe de Predicado de Etiquetas

O serviço Blob suporta um subconjunto da gramática da cláusula WHERE do SQL ANSI para o valor do TagsPredicate cabeçalho. São suportados os seguintes operadores:

Operador	Descrição	Exemplo
=	Igual	Status = 'In Progress'
<>	Diferente	Status <> 'Done'
>	Maior que	LastModified > '2018-06-18 20:51:26Z'
>=	Maior ou igual a	Priority >= '05'
<	Menor que	Age < '032'
<=	Menor ou igual a	Reviewer <= 'Smith'
AND	Lógica e	Name > 'C' AND Name < 'D' Age > '032' AND Age < '100'
OR	Lógico ou	Status = 'Done' or LastModified > '2018-06-18 20:51:26Z'

Todos os valores de etiqueta são cadeias e os operadores relacionais binários suportados utilizam uma ordenação lexicográfica dos valores da etiqueta. Para suportar tipos de dados que não sejam de cadeia, incluindo números e datas, tem de ser utilizada a preenchimento adequada e a formatação sortível. Os valores das etiquetas têm de estar entre aspas.

Se os nomes das etiquetas forem identificadores de SQL normais, poderão estar presentes sem escapar; se contiverem carateres especiais, têm de ser delimitados com aspas duplas (por exemplo, "TagName" = "TagValue").

As expressões podem incluir comparações para vários nomes e valores de etiquetas. Os parênteses (( e )) podem ser utilizados para agrupar expressões lógicas e controlar a ordem canónica da operação. Um TagsPredicate pode incluir, no máximo, dez (10) operações lógicas.

O serviço de armazenamento rejeitará qualquer pedido que contenha uma expressão inválida com o código de erro 400 (Pedido Incorreto).

Consulte também

Conceitos do Serviço blob