Partager via

Répertorier les répertoires et les fichiers

  • Article

L’opération List Directories and Files retourne une liste de fichiers ou de répertoires sous le partage ou le répertoire spécifié. Il répertorie le contenu uniquement pour un seul niveau de la hiérarchie d’annuaires. Cette opération est prise en charge dans la version 2025-05-05 et ultérieure pour les partages de fichiers avec le protocole NFS activé.

Disponibilité du protocole

Protocole de partage de fichiers activé Disponible
SMB Oui
NFS Oui

Demander

La requête List Directories and Files est construite comme suit. Nous vous recommandons d’utiliser HTTPS.

Méthode URI de requête Version HTTP
AVOIR https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&comp=list HTTP/1.1
AVOIR https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&sharesnapshot=<DateTime>&comp=list HTTP/1.1

Remplacez les composants de chemin d’accès indiqués dans l’URI de requête par vos propres composants, comme suit :

Composant Path Description
myaccount Nom de votre compte de stockage.
myshare Nom de votre partage de fichiers.
mydirectorypath Chemin d’accès au répertoire.

Pour plus d’informations sur les restrictions de nommage de chemin d’accès, consultez nommage et référencement de partages, répertoires, fichiers et métadonnées.

Paramètres d’URI

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

Paramètres d’URI courants

Paramètre Description
prefix Optionnel. Version 2016-05-31 et ultérieure. Filtre les résultats pour retourner uniquement les fichiers et répertoires qui ont des noms commençant par le préfixe spécifié.
sharesnapshot Optionnel. Version 2017-04-17 et ultérieure. Le paramètre d’instantané de partage est une valeur de DateTime opaque qui, lorsqu’elle est présente, spécifie l’instantané de partage à interroger pour obtenir la liste des fichiers et répertoires.
marker Optionnel. Valeur de chaîne qui identifie la partie de la liste à retourner avec l’opération de liste suivante. L’opération retourne une valeur de marqueur dans le corps de la réponse si la liste retournée n’a pas été terminée. Vous pouvez ensuite utiliser la valeur de marqueur dans un appel suivant pour demander l’ensemble suivant d’éléments de liste.

La valeur de marqueur est opaque pour le client.
maxresults Optionnel. Spécifie le nombre maximal de fichiers ou de répertoires à retourner. Si la requête ne spécifie pas maxresultsou spécifie une valeur supérieure à 5 000, le serveur retourne jusqu’à 5 000 éléments.

La définition de maxresults sur une valeur inférieure ou égale à zéro entraîne le code de réponse d’erreur 400 (requête incorrecte).
timeout Optionnel. Le paramètre timeout est exprimé en secondes. Pour plus d’informations, consultez Paramètre des délais d’attente pour les opérations Azure Files.

Paramètres d’URI SMB uniquement

Paramètre Description
include={Timestamps, ETag, Attributes, PermissionKey} Éventuellement disponible, à partir de la version 2020-04-08. Spécifie une ou plusieurs propriétés à inclure dans la réponse :
  • Timestamps
  • ETag
  • Attributes (attributs de fichier Win32)
  • PermissionKey

Pour spécifier plusieurs de ces options sur l’URI, vous devez séparer chaque option par une virgule codée par URL (%82).

L’en-tête x-ms-file-extended-info est implicitement supposé être true lorsque ce paramètre est spécifié.

Paramètres d’URI NFS uniquement

Aucun.

En-têtes de requête

Les en-têtes de requête obligatoires et facultatifs sont décrits dans les tableaux suivants :

En-têtes de requête courants

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 demandes vers le stockage Azure.
Date ou x-ms-date Obligatoire. Spécifie le temps universel coordonné (UTC) de la requête. Pour plus d’informations, consultez Autoriser les demandes vers le stockage Azure.
x-ms-version Obligatoire pour toutes les demandes autorisées. Spécifie la version de l’opération à utiliser pour cette requête. Cette opération est prise en charge dans la version 2025-05-05 et ultérieure pour les partages de fichiers avec le protocole NFS activé.

