Condividi tramite


Handle elenco

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 Sì
NFS No

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.

Vedi anche