Compartilhar via

Localizar Blobs por Marcas

  • Artigo

A Find Blobs by Tags operação localiza todos os blobs na conta de armazenamento cujas marcas correspondem a uma expressão de pesquisa.

Solicitação

Você pode construir a solicitação da Find Blobs by Tags seguinte maneira. Recomendamos HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento.

URI de solicitação do método GET Versão HTTP
https://myaccount.blob.core.windows.net?comp=blobs&where=<expression> HTTP/1.1

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no URI da solicitação:

Parâmetro Descrição
expression Obrigatórios. Filtra o conjunto de resultados para incluir apenas blobs cujas marcas correspondem à expressão especificada.

Para obter mais informações sobre como construir essa expressão, consulte Comentários.
marker Opcional. Um valor de cadeia de caracteres que identifica a parte do conjunto de resultados a ser retornado com a próxima operação. A operação retornará um valor de marcador dentro do corpo da resposta se o conjunto de resultados retornado não tiver sido concluído. Em seguida, o valor do marcador pode ser usado em uma chamada subsequente para solicitar o próximo conjunto de itens.

O valor do marcador é opaco ao cliente.
maxresults Opcional. Especifica o número máximo de blobs a serem retornados. Se a solicitação não especificar maxresults ou especificar um valor maior que 5.000, o servidor retornará até 5.000 itens. Se houver resultados adicionais a serem retornados, o serviço retornará um token de continuação no NextMarker elemento de resposta. Em determinados casos, o serviço pode retornar menos resultados do que maxresults o especificado. O serviço também pode retornar um token de continuação.

A configuração de maxresults com um valor menor ou igual a zero resulta em um código de resposta de erro 400 (Solicitação Incorreta).
timeout Opcional. Expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de Armazenamento de Blobs.

Cabeçalhos da solicitação

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

Cabeçalho da solicitação Descrição
Authorization Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Necessário para todas as solicitações autorizadas, mas opcional para solicitações anônimas. 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.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres kib (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor.

Corpo da solicitação

Nenhum.

Resposta

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

Código de status

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

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

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta Descrição
Content-Type Especifica application/xml como o tipo de conteúdo.
Content-Length Especifica o tamanho do documento XML retornado, em bytes.
x-ms-request-id Identifica exclusivamente a solicitação que foi feita. Você pode usá-lo para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API.
x-ms-version Indica a versão de Armazenamento de Blobs do Azure que foi usada para executar a solicitação.
Date Um valor de data/hora UTC que indica a hora em que o serviço enviou a resposta.
x-ms-client-request-id Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho será igual ao valor do x-ms-client-request-id cabeçalho, se ele estiver presente na solicitação e o valor for no máximo 1.024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Corpo da resposta

Na versão 2020-04-08 e posterior, as marcas correspondentes do blob são encapsuladas em um Tags elemento . Formato do corpo da resposta:

<?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 da resposta é um documento XML UTF-8 bem formado.

Autorização

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. Você pode autorizar a Find Blobs by Tags operação conforme descrito abaixo.

Importante

A Microsoft recomenda usar Microsoft Entra ID com identidades gerenciadas para autorizar solicitações para o Armazenamento do Azure. Microsoft Entra ID fornece segurança superior e facilidade de uso em comparação com a autorização de Chave Compartilhada.

O Armazenamento do Azure dá suporte ao uso de Microsoft Entra ID para autorizar solicitações para dados de blob. Com Microsoft Entra ID, você pode usar o RBAC (controle de acesso baseado em função) do Azure para conceder permissões a uma entidade de segurança. A entidade de segurança pode ser um usuário, um grupo, uma entidade de serviço de aplicativo ou uma identidade gerenciada do Azure. A entidade de segurança é autenticada por Microsoft Entra ID para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço de Blob.

Para saber mais sobre a autorização usando Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.

Permissões

Veja abaixo a ação RBAC necessária para um usuário Microsoft Entra, grupo, identidade gerenciada ou entidade de serviço para chamar a Find Blobs by Tags operação e a função rbac interna do Azure com privilégios mínimos que inclui esta ação:

Para saber mais sobre como atribuir funções usando o RBAC do Azure, confira Atribuir uma função do Azure para acesso aos dados de blob.

Comentários

A Find Blobs by Tags operação tem suporte na API REST versão 2019-12-12 e posterior.

Para contas com namespace hierárquico habilitado, a Find Blobs by Tags operação não tem suporte, pois não há suporte para marcas de blob para contas de namespace hierárquicas.

O índice secundário que Find Blobs by Tags usa é eventualmente consistente. Atualizações para marcas de blob por meio Set Blob Tags do pode não estar imediatamente visível para Find Blobs by Tags as operações.

Construindo uma expressão de pesquisa

O where parâmetro URI localiza blobs na conta de armazenamento cujas marcas correspondem a uma expressão. A expressão deve ser avaliada true como para que um blob seja retornado no conjunto de resultados.

O serviço de armazenamento dá suporte a um subconjunto da gramática da cláusula ANSI SQL WHERE para o valor do parâmetro de where=<expression> consulta. O serviço de armazenamento dá suporte aos seguintes operadores:

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

Observação

O valor do where parâmetro URI deve ser codificado corretamente pelo URI (incluindo espaços e operadores). Os exemplos anteriores omitem isso para facilitar a leitura.

Todos os valores de marca são cadeias de caracteres. Os operadores relacionais binários com suporte usam uma classificação lexicográfica dos valores de marca. Para dar suporte a tipos de dados que não são de cadeia de caracteres, incluindo números e datas, você deve usar o preenchimento apropriado e a formatação classificável. 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). Recomendamos que você sempre coloque nomes de marcas entre aspas duplas.

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).

Cobrança

As solicitações de preços podem ser originadas de clientes que usam APIs de Armazenamento de Blobs, diretamente por meio da API REST do Armazenamento de Blobs ou de uma biblioteca de clientes do Armazenamento do Azure. Essas solicitações acumulam encargos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura se acumulam em uma categoria de cobrança diferente das transações de gravação. A tabela a seguir mostra a categoria de cobrança para Find Blobs by Tags solicitações com base no tipo de conta de armazenamento:

Operação Tipo de conta de armazenamento Categoria de cobrança
Localizar Blobs por Marcas Blob de blocos Premium
Uso geral v2 Standard
Uso geral v1 Standard		 Listar e Create operações de contêiner

Para saber mais sobre os preços da categoria de cobrança especificada, confira Preços Armazenamento de Blobs do Azure.

Confira também

Gerenciar e localizar dados em Armazenamento de Blobs do Azure com marcas de índice de blob
Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Códigos de erro do Armazenamento de Blobs