Contrôle de version pour stockage Azure

Stockage Azure prend en charge plusieurs versions. Pour effectuer une demande 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.

Depuis le 11 mai 2026, la dernière version entièrement déployée du service stockage Azure est 2026-04-06, prise en charge par les derniers paquets SDK stockage Azure GA. 2026-06-06 est également largement déployé, et les deux sont pris en charge par les dernières versions bêta des SDK de stockage.

Si le tableau indique que est x-ms-version activé dans une région, tous les précédents x-ms-versions sont également activés. Toute tentative d’utilisation d’une version de service qui n’est pas entièrement déployée dans la région de votre compte de stockage peut générer une erreur de non-correspondance de version x-ms.

La valeur par défaut x-ms-version utilisée par les kits de développement logiciel (SDK) de plan de données de stockage Azure se trouve dans les journaux des modifications du tableau suivant :

Les SDK de stockage du plan de données n’effectuent pas de versions GA sur les autres flux de packages officiels tant que la valeur par défaut x-ms-version de la version en question n’a pas été entièrement déployée dans toutes les régions. Par conséquent, la dernière version du SDK GA des gestionnaires de paquets officiels peut être utilisée en toute sécurité dans n’importe quelle région.

La dernière version des services de stockage Azure est le 06-02-2026, et nous vous recommandons de l’utiliser autant que 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 service 2026-06-06 inclut les fonctionnalités suivantes :

• Prise en charge du message structuré pour Créer un fichier.

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

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 demande avec l’ID Microsoft Entra, transmettez l’en-tête x-ms-version à la demande avec une version de service de 2017-11-09 ou ultérieure. Pour plus d’informations, consultez Opérations de stockage d’appel 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 à la demande. Lorsque vous utilisez Stockage Blob Azure, vous pouvez spécifier la version par défaut de 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 api-version facultatif indique la version du service à utiliser pour exécuter l’opération d’API. Le paramètre SignedVersion (sv) requis spécifie la version du service à utiliser pour autoriser la demande effectuée avec la sape. 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 d’API.

• Demandes qui utilisent un accès anonyme : lors de l’utilisation d’un accès anonyme sur Stockage Blob, aucune version n’est transmise. 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 demande 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 la demande x-ms-version doit être spécifiée au format AAAA-MM-DD. Par exemple:

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

Les règles suivantes décrivent comment ces requêtes sont évaluées pour déterminer la version à utiliser pour traiter la demande.

• Si une demande a un en-tête x-ms-version valide, 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 un en-tête x-ms-version. Toutes les demandes adressées au Stockage Blob qui n’utilisent pas de signature d’accès partagé doivent spécifier un x-ms-version en-tête, sauf si la version par défaut est définie, comme décrit dans le paragraphe suivant.

• Si une demande adressée au Stockage Blob n’inclut x-ms-version pas d’en-tête, mais que le propriétaire du compte définit 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 de 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 gestion de version :

• Le paramètre de requête api-version définit la version du protocole REST à utiliser pour traiter une requête effectuée à l’aide de la sap.

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

Le paramètre de requête SignedVersion est utilisé pour l’autorisation lorsqu’un client effectue une requête à l’aide de la SAP. Les paramètres d’autorisation tels que si, sr, sp, sig, st, se, tn, spk, srk, epket erk sont tous interprétés à l’aide de la version spécifiée.

Les paramètres de protocole REST tels que rscc, rscd, rscerscl, et rsct sont appliqués à l’aide de la version fournie dans l’en-tête du api-version paramètre. Si l’en-tête api-version n’est pas renseigné, c’est la version de service prévue qui SignedVersion est utilisée.

Le paramètre api-version ne fait pas partie de l’en-tête d’autorisation de chaîne à connecter, 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 SignedVersion est défini sur la version 2014-02-14 ou ultérieure.

Exemple 1

L’exemple de demande 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 requête à l’aide de la version 2015-04-05 et exécute l’opération à l’aide de la version 2015-04-05.

Exemple 2

L’exemple de demande 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 requête à l’aide de la version 2015-04-05 et exécute l’opération à l’aide de la version 2012-02-12.

Demandes par le biais d’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.

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’est pas définie à l’aide de l’option Définir les propriétés du service Blob, le service utilise la version la plus ancienne possible pour traiter la demande. Si le conteneur a été rendu public à l’aide de l’opération Définir la liste de contrôle d’accès du conteneur à 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 d’objets 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’est pas définie à l’aide de l’option 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 d’objets blob, la version la plus ancienne est 2014-02-14.

Problèmes connus

Cette section détaille les problèmes connus liés aux API REST stockage Azure.

message d’erreur InvalidHeaderValue

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 tenter de résoudre le problème. Si le problème persiste, ou si la recommandation n’est pas réalisable, ouvrez un ticket de support pour discuter des options supplémentaires.

Voir aussi

• REST des services de stockage
• bonnes pratiques de contrôle de version
• prise en charge des versions du protocole pour les versions de la bibliothèque cliente .NET