Partages de listes

Article
07/19/2023

L’opération List Shares retourne une liste des partages et des instantanés de partage sous le compte spécifié. Cette API est entièrement prise en charge, mais il s’agit d’une API de gestion héritée. Utilisez partages de fichiers - Liste, fourni par le fournisseur de ressources de stockage (Microsoft.Storage), à la place. Pour en savoir plus sur l’interaction programmatique avec FileShare les ressources à l’aide du fournisseur de ressources de stockage, consultez Opérations sur les partages de fichiers.

Disponibilité du protocole

Protocole de partage de fichiers activé	Disponible
SMB
NFS

Requête

Vous pouvez construire la List Shares requête comme suit. HTTPS est recommandé.

Méthode	URI de demande	Version HTTP
`GET`	`https://myaccount.file.core.windows.net/?comp=list`	HTTP/1.1

Remplacez les composants du chemin indiqués dans l'URI de la demande par les vôtres, comme suit :

Composant Path	Description
`myaccount`	nom de votre compte de stockage.

Pour plus d’informations sur les restrictions de nommage de chemin d’accès, consultez Affectation de noms et référencement de partages, répertoires, fichiers et métadonnées.

Paramètres URI

Vous pouvez spécifier les paramètres supplémentaires suivants sur l’URI de requête.

Paramètre	Description
`prefix`	facultatif. Filtre les résultats pour renvoyer uniquement les partages dont le nom commence par le préfixe spécifié.
`marker`	Optionnel. Valeur de chaîne qui identifie la partie de la liste à renvoyer avec l'opération de liste suivante. L’opération retourne une valeur de marqueur dans le corps de la réponse, si la liste retournée n’est pas complète. Vous pouvez ensuite utiliser la valeur de marqueur dans un appel suivant pour demander le jeu d’éléments de liste suivant. La valeur de marqueur est opaque au client.
`maxresults`	Optionnel. Indique le nombre maximal de partages à retourner. Si la demande ne spécifie `maxresults`pas ou spécifie une valeur supérieure à 5 000, le serveur retourne jusqu’à 5 000 éléments. Si le paramètre a une valeur inférieure ou égale à zéro, le serveur retourne le code d'état 400 (Demande incorrecte).
`include=metadata,snapshots,deleted`	Optionnel. Spécifie un ou plusieurs datasets à inclure dans la réponse : - `snapshots`: version 2017-04-17 et ultérieures. Spécifie que les instantanés de partage doivent être inclus dans la réponse. Les instantanés de partage sont répertoriés du plus ancien au plus récent dans la réponse. - `metadata`: spécifie que les métadonnées de partage doivent être retournées dans la réponse. - `deleted`: spécifie que les partages de fichiers supprimés doivent être inclus dans la réponse. Pour spécifier plusieurs de ces options dans l'URI, vous devez séparer chaque option par une virgule encodée dans l'URL (« %82 »). Tous les noms de métadonnées doivent respecter les conventions d’affectation de noms pour les identificateurs C#.
`timeout`	Optionnel. Le paramètre `timeout` est exprimé en secondes. Pour plus d’informations, consultez Définition de délais d’expiration pour les opérations Azure Files.

En-têtes de requête

Le tableau suivant décrit les en-têtes de demande obligatoires ou facultatifs.

En-tête de requête	Description
`Authorization`	Obligatoire. Spécifie le schéma d’autorisation, le nom du compte et la signature. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
`Date` ou `x-ms-date`	Obligatoire. Spécifie la date/heure en temps universel coordonné (UTC) pour la requête. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
`x-ms-version`	Obligatoire pour toutes les demandes autorisées. Spécifie la version de l'opération à utiliser pour cette demande. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
`x-ms-client-request-id`	Optionnel. Fournit une valeur opaque générée par le client avec une limite de caractères de 1 kibioctet (Kio) enregistrée dans les journaux lors de la configuration de la journalisation. Nous vous recommandons vivement d’utiliser cet en-tête pour mettre en corrélation les activités côté client avec les demandes que le serveur reçoit. Pour plus d’informations, consultez Surveiller Azure Files.

Corps de la demande

Aucun.

response

La réponse inclut un code d'état HTTP, un ensemble d'en-têtes de réponse et un corps de réponse au format XML.

Code d’état

Une opération réussie envoie le code d'état 200 (OK). Pour plus d’informations sur les codes status, consultez Codes d’état et d’erreur.

En-têtes de réponse

La réponse de l'opération inclut les en-têtes suivants. La réponse inclut également des en-têtes HTTP standard supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.

