Rechercher des objets blob par étiquettes

  • Article

L’opération Find Blobs by Tags recherche tous les objets blob du compte de stockage dont les balises correspondent à une expression de recherche.

Requête

Vous pouvez construire la Find Blobs by Tags requête comme suit. Nous recommandons HTTPS. Remplacez myaccount par le nom de votre compte de stockage.

URI de requête de méthode GET Version HTTP
https://myaccount.blob.core.windows.net?comp=blobs&where=<expression> HTTP/1.1

Paramètres URI

Vous pouvez spécifier les paramètres supplémentaires suivants dans l’URI de requête :

Paramètre Description
expression Obligatoire. Filtre le jeu de résultats pour inclure uniquement les objets blob dont les balises correspondent à l’expression spécifiée.

Pour plus d’informations sur la façon de construire cette expression, consultez Remarques.
marker facultatif. Valeur de chaîne qui identifie la partie du jeu de résultats à retourner avec l’opération suivante. L’opération retourne une valeur de marqueur dans le corps de la réponse si le jeu de résultats retourné n’était pas terminé. La valeur du marqueur peut ensuite être utilisée dans un appel suivant pour demander l’ensemble d’éléments suivant.

La valeur de marqueur est opaque au client.
maxresults facultatif. Spécifie le nombre maximal d’objets blob à retourner. Si la demande ne spécifie maxresults pas ou spécifie une valeur supérieure à 5 000, le serveur retourne jusqu’à 5 000 éléments. S’il existe des résultats supplémentaires à retourner, le service retourne un jeton de continuation dans l’élément NextMarker response. Dans certains cas, le service peut retourner moins de résultats que maxresults spécifié. Le service peut également retourner un jeton de continuation.

La définition de maxresults à une valeur inférieure ou égale à zéro entraîne un code de réponse d'erreur 400 (Demande incorrecte).
timeout facultatif. Exprimée en secondes. Pour plus d’informations, consultez Définir des délais d’expiration pour les opérations de stockage Blob.

En-têtes de requête

Le tableau suivant décrit les en-têtes de requête obligatoires et facultatifs :

En-tête de requête Description
Authorization Obligatoire. Spécifie le schéma d’autorisation, le nom du compte et la signature. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
Date ou x-ms-date Obligatoire. Spécifie la date/heure en temps universel coordonné (UTC) pour la requête. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
x-ms-version Obligatoire pour toutes les demandes autorisées, mais facultatif pour les demandes anonymes. Spécifie la version de l'opération à utiliser pour cette demande. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
x-ms-client-request-id facultatif. Fournit une valeur opaque générée par le client avec une limite de caractères de 1 kibioctet (Kio) enregistrée dans les journaux lors de la configuration de la journalisation. Nous vous recommandons vivement d’utiliser cet en-tête pour mettre en corrélation les activités côté client avec les demandes que le serveur reçoit.

Corps de la demande

Aucun.

response

La réponse inclut un code de status HTTP, des en-têtes de réponse et un corps de réponse.

Code d’état

Une opération réussie envoie le code d'état 200 (OK).

Pour plus d’informations sur les codes status, consultez Codes d’état et d’erreur.

En-têtes de réponse

La réponse de l'opération inclut les en-têtes suivants. La réponse peut également inclure des en-têtes HTTP standard supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.

En-tête de réponse Description
Content-Type Spécifie application/xml comme type de contenu.
Content-Length Spécifie la taille du document XML retourné, en octets.
x-ms-request-id Identifie de manière unique la demande qui a été effectuée. Vous pouvez l’utiliser pour résoudre les problèmes liés à la demande. Pour plus d’informations, consultez Résoudre les problèmes liés aux opérations d’API.
x-ms-version Indique la version de Stockage Blob Azure qui a été utilisée pour exécuter la demande.
Date Valeur de date/heure UTC qui indique l’heure à laquelle le service a envoyé la réponse.
x-ms-client-request-id Peut être utilisé pour résoudre les problèmes liés aux demandes et aux réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l’en-tête x-ms-client-request-id , si elle est présente dans la requête et que la valeur est au maximum de 1 024 caractères ASCII visibles. Si l’en-tête x-ms-client-request-id n’est pas présent dans la demande, cet en-tête ne sera pas présent dans la réponse.

Response body

Dans les versions 2020-04-08 et ultérieures, les balises correspondantes de l’objet blob sont encapsulées dans un Tags élément. Le corps de la réponse présente le format suivant :

<?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>

Le corps de la réponse est un document XML UTF-8 bien formé.

Autorisation

Une autorisation est requise lors de l’appel d’une opération d’accès aux données dans stockage Azure. Vous pouvez autoriser l’opération Find Blobs by Tags comme décrit ci-dessous.

