Control de versiones para Azure Storage

Azure Storage admite varias versiones. Para realizar una solicitud en los servicios de almacenamiento, debe especificar la versión que desea usar para esa operación, a menos que la solicitud sea anónima.

A fecha de 11 de mayo de 2026, la última versión completamente desplegada del servicio Azure Storage es 2026-04-06, que es compatible con los últimos paquetes Azure Storage SDK GA. 2026-06-06 también se despliega ampliamente, y ambos son soportados por las últimas versiones beta de los SDKs de almacenamiento.

Si la tabla indica que an x-ms-version está habilitado en una región, también se habilitan todos los anteriores x-ms-versions . Al intentar usar una versión de servicio que no está completamente implementada en la región de la cuenta de almacenamiento, es posible que se genere un error de discrepancia x-ms-version.

El valor predeterminado x-ms-version que usan los SDK del plano de datos de Azure Storage se puede encontrar en los registros de cambios de la tabla siguiente:

Los SDK de almacenamiento del plano de datos no realizan versiones de disponibilidad general en las otras fuentes de paquetes oficiales hasta que el valor predeterminado x-ms-version de la versión en cuestión se implementa por completo en todas las regiones. Por lo tanto, la última versión del SDK de GA de los administradores de paquetes oficiales se puede usar de manera segura en cualquier región.

La última versión de los servicios de almacenamiento de Azure es el 06-02-2026, y recomendamos que la utilices siempre que sea posible. Para obtener una lista de todas las demás versiones compatibles y para obtener información sobre el uso de cada versión, consulte versiones anteriores del servicio Azure Storage.

La versión de servicio 2026-06-06 incluye las siguientes características:

• Soporte para mensajes estructurados para Crear Archivo.

Especificación de versiones de servicio en solicitudes

Cómo se especifica la versión de los servicios de almacenamiento que se van a usar para una solicitud se relaciona con cómo se autoriza esa solicitud. En las secciones siguientes se describen las opciones de autorización y cómo se especifica la versión del servicio para cada una.

• solicitudes que usan un token de OAuth 2.0 de Microsoft Entra: para autorizar una solicitud con el identificador de Microsoft Entra, pase el encabezado x-ms-version en la solicitud con una versión de servicio de 2017-11-09 o posterior. Para obtener más información, consulte Operaciones de almacenamiento de llamadas con tokens de OAuth en Autorizar con el identificador de Entra de Microsoft.

• Solicitudes que usan clave compartida o clave compartida Lite: para autorizar una solicitud con clave compartida o clave compartida Lite, pase el encabezado x-ms-version en la solicitud. Al usar Azure Blob Storage, puede especificar la versión predeterminada de todas las solicitudes llamando a Set Blob Service Properties.

• Solicitudes que usan una firma de acceso compartido (SAS): puede especificar dos opciones de control de versiones en una firma de acceso compartido. El encabezado opcional api-version indica qué versión del servicio se va a usar para ejecutar la operación de API. El parámetro SignedVersion (sv) necesario especifica la versión del servicio que se va a usar para autorizar la solicitud realizada con la SAS. Si no se especifica el encabezado api-version, el valor del parámetro SignedVersion (sv) también indica la versión que se va a usar para ejecutar la operación de API.

• Solicitudes que usan acceso anónimo: cuando se usa el acceso anónimo en Blob Storage, no se pasa ninguna versión. La heurística para determinar qué versión usar para la solicitud se describe en las secciones siguientes.

Autorización de solicitudes mediante el identificador de Entra de Microsoft, la clave compartida o la clave compartida Lite

Para autorizar una solicitud con Microsoft Entra ID, Shared Key o Shared Key Lite, especifique el encabezado x-ms-version en la solicitud. El valor del encabezado de solicitud x-ms-version debe especificarse con el formato AAAA-MM-DD. Por ejemplo:

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

Las reglas siguientes describen cómo se evalúan estas solicitudes para determinar qué versión usar para procesar la solicitud.

