Dojścia listy
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 |
![]() |
NFS |
![]() |
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
, ShareSnapshot
i 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ż
- Operacje na plikach
- operacje w katalogach