List Containers

Article
05/15/2024

L’opération List Containers retourne une liste des conteneurs sous le compte de stockage spécifié.

Requête

Vous pouvez construire la List Containers requête comme suit. HTTPS est recommandé. Remplacez myaccount par le nom de votre compte de stockage.

Méthode	URI de demande	Version HTTP
`GET`	`https://myaccount.blob.core.windows.net/?comp=list`	HTTP/1.1

Notez que l'URI doit toujours inclure la barre oblique (/) pour séparer le nom d'hôte du chemin d'accès et les portions de requête de l'URI. Dans le cadre d'une opération List Containers, la partie de chemin d'accès de l'URI est vide.

Demande de service de stockage émulée

Lorsque vous effectuez une demande auprès du service de stockage émulé, spécifiez le nom d’hôte de l’émulateur et Stockage Blob Azure port comme 127.0.0.1:10000, suivi du nom du compte de stockage émulé.

Méthode	URI de demande	Version HTTP
`GET`	`http://127.0.0.1:10000/devstoreaccount1?comp=list`	HTTP/1.1

Notez que le stockage émulé prend uniquement en charge les tailles d’objets blob jusqu’à 2 Gio.

Pour plus d’informations, consultez Utiliser l’émulateur Azurite pour le développement local du stockage Azure et Différences entre l’émulateur de stockage et les services stockage Azure.

Paramètres URI

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

Paramètre	Description
`prefix`	facultatif. Filtre les résultats pour renvoyer uniquement les conteneurs dont le nom commence par le préfixe spécifié.
`marker`	facultatif. Valeur de chaîne qui identifie la partie de la liste des conteneurs à retourner avec l’opération de référencement suivante. L’opération retourne la `NextMarker` valeur dans le corps de la réponse, si l’opération de référencement n’a pas retourné tous les conteneurs restant à répertorier avec la page active. Vous pouvez utiliser la `NextMarker` valeur comme valeur du `marker` paramètre dans un appel suivant pour demander la page suivante des éléments de liste. La valeur de marqueur est opaque au client.
`maxresults`	facultatif. Indique le nombre maximal de conteneurs à 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. Notez que si l’opération de référencement dépasse une limite de partition, le service retourne un jeton de continuation pour récupérer le reste des résultats. Pour cette raison, il est possible que le service retourne moins de résultats que celui spécifié par `maxresults`, ou que la valeur par défaut de 5000. Si le paramètre est défini sur une valeur inférieure ou égale à zéro, le serveur retourne status code 400 (requête incorrecte).
`include={metadata,deleted,system}`	facultatif. Spécifie un ou plusieurs datasets à inclure dans la réponse : - `metadata`: Notez que les métadonnées demandées avec ce paramètre doivent être stockées conformément aux restrictions de nommage imposées par la version 2009-09-19 du Stockage Blob. À compter de cette version, tous les noms de métadonnées doivent respecter les conventions de nommage des identificateurs C#. - `deleted`: Version 2019-12-12 et ultérieures. Spécifie que les conteneurs supprimés de manière réversible doivent être inclus dans la réponse. - `system`: Version 2020-10-02 et ultérieures. Spécifie si les conteneurs système doivent être inclus dans la réponse. L’inclusion de cette option répertorie les conteneurs système, tels que `$logs` et `$changefeed`. Notez que les conteneurs système spécifiques retournés varient en fonction des fonctionnalités de service activées sur le compte de stockage.
`timeout`	facultatif. Le paramètre `timeout` est exprimé en secondes. Pour plus d’informations, consultez Définition de 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 demande obligatoires ou 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. 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 reçues par le serveur. Pour plus d’informations, consultez Surveiller Stockage Blob Azure.

Corps de la demande

Aucun.

response

La réponse inclut un code d'état HTTP, un ensemble d'en-têtes de réponse et un corps de réponse au format XML.

Code d’état

Une opération réussie envoie le code d'état 200 (OK). Pour plus d’informations sur les codes status, consultez État et codes d’erreur.

En-têtes de réponse

La réponse de l'opération inclut les en-têtes suivants. La réponse inclut également 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`	En-tête HTTP/1.1 standard. Spécifie le format dans lequel les résultats sont renvoyés. Actuellement, cette valeur est `application/xml`.
`x-ms-request-id`	Cet en-tête identifie de manière unique la demande qui a été effectuée et peut être utilisé pour la résolution des problèmes de la demande. Pour plus d’informations, consultez Résolution des problèmes liés aux opérations d’API.
`x-ms-version`	Indique la version du stockage Blob utilisée pour exécuter la demande. Cet en-tête est renvoyé pour les demandes effectuées avec la version 2009-09-19 ou une version ultérieure.
`Date`	Valeur de date/heure UTC qui indique l’heure à laquelle la réponse a été lancée. Le service génère cette valeur.
`x-ms-client-request-id`	Vous pouvez utiliser cet en-tête pour résoudre les demandes et les réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l’en-tête `x-ms-client-request-id` , s’il est présent dans la demande. 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 requête, cet en-tête ne sera pas présent dans la réponse.