Pour plus d’informations, consultez Contrôle de version pour les services stockage Azure.
x-ms-client-request-id Optionnel. Fournit une valeur opaque générée par le client avec une limite de caractères de 1 kibioctet (KiB) 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 Monitor Azure Files.
x-ms-file-request-intent Obligatoire si Authorization en-tête spécifie un jeton OAuth. La valeur acceptable est backup. Cet en-tête spécifie que les Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action doivent être accordés s’ils sont inclus dans la stratégie RBAC affectée à l’identité autorisée à l’aide de l’en-tête Authorization. Disponible pour la version 2022-11-02 et ultérieure.
x-ms-allow-trailing-dot: { <Boolean> } Optionnel. Version 2022-11-02 et ultérieure. La valeur booléenne spécifie si un point de fin présent dans l’URL de requête doit être supprimé ou non.

Cet en-tête est ignoré si la cible se trouve sur un partage de fichiers avec le protocole NFS activé, qui prend en charge le point de fin par défaut.

Pour plus d’informations, consultez nommage et référencement de partages, répertoires, fichiers et métadonnées.

En-têtes de requête SMB uniquement

En-tête de requête Description
x-ms-file-extended-info: {true} Optionnel. Version 2020-04-08 et ultérieure. Cet en-tête est implicitement supposé être vrai si le paramètre de requête include n’est pas vide. Si la valeur est true, la propriété Content-Length pour les fichiers qui indique la taille du fichier sera à jour.

En-têtes de requête NFS uniquement

Aucun.

Corps de la demande

Aucun.

Réponse

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 retourne le code d’état 200 (OK). Pour plus d’informations sur les codes d’état, consultez Les codes d’état et d’erreur.

En-têtes de réponse

La réponse de cette opération inclut les en-têtes dans les tableaux 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 de protocole HTTP/1.1 .

En-têtes de réponse courants

En-tête de réponse Description
Content-Type Spécifie le format dans lequel les résultats sont retourné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 résoudre les problèmes de la demande. Pour plus d’informations, consultez Résolution des problèmes des opérations d’API.
x-ms-version Indique la version d’Azure Files utilisée pour exécuter la requête.
Date ou x-ms-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, si elle est présente dans la requête. La valeur est au maximum 1024 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.

En-têtes de réponse SMB uniquement

Aucun.

En-têtes de réponse NFS uniquement

Aucun.

Corps de la réponse

Le format de la réponse XML est le suivant.

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

L’élément Content-Length est retourné dans la liste des fichiers, ce qui indique la taille du fichier. Toutefois, cette valeur peut ne pas être up-to-date, car un client SMB ou NFS a peut-être modifié le fichier localement. La valeur de Content-Length peut ne pas refléter ce fait tant que le handle n’est pas fermé ou que le verrou d’opération SMB est rompu. Pour récupérer les valeurs de propriété actuelles, utilisez x-ms-file-extended-info: true pour un répertoire situé sur un partage de fichiers avec le protocole SMB activé ou appelez Obtenir des propriétés de fichier sur le fichier spécifique.

Dans les versions 2021-12-02 et ultérieures, List Directory and Files encodera en pourcentage (par RFC 2396) toutes les FileName, DirectoryName, Prefix ou DirectoryPath valeurs d’élément qui contiennent des caractères non valides dans XML (en particulier, U+FFFE ou U+FFFF). Encodé, l’élément Name, Prefix ou EnumerationResults inclut un attribut Encoded=true. Cela se produit uniquement pour les valeurs d’élément Name contenant les caractères non valides dans XML, et non les éléments Name restants dans la réponse.

