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 dos valores de data/hora nos 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 dos valores de data/hora nos 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 o ETag do recurso corresponder ao valor especificado. Para as versões 2011-08-18 e mais recentes, o ETag pode ser especificado em aspas. |
If-None-Match |
Um valor ETag ou o caráter universal (*). Especifique este cabeçalho para executar a operação apenas se o ETag do recurso não corresponder ao valor especificado. Para as versões 2011-08-18 e mais recentes, o ETag pode ser especificado em aspas. Especifique o caráter universal (*) para efetuar a operação apenas se o recurso não existir e falhar a operação se existir. |
Especificar Cabeçalhos Condicionais para Operações de Leitura do Serviço de Blobs na Versão 2013-08-15 ou Posterior
A partir da versão 2013-08-15, as operações Obter Propriedades do Blob e Obter 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 para 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 voo. Seguem-se alguns exemplos de diferentes combinações de cabeçalhos condicionais.
Exemplo 1:
Considere um pedido Obter Blob que contenha 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 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 If-Modified-Since cabeçalhos.
| Cabeçalhos condicionais | Resultado se 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 contém If-Modified-Sincee If-Unmodified-SinceIf-Match cabeçalhos.
| Cabeçalhos condicionais | Resultado se 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-Sincecontenha , If-None-MatchIf-Unmodified-Since e 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 Propriedades do Blob e Obter Blobs) 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-Matchcabeçalhos eIf-Modified-Since, em seguida, o pedido é avaliado com base nos critérios especificados emIf-None-Match.Se um pedido especificar os
If-Matchcabeçalhos eIf-Unmodified-Since, em seguida, o pedido é avaliado com base nos critérios especificados emIf-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 um ETag, verifique a versão do pedido e da resposta antes de processar o ETag. Por exemplo, a versão 2011-08-18 e posterior devolve um ETag citado, mas as versões mais antigas não. Certifique-se de que a sua aplicação pode processar ambos os formatos 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 de um valor ETag resulta no código de estado 400 (
Bad Request).
Operações de Suporte de 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 |
|
Bloco de Acréscimo 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 Bloqueios | 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 Blob 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 | Escrita | 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:
Http Response Codes for Operations Support Conditional Headers (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 |
Precondition Failed (412 (Precondition Failed)) |
If-Match |
Precondition Failed (412 (Precondition Failed)) |
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 |
Precondition Failed (412 (Precondition Failed)) |
If-Unmodified-Since |
Precondition Failed (412 (Precondition Failed)) |
If-Match |
Precondition Failed (412 (Precondition Failed)) |
If-None-Match |
Precondition Failed (412 (Precondition Failed)) |
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 |
Precondition Failed (412 (Precondition Failed)) |
If-Unmodified-Since |
Precondition Failed (412 (Precondition Failed)) |
If-Match |
Precondition Failed (412 (Precondition Failed)) |
If-None-Match |
Precondition Failed (412 (Precondition Failed)) |
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).