Handles de liste

Article
02/19/2025

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 les répertoires et les fichiers. Cette API est disponible depuis la version 2018-11-09.

Disponibilité du protocole

Protocole de partage de fichiers activé	Disponible
SMB
NFS

Demander

La requête List Handles 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/myfileordirectory?comp=listhandles`	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`	Optionnel. Chemin d’accès 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 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ètre	Description
`marker`	Optionnel. Valeur de chaîne qui identifie la partie de la liste à retourner avec l’opération de `List Handles` 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 handles pris sur les fichiers ou répertoires à retourner. 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 Définition des délais d’expiration pour les opérations Azure Files.
`sharesnapshot`	Optionnel. Le paramètre `sharesnapshot` est une valeur de `DateTime` opaque qui, lorsqu’il est présent, spécifie l’instantané de partage à interroger pour la liste des handles.

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 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, facultatif pour les demandes anonymes. Spécifie la version de l’opération à utiliser pour cette requête. 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-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` 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. Pour plus d’informations, consultez nommage et référencement de partages, répertoires, fichiers et métadonnées.

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 du tableau suivant. 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 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`	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.

Corps de la réponse

Le format de la réponse XML est le suivant. Notez que les éléments Marker, ShareSnapshotet MaxResults sont présents uniquement si vous les avez spécifiés 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.

ClientName champ en réponse est facultatif et retourné uniquement lorsqu’il est disponible pour le service.

<?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>
            <ClientName>client-name</ClientName>
            <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	But
`HandleId`	ID de handle de service XSMB, UINT64.	Utilisé pour identifier le handle.
`Path`	Nom de fichier, y compris le chemin d’accès complet, à partir de la racine du partage. Corde.	Permet d’identifier le nom de l’objet pour lequel le handle est ouvert.
`ClientIp`	Adresse IP du client qui a ouvert le handle. Corde.	Utilisé pour décider si la poignée a pu être divulguée.
`ClientName`	Champ facultatif. Prise en charge en 2024-02-04 et versions ultérieures. Nom du client (station de travail ou nom d’utilisateur du système d’exploitation) qui a ouvert le handle. Corde.	Utilisé pour décider si la poignée a pu être divulguée.
`OpenTime`	Le handle d’heure a été ouvert (UTC). `DateTime` sous forme de chaîne.	Utilisé pour décider si la poignée a pu être divulguée. Les poignées divulguées ont généralement été ouvertes depuis longtemps.
`LastReconnectTime`	Le handle d’heure a été ouvert (UTC). `DateTime` sous forme de chaîne.	Utilisé pour déterminer si le handle a été rouvert après une déconnexion client/serveur, en raison d’une mise en réseau ou d’autres erreurs. Le champ est inclus dans le corps de la réponse uniquement si l’événement de déconnexion s’est produit et que le handle a été rouvert.
`FileId`	ID de fichier, UINT64.	`FileId` identifie de manière unique le fichier. Il est utile pendant les 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 pendant les 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. Permet d’interroger les autorisations d’accès conservées 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 encodera en pourcentage (par RFC 2396) toutes les valeurs d’élément Path 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 attribut Encoded=true. Notez que cela se produit uniquement pour les valeurs d’élément Path contenant les caractères non valides dans XML, et non pour les éléments Path restants dans la réponse.

ClientName est pris en charge dans la version 2024-02-04 et ultérieure.

Autorisation

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

Remarques

Le 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

opérations sur les fichiers
Opérations de sur les répertoires

Partager via