Wyświetlanie listy udziałów

Artykuł
08/07/2024

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 — zamiast tego wyświetl listę, dostarczoną przez dostawcę zasobów magazynu (Microsoft.Storage). Aby dowiedzieć się więcej o programowej interakcji z zasobami FileShare przy użyciu dostawcy zasobów magazynu, zobacz Operations on FileShares.

Dostępność protokołu

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

Prosić

Żądanie List Shares można skonstruować w następujący sposób. Zalecany jest protokół 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

Możesz określić następujące dodatkowe parametry dla identyfikatora URI żądania.

Parametr	Opis
`prefix`	Fakultatywny. Filtruje wyniki, aby zwracać tylko udziały, które mają nazwy rozpoczynające się od określonego prefiksu.
`marker`	Fakultatywny. 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`	Fakultatywny. Określa maksymalną liczbę udziałów do zwrócenia. Jeśli żądanie nie określi `maxresults`lub określa wartość większą niż 5000, serwer zwróci do 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`	Fakultatywny. Określa co najmniej jeden zestaw danych do uwzględnienia w odpowiedzi: - `snapshots`: wersja 2017-04-17 lub nowsza. Określa, że migawki udziałów powinny być uwzględnione w odpowiedzi. Migawki udziałów są wyświetlane od najstarszych do najnowszych 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`	Fakultatywny. Parametr `timeout` jest wyrażony w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi 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 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ń. 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.

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 następujące nagłówki. Odpowiedź zawiera również dodatkowe, standardowe nagłówki HTTP. Wszystkie standardowe nagłówki 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ść 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` lub `x-ms-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 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>
        <PaidBurstingEnabled>true</PaidBurstingEnabled>
        <PaidBurstingMaxIops>20000</PaidBurstingMaxIops>
        <PaidBurstingMaxBandwidthMibps>4000</PaidBurstingMaxBandwidthMibps>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Share>  
  </Shares>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

Element EnabledProtocols pojawia się 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. Ten element zostanie zwrócony tylko dla udziałów, a nie dla migawek.
Element Quota pojawia się w treści odpowiedzi tylko w wersji 2015-02-21 lub nowszej.
Elementy Version, Deleted, DeletedTimei RemainingRetentionDays są wyświetlane w treści odpowiedzi tylko w wersji 2019-12-12 i nowszych.
Elementy Prefix, Markeri MaxResults są obecne tylko w przypadku określenia ich 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 parametr include=metadata w identyfikatorze URI. W ramach elementu Metadata wartość każdej pary nazwa-wartość jest wyświetlana w elemecie odpowiadającym nazwie pary.
Migawki są uwzględniane w odpowiedzi tylko wtedy, gdy określisz parametrinclude=snapshots 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 kontach magazynu usługi Azure Files właściwość będzie Premium, 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 kont usługi Premium 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 kont usługi Premium 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 kont usługi Premium Azure Files i w wersji 2021-02-12 lub nowszej. Pokazuje aprowizowaną przepustowość (ruch przychodzący + ruch wychodzący połączony) w usłudze MiB/s.
Element EnableSnapshotVirtualDirectoryAccess pojawia się w treści odpowiedzi tylko w wersji 2024-08-04 lub nowszej, gdy włączone protokoły zawierają system plików NFS. Ten element zostanie zwrócony tylko dla udziałów, a nie dla migawek.
Element PaidBurstingEnabled jest obecny tylko dla kont usługi Premium Azure Files w wersji 2024-11-04 lub nowszej. Ten element zostanie zwrócony tylko dla udziałów, a nie dla migawek.
Element PaidBurstingMaxIops jest obecny tylko dla kont usługi Premium Azure Files w wersji 2024-11-04 lub nowszej. Zostanie zwrócona tylko wtedy, gdy wartość PaidBurstingEnabled ma wartość true dla udziału. Ten element zostanie zwrócony tylko dla udziałów, a nie dla migawek.
Element PaidBurstingMaxBandwidthMibps jest obecny tylko dla kont usługi Premium Azure Files w wersji 2024-11-04 lub nowszej. Zostanie zwrócona tylko wtedy, gdy wartość PaidBurstingEnabled ma wartość true dla udziału. Ten element zostanie zwrócony tylko dla udziałów, a nie dla migawek.

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 maxresults, treść odpowiedzi zawiera element NextMarker. 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ść NextMarker powinna być traktowana jako nieprzezroczyste.

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

Limit czasu operacji List Shares 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 element NextMarker 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>
      </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ż

interfejsu API REST usługi Azure Files

Udostępnij za pośrednictwem