Response body

Le format du corps de la réponse est le suivant.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Containers>  
    <Container>  
      <Name>container-name</Name>  
      <Version>container-version</Version>
      <Deleted>true</Deleted>
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <LeaseStatus>locked | unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration> 
        <PublicAccess>container | blob</PublicAccess>
        <HasImmutabilityPolicy>true | false</HasImmutabilityPolicy>
        <HasLegalHold>true | false</HasLegalHold>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Container>  
  </Containers>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

LeaseStatus, LeaseState et LeaseDuration apparaissent uniquement dans la version du 12/02/2012 et ultérieure.

À compter de la version du 15/08/2013, l'attribut AccountName de l'élément EnumerationResults a été renommé ServiceEndpoint. L'élément URL a également été supprimé de l'élément Container. Pour les versions antérieures à 2013-08-15, l’URL du conteneur, telle que spécifiée par le URL champ, n’inclut pas le restype=container paramètre . Si vous utilisez cette valeur pour effectuer d'autres demandes sur les conteneurs énumérés, ajoutez ce paramètre pour indiquer que le type de ressource est un conteneur.

Les Prefixéléments , Markeret MaxResults ne sont présents que si vous les spécifiez sur l’URI. L’élément NextMarker a une valeur uniquement si les résultats de la liste ne sont pas terminés.

L’élément Metadata est présent uniquement si vous spécifiez le include=metadata paramètre sur l’URI. Dans l'élément Metadata, la valeur de chaque paire nom-valeur est indiquée dans un élément correspondant au nom de la paire.

Si une paire nom-valeur de métadonnées enfreint les restrictions de nommage appliquées par la version 2009-09-19, le corps de la réponse indique le nom problématique dans un x-ms-invalid-name élément. Le fragment XML suivant illustre ceci :

  
<Metadata>  
  <MyMetadata1>first value</MyMetadata1>  
  <MyMetadata2>second value</MyMetadata2>  
  <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>  
</Metadata>

À compter de la version 2016-05-31, les autorisations publiques de conteneur sont fournies dans la PublicAccess propriété . Il indique si les données du conteneur sont accessibles publiquement et le niveau d’accès. Les valeurs possibles incluent :

container: indique un accès en lecture public complet pour les données de conteneur et d’objet blob. Les clients peuvent énumérer des objets blob dans le conteneur via une requête anonyme, mais ils ne peuvent pas énumérer les conteneurs dans le compte de stockage.
blob: indique l’accès en lecture public pour les objets blob. Les données blob au sein de ce conteneur peuvent être lues via une demande anonyme, mais les données de conteneur ne sont pas disponibles. Les clients ne peuvent pas énumérer les objets blob dans le conteneur via une demande anonyme.

Si cette propriété n’est pas spécifiée dans la <properties> section, le conteneur est privé pour le propriétaire du compte.

HasImmutabilityPolicy et HasLegalHold apparaissent uniquement dans la version 2017-11-09 et ultérieure. HasImmutabilityPolicy est si une stratégie d’immuabilité est true définie sur le conteneur, et false sinon. HasLegalHold est true si le conteneur a une ou plusieurs conservations légales, et false sinon.

Notes

À compter de la version 2009-09-19, le corps de la réponse pour List Containers retourne l’heure de la dernière modification du conteneur, dans un élément nommé Last-Modified. Dans les versions précédentes, cet élément était nommé LastModified.

Les Versionéléments , Deleted, DeletedTimeet RemainingRetentiondays apparaissent uniquement dans la version 2019-12-12 et ultérieure si vous spécifiez la deleted valeur du paramètre includede requête . Ces éléments apparaissent uniquement si le conteneur est supprimé de manière réversible et est éligible à la restauration. Les Versionéléments , Deleted, DeletedTimeet RemainingRetentiondays apparaissent uniquement dans la version 2019-12-12 et ultérieure si la valeur supprimée est spécifiée pour le include paramètre de requête et si le conteneur est supprimé de manière réversible et peut être restauré.

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 List Containers comme décrit ci-dessous.

Important

Microsoft recommande d’utiliser Microsoft Entra ID avec des identités managées pour autoriser les demandes dans le stockage Azure. Microsoft Entra ID offre une sécurité et une facilité d’utilisation supérieures par rapport à l’autorisation de clé partagée.

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, une identité managée ou un principal de service Microsoft Entra appelle l’opérationList Containers, ainsi que le rôle RBAC Azure intégré le moins privilégié qui inclut cette action :

Action RBAC Azure :Microsoft.Storage/storageAccounts/blobServices/containers/read (étendue au compte de stockage ou au-dessus)
Rôle intégré le moins privilégié :Contributeur aux données Blob de stockage (limité au compte de stockage ou supérieur)

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.