Corps de réponse pour les partages de fichiers avec le protocole SMB activé

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.file.core.windows.net/" ShareName="myshare" ShareSnapshot="date-time" DirectoryPath="directory-path">  
  <Marker>string-value</Marker>
  <Prefix>string-value</Prefix>
  <MaxResults>int-value</MaxResults>
  <DirectoryId>directory-id</DirectoryId>
  <Entries>
    <File>
      <FileId>file-id</FileId>
      <Name>file-name</Name>  
      <Properties>  
        <Content-Length>size-in-bytes</Content-Length>
        <CreationTime>datetime</CreationTime>
        <LastAccessTime>datetime</LastAccessTime>
        <LastWriteTime>datetime</LastWriteTime>
        <ChangeTime>datetime</ChangeTime>
        <Last-Modified>datetime</Last-Modified>
        <Etag>etag</Etag>
      </Properties>
      <Attributes>Archive|Hidden|Offline|ReadOnly</Attributes>
      <PermissionKey>4066528134148476695*1</PermissionKey>
    </File>  
    <Directory>
      <FileId>file-id</FileId>
      <Name>directory-name</Name>  
      <Properties>
        <CreationTime>datetime</CreationTime>
        <LastAccessTime>datetime</LastAccessTime>
        <LastWriteTime>datetime</LastWriteTime>
        <ChangeTime>datetime</ChangeTime>
        <Last-Modified>datetime</Last-Modified>
        <Etag>etag</Etag>
      </Properties>
      <Attributes>Archive|Hidden|Offline|ReadOnly</Attributes>
      <PermissionKey>4066528134148476695*1</PermissionKey>
    </Directory>  
  </Entries>  
  <NextMarker />  
</EnumerationResults>

Dans les versions 2020-04-08, 2020-06-12 et 2020-08-04, FileId est retournée pour les fichiers et répertoires si l’en-tête x-ms-file-extended-info est vrai. Dans la version 2020-10-02 et ultérieure, FileId est toujours retourné pour les fichiers et les répertoires.

Dans la version 2020-04-08, include={timestamps} retourne les propriétés d’horodatage suivantes : CreationTime, LastAccessTimeet LastWriteTime. Dans la version 2020-06-12 et les versions ultérieures, include={timestamps} retourne les propriétés d’horodatage suivantes : CreationTime, LastAccessTime, LastWriteTime, ChangeTimeet Last-Modified.

Dans la version 2020-10-02 et ultérieure, DirectoryId est retournée dans la réponse. Il spécifie la FileId du répertoire sur lequel l’API est appelée.

Corps de réponse pour les partages de fichiers avec le protocole NFS activé

<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults ServiceEndpoint="https://myaccount.file.core.windows.net/" ShareName="myshare" ShareSnapshot="date-time" DirectoryPath="directory-path">
  <Marker>string-value</Marker>
  <Prefix>string-value</Prefix>
  <MaxResults>int-value</MaxResults>
  <DirectoryId>directory-id</DirectoryId>
  <Entries>
    <File>
      <FileId>file-id</FileId>
      <Name>file-name</Name>
      <Properties>
        <Content-Length>size-in-bytes</Content-Length>
      </Properties>
    </File>
    <Directory>
      <FileId>file-id</FileId>
      <Name>directory-name</Name>
    </Directory>
  </Entries>
  <NextMarker />
</EnumerationResults>

Format Datetime et version de l’API pour les champs d’horodatage

Élément Format Datetime Exemple de valeur Version de l’API
CreationTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 et versions ultérieures
LastAccessTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 et versions ultérieures
LastWriteTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 et versions ultérieures
ChangeTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-06-12 et versions ultérieures
Last-Modified RFC 1123 Thu, 17 Sep 2020 13:38:07 GMT 2020-06-12 et versions ultérieures

Autorisation

Seul le propriétaire du compte peut appeler cette opération.

Remarques

La valeur retournée dans l’élément Content-Length correspond à la valeur de l’en-tête x-ms-content-length du fichier.

Chaque élément Directory retourné compte vers le résultat maximal, tout comme chaque élément File. Les fichiers et les répertoires sont répertoriés dans un ordre lexiquement trié dans le corps de la réponse.

La liste est limitée à un seul niveau de la hiérarchie d’annuaires. Pour répertorier plusieurs niveaux, vous pouvez effectuer plusieurs appels de manière itérative. Utilisez la valeur Directory retournée à partir d’un résultat dans un appel ultérieur à List Directories and Files.

Voir aussi

Opérations de sur les répertoires