Contrôle de version pour les services stockage Azure

Plusieurs versions des services de stockage Microsoft Azure sont prises en charge. Pour effectuer une requête auprès des services de stockage, vous devez spécifier la version que vous souhaitez utiliser pour cette opération, sauf si la requête est anonyme.

La version actuelle des services de stockage Azure est 2021-12-02, et l’utilisation de cette version est recommandée si possible. Pour obtenir la liste de toutes les autres versions prises en charge et pour plus d’informations sur l’utilisation de chaque version, consultez Versions précédentes du service Stockage Azure.

La version de service 2021-12-02 comprend les fonctionnalités suivantes :

  • Possibilité de définir le niveau d’accès d’un objet blob sur Cold avec Définir le niveau d’objet blob.
  • Répertorier les répertoires et les fichiers encodera désormais en pourcentage (selon RFC 2396) toutes les FileNamevaleurs d’élément , PrefixDirectoryNameou DirectoryPath qui contiennent des caractères non valides dans XML (en particulier, U+FFFE ou U+FFFF).
  • Les handles de liste encoderont désormais en pourcentage (selon RFC 2396) toutes les Path valeurs d’élément qui contiennent des caractères non valides dans XML (en particulier, U+FFFE ou U+FFFF).

Spécification des versions de service dans les requêtes

La façon dont vous spécifiez la version des services de stockage à utiliser pour une requête est liée à la façon dont cette demande est autorisée. Les sections suivantes décrivent les options d’autorisation et la façon dont la version du service est spécifiée pour chacune d’elles :

  • Demandes à l’aide d’un jeton OAuth 2.0 d’Azure Active Directory (Azure AD). Pour autoriser une demande avec Azure AD, transmettez l’en-tête x-ms-version de la demande avec une version de service de 2017-11-09 ou ultérieure. Pour plus d’informations, consultez Appeler des opérations de stockage avec des jetons OAuth dans Autoriser avec Azure Active Directory.

  • Demandes utilisant Shared Key ou Shared Key Lite Pour autoriser une requête avec la clé partagée/la clé partagée Lite, transmettez l’en-tête x-ms-version sur la demande. Dans le cas du service Blob, vous pouvez spécifier la version par défaut pour toutes les requêtes en appelant Définir les propriétés du service Blob.

  • Demandes à l’aide d’une signature d’accès partagé (SAP). Vous pouvez spécifier deux options de contrôle de version pour une signature d'accès partagé. L’en-tête facultatif api-version indique la version de service à utiliser pour exécuter l’opération d’API. Le paramètre requis SignedVersion (sv) spécifie la version de service à utiliser pour autoriser la requête effectuée avec la sap. Si l'en-tête api-version n'est pas spécifié, la valeur du paramètre SignedVersion (sv) indique également la version à utiliser pour exécuter l'opération de l'API.

  • Demandes utilisant l'accès anonyme Dans le cas d'une demande anonyme au service BLOB, aucune version n'est spécifiée. Le choix de la version utilisée est déterminé par certaines règles (voir plus bas).

Demandes autorisées à l’aide d’Azure AD, d’une clé partagée ou d’une clé partagée Lite

Pour autoriser une requête avec Azure AD, Shared Key ou Shared Key Lite, spécifiez l’en-tête x-ms-version sur la demande. La valeur d'en-tête de demande x-ms-version doit être spécifiée au format AAAA-MM-JJ. Par exemple :

Request Headers:  
x-ms-version: 2020-04-08

Les règles suivantes indiquent comment ces demandes sont évaluées pour déterminer la version à utiliser dans le traitement de la demande.

  • Si une demande a un en-tête valide x-ms-version, le service de stockage utilise la version spécifiée. Toutes les demandes aux services de Table et de File d'attente qui n'utilisent pas une signature d'accès partagé doivent spécifier un en-tête x-ms-version. Toutes les demandes au service BLOB qui n'utilisent pas de signature d'accès partagé doivent spécifier un en-tête x-ms-version, sauf si la version par défaut a été définie, comme décrit ci-dessous.

  • Si une requête adressée au service Blob n’a pas d’en-tête x-ms-version , mais que le propriétaire du compte a défini une version par défaut à l’aide de Définir les propriétés du service Blob, la version par défaut spécifiée est utilisée comme version pour la demande.

