Udostępnij za pośrednictwem

Dojścia listy

  • Artykuł

Operacja List Handles zwraca listę otwartych dojść w katalogu lub pliku. Opcjonalnie może rekursywnie 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ępny
SMB Tak
NFS nie

Prosić

Żądanie List Handles jest konstruowane w następujący sposób. Zalecamy używanie protokołu HTTPS.

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

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

Składnik ścieżki Opis
myaccount Nazwa konta magazynu.
myshare Nazwa udziału plików.
mydirectorypath Fakultatywny. Ś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 Fakultatywny. Wartość ciągu identyfikującą część listy, która ma zostać zwrócona przy użyciu następnej operacji List Handles. 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 Fakultatywny. 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 Fakultatywny. Parametr timeout jest wyrażony w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Azure Files.
sharesnapshot Fakultatywny. Parametr sharesnapshot jest nieprzezroczystą wartością DateTime, która w chwili obecnej określa migawkę udziału, aby wykonać zapytanie dotyczące listy 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 uniwersalny czas koordynowany (UTC) dla żądania. 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 Fakultatywny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB), który jest rejestrowany 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 Monitor Azure Files.
x-ms-recursive Fakultatywny. 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 nagłówek Authorization określa token OAuth. Akceptowalna wartość to backup. Ten nagłówek określa, że Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action lub Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action należy przyznać, jeśli są one uwzględnione w zasadach RBAC przypisanych do tożsamości autoryzowanej przy użyciu nagłówka Authorization. Dostępne dla wersji 2022-11-02 lub nowszej.
x-ms-allow-trailing-dot: { <Boolean> } Fakultatywny. 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

Żaden.

Odpowiedź

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 Stan i kody błędów.

Nagłówki odpowiedzi

Odpowiedź dla tej operacji zawiera nagłówki w poniższej tabeli. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1 .

Typowe nagłówki

Nagłówek odpowiedzi Opis
Content-Type Określa format, w którym są zwracane wyniki. Obecnie ta wartość jest 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ę usługi 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 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. Jeśli nagłówek x-ms-client-request-id nie znajduje się 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 elementy Marker, ShareSnapshoti MaxResults są obecne tylko wtedy, gdy określono je w identyfikatorze URI żądania. Element NextMarker ma wartość tylko wtedy, gdy wyniki listy nie zostaną ukończone.

ClientName pole w odpowiedzi jest opcjonalne i zwracane tylko wtedy, gdy jest dostępne dla usługi.

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

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

Pole Opis Cel
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. Struna. Służy do identyfikowania nazwy obiektu, dla którego jest otwarty uchwyt.
ClientIp Adres IP klienta, który otworzył dojście. Struna. Służy do decydowania, czy uchwyt mógł zostać ujawniony.
ClientName Pole opcjonalne. Obsługiwane w wersji 2024-02-04 lub nowszej. Nazwa klienta (stacja robocza lub nazwa użytkownika systemu operacyjnego), która otworzyła dojście. Struna. Służy do decydowania, czy uchwyt mógł zostać ujawniony.
OpenTime Otwarto uchwyt czasu (UTC). DateTime jako ciąg. Służy do decydowania, czy uchwyt mógł zostać ujawniony. Wyciekły uchwyty były zwykle otwarte przez długi czas.
LastReconnectTime Otwarto uchwyt czasu (UTC). DateTime jako ciąg. Służy do decydowania, czy obsługa została ponownie otwarta po rozłączeniu klienta/serwera z powodu sieci lub innych błędów. Pole jest uwzględniane w treści odpowiedzi tylko wtedy, gdy wystąpiło zdarzenie rozłączenia, a dojście zostało ponownie otwarte.
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 się nie zmienia.
SessionId Identyfikator sesji SMB określający kontekst, w którym otwarto dojście do pliku. UINT64. SessionId jest uwzględniana w dziennikach podglądu zdarzeń, gdy sesje są wymuszone rozłączone. 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 wymieniono wszystkie odpowiednie uchwyty.

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

ClientName jest obsługiwana w wersji 2024-02-04 lub nowszej.

Autoryzacja

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

Uwagi

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

Zobacz też