Le Stockage Azure prend en charge l’utilisation de Microsoft Entra ID pour autoriser les demandes de données blob. Avec Microsoft Entra ID, vous pouvez utiliser le contrôle d’accès en fonction du rôle Azure (Azure RBAC) pour accorder des autorisations à un principal de sécurité. Le principal de sécurité peut être un utilisateur, un groupe, un principal de service d’application ou une identité managée Azure. Le principal de sécurité est authentifié par Microsoft Entra ID pour retourner un jeton OAuth 2.0. Le jeton peut ensuite être utilisé pour autoriser une requête auprès du service BLOB.

Pour en savoir plus sur l’autorisation à l’aide de Microsoft Entra ID, consultez Autoriser l’accès aux objets blob à l’aide de Microsoft Entra ID.

Autorisations

Vous trouverez ci-dessous l’action RBAC nécessaire pour qu’un utilisateur, un groupe ou un principal de service Microsoft Entra appelle l’opérationFind Blobs by Tags, ainsi que le rôle RBAC intégré Azure le moins privilégié qui inclut cette action :

Pour en savoir plus sur l’attribution de rôles à l’aide d’Azure RBAC, consultez Attribuer un rôle Azure pour accéder aux données blob.

Remarques

L’opération Find Blobs by Tags est prise en charge dans l’API REST version 2019-12-12 et ultérieure.

Pour les comptes avec un espace de noms hiérarchique activé, l’opération Find Blobs by Tags n’est pas prise en charge, car les balises d’objets blob ne sont pas prises en charge pour les comptes d’espace de noms hiérarchiques.

L’index secondaire qui Find Blobs by Tags utilise est finalement cohérent. Mises à jour aux balises d’objet blob via Set Blob Tags peuvent ne pas être immédiatement visibles par les Find Blobs by Tags opérations.

Construction d’une expression de recherche

Le where paramètre URI recherche les objets blob dans le compte de stockage dont les balises correspondent à une expression. L’expression doit évaluer à true pour qu’un objet blob soit retourné dans le jeu de résultats.

Le service de stockage prend en charge un sous-ensemble de la grammaire de la clause SQL WHERE ANSI pour la valeur du where=<expression> paramètre de requête. Le service de stockage prend en charge les opérateurs suivants :

Opérateur Description Exemple
= Égal à &where=Status = 'In Progress'
> Supérieur à &where=LastModified > '2018-06-18 20:51:26Z'
>= Supérieur ou égal à &where=Priority >= '05'
< Inférieur à &where=Age < '032'
<= Inférieur ou égal à &where=Reviewer <= 'Smith'
AND ET logique &where=Name > 'C' AND Name < 'D'
&where=Age > '032' AND Age < '100'
@container Spécifier un conteneur &where=@container='mycontainer' AND Name = 'C'

Notes

La valeur du where paramètre URI doit être correctement encodée dans l’URI (y compris les espaces et les opérateurs). Les exemples précédents omettent cela pour des motifs de lisibilité.

Toutes les valeurs de balise sont des chaînes. Les opérateurs relationnels binaires pris en charge utilisent un tri lexicographique des valeurs de balise. Pour prendre en charge les types de données autres que les chaînes, y compris les nombres et les dates, vous devez utiliser le remplissage approprié et la mise en forme triable. Les valeurs des étiquettes doivent être placées entre guillemets simples.

Si les noms de balise sont des identificateurs SQL standard, ils peuvent être présents sans échappement. S’ils contiennent des caractères spéciaux, ils doivent être délimités par des guillemets doubles (par exemple, "TagName" = TagValue). Nous vous recommandons de toujours placer les noms de balises entre guillemets doubles.

Le service de stockage rejette toute requête qui contient une expression non valide avec le code d’erreur 400 (Demande incorrecte).

Facturation

Les demandes de tarification peuvent provenir de clients qui utilisent les API Stockage Blob, soit directement via l’API REST Stockage Blob, soit à partir d’une bibliothèque cliente stockage Azure. Ces demandes accumulent des frais par transaction. Le type de transaction affecte la façon dont le compte est facturé. Par exemple, les transactions de lecture s’accumulent dans une catégorie de facturation différente de celle des transactions d’écriture. Le tableau suivant montre la catégorie de facturation pour Find Blobs by Tags les demandes en fonction du type de compte de stockage :

Opération Type de compte de stockage Catégorie de facturation
Rechercher des objets blob par étiquettes Objet blob de blocs Premium
Usage général v2 Standard
Usage général v1 standard		 Opérations de liste et de création de conteneur

Pour en savoir plus sur la tarification de la catégorie de facturation spécifiée, consultez tarification Stockage Blob Azure.

Voir aussi

Gérer et rechercher des données sur Stockage Blob Azure avec des balises d’index d’objet blob
Autoriser les demandes dans le Stockage Azure
Codes d’état et d’erreur
Codes d’erreur stockage Blob