Demandes autorisées avec une signature d’accès partagé

Une signature d’accès partagé (SAP) générée à l’aide de la version 2014-02-14 ou ultérieure prend en charge deux options de contrôle de version :

  • Le paramètre de requête api-version définit la version du protocole REST à utiliser pour traiter une demande effectuée avec une signature d'accès partagé (SAS).

  • Le SignedVersion (sv) paramètre de requête définit la version SAS à utiliser pour l’autorisation.

Le SignedVersion paramètre de requête est utilisé pour l’autorisation lorsqu’un client effectue une demande à l’aide de la sap. Les paramètres d’autorisation tels que si, sr, sp, tnsigsest, spksrk, , epk, , et erk sont tous interprétés à l’aide de la version spécifiée.

Les paramètres de protocole REST tels que rscc, rscd, rsce, rsclet rsct sont appliqués à l’aide de la version fournie dans l’en-tête de api-version paramètre. Si l'en-tête api-version n'est pas spécifié, la version des services utilisée est celle indiquée par le paramètre SignedVersion.

Le api-version paramètre ne fait pas partie de la chaîne de connexion à l’en-tête d’autorisation, comme décrit dans Créer une sap de service.

Le tableau suivant explique le schéma de contrôle de version utilisé par le service pour l’autorisation et pour appeler le protocole REST lorsque le paramètre est défini sur la SignedVersion version 2014-02-14 ou ultérieure.

Valeur du paramètre api-version Version utilisée pour l’autorisation Version utilisée pour le comportement de protocole
Non spécifié Version spécifiée dans le sv paramètre Version spécifiée dans le sv paramètre
N'importe quelle version valide des services de stockage, au format XXXX-XX-XX Version spécifiée dans le sv paramètre N'importe quelle version valide des services de stockage, au format XXXX-XX-XX

Exemple 1

L’exemple de requête suivant appelle List Blobs avec sv=2015-04-05et sans le api-version paramètre .

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d

Dans ce cas, le service authentifie et autorise la demande à l’aide de la version 2015-04-05 et exécute également l’opération à l’aide de la version 2015-04-05.

Exemple 2

L’exemple de requête suivant appelle List Blobs avec sv=2015-04-05 et avec le api-version paramètre .

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d&api-version=2012-02-12

Ici, le service autorise la demande à l’aide de la version 2015-04-05 et exécute l’opération à l’aide de la version 2012-02-12.

Notes

La bibliothèque cliente de stockage pour .NET définit toujours la version du protocole REST (avec le paramètre api-version) en fonction de sa version de base.

Demandes via un accès anonyme

Les demandes effectuées via l’accès anonyme sont gérées différemment en fonction du type de compte de stockage sur lequel elles sont effectuées.

Pour les comptes de stockage à usage général

Si une requête anonyme adressée à un compte de stockage à usage général ne spécifie pas l’en-tête x-ms-version et que la version par défaut du service n’a pas été définie à l’aide de Définir les propriétés du service Blob, le service utilise la version la plus ancienne possible pour traiter la demande. Toutefois, si le conteneur a été rendu public avec une opération Set Container ACL effectuée à l’aide de la version 2009-09-19 ou ultérieure, la demande est traitée à l’aide de la version 2009-09-19.

Pour les comptes de stockage Blob

Si une demande anonyme adressée à un compte de stockage Blob ne spécifie pas l’en-tête x-ms-version et que la version par défaut du service n’a pas été définie à l’aide de Définir les propriétés du service Blob, le service utilise la version la plus ancienne possible pour traiter la demande. Pour un compte de stockage Blob, la version la plus ancienne possible est 2014-02-14.

Voir aussi