En-tête de réponse	Description
`Content-Type`	En-tête HTTP/1.1 standard. Spécifie le format dans lequel les résultats sont renvoyés. Actuellement, cette valeur est `application/xml`.
`x-ms-request-id`	Cet en-tête identifie de manière unique la requête qui a été effectuée et peut être utilisé pour la résolution des problèmes de la demande. Pour plus d’informations, consultez Résolution des problèmes liés aux opérations d’API.
`x-ms-version`	Indique la version de Azure Files utilisée pour exécuter la demande.
`Date` ou `x-ms-date`	Valeur de date/heure UTC qui indique l’heure à laquelle la réponse a été lancée. Le service génère cette valeur.
`x-ms-client-request-id`	Vous pouvez utiliser cet en-tête pour résoudre les problèmes liés aux demandes et aux réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l’en-tête `x-ms-client-request-id` , s’il est présent dans la requête. La valeur est au maximum de 1 024 caractères ASCII visibles. Si l’en-tête `x-ms-client-request-id` n’est pas présent dans la demande, cet en-tête ne sera pas présent dans la réponse.

Response body

Le format du corps de la réponse est le suivant.

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

L’élément EnabledProtocols apparaît dans le corps de la réponse uniquement dans la version 2020-02-10 et les versions ultérieures.
L’élément RootSquash apparaît dans le corps de la réponse uniquement dans la version 2020-02-10 et ultérieure, lorsque les protocoles activés contiennent NFS.
L’élément Quota apparaît dans le corps de la réponse uniquement dans la version 2015-02-21 et ultérieure.
Les Versionéléments , Deleted, DeletedTimeet RemainingRetentionDays apparaissent dans le corps de la réponse uniquement dans la version 2019-12-12 et ultérieure.
Les Prefixéléments , Markeret MaxResults ne sont présents que si vous les spécifiez sur l’URI. L’élément NextMarker a une valeur uniquement si les résultats de la liste ne sont pas terminés.
L’élément Metadata est présent uniquement si vous spécifiez le include=metadata paramètre sur l’URI. Dans l'élément Metadata, la valeur de chaque paire nom-valeur est indiquée dans un élément correspondant au nom de la paire.
Les instantanés sont inclus dans la réponse uniquement si vous spécifiez leinclude=snapshots paramètre avec le include paramètre sur l’URI de la demande.
L’élément AccessTier contient le niveau du partage. Si le niveau du partage n’a pas été modifié, cette propriété est le niveau TransactionOptimized par défaut des comptes de stockage à usage général version 2 (GPv2). Sur Azure Files comptes de stockage, la propriété est Premium, qui est le seul niveau pris en charge.
L’élément AccessTierChangeTime est présent uniquement si vous définissez explicitement le niveau d’accès sur le partage.
L’élément AccessTierTransitionState est présent uniquement si le partage passe d’un niveau à un autre. Il indique le niveau à partir duquel il effectue la transition.
L’élément ProvisionedIngressMBps est présent uniquement pour Premium les comptes Azure Files et la version 2019-07-07 ou ultérieure. Il montre l’entrée provisionnée en Mio/s.
L’élément ProvisionedEgressMBps est présent uniquement pour Premium les comptes Azure Files et la version 2019-07-07 ou ultérieure. Il montre la sortie provisionnée en Mio/s.
L’élément ProvisionedBandwidthMiBps est présent uniquement pour Premium les comptes Azure Files et la version 2021-02-12 ou ultérieure. Il montre la bande passante provisionnée (entrée + sortie combinée) en Mio/s.

Exemple de réponse

Consultez la section Exemple de demande et de réponse plus loin dans cette rubrique.

Autorisation

Seul le propriétaire du compte peut appeler cette opération.

Notes

Si vous spécifiez une valeur pour le maxresults paramètre et que le nombre de partages à retourner dépasse cette valeur, ou dépasse la valeur par défaut pour maxresults, le corps de la réponse contient un NextMarker élément . Cet élément indique le partage suivant à retourner lors d’une demande ultérieure. Pour renvoyer l'ensemble suivant d'éléments, spécifiez la valeur de NextMarker comme paramètre de marqueur dans l'URI pour la demande suivante.

Notez que la valeur de NextMarker doit être traitée comme opaque.

Les partages sont répertoriés par ordre alphabétique dans le corps de la réponse.

L'opération List Shares expire après 30 secondes.

Exemple de requête et de réponse

L’exemple d’URI suivant demande la liste des partages pour un compte. Il définit le nombre maximal de résultats à retourner pour l’opération initiale sur trois.

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

La demande est envoyée avec ces en-têtes :

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

Le code d'état et les en-têtes de réponse sont renvoyés comme suit :

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

Le code XML de réponse pour cette demande est le suivant : Notez que l’élément NextMarker suit l’ensemble de partages et inclut le nom du partage suivant à retourner.

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

L'opération de liste suivante spécifie le marqueur dans l'URI de la demande, comme suit. L’ensemble de résultats suivant est retourné, en commençant par le partage spécifié par le marqueur.

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

Voir aussi

API REST Azure Files