Compartir por

Control de versiones para Azure Storage

  • Artigo

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 2024-11-04 y se recomienda usarlo 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 2024-11-04 incluye las siguientes características:

  • Compatibilidad con la autenticación basada en tokens para todas las API del plano de datos del servicio de archivos. Para obtener más información, vea Autorizar con el identificador de Entra de Microsoft.
  • Compatibilidad con la expansión de pago en cuentas de recursos compartidos de archivos Premium. Esta característica se puede habilitar con las API Create Share y set Share Properties Set Share Properties.
  • Compatibilidad con el formato binario al obtener y establecer permisos de archivo en el servicio de archivos. Para obtener más información, consulte Create Permission and Get Permission

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. En el caso de Azure Blob Storage, puede especificar la versión predeterminada para todas las solicitudes llamando 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 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 usande 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 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 usan una firma de acceso compartido deben especificar un encabezado x-ms-version 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 encabezado x-ms-version, pero el propietario de la cuenta ha establecido una versión predeterminada mediante la operación Set Blob Service Properties, 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) 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 rscc, rscd, rsce, rscly rsct se aplican mediante la versión proporcionada en el encabezado de parámetro api-version. Si no se especifica el encabezado api-version, se usa la versión del servicio que se proporciona para 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.

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

Ejemplo 1

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

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 Enumerar blobs con sv=2015-04-05 y con el parámetro api-version.

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.

Nota

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

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.

Para cuentas de almacenamiento de uso general

Si una solicitud anónima a una cuenta de almacenamiento de uso general no especifica el encabezado x-ms-version 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 Set Container ACL operación que se realizó 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 encabezado x-ms-version y la versión predeterminada del servicio no se ha establecido mediante Set Blob Service Properties, el servicio usa la versión más temprana 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 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 otras opciones.

Consulte también