Liste des répertoires et des fichiers

Article
03/29/2023

L'opération List Directories and Files renvoie la liste des fichiers ou répertoires figurant sous le partage ou répertoire spécifié. Elle ne répertorie le contenu que pour un seul niveau de la hiérarchie de répertoires.

Disponibilité du protocole

Protocole de partage de fichiers activé	Disponible
SMB
NFS

Requête

Vous pouvez construire la List Directories and Files requête comme suit. HTTPS est recommandé.

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

Remplacez les composants du chemin indiqués dans l'URI de la demande par les vôtres, comme suit :

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

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

Paramètres URI

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

Paramètre	Description
`prefix`	facultatif. Version 2016-05-31 et ultérieures. Filtre les résultats pour renvoyer uniquement les fichiers et les répertoires dont les noms commencent par le préfixe spécifié.
`sharesnapshot`	facultatif. Version 2017-04-17 et versions ultérieures. Le paramètre share instantané est une valeur opaque `DateTime` qui, lorsqu’elle est présente, spécifie le partage instantané à interroger pour la liste des fichiers et répertoires.
`marker`	facultatif. Valeur de chaîne qui identifie la partie de la liste à renvoyer 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’était pas terminée. Vous pouvez ensuite utiliser la valeur du marqueur dans un appel suivant pour demander l’ensemble suivant d’éléments de liste. La valeur de marqueur est opaque au client.
`maxresults`	facultatif. Spécifie le nombre maximal de fichiers ou de répertoires à retourner. Si la requête ne spécifie `maxresults`pas ou spécifie une valeur supérieure à 5 000, le serveur retourne jusqu’à 5 000 éléments. 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).
`include={Timestamps, ETag, Attributes, PermissionKey}`	Disponible en option, à 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 encodée avec une URL (`%82`). L’en-tête `x-ms-file-extended-info` est implicitement supposé être vrai lorsque ce paramètre est spécifié.
`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 Azure Files.

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, facultatif pour les requêtes 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 reçues par le serveur. Pour plus d’informations, consultez Surveiller Azure Files.
`x-ms-file-extended-info: {true}`	facultatif. Version 2020-04-08 et versions ultérieures. Cet en-tête est implicitement supposé vrai si le `include` paramètre de requête n’est pas vide. Si la valeur est true, la `Content-Length` propriété est à jour. Dans les versions 2020-04-08, 2020-06-12 et 2020-08-04, `FileId` est retourné pour les fichiers et les répertoires uniquement si cet en-tête est true. Dans les versions 2020-10-02 et ultérieures, `FileId` est toujours retourné pour les fichiers et les répertoires.
`x-ms-file-request-intent`	Obligatoire si `Authorization` l’en-tête spécifie un jeton OAuth. La valeur acceptable est `backup`. Cet en-tête spécifie que le `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` doit être accordé s’il est inclus dans la stratégie RBAC affectée à l’identité autorisée à l’aide de l’en-tête `Authorization` . Disponible pour les versions 2022-11-02 et ultérieures.
`x-ms-allow-trailing-dot: { <Boolean> }`	facultatif. Version 2022-11-02 et ultérieures. La valeur booléenne spécifie si un point de fin présent dans l’URL de la demande doit être rogné ou non. Pour plus d’informations, consultez Nommer et référencer des partages, des répertoires, des fichiers et des métadonnées.

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 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 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 requête 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 de Azure Files utilisée pour exécuter la demande.
`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 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` , s’il est présent dans la requête. 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

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

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

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

Notez que l'élément Content-Length est renvoyé dans la liste. Toutefois, cette valeur peut ne pas être à jour, car un client SMB 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 est rompu. Pour récupérer les valeurs de propriété actuelles, utilisez x-ms-file-extended-info: trueou appelez Obtenir les propriétés du fichier.

Dans les versions 2020-04-08, 2020-06-12 et 2020-08-04, FileId est retourné pour les fichiers et répertoires si l’en-tête x-ms-file-extended-info est true. Dans les versions 2020-10-02 et ultérieures, 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 les versions 2020-06-12 et versions ultérieures, include={timestamps} retourne les propriétés d’horodatage suivantes : CreationTime, LastAccessTime, LastWriteTime, ChangeTimeet Last-Modified.

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

Dans les versions 2021-12-02 et ultérieures, List Directory and Files encodera en pourcentage (selon RFC 2396) toutes lesNameFile valeurs d’élément , PrefixDirectoryNameou DirectoryPath qui contiennent des caractères non valides en XML (en particulier, U+FFFE ou U+FFFF). S’il est encodé, l’élément Nameou PrefixEnumerationResults inclut un Encoded=true attribut . Notez que cela se produit uniquement pour les Name valeurs d’élément contenant les caractères non valides en XML, et non pour les éléments restants Name dans la réponse.

Format datetime et version de l’API pour les champs timestamp

Élément	Format de date/heure	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 du x-ms-content-length fichier.

Notez que chaque élément Directory renvoyé est comptabilisé dans le résultat, tout comme chaque élément File. Les fichiers et les répertoires sont répertoriés entremêlés, dans un ordre lexical trié dans le corps de la réponse.

La liste se limite à un seul niveau de la hiérarchie de répertoires. Pour répertorier plusieurs niveaux, vous pouvez effectuer plusieurs appels de manière itérative. Utilisez la Directory valeur retournée par un résultat dans un appel suivant à List Directories and Files.

Voir aussi

Opérations sur les répertoires

Partager via