• Si una solicitud tiene un encabezado x-ms-version válido, el servicio de almacenamiento usa la versión especificada. Todas las solicitudes a Azure Table Storage y Azure Queue Storage que no usan una firma de acceso compartido deben especificar un encabezado x-ms-version. Todas las solicitudes a Blob Storage que no usen una firma de acceso compartido deben especificar un x-ms-version encabezado, a menos que se establezca la versión predeterminada, como se describe en el párrafo siguiente.

• Si una solicitud a Blob Storage no incluye un x-ms-version encabezado, pero el propietario de la cuenta establece una versión predeterminada mediante la operación Establecer propiedades de Blob Service , se usa la versión predeterminada especificada como versión de la solicitud.

Autorización de solicitudes mediante una firma de acceso compartido

Una firma de acceso compartido (SAS) que se genera mediante la versión 2014-02-14 o posterior admite dos opciones de control de versiones:

• El parámetro de consulta api-version define la versión del protocolo REST que se usará para procesar una solicitud realizada mediante la SAS.

• El parámetro de consulta SignedVersion (sv) define la versión de SAS que se usará para la autorización.

El parámetro de consulta SignedVersion se usa para la autorización cuando un cliente realiza una solicitud mediante la SAS. Los parámetros de autorización, como si, sr, sp, sig, st, se, tn, spk, srk, epky erk se interpretan mediante la versión especificada.

Los parámetros del protocolo REST, como , , , , y rscc se aplican mediante la versión proporcionada en el encabezado del rscd parámetro. rscersclrsctapi-version Si no se especifica el api-version encabezado, se usa la versión de servicio proporcionada SignedVersion .

El parámetro api-version no forma parte de la cadena para iniciar sesión en el encabezado de autorización, como se describe en Crear una SAS de servicio.

En la tabla siguiente se explica el esquema de control de versiones que usa el servicio para la autorización y para llamar al protocolo REST cuando el parámetro SignedVersion está establecido en la versión 2014-02-14 o posterior.

Ejemplo 1

La siguiente solicitud de ejemplo llama a List Blobs con sv=2015-04-05y sin el api-version parámetro.

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

En este caso, el servicio autentica y autoriza la solicitud mediante la versión 2015-04-05 y ejecuta la operación mediante la versión 2015-04-05.

Ejemplo 2

En la siguiente solicitud de ejemplo se llama a List Blobs con sv=2015-04-05 y con el api-version parámetro.

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

Aquí, el servicio autoriza la solicitud mediante la versión 2015-04-05 y ejecuta la operación con la versión 2012-02-12.

Solicitudes a través del acceso anónimo

Las solicitudes realizadas a través del acceso anónimo se controlan de forma diferente, en función del tipo de cuenta de almacenamiento en la que se realicen.

Cuentas de almacenamiento de uso general

Si una solicitud anónima a una cuenta de almacenamiento de uso general no especifica el x-ms-version encabezado y la versión predeterminada del servicio no se establece mediante Set Blob Service Properties, el servicio usa la versión más antigua posible para procesar la solicitud. Si el contenedor se hizo público mediante la operación Set Container ACL con la versión 2009-09-19 o posterior, la solicitud se procesa mediante la versión 2009-09-19.

Para cuentas de Blob Storage

Si una solicitud anónima a una cuenta de Blob Storage no especifica el x-ms-version encabezado y la versión predeterminada del servicio no se establece mediante Establecer propiedades del servicio Blob, el servicio usa la versión más antigua posible para procesar la solicitud. Para una cuenta de Blob Storage, la versión más antigua posible es 2014-02-14.

Problemas conocidos

En esta sección se detallan los problemas conocidos de las API REST de Azure Storage.

InvalidHeaderValue mensaje de error

En escenarios poco frecuentes, las aplicaciones que realizan llamadas directas a la API REST pueden recibir un mensaje de error InvalidHeaderValue. El error es similar al ejemplo siguiente:

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> 

Se recomienda utilizar una versión anterior de la API de REST para intentar resolver el problema. Si el problema persiste, o si la recomendación no es factible, abre un ticket de soporte para discutir más opciones.

Consulte también

• rest de servicios de almacenamiento de
• procedimientos recomendados de control de versiones de
• compatibilidad con la versión del protocolo para las versiones de la biblioteca cliente de .NET