Handles de liste

  • Article

L’opération List Handles retourne une liste de handles ouverts sur un répertoire ou un fichier. Si vous le souhaitez, il peut énumérer de manière récursive les handles ouverts sur des répertoires et des fichiers. Cette API est disponible à partir de la version 2018-11-09.

Disponibilité du protocole

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

Requête

Vous pouvez construire la List Handles requête comme suit. HTTPS est recommandé.

Méthode URI de demande Version HTTP
GET https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles HTTP/1.1

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

Composant Path Description
myaccount nom de votre compte de stockage.
myshare Nom du partage de fichiers.
mydirectorypath Optionnel. Chemin au répertoire.
myfileordirectory Nom du fichier ou du répertoire.

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

Paramètres URI

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

Paramètre Description
marker facultatif. Valeur de chaîne qui identifie la partie de la liste à retourner avec l’opération suivante List Handles . L’opération retourne une valeur de marqueur dans le corps de la réponse, si la liste retournée n’est pas complète. Vous pouvez ensuite utiliser la valeur de marqueur dans un appel suivant pour demander le jeu d’éléments de liste suivant.

La valeur de marqueur est opaque au client.
maxresults Optionnel. Spécifie le nombre maximal de handles pris sur les fichiers ou répertoires à retourner.

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 Optionnel. 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.
sharesnapshot Optionnel. Le sharesnapshot paramètre est une valeur opaque DateTime qui, lorsqu’il est présent, spécifie le partage instantané à interroger pour obtenir la liste des handles.

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 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 Optionnel. 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. Pour plus d’informations, consultez Surveiller Azure Files.
x-ms-recursive Optionnel. Valeur booléenne qui spécifie si l’opération doit également s’appliquer aux fichiers et sous-répertoires du répertoire spécifié dans l’URI.
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 la version 2022-11-02 et ultérieure.
x-ms-allow-trailing-dot: { <Boolean> } Optionnel. 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 supprimé ou non. Pour plus d’informations, consultez Affectation de noms et référencement de partages, de répertoires, de fichiers et de métadonnées.

Corps de la demande

Aucune.

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 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 sont présents uniquement si vous les avez spécifiés sur l’URI de requête. 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>
    <HandleList>
        <Handle>
            <HandleId>handle-id</HandleId>
            <Path>file-or-directory-name-including-full-path</Path>
            <FileId>file-id</FileId>
            <ParentId>parent-file-id</ParentId>
            <SessionId>session-id</SessionId>
            <ClientIp>client-ip</ClientIp>
            <OpenTime>opened-time</OpenTime>
            <LastReconnectTime>lastreconnect-time</LastReconnectTime>
            <AccessRightList>
                <AccessRight>Read</AccessRight>
                <AccessRight>Write</AccessRight>
                <AccessRight>Delete</AccessRight>
            </AccessRightList>
        </Handle>
        ...
    </HandleList>
    <NextMarker>next-marker</NextMarker>
</EnumerationResults>

Le tableau suivant décrit les champs du corps de la réponse :

Champ Description Objectif
HandleId ID de handle de service XSMB, UINT64. Utilisé pour identifier le handle.
Path Nom du fichier, y compris le chemin d’accès complet, à partir de la racine du partage. Chaîne. Utilisé pour identifier le nom de l’objet pour lequel le handle est ouvert.
ClientIp Adresse IP cliente qui a ouvert le handle. Chaîne. Utilisé pour déterminer si le handle a peut-être été divulgué.
OpenTime Le handle d’heure a été ouvert (UTC). DateTime en tant que Chaîne. Utilisé pour déterminer si le handle a peut-être été divulgué. Les handles ayant fui sont généralement ouverts depuis longtemps.
LastReconnectTime Le handle d’heure a été ouvert (UTC). DateTime en tant que Chaîne. Permet de déterminer si le handle a été rouvert après la déconnexion d’un client/serveur, en raison d’une panne de mise en réseau ou d’autres. Le champ n’est inclus dans le corps de la réponse que si l’événement de déconnexion s’est produit et que le handle a été rouvert.
FileId ID de fichier, UINT64. FileId identifie le fichier de manière unique. Il est utile lors des renommages, car le FileId ne change pas.
ParentId ID de fichier parent, UINT64. ParentId identifie de manière unique le répertoire. Cela est utile lors des renommages, car le ParentId ne change pas.
SessionId ID de session SMB qui spécifie le contexte dans lequel le handle de fichier a été ouvert. UINT64. SessionId est inclus dans les journaux de l’observateur d’événements lorsque les sessions sont déconnectées de force. Il vous permet d’associer un lot spécifique de handles fuites à un incident réseau spécifique.
AccessRightList Autorisations d’accès accordées au handle ouvert sur le fichier ou le répertoire. Disponible dans le service version 2023-01-03 et ultérieure.

Utilisé pour interroger les autorisations d’accès détenues sur un fichier ou un répertoire par différents handles ouverts. Les valeurs possibles sont READ, WRITE et DELETE, ou une combinaison de ces valeurs.
NextMarker Chaîne qui décrit le handle suivant à répertorier. Il est retourné lorsque d’autres handles doivent être répertoriés pour terminer la demande. La chaîne est utilisée dans les requêtes suivantes pour répertorier les handles restants. L’absence de NextMarker indique que tous les handles pertinents ont été répertoriés.

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

Autorisation

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

Notes

HandleId est un ID de handle côté service, distinct de l’ID de handle client. Le mappage entre les deux est possible au niveau du client.

Voir aussi