Udostępnij za pośrednictwem

Dojścia listy

  • Artykuł

Operacja List Handles zwraca listę otwartych dojść w katalogu lub pliku. Opcjonalnie może cyklicznie wyliczać otwarte dojścia w katalogach i plikach. Ten interfejs API jest dostępny od wersji 2018-11-09.

Dostępność protokołu

Włączony protokół udziału plików Dostępne
SMB Tak
NFS Nie

Żądanie

Żądanie można skonstruować List Handles w następujący sposób. Zalecane jest użycie protokołu HTTPS.

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
GET https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles HTTP/1.1

Zastąp składniki ścieżki wyświetlane w identyfikatorze URI żądania własnymi elementami w następujący sposób:

Składnik ścieżki Opis
myaccount Nazwa konta magazynu.
myshare Nazwa udziału plików.
mydirectorypath Opcjonalny. Ścieżka do katalogu.
myfileordirectory Nazwa pliku lub katalogu.

Aby uzyskać szczegółowe informacje na temat ograniczeń nazewnictwa ścieżek, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

Parametry identyfikatora URI

W identyfikatorze URI można określić następujące dodatkowe parametry.

Parametr Opis
marker Opcjonalny. Wartość ciągu identyfikującą część listy, która ma zostać zwrócona przy użyciu następnej List Handles operacji. Operacja zwraca wartość znacznika w treści odpowiedzi, jeśli zwrócona lista nie została ukończona. Następnie możesz użyć wartości znacznika w kolejnym wywołaniu, aby zażądać następnego zestawu elementów listy.

Wartość znacznika jest nieprzezroczysta dla klienta.
maxresults Opcjonalny. Określa maksymalną liczbę dojść pobranych do plików lub katalogów do zwrócenia.

Ustawienie maxresults wartości mniejszej lub równej zero powoduje wyświetlenie kodu odpowiedzi błędu 400 (Nieprawidłowe żądanie).
timeout Opcjonalny. Parametr jest wyrażony timeout w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji Azure Files.
sharesnapshot Opcjonalny. Parametr sharesnapshot jest nieprzezroczystą DateTime wartością, która w chwili obecnej określa migawkę udziału, aby wykonać zapytanie o listę dojść.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.

Nagłówek żądania Opis
Authorization Wymagane. Określa schemat autoryzacji, nazwę konta i podpis. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
Date lub x-ms-date Wymagane. Określa dla żądania godzinę w formacie uniwersalnego czasu koordynowanego (UTC). Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
x-ms-version Wymagane dla wszystkich autoryzowanych żądań, opcjonalnie dla żądań anonimowych. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
x-ms-client-request-id Opcjonalny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB) rejestrowanym w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer. Aby uzyskać więcej informacji, zobacz Monitorowanie Azure Files.
x-ms-recursive Opcjonalny. Wartość logiczna określająca, czy operacja powinna być również stosowana do plików i podkatalogów katalogu określonego w identyfikatorze URI.
x-ms-file-request-intent Wymagane, jeśli Authorization nagłówek określa token OAuth. Akceptowalna wartość to backup. Ten nagłówek określa, czy Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action element lub Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action ma zostać przyznany, jeśli są one uwzględnione w zasadach RBAC przypisanych do tożsamości, która jest autoryzowana przy użyciu nagłówka Authorization . Dostępne dla wersji 2022-11-02 lub nowszej.
x-ms-allow-trailing-dot: { <Boolean> } Opcjonalny. Wersja 2022-11-02 lub nowsza. Wartość logiczna określa, czy końcowa kropka obecna w adresie URL żądania powinna zostać przycięta, czy nie. Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

Treść żądania

Brak.

Reakcja

Odpowiedź zawiera kod stanu HTTP, zestaw nagłówków odpowiedzi i treść odpowiedzi w formacie XML.

Kod stanu

Pomyślna operacja zwraca kod stanu 200 (OK). Aby uzyskać informacje o kodach stanu, zobacz Kody stanu i błędów.

Nagłówki odpowiedzi

Odpowiedź na tę operację zawiera następujące nagłówki. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1.

