Handle elenco

Articolo
03/29/2023

L'operazione List Handles restituisce un elenco di handle aperti in una directory o in un file. Facoltativamente, può enumerare in modo ricorsivo handle aperti nelle directory e nei file. Questa API è disponibile a partire dalla versione 2018-11-09.

Disponibilità del protocollo

Protocollo di condivisione file abilitato	Disponibile
SMB
NFS

Richiesta

È possibile costruire la List Handles richiesta come indicato di seguito. È consigliato il protocollo HTTPS.

Metodo	URI richiesta	Versione HTTP
`GET`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles`	HTTP/1.1

Sostituire i componenti del percorso mostrati nell'URI di richiesta con valori personalizzati, come illustrato di seguito:

Componente percorso	Descrizione
`myaccount`	nome dell'account di archiviazione.
`myshare`	Nome della condivisione file.
`mydirectorypath`	Facoltativa. Percorso della directory.
`myfileordirectory`	Nome del file o della directory.

Per informazioni dettagliate sulle restrizioni di denominazione del percorso, vedere Denominazione e riferimento a condivisioni, directory, file e metadati.

Parametri URI

È possibile specificare i parametri aggiuntivi seguenti nell'URI.

Parametro	Descrizione
`marker`	Facoltativa. Valore stringa che identifica la parte dell'elenco da restituire con l'operazione successiva `List Handles` . L'operazione restituisce un valore di marcatore all'interno del corpo della risposta, se l'elenco restituito non è stato completato. È quindi possibile usare il valore del marcatore in una chiamata successiva per richiedere il set successivo di elementi di elenco. Il valore marcatore risulta opaco al client.
`maxresults`	Facoltativa. Specifica il numero massimo di handle eseguiti su file o directory da restituire. L'impostazione di `maxresults` su un valore minore o uguale a zero restituisce il codice di risposta 400 (Richiesta non valida).
`timeout`	Facoltativa. Il parametro `timeout` viene espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di File di Azure.
`sharesnapshot`	Facoltativa. Il `sharesnapshot` parametro è un valore opaco `DateTime` che, quando presente, specifica lo snapshot di condivisione per eseguire query per l'elenco di handle.

Intestazioni della richiesta

Nella seguente tabella vengono descritte le intestazioni di richiesta obbligatorie e facoltative.

Intestazione della richiesta	Descrizione
`Authorization`	Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`Date` o `x-ms-date`	Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`x-ms-version`	Obbligatorio per tutte le richieste autorizzate, facoltativo per le richieste anonime. Specifica la versione dell'operazione da usare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
`x-ms-client-request-id`	Facoltativa. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log quando la registrazione è configurata. È consigliabile usare questa intestazione per correlare le attività lato client con le richieste ricevute dal server. Per altre informazioni, vedere Monitorare File di Azure.
`x-ms-recursive`	Facoltativa. Valore booleano che specifica se l'operazione deve essere applicata anche ai file e alle sottodirectory della directory specificata nell'URI.
`x-ms-file-request-intent`	Obbligatorio se `Authorization` l'intestazione specifica un token OAuth. Il valore accettabile è `backup`. Questa intestazione specifica che l'oggetto `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` o `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` deve essere concesso se sono inclusi nei criteri di controllo degli accessi in base al ruolo assegnati all'identità autorizzata usando l'intestazione `Authorization` . Disponibile per la versione 2022-11-02 e versioni successive.
`x-ms-allow-trailing-dot: { <Boolean> }`	Facoltativa. Versione 2022-11-02 e versioni successive. Il valore booleano specifica se un punto finale presente nell'URL della richiesta deve essere tagliato o meno. Per altre informazioni, vedere Denominazione e riferimenti a condivisioni, directory, file e metadati.

Testo della richiesta

Nessuno.

Risposta

Nella risposta sono inclusi un codice di stato HTTP, un set di intestazioni di risposta e il corpo della risposta nel formato XML.

Codice stato

Un'operazione completata correttamente restituisce 200 (OK). Per informazioni sui codici di stato, vedere Codici di stato e di errore.

Intestazioni di risposta

Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; La risposta può includere anche intestazioni HTTP aggiuntive e standard. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Intestazione risposta	Descrizione
`Content-Type`	Specifica il formato in cui vengono restituiti i risultati. Attualmente questo valore è `application/xml`.
`x-ms-request-id`	Questa intestazione identifica in modo univoco la richiesta effettuata e può essere usata per la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risoluzione dei problemi relativi alle operazioni api.
`x-ms-version`	Indica la versione di File di Azure usata per eseguire la richiesta.
`Date`	Valore di data/ora UTC che indica l'ora in cui è stata avviata la risposta. Il servizio genera questo valore.
`x-ms-client-request-id`	È possibile usare questa intestazione per risolvere le richieste e le risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione `x-ms-client-request-id` , se presente nella richiesta. Il valore è al massimo 1024 caratteri ASCII visibili. Se l'intestazione `x-ms-client-request-id` non è presente nella richiesta, questa intestazione non sarà presente nella risposta.

Corpo della risposta

Il formato della risposta XML è il seguente. Si noti che gli Markerelementi , ShareSnapshote MaxResults sono presenti solo se sono stati specificati nell'URI della richiesta. L'elemento NextMarker ha un valore solo se i risultati dell'elenco non sono completati.

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

La tabella seguente descrive i campi del corpo della risposta:

Campo	Descrizione	Scopo
`HandleId`	ID dell'handle del servizio XSMB, UINT64.	Usato per identificare handle.
`Path`	Nome file, incluso il percorso completo, a partire dalla radice della condivisione. Stringa.	Usato per identificare il nome dell'oggetto per il quale l'handle è aperto.
`ClientIp`	IP client che ha aperto l'handle. Stringa.	Usato per decidere se l'handle potrebbe essere stato trapelato.
`OpenTime`	L'handle ora è stato aperto (UTC). `DateTime` come Stringa.	Usato per decidere se l'handle potrebbe essere stato trapelato. I handle con perdita di dati sono in genere aperti da molto tempo.
`LastReconnectTime`	L'handle ora è stato aperto (UTC). `DateTime` come Stringa.	Usato per decidere se l'handle è stato riaperto dopo una disconnessione client/server, a causa di problemi di rete o di altri errori. Il campo è incluso nel corpo della risposta solo se si è verificato l'evento di disconnessione e l'handle è stato riaperto.
`FileId`	ID file, UINT64.	`FileId` identifica in modo univoco il file. È utile durante le rinomina, perché `FileId` non cambia.
`ParentId`	ID file padre, UINT64.	`ParentId` identifica in modo univoco la directory. Questa operazione è utile durante le rinomina, perché non `ParentId` cambia.
`SessionId`	ID sessione SMB che specifica il contesto in cui è stato aperto l'handle di file. UINT64.	`SessionId` è incluso nei log del visualizzatore eventi quando le sessioni vengono disconnesse in modo forcibly. Consente di associare un batch specifico di handle perdite a un evento imprevisto di rete specifico.
`AccessRightList`	Autorizzazioni di accesso concesse all'handle aperto nel file o nella directory.	Disponibile nella versione del servizio 2023-01-03 e versioni successive. Usato per eseguire query sulle autorizzazioni di accesso mantenute in un file o in una directory da vari handle aperti. I valori possibili sono READ, WRITE e DELETE o una combinazione di questi valori.
`NextMarker`	Stringa che descrive l'handle successivo da elencare. Viene restituito quando è necessario elencare più handle per completare la richiesta.	La stringa viene usata nelle richieste successive per elencare gli handle rimanenti. L'assenza di `NextMarker` indica che sono stati elencati tutti gli handle pertinenti.

Nelle versioni 2021-12-02 e versioni successive, List Handles codifica per percentuale (per RFC 2396) tutti i Path valori di elemento che contengono caratteri non validi in XML (in particolare U+FFFE o U+FFFF). Se codificato, l'elemento Path includerà un Encoded=true attributo. Si noti che si verificherà solo per i Path valori di elemento contenenti i caratteri non validi in XML, non gli elementi rimanenti Path nella risposta.

Autorizzazione

Solo il proprietario dell'account può chiamare questa operazione.

Commenti

L'oggetto HandleId è un ID handle lato servizio, distinto dall'ID dell'handle client. Il mapping tra i due è possibile nel client.