Freigaben auflisten

Artikel
08/07/2024

Der vorgang List Shares gibt eine Liste der Freigaben und Freigabemomentaufnahmen unter dem angegebenen Konto zurück. Diese API wird vollständig unterstützt, aber es handelt sich um eine Legacyverwaltungs-API. Verwenden Sie stattdessen Dateifreigaben –auflisten, die vom Speicherressourcenanbieter (Microsoft.Storage) bereitgestellt werden. Weitere Informationen zur programmgesteuerten Interaktion mit FileShare Ressourcen mithilfe des Speicherressourcenanbieters finden Sie unter Vorgänge auf FileShares.

Protokollverfügbarkeit

Aktiviertes Dateifreigabeprotokoll	Verfügbar
SMB
NFS

Bitten

Sie können die List Shares Anforderung wie folgt erstellen. HTTPS wird empfohlen.

Methode	Anforderungs-URI	HTTP-Version
`GET`	`https://myaccount.file.core.windows.net/?comp=list`	HTTP/1.1

Ersetzen Sie die pfadkomponenten, die im Anforderungs-URI angezeigt werden, wie folgt:

Pfadkomponente	Beschreibung
`myaccount`	Der Name Ihres Speicherkontos.

Ausführliche Informationen zu Pfadbenennungseinschränkungen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.

URI-Parameter

Sie können die folgenden zusätzlichen Parameter für den Anforderungs-URI angeben.

Parameter	Beschreibung
`prefix`	Wahlfrei. Filtert die Ergebnisse, um nur Freigaben mit Namen zurückzugeben, die mit dem angegebenen Präfix beginnen.
`marker`	Wahlfrei. Ein Zeichenfolgenwert, der den Teil der Liste identifiziert, der mit dem nächsten Listenvorgang zurückgegeben werden soll. Der Vorgang gibt einen Markierungswert im Antworttext zurück, wenn die zurückgegebene Liste nicht abgeschlossen wurde. Anschließend können Sie den Markierungswert in einem nachfolgenden Aufruf verwenden, um den nächsten Satz von Listenelementen anzufordern. Der Markerwert ist für den Client nicht transparent.
`maxresults`	Wahlfrei. Gibt die maximale Anzahl der zurückzugebenden Freigaben an. Wenn die Anforderung nicht `maxresults`angibt oder einen Wert größer als 5.000 angibt, gibt der Server bis zu 5.000 Elemente zurück. Wenn der Parameter auf einen Wert kleiner oder gleich Null festgelegt ist, gibt der Server den Statuscode 400 (Ungültige Anforderung) zurück.
`include=metadata,snapshots,deleted`	Wahlfrei. Gibt ein oder mehrere Datasets an, die in die Antwort eingeschlossen werden sollen: - `snapshots`: Version 2017-04-17 und höher. Gibt an, dass Die Freigabemomentaufnahmen in die Antwort einbezogen werden sollen. Freigabemomentaufnahmen werden von der ältesten bis zur neuesten in der Antwort aufgelistet. - `metadata`: Gibt an, dass Freigabemetadaten in der Antwort zurückgegeben werden sollen. - `deleted`: Gibt an, dass gelöschte Dateifreigaben in die Antwort einbezogen werden sollen. Um mehrere dieser Optionen für den URI anzugeben, müssen Sie jede Option durch ein URL-codiertes Komma ("%82") trennen. Alle Metadatennamen müssen den Benennungskonventionen für C#-Bezeichnerentsprechen.
`timeout`	Wahlfrei. Der parameter `timeout` wird in Sekunden ausgedrückt. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Files-Vorgänge.

Anforderungsheader

In der folgenden Tabelle werden die erforderlichen und optionalen Anforderungsheader beschrieben.

