Handle elenco

Articolo
02/21/2025

L'operazione List Handles restituisce un elenco di handle aperti in una directory o in un file. Facoltativamente, può enumerare in modo ricorsivo gli 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

La richiesta di List Handles viene costruita nel modo seguente. È consigliabile usare HTTPS.

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

Sostituire i componenti del percorso visualizzati nell'URI della richiesta con i propri, come indicato di seguito:

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

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

Parametri URI

È possibile specificare i parametri aggiuntivi seguenti nell'URI.

Parametro	Descrizione
`marker`	Opzionale. Valore stringa che identifica la parte dell'elenco da restituire con l'operazione di `List Handles` successiva. L'operazione restituisce un valore 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 dell'indicatore è opaco per il client.
`maxresults`	Opzionale. Specifica il numero massimo di handle eseguiti su file o directory da restituire. Se si imposta `maxresults` su un valore minore o uguale a zero, viene restituito il codice di risposta di errore 400 (richiesta non valida).
`timeout`	Opzionale. Il parametro `timeout` è espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di File di Azure.
`sharesnapshot`	Opzionale. Il parametro `sharesnapshot` è un valore opaco `DateTime` che, quando presente, specifica lo snapshot di condivisione su cui eseguire una query per l'elenco di handle.

Intestazioni della richiesta

Nella tabella seguente 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 l'ora UTC (Coordinated Universal Time) per la richiesta. 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 utilizzare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
`x-ms-client-request-id`	Opzionale. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log quando viene configurata la registrazione. È consigliabile usare questa intestazione per correlare le attività sul lato client alle richieste ricevute dal server. Per altre informazioni, vedere Monitorare File di Azure.
`x-ms-recursive`	Opzionale. 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` intestazione specifica un token OAuth. Il valore accettabile è `backup`. Questa intestazione specifica che il `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 successive.
`x-ms-allow-trailing-dot: { <Boolean> }`	Opzionale. Versione 2022-11-02 e 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 riferimento a condivisioni, directory, file e metadati.

Corpo della richiesta

Nessuno.

Risposta

La risposta include un codice di stato HTTP, un set di intestazioni di risposta e un corpo della risposta in formato XML.

Codice di stato

Un'operazione riuscita restituisce il codice di stato 200 (OK). Per informazioni sui codici di stato, vedere Stato e codici di errore.

Intestazioni di risposta

La risposta per questa operazione include le intestazioni nella tabella seguente. La risposta può includere anche intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1 .

Intestazioni comuni

Intestazione della 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 delle 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 i problemi relativi alle richieste e alle 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 elementi Marker, 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 completi.

ClientName campo in risposta è facoltativo e restituito solo quando disponibile per il servizio.

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

La tabella seguente descrive i campi del corpo della risposta:

Campo	Descrizione	Scopo
`HandleId`	ID dell'handle del servizio XSMB, UINT64.	Usato per identificare l'handle.
`Path`	Nome file, incluso il percorso completo, a partire dalla radice della condivisione. Corda.	Utilizzato per identificare il nome dell'oggetto per il quale l'handle è aperto.
`ClientIp`	IP client che ha aperto l'handle. Corda.	Usato per decidere se l'handle potrebbe essere stato trapelato.
`ClientName`	Campo facoltativo. Supportato nel 2024-02-04 e versioni successive. Nome client (workstation o nome utente del sistema operativo) che ha aperto l'handle. Corda.	Usato per decidere se l'handle potrebbe essere stato trapelato.
`OpenTime`	Handle di ora aperto (UTC). `DateTime` come Stringa.	Usato per decidere se handle potrebbe essere stato trapelato. Le handle perse sono in genere state aperte da molto tempo.
`LastReconnectTime`	Handle di ora 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 altro tipo. 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 ridenominazione, perché il `FileId` non cambia.
`ParentId`	ID file padre, UINT64.	`ParentId` identifica in modo univoco la directory. Ciò è utile durante le ridenominazione, perché il `ParentId` non cambia.
`SessionId`	ID sessione SMB che specifica il contesto in cui è stato aperto l'handle di file. UINT64.	`SessionId` è incluso nei registri del visualizzatore eventi quando le sessioni vengono disconnesse forzatamente. Consente di associare un batch specifico di handle persi a un evento imprevisto di rete specifico.
`AccessRightList`	Autorizzazioni di accesso concesse all'handle aperto nel file o nella directory.	Disponibile nel servizio versione 2023-01-03 e successive. Consente di 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 oppure 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 successive List Handles codifica percentuale (per RFC 2396) tutti i valori degli elementi Path che contengono caratteri non validi in XML (in particolare U+FFFE o U+FFFF). Se codificato, l'elemento Path includerà un attributo Encoded=true. Si noti che ciò si verificherà solo per i valori degli elementi Path contenenti i caratteri non validi in XML, non per gli elementi Path rimanenti nella risposta.

ClientName è supportato nella versione 2024-02-04 e successive.

Autorizzazione

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

Osservazioni

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

Vedere anche

operazioni di su file
operazioni sulle directory

Condividi tramite