Nagłówek odpowiedzi Opis
Content-Type Określa format, w którym są zwracane wyniki. Obecnie ta wartość to application/xml.
x-ms-request-id Ten nagłówek jednoznacznie identyfikuje wykonane żądanie i może służyć do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z operacjami interfejsu API.
x-ms-version Wskazuje wersję Azure Files używaną do uruchomienia żądania.
Date Wartość daty/godziny UTC wskazująca godzinę, o której zainicjowano odpowiedź. Usługa generuje tę wartość.
x-ms-client-request-id Ten nagłówek służy do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości nagłówka x-ms-client-request-id , jeśli jest obecna w żądaniu. Wartość jest najwyżej 1024 widocznymi znakami ASCII. x-ms-client-request-id Jeśli nagłówek nie istnieje w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Treść odpowiedzi

Format odpowiedzi XML jest następujący. Należy pamiętać, że Markerelementy , ShareSnapshoti MaxResults są obecne tylko wtedy, gdy zostały określone w identyfikatorze URI żądania. Element NextMarker ma wartość tylko wtedy, gdy wyniki listy nie zostaną ukończone.

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

W poniższej tabeli opisano pola treści odpowiedzi:

Pole Opis Przeznaczenie
HandleId Identyfikator uchwytu usługi XSMB, UINT64. Służy do identyfikowania uchwytu.
Path Nazwa pliku, w tym pełna ścieżka, zaczynając od katalogu głównego udziału. Ciąg. Służy do identyfikowania nazwy obiektu, dla którego jest otwarty uchwyt.
ClientIp Adres IP klienta, który otworzył dojście. Ciąg. Służy do decydowania, czy dojście mogło zostać ujawnione.
OpenTime Czas otwarcia dojścia (UTC). DateTime jako ciąg. Służy do decydowania, czy dojście mogło zostać ujawnione. Wyciekły uchwyty były zwykle otwarte przez długi czas.
LastReconnectTime Czas otwarcia dojścia (UTC). DateTime jako ciąg. Służy do określania, czy uchwyt został ponownie otwarty po rozłączeniu klienta/serwera z powodu sieci lub innych błędów. Pole jest uwzględniane w treści odpowiedzi tylko w przypadku wystąpienia zdarzenia rozłączenia i ponownego otwarcia dojścia.
FileId Identyfikator pliku, UINT64. FileId jednoznacznie identyfikuje plik. Jest to przydatne podczas zmieniania nazw, ponieważ FileId nie zmienia się.
ParentId Identyfikator pliku nadrzędnego, UINT64. ParentId jednoznacznie identyfikuje katalog. Jest to przydatne podczas zmieniania nazw, ponieważ ParentId nie zmienia się.
SessionId Identyfikator sesji SMB określający kontekst, w którym otwarto dojście do pliku. UINT64. SessionId Jest uwzględniany w dziennikach podglądu zdarzeń, gdy sesje są wymuszone rozłączenia. Umożliwia skojarzenie określonej partii ujawnionych dojść z określonym zdarzeniem sieciowym.
AccessRightList Uprawnienia dostępu przyznane otwartemu dojściu do pliku lub katalogu. Dostępne w usłudze w wersji 2023-01-03 lub nowszej.

Służy do wykonywania zapytań dotyczących uprawnień dostępu przechowywanych w pliku lub katalogu przez różne otwarte dojścia. Możliwe wartości to READ, WRITE i DELETE lub kombinacja tych wartości.
NextMarker Ciąg, który opisuje następny dojście do na liście. Jest zwracany, gdy należy wymienić więcej dojść, aby ukończyć żądanie. Ciąg jest używany w kolejnych żądaniach, aby wyświetlić listę pozostałych dojść. Brak NextMarker wskazuje, że zostały wymienione wszystkie odpowiednie dojścia.

W wersjach 2021-12-02 i nowszych List Handles będzie kodować procent (zgodnie z RFC 2396) wszystkie Path wartości elementów, które zawierają znaki nieprawidłowe w kodzie XML (w szczególności U+FFFE lub U+FFFF). W przypadku kodowania Path element będzie zawierać Encoded=true atrybut . Należy pamiętać, że będzie to miało miejsce tylko w przypadku Path wartości elementów zawierających nieprawidłowe znaki w kodzie XML, a nie pozostałych Path elementów w odpowiedzi.

Autoryzacja

Tylko właściciel konta może wywołać tę operację.

Uwagi

Jest HandleId to identyfikator dojścia po stronie usługi, różniące się od identyfikatora dojścia klienta. Mapowanie między nimi jest możliwe na kliencie.

Zobacz też