Localizar blobs por marcas no contêiner

  • Artigo

A Find Blobs by Tags in Container operação localiza todos os blobs cujas marcas correspondem a uma expressão de pesquisa em um contêiner.

Solicitação

Você pode construir a solicitação da Find Blobs by Tags in Container seguinte maneira. Recomendamos HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento e mycontainer pelo nome do contêiner de armazenamento.

URI de solicitação do método GET Versão HTTP
https://myaccount.blob.core.windows.net/mycontainer?restype=container&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 informações sobre como construir essa expressão, consulte Comentários mais adiante neste artigo.
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, mas ainda 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

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 in Container operação conforme descrito abaixo.

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 que um usuário, grupo ou entidade de serviço Microsoft Entra chame a Find Blobs by Tags in Container operação e a função rbac interna do Azure com privilégios mínimos que inclua 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 in Container operação tem suporte na API REST versão 2021-04-10 e posterior.

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

Construindo uma expressão de pesquisa

O where parâmetro URI localiza blobs na conta de armazenamento e no contêiner 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 SQL WHERE ANSI 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'

Observação

O valor do where parâmetro URI deve ser codificado corretamente no URI (incluindo espaços e operadores). Os exemplos anteriores omitem isso para legibilidade. @container não há suporte quando o contêiner faz parte de um URI.

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 marcas 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 in Container 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 no contêiner Blob de blocos Premium
Uso geral v2 Standard
Uso geral v1 Standard		 Listar e criar operações de contêiner

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

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