Contrôle de version pour stockage Azure
Stockage Azure prend en charge plusieurs versions. 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 2024-08-04, et nous vous recommandons de l’utiliser 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 du service 2024-08-04 comprend les fonctionnalités suivantes :
- L’en-tête de demande est désormais pris en charge par la
x-ms-enable-snapshot-virtual-directory-access
création de propriétés de partage et de définition de partage. Cette propriété est maintenant retournée en tant qu’en-tête de réponse par Obtenir les propriétés du partage et en tant qu’élémentEnableSnapshotVirtualDirectoryAccess
XML retourné par les partages de liste. - Les corps de réponse d’erreur liés à l’authentification contiennent désormais l’élément
ExtendedErrorDetail
xml, ce qui fournit plus de contexte sur l’échec d’authentification. Pour plus d’informations, consultez Codes d’état et d’erreur.
Spécifier les versions de service dans les demandes
La façon dont vous spécifiez la version des services de stockage à utiliser pour une demande 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 qui utilisent un jeton OAuth 2.0 de Microsoft Entra : pour autoriser une requête avec l’ID Microsoft Entra, transmettez l’en-tête
x-ms-version
de la demande avec une version de service 2017-11-09 ou ultérieure. Pour plus d’informations, consultez Appeler des opérations de stockage avec des jetons OAuth dans Autoriser avec l’ID Microsoft Entra.Demandes qui utilisent une clé partagée ou une clé partagée Lite : pour autoriser une demande avec une clé partagée ou une clé partagée Lite, transmettez l’en-tête
x-ms-version
sur la demande. Dans le cas du Stockage Blob Azure, vous pouvez spécifier la version par défaut pour toutes les demandes en appelant Définir les propriétés du service Blob.Demandes qui utilisent une signature d’accès partagé (SAP) : vous pouvez spécifier deux options de contrôle de version sur 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 requisSignedVersion (sv)
spécifie la version de service à utiliser pour autoriser la requête effectuée avec la signature d’accès partagé. Si l’en-têteapi-version
n’est pas spécifié, la valeur duSignedVersion (sv)
paramètre indique également la version à utiliser pour exécuter l’opération d’API.Demandes qui utilisent l’accès anonyme : dans le cas d’un accès anonyme sur le Stockage Blob, aucune version n’est passée. Les heuristiques permettant de déterminer la version à utiliser pour la demande sont décrites dans les sections suivantes.
Autoriser les demandes à l’aide de l’ID Microsoft Entra, de la clé partagée ou de la clé partagée Lite
Pour autoriser une requête avec l’ID Microsoft Entra, la clé partagée ou la clé partagée 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 décrivent comment ces demandes sont évaluées pour déterminer la version à utiliser pour traiter 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 adressées au Stockage Table Azure et au Stockage File d’attente Azure qui n’utilisent pas de signature d’accès partagé doivent spécifier unx-ms-version
en-tête. Toutes les demandes adressées au Stockage Blob qui n’utilisent pas de signature d’accès partagé doivent spécifier unx-ms-version
en-tête, sauf si la version par défaut a été définie, comme décrit dans le paragraphe suivant.Si une demande adressée au Stockage 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 l’opération 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.
Autoriser les demandes à l’aide d’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
api-version
paramètre de requête définit la version du protocole REST à utiliser pour traiter une requête effectuée à l’aide de la signature d’accès partagé.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 signature d’accès partagé. Les paramètres d’autorisation tels que si
, sr
, sp
sig
, tn
se
st
spk
, srk
, 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
, rscl
et 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 de service fournie est SignedVersion
utilisée.
Le api-version
paramètre ne fait pas partie de la chaîne de connexion dans l’en-tête d’autorisation, comme décrit dans Créer une sape 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 SignedVersion
paramètre est défini sur la 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-05
et 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 il exécute 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 .NET définit toujours la version du protocole REST (dans le api-version
paramètre ) sur la version sur laquelle elle est basée.
Demandes via un accès anonyme
Les demandes effectuées via l’accès anonyme sont gérées différemment, selon le type de compte de stockage sur lequel elles sont effectuées.
Pour les comptes de stockage à usage général
Si une demande 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 qui a été 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.
Problèmes connus
Cette section détaille les problèmes connus pour les API REST stockage Azure.
InvalidHeaderValue
message d’erreur
Dans de rares scénarios, les applications effectuant des appels d’API REST directs peuvent recevoir un message d’erreur InvalidHeaderValue
. L’erreur ressemble à l’exemple suivant :
HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error>
Il est recommandé d’utiliser une version antérieure de l’API REST pour voir si le problème est résolu. Si le problème persiste ou si la recommandation n’est pas réalisable, ouvrez un ticket de support pour discuter d’autres options.