Encontre Blobs por Tags

A Find Blobs by Tags operação encontra todas as bolhas na conta de armazenamento cujas etiquetas correspondem a uma determinada expressão de pesquisa.

Pedir

O Find Blobs by Tags pedido pode ser construído da seguinte forma. HTTPS é recomendado. Substitua a minha conta pelo nome da sua conta de armazenamento:

GET Método Request URI Versão HTTP
https://myaccount.blob.core.windows.net?comp=blobs&where=<expression> HTTP/1.1

Parâmetros URI

Os seguintes parâmetros adicionais podem ser especificados no pedido URI.

Parâmetro Descrição
expression Obrigatório. Filtra o resultado definido apenas para incluir bolhas cujas etiquetas correspondem à expressão especificada.

Consulte as Observações para obter mais informações sobre como construir esta expressão.
marker Opcional. Um valor de corda que identifica a parte do resultado definido para ser devolvido com a operação seguinte. A operação devolve um valor de marcador dentro do organismo de resposta se o resultado definido não estiver completo. O valor do marcador pode então ser utilizado numa chamada posterior para solicitar o próximo conjunto de itens.

O valor do marcador é opaco para o cliente.
maxresults Opcional. Especifica o número máximo de bolhas para devolver. Se o pedido não especificar maxresults ou especificar um valor superior a 5.000, o servidor devolverá até 5.000 itens.

Definir maxresults um valor inferior ou igual a zero resulta no código de resposta de erro 400 (Mau Pedido).
timeout Opcional. O timeout parâmetro é expresso em segundos. Para obter mais informações, consulte os intervalos de definição para operações de serviço de blob.

Pedido cabeçalhos

A tabela seguinte descreve os cabeçalhos de pedido necessários e opcionais.

Cabeçalho do Pedido Description
Authorization Obrigatório. Especifica o esquema de autorização, nome da conta e assinatura. Para mais informações, consulte Os pedidos autorizados à Azure Armazenamento.
Date ou x-ms-date Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para mais informações, consulte Os pedidos autorizados à Azure Armazenamento.
x-ms-version Requerido para todos os pedidos autorizados, opcional para pedidos anónimos. Especifica a versão da operação a utilizar para este pedido. Para mais informações, consulte a versão para os Serviços Azure Armazenamento.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres de 1 KiB que é gravado nos registos de análise quando o registo de análise de armazenamento está ativado. Recomenda-se a utilização deste cabeçalho para correlacionar as atividades do lado do cliente com os pedidos recebidos pelo servidor. Para obter mais informações, consulte Sobre Armazenamento Analítica registação e registo de registos Azure: Utilização de Registos para rastrear pedidos de Armazenamento.

Corpo do Pedido

Nenhum.

Resposta

A resposta inclui um código de estado HTTP, cabeçalhos de resposta e corpo de resposta.

Código de Estado

Uma operação bem sucedida devolve o código de estado 200 (OK).

Para obter informações sobre códigos de estado, consulte códigos de estado 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 standard estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta Descrição
Content-Type application/xml
Content-Length O tamanho do documento XML devolvido, em bytes
x-ms-request-id Este cabeçalho identifica exclusivamente o pedido que foi feito e pode ser usado para resolver problemas no pedido. Para obter mais informações, consulte operações de API de resolução de problemas.
x-ms-version Indica a versão do serviço Blob utilizado para executar o pedido.
Date Uma data/valor de hora UTC gerado pelo serviço que indica o momento em que a resposta foi iniciada.
x-ms-client-request-id Este cabeçalho pode ser usado para resolver pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho se estiver presente no pedido e o valor for no máximo 1024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, este cabeçalho não estará presente na resposta.

Corpo de Resposta

Na versão 2020-04-08 e mais recente, as etiquetas correspondentes da blob são encapsuladas dentro de um elemento Tags. O formato do corpo de resposta é o seguinte:

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint=http://myaccount.blob.core.windows.net/>  
  <Where>string-value</Where>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</Name>  
      <ContainerName>container-name</ContainerName>  
      <Tags>
        <TagSet>
          <Tag>
            <Key>matching-tag-name1</Key>
            <Value>matching-tag-value1</Value>
          </Tag>
          <Tag>
            <Key>matching-tag-name2</Key>
            <Value>matching-tag-value2</Value>
          </Tag>
        </TagSet>
      </Tags> 
    </Blob>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>  

O corpo de resposta é um documento UTF-8 XML bem formado.

Autorização

Esta operação pode ser chamada pelo proprietário da conta e por qualquer pessoa com uma Assinatura de Acesso Partilhado que tenha permissão para encontrar bolhas por tags (a f permissão SAS).

Além disso, os utilizadores do RBAC com a Microsoft.Storage/storageAccounts/blobServices/containers/blobs/filter/action permissão podem realizar esta operação.

Observações

A Find Blobs by Tags operação é suportada na versão REST API 2019-12-12 e posteriormente.

O índice secundário usado é Find Blobs by Tags eventualmente consistente. As atualizações às etiquetas blob através de Set Blob Tags muitas não são imediatamente visíveis para as Find Blobs by Tags operações.

Construção de uma expressão de pesquisa

O where parâmetro URI encontra bolhas na conta de armazenamento cujas etiquetas correspondem a uma determinada expressão. A expressão deve avaliar true para que uma bolha seja devolvida no conjunto de resultados.

O serviço de armazenamento suporta um subconjunto da gramática da cláusula ANSI SQL WHERE para o valor do parâmetro de where=<expression> consulta. São apoiados os seguintes operadores:

Operador Descrição Exemplo
= Igual &where=Status = 'In Progress'
> Maior que &where=LastModified > '2018-06-18 20:51:26Z'
>= Maior ou igual a &where=Priority >= '05'
< Menor que &where=Age < '032'
<= Menor ou igual a &where=Reviewer <= 'Smith'
AND Lógico e &where=Name > 'C' AND Name < 'D'
&where=Age > '032' AND Age < '100'
@container Especificar um recipiente &where=@container='mycontainer' AND Name = 'C'

Nota: o valor do where parâmetro URI deve ser devidamente codificado URI (incluindo espaços e operadores). Os exemplos acima omitem para a legibilidade.

Todos os valores da etiqueta são cordas, e os operadores binários suportados usam uma triagem lexicográfica dos valores da etiqueta. Para suportar tipos de dados não-cordas, incluindo números e datas, deve ser utilizado um acolchoamento adequado e formatação ordenada. Os valores da etiqueta devem ser incluídos em cotações únicas.

Se os nomes de etiquetas forem identificadores SQL regulares, podem estar presentes sem escapar; se contiverem caracteres especiais, devem ser delimitados com citações duplas (por exemplo, "TagName" = 'TagValue'). Recomenda-se sempre que se coloquem sempre os nomes das etiquetas em ações duplas.

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

Ver também

Gerir e localizar dados no Armazenamento de Blobs do Azure com o Índice de Blobs
Autorizar pedidos à Azure Armazenamento
Códigos de Estado e erro
Códigos de Erro do Serviço de Blobs