Auflisten von Freigaben

Artikel
08/05/2023

Der List Shares Vorgang 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: Liste, die vom Speicherressourcenanbieter (Microsoft.Storage) bereitgestellt wird. Weitere Informationen zur programmgesteuerten Interaktion mit FileShare Ressourcen mithilfe des Speicherressourcenanbieters finden Sie unter Vorgänge auf Dateifreigaben.

Protokollverfügbarkeit

Aktiviertes Dateifreigabeprotokoll	Verfügbar
SMB
NFS

Anforderung

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 im Anforderungs-URI angezeigten Pfadkomponenten wie folgt durch Ihre eigenen Angaben:

Pfadkomponente	BESCHREIBUNG
`myaccount`	Der Name Ihres Speicherkontos.

Ausführliche Informationen zu Einschränkungen bei der Pfadbenennung 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`	Optional. Filtert die Ergebnisse, um nur Freigaben zurückzugeben, deren Namen mit dem angegebenen Präfix beginnen.
`marker`	Optional. Ein Zeichenfolgenwert, der den Teil der Liste angibt, der mit dem nächsten Auflistungsvorgang zurückgegeben wird. Der Vorgang gibt einen Markerwert innerhalb des Antworttexts zurück, wenn die zurückgegebene Liste nicht vollständig war. Sie können dann den Markerwert in einem nachfolgenden Aufruf verwenden, um den nächsten Satz von Listenelementen anzufordern. Der Markerwert ist für den Client nicht transparent.
`maxresults`	Optional. Gibt die maximale zurückzugebende Anzahl von Freigaben an. Wenn die Anforderung nicht angibt `maxresults`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 0 (null) festgelegt ist, gibt der Server den Statuscode 400 (Ungültige Anforderung) zurück.
`include=metadata,snapshots,deleted`	Optional. Gibt ein oder mehrere Datasets an, die in der Antwort eingeschlossen werden sollen: - `snapshots`: Version 2017-04-17 und höher. Gibt an, dass Freigabemomentaufnahmen in die Antwort eingeschlossen werden sollen. Freigabemomentaufnahmen werden in der Antwort von der ältesten bis zur neuesten aufgelistet. - `metadata`: Gibt an, dass Freigabemetadaten in der Antwort zurückgegeben werden sollen. - `deleted`: Gibt an, dass gelöschte Dateifreigaben in die Antwort eingeschlossen werden sollen. Um mehr als eine dieser Optionen im URI anzugeben, müssen Sie die Optionen jeweils mit einem URL-codierten Komma ("%82") trennen. Alle Metadatennamen müssen den Benennungskonventionen für C#-Bezeichner entsprechen.
`timeout`	Optional. Der `timeout`-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Files Vorgänge.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale 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 (Coordinated Universal Time, 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 für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
`x-ms-client-request-id`	Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (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 Azure Files.

Anforderungstext

Keine.

Antwort

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

Statuscode

Bei einem erfolgreichen Vorgang wird der Statuscode 200 (OK) zurückgegeben. Informationen zu status Codes finden Sie unter Status- und Fehlercodes.

Antwortheader

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

Antwortheader	BESCHREIBUNG
`Content-Type`	HTTP/1.1-Standardheader. Gibt das Format an, in dem die Ergebnisse zurückgegeben werden. Derzeit ist `application/xml`dieser Wert .
`x-ms-request-id`	Dieser Header identifiziert die durchgeführte 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 den Zeitpunkt angibt, zu dem die Antwort initiiert wurde. Der Dienst generiert diesen Wert.
`x-ms-client-request-id`	Sie können diesen Header verwenden, um Probleme mit Anforderungen und entsprechenden Antworten zu beheben. 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 sieht wie folgt aus.

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

Das EnabledProtocols -Element wird im Antworttext nur in Version 2020-02-10 und höher angezeigt.
Das RootSquash -Element wird im Antworttext nur ab Version 2020-02-10 angezeigt, wenn die aktivierten Protokolle NFS enthalten.
Das Quota Element wird nur in Version 2015-02-21 und höher im Antworttext angezeigt.
Die VersionElemente , Deleted, DeletedTimeund RemainingRetentionDays werden nur in Version 2019-12-12 und höher im Antworttext angezeigt.
Die PrefixElemente , Marker, und MaxResults sind nur vorhanden, wenn Sie sie für den URI angeben. Das NextMarker Element verfügt nur dann über einen Wert, wenn die Listenergebnisse nicht vollständig sind.
Das Metadata Element ist nur vorhanden, wenn Sie den include=metadata Parameter für den URI angeben. Im Metadata-Element wird der Wert jedes Name-Wert-Paars in einem Element aufgelistet, das dem Namen des Paars entspricht.
Die Momentaufnahmen sind nur in der Antwort enthalten, wenn Sie deninclude=snapshots Parameter mit dem include Parameter für den Anforderungs-URI angeben.
Das AccessTier Element enthält die Ebene der Freigabe. Wenn die Ebene der Freigabe nicht geändert wurde, ist diese Eigenschaft die Standardebene TransactionOptimized für Speicherkonten der allgemeinen Version 2 (GPv2). Auf Azure Files Speicherkonten lautet Premiumdie Eigenschaft , 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 zur anderen wechselt. Sie gibt die Ebene an, aus der der Übergang erfolgt.
Das ProvisionedIngressMBps Element ist nur für Premium Azure Files Konten und version 2019-07-07 oder höher vorhanden. Es zeigt den bereitgestellten Eingangseingang 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 Ausgehenden in MiB/s an.
Das ProvisionedBandwidthMiBps Element ist nur für Premium Azure Files Konten und version 2021-02-12 oder höher vorhanden. Es zeigt die bereitgestellte Bandbreite (eingangs und ausgehend kombiniert) in MiB/s an.

Beispiel für eine Antwort

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

Authorization

Nur der Kontobesitzer kann diesen Vorgang aufrufen.

Hinweise

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 bei einer nachfolgenden Anforderung zurückgegeben werden soll. Geben Sie zum Zurückgeben des nächsten Satzes von Elementen den Wert von NextMarker als Markerparameter im URI für die nächste Anforderung an.

Beachten Sie, dass der Wert von NextMarker als nicht transparent behandelt werden muss.

Freigaben werden im Antworttext in alphabetischer Reihenfolge aufgeführt.

Das Timeout des List Shares-Vorgangs beträgt 30 Sekunden.

Beispielanforderung und -antwort

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

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

Die Anforderung wird mit den 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

Das Antwort-XML für diese Anforderung lautet wie folgt. Beachten Sie, dass das NextMarker Element dem Satz von Freigaben folgt und den Namen der nächsten Freigabe enthält, die zurückgegeben werden soll.

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

Der folgende Auflistungsvorgang gibt den Marker im Anforderungs-URI wie folgt an. Der nächste Satz von Ergebnissen wird zurückgegeben, beginnend mit der vom Marker angegebenen Freigabe.

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

Weitere Informationen

REST-API für Azure Files