Une signature d’accès partagé (SAP) fournit un accès délégué sécurisé aux ressources d’un compte de stockage. Avec une SAP, vous disposez d’un contrôle granulaire sur la façon dont un client peut accéder aux données. Vous pouvez spécifier la ressource à laquelle le client peut accéder, les autorisations dont il dispose sur ces ressources et la durée de validité de la signature d’accès partagé.

L’opération List Containers prend en charge l’autorisation à l’aide d’une SAP de compte.

Lorsque l’accès à la clé partagée n’est pas autorisé pour le compte de stockage, un jeton SAP de compte n’est pas autorisé sur une demande adressée au stockage Blob. Pour en savoir plus, consultez Comprendre comment l’interdiction de la clé partagée affecte les jetons SAP.

SAP de compte

Une SAP de compte est sécurisée à l’aide de la clé de compte de stockage. Une SAP de compte délègue l’accès aux ressources d’un ou plusieurs des services de stockage. Toutes les opérations disponibles via une SAP de service ou de délégation d’utilisateur sont également disponibles via une SAP de compte.

Le tableau suivant indique le type de ressource signé et les autorisations signées à spécifier lors de la délégation de l’accès :

Opération	Service signé	Type de ressource signé	Autorisation signée
List Containers	Blob (b)	Service(s)	Liste (l)

Pour en savoir plus sur la SAP de compte, consultez Create une SAP de compte.

L’opération List Containers prend en charge l’autorisation de clé partagée. L’autorisation avec des clés de compte n’est pas recommandée pour la plupart des scénarios, car elle est moins sécurisée. Microsoft recommande d’interdire l’autorisation de clé partagée pour le compte de stockage lorsque cela est possible. Pour plus d’informations, consultez Empêcher l’autorisation avec une clé partagée.

Remarques

Si vous spécifiez une valeur pour le maxresults paramètre et que le nombre de conteneurs à retourner dépasse cette valeur, ou dépasse la valeur par défaut pour maxresults, le corps de la réponse contient l’élément NextMarker . (Il s’agit également d’un jeton de continuation).

NextMarker indique le conteneur suivant à retourner lors d’une demande ultérieure. Pour retourner l’ensemble d’éléments suivant, spécifiez la valeur de NextMarker pour le marker paramètre sur l’URI de la requête suivante. Notez que la valeur de NextMarker doit être traitée comme opaque.

Si l’opération de référencement dépasse une limite de partition, le service retourne une valeur pour l’élément NextMarker pour récupérer le reste des résultats de la partition suivante. Une opération de référencement qui s’étend sur plusieurs partitions entraîne le retour d’un ensemble d’éléments plus petit que celui spécifié par maxresults, ou la valeur par défaut de 5 000. Votre application doit toujours case activée pour la présence de l’élément NextMarker lorsque vous effectuez une opération de référencement et la gérer en conséquence.

Les conteneurs sont répertoriés par ordre alphabétique dans le corps de la réponse.

L'opération List Containers expire après 30 secondes.

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 List Containers les demandes en fonction du type de compte de stockage :

Opération	Type de compte de stockage	Catégorie de facturation
List Containers	Objet blob de blocs Premium Usage général v2 Standard Usage général v1 standard	Répertorier et Create opérations de conteneur

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

Exemple de requête et de réponse

L’exemple d’URI suivant demande la liste des conteneurs d’un compte, en définissant le nombre maximal de résultats à retourner pour l’opération initiale sur trois.

GET https://myaccount.blob.core.windows.net/?comp=list&maxresults=3 HTTP/1.1

La demande est envoyée avec ces en-têtes :

x-ms-version: 2016-05-31  
x-ms-date: Wed, 26 Oct 2016 22:08:44 GMT  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=

Le code d'état et les en-têtes de réponse sont renvoyés comme suit :

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Wed, 26 Oct 2016 22:08:54 GMT  
x-ms-version: 2016-05-31  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Le code XML de réponse pour cette demande est le suivant : Notez que l’élément NextMarker suit l’ensemble de conteneurs et inclut le nom du conteneur suivant à retourner.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net/">  
  <MaxResults>3</MaxResults>  
  <Containers>  
    <Container>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag> 
        <PublicAccess>container</PublicAccess> 
      </Properties>  
    </Container>  
    <Container>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>  
      </Properties>  
    </Container>  
    <Container>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
      </Properties>  
    </Container>  
  </Containers>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>

L'opération de liste suivante spécifie le marqueur dans l'URI de la demande, comme suit. L’ensemble de résultats suivant est retourné, en commençant par le conteneur spécifié par le marqueur.

https://myaccount.blob.core.windows.net/?comp=list&maxresults=3&marker=video

Voir aussi

Autoriser les demandes dans le Stockage Azure
Codes d’état et d’erreur
Codes d’erreur stockage Blob
Énumération des ressources d’objets blob
Utilisation de l’émulateur de stockage Azure pour le développement et les tests
Définition des délais d’expiration pour les opérations de stockage Blob

Partager via