Especificando cabeçalhos condicionais para operações de serviço blob
Várias operações do serviço Blob oferecem suporte ao uso de cabeçalhos condicionais. Você pode especificar cabeçalhos condicionais para realizar uma operação apenas se uma condição especificada foi atendida.
O serviço Blob segue a especificação de protocolo HTTP/1.1 para cabeçalhos condicionais.
Cabeçalhos condicionais com suporte
Os cabeçalhos condicionais com suporte são descritos na tabela a seguir.
| Cabeçalho condicional | Descrição |
|---|---|
If-Modified-Since |
Um valor DateTime. O formato da data segue RFC 1123. Para obter mais informações, consulte Representação de valores de data e hora em cabeçalhos. Especifique esse cabeçalho para executar a operação somente se o recurso tiver sido modificado desde a hora especificada. |
If-Unmodified-Since |
Um valor DateTime. O formato da data segue RFC 1123. Para obter mais informações, consulte Representação de valores de data e hora em cabeçalhos. Especifique esse cabeçalho para executar a operação somente se o recurso não tiver sido modificado desde a data/hora especificada. |
If-Match |
Um valor de ETag. Especifique esse cabeçalho para executar a operação somente se a ETag do recurso corresponder ao valor especificado. Para versões 2011-08-18 e mais recente, a ETag pode ser especificada entre aspas. |
If-None-Match |
Um valor de ETag ou o caractere curinga (*). Especifique esse cabeçalho para executar a operação somente se a ETag do recurso não corresponder ao valor especificado. Para versões 2011-08-18 e mais recente, a ETag pode ser especificada entre aspas. Especifique o caractere curinga (*) para executar a operação somente se o recurso não existir e não executar a operação se ele existir. |
Especificando 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 Propriedades de Blob e Obter Blob dão suporte a vários cabeçalhos condicionais. Você pode especificar qualquer combinação de cabeçalhos condicionais com suporte. 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)
Você também pode fornecer vários valores separados por vírgulas para If-Match e If-None-Match. Se você especificar vários valores para If-Match, o serviço Blob executará uma operação lógica OR em todos os valores fornecidos antes de avaliar a expressão inteira. Se você especificar vários valores para if-None-Match, o serviço executará uma operação lógica AND antes de avaliar a expressão inteira. Especificar vários valores para If-Modified-Since e If-Unmodified-Since não tem suporte e resulta no código de erro 400 (Bad Request).
Esse recurso está habilitado para cumprir a especificação HTTP/1.1 e atender a cenários em que uma CDN (Rede de Distribuição de Conteúdo) ou um servidor proxy adiciona cabeçalhos condicionais adicionais a uma solicitação de bordo. A seguir estão alguns exemplos de combinações diferentes de cabeçalhos condicionais.
Exemplo 1:
Considere uma solicitação Obter Blob que contém os If-Match cabeçalhos e If-Modified-Since . A tabela a seguir indica o resultado se os cabeçalhos são avaliados individualmente, e o resultado se são avaliados juntos.
| Cabeçalhos condicionais | Resultado se for avaliado individualmente | Resultado se for 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 (sem modificação) | 412 (falha na pré-condição) |
If-Match |
200 (OK) | 200 (OK) |
If-Modified-Since |
200 (OK) | 200 (OK) |
If-Match |
200 (OK) | 304 (sem modificação) |
If-Modified-Since |
304 (sem modificação) | 304 (sem modificação) |
Exemplo 2:
Considere uma solicitação os cabeçalhos If-None-Match e If-Modified-Since.
| Cabeçalhos condicionais | Resultado se for avaliado individualmente | Resultado se for avaliado em combinação |
|---|---|---|
If-None-Match |
304 (sem modificação) | 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 (sem modificação) | 200 (OK) |
If-None-Match |
304 (sem modificação) | 304 (sem modificação) |
If-Modified-Since |
304 (sem modificação) | 304 (sem modificação) |
Exemplo 3:
Considere uma solicitação os cabeçalhos If-Modified-Since, If-Match e If-Unmodified-Since.
| Cabeçalhos condicionais | Resultado se for avaliado individualmente | Resultado se for 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 (sem modificação) | 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 (sem modificação) | 304 (sem modificação) |
If-Match |
200 (OK) | 304 (sem modificação) |
If-Unmodified-Since |
200 (OK) | 304 (sem modificação) |
Exemplo 4:
Considere uma solicitação os cabeçalhos If-Modified-Since, If-None-Match, If-Unmodified-Since e If-Match.
| Combinação | Código de status de HTTP individual | Obter o resultado de status de 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 (sem modificação) | 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 (sem modificação) | 200 (OK) |
If-Unmodified-Since |
200 (OK) | 200 (OK) |
If-Match |
200 (OK) | 200 (OK) |
If-Modified-Since |
304 (sem modificação) | 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 (sem modificação) | 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 (sem modificação) | 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 (sem modificação) | 412 (falha na pré-condição) |
If-None-Match |
304 (sem modificação) | 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) |
Especificando cabeçalhos condicionais para operações de leitura em versões anteriores a 2013-08-15 e para operações de gravação (todas as versões)
Ao chamar operações de leitura do serviço Blob (Obter Propriedades de Blob e Obter Blob) com versões anteriores a 2013-08-15 e ao chamar qualquer operação de gravação, independentemente da versão, tenha em mente o seguinte:
Se uma solicitação especificar os cabeçalhos
If-None-MatcheIf-Modified-Since, a solicitação será avaliada com base nos critérios especificados emIf-None-Match.Se uma solicitação especificar os cabeçalhos
If-MatcheIf-Unmodified-Since, a solicitação será avaliada com base nos critérios especificados emIf-Match.Com exceção das duas combinações de cabeçalhos condicionais listados acima, uma solicitação poderá especificar apenas um único cabeçalho condicional. A especificação de mais de um cabeçalho condicional resulta no código de status 400 (
Bad Request).Se uma resposta incluir uma ETag, verifique a versão da solicitação e a resposta antes de processar a ETag. Por exemplo, a versão 2011-08-18 e posterior retornam uma ETag entre aspas, mas versões anteriores não. Certifique-se de que o aplicativo possa processar ambos os formatos de ETag antes de serem avaliadas.
O RFC 2616 permite vários valores de ETag em um único cabeçalho, mas as solicitações para o serviço Blob só podem incluir um valor de ETag. A especificação de mais de um valor de ETag resulta no código de status 400 (
Bad Request).
Operações que oferecem suporte a cabeçalhos condicionais
As operações que dão suporte a cabeçalhos condicionais são descritos na tabela a seguir.
| Operação REST | Tipo de operação | Cabeçalhos condicionais com suporte |
|---|---|---|
|
Acrescentar Bloco (versão 2015-02-21 e posterior) |
Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
|
Acrescentar Bloco da URL (versão 2018-11-09 e posterior) |
Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Copiar blob | Leitura e gravação | 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 |
| Excluir blob | Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Delete Container | Gravar |
If-Modified-Since If-Unmodified-Since |
| Get Blob | Ler |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Get Blob Metadata | Ler |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Obter propriedades do blob | Ler |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
|
Obter marcas de blob (versão 2019-12-12 e posterior) |
Ler | x-ms-if-tags |
| Get Block List | Ler | x-ms-if-tags |
| OBter Intervalos de Página | Ler |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Concessão de blob | Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Lease Container | Gravar |
If-Modified-Since If-Unmodified-Since |
| Put Blob From URL | Gravar |
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 |
| Put Blob | Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
|
Colocar Bloco da URL (versão 2018-03-28 e posterior) |
Gravar |
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 | Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Colocar Página | Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
|
Colocar Página da URL (versão 2018-11-09 e posterior) |
Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Set Blob Metadata | Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Set Blob Properties | Gravar |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Definir ACL do contêiner | Gravar |
If-Modified-Since If-Unmodified-Since |
| Definir Metadados de Contêiner | Gravar | If-Modified-Since |
|
Definir marcas de blob (versão 2019-12-12 e posterior) |
Gravar | x-ms-if-tags |
| Definir camada do blob | Gravar | x-ms-if-tags |
| Blob de instantâneo | Ler |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Definir Política de Imutabilidade de Blob | Gravar | If-Unmodified-Since |
As seguintes operações de dados de serviço Blob atualmente não dão suporte a cabeçalhos condicionais:
Códigos de resposta HTTP para operações que dão suporte a cabeçalhos condicionais
Se a solicitação incluir um cabeçalho condicional e a condição especificada não for atendida pelo recurso que está sendo solicitado, o serviço Blob retornará um código de resposta HTTP. Os códigos de resposta são retornados de acordo com a especificação do protocolo HTTP/1.1 (RFC 2616).
Os métodos na biblioteca de clientes do .NET do Azure convertem esses códigos de resposta de erro em um objeto StorageException.
Operações de leitura
A tabela a seguir indica os códigos de resposta retornados para uma condição não atendida para cada cabeçalho condicional quando a operação é de leitura. As operações de leitura usam os verbos GET ou HEAD.
| Cabeçalho condicional | Código de resposta se a condição não foi atendida |
|---|---|
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)) |
Consulte os exemplos anteriores para obter resultados ao usar vários cabeçalhos com versões 2013-08-15 ou posterior.
Operações de gravação
A tabela a seguir indica os códigos de resposta retornados para uma condição não atendida para cada cabeçalho condicional quando a operação é de gravação. As operações de gravação usam os verbos PUT ou DELETE.
| Cabeçalho condicional | Código de resposta se a condição não foi atendida |
|---|---|
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 a seguir indica os códigos de resposta retornados para uma condição não atendida para cada cabeçalho condicional quando a operação é de cópia. A operação Copiar Blob usa os verbos PUT.
| Cabeçalho condicional | Código de resposta se a condição não foi atendida |
|---|---|
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 |
Falha na pré-condição (412 (falha na pré-condição)) |
x-ms-source-if-unmodified-since |
Falha na pré-condição (412 (falha na pré-condição)) |
x-ms-source-if-match |
Falha na pré-condição (412 (falha na pré-condição)) |
x-ms-source-if-none-match |
Falha na pré-condição (412 (falha na pré-condição)) |
Operações condicionais de marcas
Além dos cabeçalhos condicionais HTTP padrão compatíveis com o serviço Blob, várias operações também dão suporte a condições em relação às marcas em um recurso de blob.
| Cabeçalho condicional | Descrição |
|---|---|
x-ms-if-tags |
Versão 2019-12-12 e mais recente. Um valor TagsPredicate. Especifique true esse cabeçalho para executar a operação somente se o predicado for avaliado como em relação às marcas do blob. |
x-ms-source-if-tags |
Versão 2019-12-12 e mais recente. Aplica-se somente a Copiar Blob. Um valor TagsPredicate. Especifique true esse cabeçalho para executar a operação somente se o predicado for avaliado como em relação às marcas do blob de origem. |
Se o x-ms-if-tags cabeçalho condicional ou x-ms-source-if-tags estiver presente em uma solicitação e o TagsPredicate for avaliado como false, o serviço Blob retornará o código de erro 412 (Falha de Pré-condição) para a operação.
O chamador deve ter permissão para ler as marcas em um blob para usar os x-ms-if-tags cabeçalhos condicionais ou x-ms-source-if-tags .
Sintaxe de predicado de marcas
O serviço Blob dá suporte a um subconjunto da gramática da cláusula ANSI SQL WHERE para o valor do TagsPredicate cabeçalho. Há suporte para 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 | Priority >= '05' |
< |
Menor que | Age < '032' |
<= |
Inferior ou igual | Reviewer <= 'Smith' |
AND |
AND lógico | Name > 'C' AND Name < 'D'Age > '032' AND Age < '100' |
OR |
OR lógico | Status = 'Done' or LastModified > '2018-06-18 20:51:26Z' |
Todos os valores de marca são cadeias de caracteres e os operadores relacionais binários com suporte usam uma classificação lexicográfica dos valores de marca. Para dar suporte a tipos de dados não cadeia de caracteres, incluindo números e datas, o preenchimento apropriado e a formatação classificável devem ser empregados. Os valores de marca devem ser colocados entre aspas simples.
Se os nomes de marca forem identificadores SQL regulares, eles poderão estar presentes sem escape; se contiverem caracteres especiais, eles deverão ser delimitados com aspas duplas (por exemplo, "TagName" = 'TagValue').
As expressões podem incluir comparações para vários nomes de marcas e valores. Parênteses (( e )) podem ser usados 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 solicitação que contenha uma expressão inválida com o código de erro 400 (Solicitação Incorreta).