Répertorier les partages

Article
08/07/2024

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 elle est une API de gestion héritée. Utilisez partages de fichiers - Répertoriez les, fournies par le fournisseur de ressources de stockage (Microsoft.Storage), à la place. Pour en savoir plus sur l’interaction programmatique avec des ressources FileShare à l’aide du fournisseur de ressources de stockage, consultez Opérations sur FileShares.

Disponibilité du protocole

Protocole de partage de fichiers activé	Disponible
SMB
NFS

Demander

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

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

Remplacez les composants de chemin d’accès indiqués dans l’URI de requête par vos propres composants, 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 nommage et référencement de partages, répertoires, fichiers et métadonnées.

Paramètres d’URI

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

Paramètre	Description
`prefix`	Optionnel. Filtre les résultats pour retourner 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 à retourner 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’a pas été terminée. Vous pouvez ensuite utiliser la valeur de marqueur dans un appel suivant pour demander l’ensemble suivant d’éléments de liste. La valeur de marqueur est opaque pour le client.
`maxresults`	Optionnel. Spécifie le nombre maximal de partages à retourner. Si la requête ne spécifie pas `maxresults`ou spécifie une valeur supérieure à 5 000, le serveur retourne jusqu’à 5 000 éléments. Si le paramètre est défini sur une valeur inférieure ou égale à zéro, le serveur retourne le code d’état 400 (Requête incorrecte).
`include=metadata,snapshots,deleted`	Optionnel. Spécifie un ou plusieurs jeux de données à inclure dans la réponse : - `snapshots`: version 2017-04-17 et ultérieure. 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 sur l’URI, vous devez séparer chaque option par une virgule codée par 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 des 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 requête obligatoires et 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 demandes vers le stockage Azure.
`Date` ou `x-ms-date`	Obligatoire. Spécifie le temps universel coordonné (UTC) de la requête. Pour plus d’informations, consultez Autoriser les demandes vers le stockage Azure.
`x-ms-version`	Obligatoire pour toutes les demandes autorisées. Spécifie la version de l’opération à utiliser pour cette requête. Pour plus d’informations, consultez Contrôle de version pour les services stockage 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 (KiB) 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 reçues par le serveur. Pour plus d’informations, consultez Monitor Azure Files.

Corps de la demande

Aucun.

Réponse

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 retourne le code d’état 200 (OK). Pour plus d’informations sur les codes d’état, consultez Les codes d’état et d’erreur.

En-têtes de réponse

La réponse de cette opération inclut les en-têtes suivants. La réponse inclut également des en-têtes HTTP supplémentaires et standard. Tous les en-têtes standard sont conformes à la spécification de 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 retournés. Actuellement, cette valeur est `application/xml`.
`x-ms-request-id`	Cet en-tête identifie de manière unique la demande qui a été effectuée et peut être utilisé pour résoudre les problèmes de la demande. Pour plus d’informations, consultez Résolution des problèmes des opérations d’API.
`x-ms-version`	Indique la version d’Azure Files utilisée pour exécuter la requête.
`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 demandes et les réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l’en-tête `x-ms-client-request-id`, si elle est présente dans la requête. La valeur est au maximum 1024 caractères ASCII visibles. Si l’en-tête `x-ms-client-request-id` n’est pas présent dans la requête, cet en-tête ne sera pas présent dans la réponse.

Corps de la réponse

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>
        <PaidBurstingEnabled>true</PaidBurstingEnabled>
        <PaidBurstingMaxIops>20000</PaidBurstingMaxIops>
        <PaidBurstingMaxBandwidthMibps>4000</PaidBurstingMaxBandwidthMibps>
      </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 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. Cet élément est retourné uniquement pour les partages, et non pour les instantanés.
L’élément Quota apparaît dans le corps de la réponse uniquement dans la version 2015-02-21 et ultérieure.
Les éléments Version, Deleted, DeletedTimeet RemainingRetentionDays apparaissent dans le corps de la réponse uniquement dans la version 2019-12-12 et ultérieures.
Les éléments Prefix, 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 paramètre include=metadata sur l’URI. Dans l’élément Metadata, la valeur de chaque paire nom-valeur est répertorié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 le paramètreinclude=snapshots avec le paramètre include sur l’URI de la requête.
L’élément AccessTier contient le niveau du partage. Si le niveau du partage n’a pas été modifié, cette propriété sera le niveau par défaut TransactionOptimized sur les comptes de stockage À usage général version 2 (GPv2). Sur les comptes de stockage Azure Files, 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 passe.
L’élément ProvisionedIngressMBps est présent uniquement pour Premium comptes Azure Files et la version 2019-07-07 ou ultérieure. Il affiche l’entrée provisionnée en MiB/s.
L’élément ProvisionedEgressMBps est présent uniquement pour Premium comptes Azure Files et la version 2019-07-07 ou ultérieure. Il affiche la sortie provisionnée en MiB/s.
L’élément ProvisionedBandwidthMiBps est présent uniquement pour Premium comptes Azure Files et la version 2021-02-12 ou ultérieure. Il affiche la bande passante provisionnée (entrée + sortie combinée) en Mio/s.
L’élément EnableSnapshotVirtualDirectoryAccess apparaît dans le corps de la réponse uniquement dans la version 2024-08-04 et ultérieure, lorsque les protocoles activés contiennent NFS. Cet élément est retourné uniquement pour les partages, et non pour les instantanés.
L’élément PaidBurstingEnabled est présent uniquement pour Premium comptes Azure Files, dans la version 2024-11-04 ou ultérieure. Cet élément est retourné uniquement pour les partages, et non pour les instantanés.
L’élément PaidBurstingMaxIops est présent uniquement pour Premium comptes Azure Files, dans la version 2024-11-04 ou ultérieure. Elle ne sera retournée que si PaidBurstingEnabled est vrai pour le partage. Cet élément est retourné uniquement pour les partages, et non pour les instantanés.
L’élément PaidBurstingMaxBandwidthMibps est présent uniquement pour Premium comptes Azure Files, dans la version 2024-11-04 ou ultérieure. Elle ne sera retournée que si PaidBurstingEnabled est vrai pour le partage. Cet élément est retourné uniquement pour les partages, et non pour les instantané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.

Remarques

Si vous spécifiez une valeur pour le paramètre maxresults 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 élément NextMarker. Cet élément indique le partage suivant à retourner sur une demande ultérieure. Pour retourner le jeu d’éléments suivant, spécifiez la valeur de NextMarker comme paramètre de marqueur sur l’URI de la requête 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 demande et de réponse

L’exemple d’URI suivant demande la liste des partages pour un compte. Il définit les résultats maximum à 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 retourné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 de cette requête 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>
      </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 sur l’URI de requête, comme suit. Le jeu 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

Partager via