Wyświetlanie listy udziałów

Artykuł
08/05/2023

Operacja List Shares zwraca listę udziałów i migawek udziałów w ramach określonego konta. Ten interfejs API jest w pełni obsługiwany, ale jest to starszy interfejs API zarządzania. Użyj udziałów plików — lista dostarczana przez dostawcę zasobów magazynu (Microsoft.Storage), zamiast tego. Aby dowiedzieć się więcej o programowej interakcji z FileShare zasobami przy użyciu dostawcy zasobów magazynu, zobacz Operacje na udziałach plików.

Dostępność protokołu

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

Żądanie

Żądanie można skonstruować List Shares 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/?comp=list`	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.

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 żądania można określić następujące dodatkowe parametry.

Parametr	Opis
`prefix`	Opcjonalny. Filtruje wyniki, aby zwrócić tylko udziały, które mają nazwy rozpoczynające się od określonego prefiksu.
`marker`	Opcjonalny. Wartość ciągu identyfikującą część listy, która ma zostać zwrócona przy użyciu następnej operacji listy. 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ę udziałów do zwrócenia. Jeśli żądanie nie określi `maxresults`wartości lub określa wartość większą niż 5000, serwer zwróci maksymalnie 5000 elementów. Jeśli parametr jest ustawiony na wartość mniejszą lub równą zero, serwer zwróci kod stanu 400 (nieprawidłowe żądanie).
`include=metadata,snapshots,deleted`	Opcjonalny. Określa co najmniej jeden zestaw danych do uwzględnienia w odpowiedzi: - `snapshots`: wersja 2017-04-17 lub nowsza. Określa, że migawki udziału powinny być uwzględnione w odpowiedzi. Migawki udziałów są wyświetlane od najstarszego do najnowszego w odpowiedzi. - `metadata`: Określa, że metadane udziału powinny być zwracane w odpowiedzi. - `deleted`: Określa, że usunięte udziały plików powinny być uwzględnione w odpowiedzi. Aby określić więcej niż jedną z tych opcji w identyfikatorze URI, należy oddzielić każdą opcję przecinkiem zakodowanym pod adresem URL ("%82"). Wszystkie nazwy metadanych muszą być zgodne z konwencjami nazewnictwa identyfikatorów języka C#.
`timeout`	Opcjonalny. Parametr jest wyrażony `timeout` w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji Azure Files.

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ń. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage.
`x-ms-client-request-id`	Opcjonalny. Udostępnia 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 Monitorowanie Azure Files.

Treść żądania

Brak.

Reakcja

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

Kod stanu

Operacja zakończona powodzeniem zwraca kod stanu 200 (OK). Aby uzyskać informacje o kodach stanu, zobacz Stan i kody błędów.

Nagłówki odpowiedzi

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

Nagłówek odpowiedzi	Opis
`Content-Type`	Standardowy nagłówek HTTP/1.1. 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żytą do uruchomienia żądania.
`Date` lub `x-ms-date`	Wartość daty/godziny UTC wskazująca godzinę, w 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 `x-ms-client-request-id` nagłówka, jeśli jest obecna w żądaniu. Wartość wynosi co najwyżej 1024 widoczne znaki ASCII. `x-ms-client-request-id` Jeśli nagłówek nie znajduje się w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Treść odpowiedzi

Format treści odpowiedzi jest następujący.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults AccountName="https://myaccount.file.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Shares>  
    <Share>  
      <Name>share-name</Name>  
      <Snapshot>Date-Time Value</Snapshot>
      <Version>01D2AC0C18EDFE36</Version> 
      <Deleted>true</Deleted>  
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <Quota>max-share-size</Quota>
        <DeletedTime>Mon, 24 Aug 2020 04:56:10 GMT</DeletedTime>  
        <RemainingRetentionDays>360</RemainingRetentionDays>
        <AccessTier>TransactionOptimized</AccessTier>
        <AccessTierChangeTime>Mon, 24 Aug 2020 03:56:10 GMT</AccessTierChangeTime>
        <AccessTierTransitionState>pending-from-cool</AccessTierTransitionState>
        <EnabledProtocols>SMB</EnabledProtocols>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Share>  
  </Shares>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

Element EnabledProtocols jest wyświetlany w treści odpowiedzi tylko w wersji 2020-02-10 lub nowszej.
Element RootSquash pojawia się w treści odpowiedzi tylko w wersji 2020-02-10 lub nowszej, gdy włączone protokoły zawierają system plików NFS.
Element Quota pojawia się w treści odpowiedzi tylko w wersji 2015-02-21 lub nowszej.
VersionElementy , Deleted, DeletedTimei RemainingRetentionDays są wyświetlane w treści odpowiedzi tylko w wersji 2019-12-12 lub nowszej.
PrefixElementy , Markeri MaxResults są obecne tylko wtedy, gdy określisz je w identyfikatorze URI. Element NextMarker ma wartość tylko wtedy, gdy wyniki listy nie zostaną ukończone.
Element Metadata jest obecny tylko wtedy, gdy określisz include=metadata parametr w identyfikatorze URI. W elemecie Metadata wartość każdej pary name-value jest wyświetlana w elemecie odpowiadającym nazwie pary.
Migawki są uwzględniane w odpowiedzi tylko wtedy, gdy określiszinclude=snapshots parametr z parametrem include w identyfikatorze URI żądania.
Element AccessTier zawiera warstwę udziału. Jeśli warstwa udziału nie została zmieniona, ta właściwość będzie domyślną warstwą TransactionOptimized na kontach magazynu ogólnego przeznaczenia w wersji 2 (GPv2). Na Azure Files kontach magazynu właściwość będzie Premiummieć wartość , która jest jedyną obsługiwaną warstwą.
Element AccessTierChangeTime jest obecny tylko wtedy, gdy jawnie ustawisz warstwę dostępu w udziale.
Element AccessTierTransitionState jest obecny tylko wtedy, gdy udział przechodzi z jednej warstwy do innej. Wskazuje ona warstwę, z która przechodzi.
Element ProvisionedIngressMBps jest obecny tylko dla Premium kont Azure Files i w wersji 2019-07-07 lub nowszej. Pokazuje on aprowizowany ruch przychodzący w usłudze MiB/s.
Element ProvisionedEgressMBps jest obecny tylko dla Premium kont Azure Files i w wersji 2019-07-07 lub nowszej. Pokazuje on aprowizowany ruch wychodzący w usłudze MiB/s.
Element ProvisionedBandwidthMiBps jest obecny tylko dla Premium kont Azure Files i w wersji 2021-02-12 lub nowszej. Pokazuje aprowizowaną przepustowość (ruch przychodzący i ruch wychodzący połączony) w usłudze MiB/s.

Przykładowa odpowiedź

Zobacz sekcję Przykładowe żądanie i odpowiedź w dalszej części tego tematu.

Autoryzacja

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

Uwagi

Jeśli określisz wartość parametru maxresults , a liczba udziałów do zwrócenia przekroczy tę wartość lub przekroczy wartość domyślną dla maxresultsparametru , treść odpowiedzi zawiera NextMarker element. Ten element wskazuje następny udział, który ma powrócić do kolejnego żądania. Aby zwrócić następny zestaw elementów, określ wartość NextMarker jako parametr znacznika w identyfikatorze URI dla kolejnego żądania.

Należy pamiętać, że wartość elementu powinna być traktowana NextMarker jako nieprzezroczyste.

Udziały są wymienione w kolejności alfabetycznej w treści odpowiedzi.

Operacja przekroczyła List Shares limit czasu po 30 sekundach.

Przykładowe żądanie i odpowiedź

Poniższy przykładowy identyfikator URI żąda listy udziałów dla konta. Ustawia maksymalne wyniki, które mają być zwracane dla operacji początkowej na trzy.

GET https://myaccount.file.core.windows.net/?comp=list&maxresults=3&include=snapshots HTTP/1.1

Żądanie jest wysyłane z następującymi nagłówkami:

x-ms-version: 2020-02-10  
x-ms-date: <date>  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=

Kod stanu i nagłówki odpowiedzi są zwracane w następujący sposób:

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: <date>  
x-ms-version: 2020-02-10  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

Kod XML odpowiedzi dla tego żądania jest następujący. Należy pamiętać, że NextMarker element jest zgodny z zestawem udziałów i zawiera nazwę następnego udziału, który ma zostać zwrócony.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint=" https://myaccount.file.core.windows.net">  
  <MaxResults>3</MaxResults>  
  <Shares>  
    <Share>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified><date></Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag>  
        <Quota>55</Quota>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>SMB</EnabledProtocols>
      </Properties>  
    </Share>  
    <Share>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified><date></Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>SMB</EnabledProtocols>
      </Properties>  
    </Share>  
    <Share>
      <Name>textfiles</Name>
      <Snapshot>2017-05-12T20:52:22.0000000Z</Snapshot>
      <Properties>
        <Last-Modified><date></Last-Modified>
        <Etag>0x8D3F2E1A9D14700</Etag>
        <Quota>30</Quota>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>NFS</EnabledProtocols>
        <RootSquash>RootSquash</RootSquash>
      </Properties>
    </Share>
    <Share>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified><date></Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
        <Quota>30</Quota>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>NFS</EnabledProtocols>
        <RootSquash>AllSquash</RootSquash>  
      </Properties>  
    </Share>
  </Shares>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>

Kolejna operacja listy określa znacznik identyfikatora URI żądania w następujący sposób. Zostanie zwrócony następny zestaw wyników, rozpoczynając od udziału określonego przez znacznik.

https://myaccount.file.core.windows.net/?comp=list&maxresults=3&marker=video

Zobacz też

interfejs API REST Azure Files