Control de versiones para Azure Storage

  • Artículo

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.

La versión actual de los servicios de almacenamiento de Azure es 2023-11-03 y se recomienda usarla 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 del servicio 2023-11-03 incluye las siguientes características:

  • Ninguno.

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 la autorización de 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 Microsoft Entra ID, pase el x-ms-version encabezado de la solicitud con una versión de servicio de 2017-11-09 o posterior. Para más información, consulte Llamada a operaciones de almacenamiento con tokens de OAuth en Autorización con Microsoft Entra ID.

  • Solicitudes que usan clave compartida o clave compartida Lite: para autorizar una solicitud con clave compartida o clave compartida Lite, pase el x-ms-version encabezado en la solicitud. En el caso de Azure Blob Storage, puede especificar la versión predeterminada para todas las solicitudes mediante una llamada a Establecer propiedades de Blob Service.

  • 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 la versión del servicio que se va a usar para ejecutar la operación de API. El parámetro necesario SignedVersion (sv) especifica la versión del servicio que se va a usar para autorizar la solicitud realizada con la SAS. Si no se especifica el api-version encabezado, el valor del SignedVersion (sv) parámetro también indica la versión que se va a usar para ejecutar la operación de API.

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

Autorización de solicitudes mediante Microsoft Entra ID, Clave compartida o Shared Key Lite

Para autorizar una solicitud con Microsoft Entra ID, Clave compartida o Shared Key Lite, especifique el x-ms-version encabezado 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 utiliza 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 x-ms-version encabezado. Todas las solicitudes a Blob Storage que no usan una firma de acceso compartido deben especificar un x-ms-version encabezado a menos que se haya establecido la versión predeterminada, como se describe en el párrafo siguiente.

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

Autorización de solicitudes mediante una firma de acceso compartido

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

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

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

El SignedVersion parámetro de consulta 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, sespksigtnsrkst, epky erk se interpretan mediante la versión especificada.

Los parámetros del protocolo REST como rscc, rscd, rsce, rscly rsct se aplican mediante la versión que se proporciona en el encabezado de api-version parámetro. Si no se especifica el api-version encabezado, se usa la versión del servicio para SignedVersion la que se proporciona.

El api-version parámetro no forma parte de la cadena para iniciar sesión en el encabezado de autorización, como se describe en Creación de 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 SignedVersion parámetro se establece en la versión 2014-02-14 o posterior.

Valor del parámetro api-version Versión usada para la autorización Versión usada para el comportamiento del protocolo
Sin especificar Versión especificada en el parámetro sv Versión especificada en el parámetro sv
Cualquier versión de servicios de almacenamiento en el formato XXXX-XX-XX Versión especificada en el parámetro sv Versión de servicios de almacenamiento válida XXXX-XX-XX

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

La siguiente solicitud de ejemplo 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 mediante la versión 2012-02-12.

Nota

La biblioteca cliente de almacenamiento de .NET siempre establece la versión del protocolo REST (en el api-version parámetro ) en la versión en la que se basa.

Solicitudes a través del acceso anónimo

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

Para 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 ha establecido mediante Establecer propiedades de Blob Service, el servicio usa la versión más antigua posible para procesar la solicitud. Sin embargo, si el contenedor se hizo público con una operación Set Container ACL que se realizó mediante 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 ha establecido mediante Establecer propiedades de Blob Service, 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 InvalidHeaderValue mensaje de error. 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 usar una versión anterior de la API REST para ver si el problema se resuelve. Si el problema persiste o si la recomendación no es factible, abra una incidencia de soporte técnico para analizar más opciones.

Consulte también