Anforderungsheader	Beschreibung
`Authorization`	Erforderlich. Gibt das Autorisierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`Date` oder `x-ms-date`	Erforderlich. Gibt die koordinierte Weltzeit (UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`x-ms-version`	Erforderlich für alle autorisierten Anforderungen. Gibt die Version des Vorgangs an, der für diese Anforderung verwendet werden soll. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure Storage-Dienste.
`x-ms-client-request-id`	Wahlfrei. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem 1-Kibibyte-Zeichenlimit (KiB) bereit, der in den Protokollen aufgezeichnet wird, wenn die Protokollierung konfiguriert ist. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt. Weitere Informationen finden Sie unter Überwachen von Azure Files.

Anforderungstext

Nichts.

Antwort

Die Antwort enthält einen HTTP-Statuscode, eine Reihe von Antwortheadern und einen Antworttext im XML-Format.

Statuscode

Ein erfolgreicher Vorgang gibt den Statuscode 200 (OK) zurück. Informationen zu Statuscodes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang enthält die folgenden Header. Die Antwort enthält auch zusätzliche, standardmäßige HTTP-Header. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortheader	Beschreibung
`Content-Type`	Standard-HTTP/1.1-Header. Gibt das Format an, in dem die Ergebnisse zurückgegeben werden. Derzeit ist dieser Wert `application/xml`.
`x-ms-request-id`	Dieser Header identifiziert die anforderung eindeutig und kann für die Problembehandlung der Anforderung verwendet werden. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
`x-ms-version`	Gibt die Version von Azure Files an, die zum Ausführen der Anforderung verwendet wird.
`Date` oder `x-ms-date`	Ein UTC-Datums-/Uhrzeitwert, der die Uhrzeit angibt, zu der die Antwort initiiert wurde. Der Dienst generiert diesen Wert.
`x-ms-client-request-id`	Sie können diesen Header verwenden, um Anfragen und entsprechende Antworten zu behandeln. Der Wert dieses Headers ist gleich dem Wert des `x-ms-client-request-id`-Headers, wenn er in der Anforderung vorhanden ist. Der Wert beträgt höchstens 1024 sichtbare ASCII-Zeichen. Wenn der `x-ms-client-request-id`-Header in der Anforderung nicht vorhanden ist, ist dieser Header in der Antwort nicht vorhanden.

Antworttext

Das Format des Antworttexts lautet wie folgt.

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

Das EnabledProtocols-Element wird nur in Version 2020-02-10 und höher im Antworttext angezeigt.
Das RootSquash-Element wird nur in Version 2020-02-10 und höher im Antworttext angezeigt, wenn die aktivierten Protokolle NFS enthalten. Dieses Element wird nur für Freigaben zurückgegeben, nicht für Momentaufnahmen.
Das Quota-Element wird nur in Version 2015-02-21 und höher im Antworttext angezeigt.
Die Elemente Version, Deleted, DeletedTimeund RemainingRetentionDays werden nur in Version 2019-12-12 und höher im Antworttext angezeigt.
Die elemente Prefix, Markerund MaxResults sind nur vorhanden, wenn Sie sie für den URI angeben. Das NextMarker-Element weist nur dann einen Wert auf, wenn die Listenergebnisse nicht abgeschlossen sind.
Das Metadata-Element ist nur vorhanden, wenn Sie den include=metadata Parameter für den URI angeben. Innerhalb des Metadata Elements wird der Wert jedes Namens-Wert-Paars innerhalb eines Elements aufgeführt, das dem Namen des Paares entspricht.
Die Momentaufnahmen sind nur in der Antwort enthalten, wenn Sie deninclude=snapshots-Parameter mit dem parameter include für den Anforderungs-URI angeben.
Das AccessTier-Element enthält die Ebene der Freigabe. Wenn die Freigabeebene nicht geändert wurde, ist diese Eigenschaft die Standardebene TransactionOptimized für allgemeine Speicherkonten der Version 2 (GPv2). Bei Azure Files-Speicherkonten wird die Eigenschaft Premium, was die einzige unterstützte Ebene ist.
Das AccessTierChangeTime-Element ist nur vorhanden, wenn Sie die Zugriffsebene für die Freigabe explizit festlegen.
Das AccessTierTransitionState-Element ist nur vorhanden, wenn die Freigabe von einer Ebene zu einer anderen wechselt. Sie gibt die Ebene an, von der sie wechselt.
Das ProvisionedIngressMBps-Element ist nur für Premium Azure Files-Konten und Version 2019-07-07 oder höher vorhanden. Er zeigt den bereitgestellten Eingangsschritt in MiB/s an.
Das ProvisionedEgressMBps-Element ist nur für Premium Azure Files-Konten und Version 2019-07-07 oder höher vorhanden. Es zeigt den bereitgestellten Ausgang in MiB/s.
Das ProvisionedBandwidthMiBps-Element ist nur für Premium Azure Files-Konten und Version 2021-02-12 oder höher vorhanden. Es zeigt bereitgestellte Bandbreite (Ausgang + Ausgang kombiniert) in MiB/s.
Das EnableSnapshotVirtualDirectoryAccess-Element wird nur in Version 2024-08-04 und höher im Antworttext angezeigt, wenn die aktivierten Protokolle NFS enthalten. Dieses Element wird nur für Freigaben zurückgegeben, nicht für Momentaufnahmen.
Das PaidBurstingEnabled-Element ist nur für Premium Azure Files-Konten in Version 2024-11-04 oder höher vorhanden. Dieses Element wird nur für Freigaben zurückgegeben, nicht für Momentaufnahmen.
Das PaidBurstingMaxIops-Element ist nur für Premium Azure Files-Konten in Version 2024-11-04 oder höher vorhanden. Sie wird nur zurückgegeben, wenn PaidBurstingEnabled für die Aktie wahr ist. Dieses Element wird nur für Freigaben zurückgegeben, nicht für Momentaufnahmen.
Das PaidBurstingMaxBandwidthMibps-Element ist nur für Premium Azure Files-Konten in Version 2024-11-04 oder höher vorhanden. Sie wird nur zurückgegeben, wenn PaidBurstingEnabled für die Aktie wahr ist. Dieses Element wird nur für Freigaben zurückgegeben, nicht für Momentaufnahmen.

Beispielantwort

Weitere Informationen finden Sie im Abschnitt Beispielanforderung und -antwort weiter unten in diesem Thema.

Ermächtigung

Nur der Kontobesitzer kann diesen Vorgang aufrufen.

Bemerkungen

Wenn Sie einen Wert für den maxresults-Parameter angeben und die Anzahl der zurückzugebenden Freigaben diesen Wert überschreitet oder den Standardwert für maxresultsüberschreitet, enthält der Antworttext ein NextMarker Element. Dieses Element gibt die nächste Freigabe an, die für eine nachfolgende Anforderung zurückgegeben werden soll. Um den nächsten Satz von Elementen zurückzugeben, geben Sie den Wert NextMarker als Markerparameter für den URI für die nachfolgende Anforderung an.

Beachten Sie, dass der Wert von NextMarker als undurchsichtig behandelt werden sollte.

Freigaben werden im Antworttext in alphabetischer Reihenfolge aufgeführt.

Der List Shares Vorgang ist nach 30 Sekunden nicht mehr erfolgreich.

Beispielanforderung und -antwort

Der folgende Beispiel-URI fordert die Liste der Freigaben für ein Konto an. Sie legt die maximalen Ergebnisse fest, die für den anfänglichen Vorgang auf drei zurückgegeben werden sollen.

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

Die Anforderung wird mit folgenden Headern gesendet:

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

Der Statuscode und die Antwortheader werden wie folgt zurückgegeben:

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

Die Antwort-XML für diese Anforderung lautet wie folgt. Beachten Sie, dass das NextMarker-Element auf die Gruppe der Freigaben folgt und den Namen der nächsten zu zurückgebenden Freigabe enthält.

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

Der nachfolgende Listenvorgang gibt die Markierung für den Anforderungs-URI wie folgt an. Der nächste Satz von Ergebnissen wird zurückgegeben, beginnend mit der durch die Markierung angegebenen Freigabe.

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

Siehe auch

Rest-API für Azure Files

Freigeben über