Dojścia listy

Artykuł
06/01/2023

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
NFS

Żą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.