Directiva de control de versiones para servicios, SDK y herramientas de la CLI de Azure

Artículo
12/13/2023

La mayoría de los servicios de Azure permiten controlar y administrar mediante programación sus recursos con las API REST. Los servicios evolucionan a través de nuevas versiones publicadas de sus API con diferentes contratos que agregan nuevas características o modifican sus comportamientos.

En este artículo se describe la directiva que usan los equipos del servicio, el SDK y la CLI de Azure para el control de versiones de las API REST de Azure. Aunque los equipos de Azure realizan todos los esfuerzos para cumplir esta directiva, las desviaciones pueden producirse ocasionalmente.

Control de versiones de servicios

Cada versión publicada de una API se identifica mediante un valor de fecha en YYYY-MM-DD formato, denominado api-version. Las versiones más recientes tienen fechas posteriores.

Todas las operaciones de API requieren que los clientes especifiquen una versión de API válida para el servicio a través del api-version parámetro de cadena de consulta en la dirección URL. Por ejemplo: https://management.azure.com/subscriptions?api-version=2020-01-01. Los SDK de cliente y las herramientas incluyen el api-version valor automáticamente. Para obtener más consideraciones, consulte la sección SDK de cliente y versiones de servicio más adelante en este artículo.

Normalmente, las versiones de servicio publicadas siguen estando disponibles y admitidas durante muchos años, incluso a medida que las versiones más recientes estén disponibles. En la mayoría de los casos, la única vez que debe adoptar una nueva versión de servicio dentro del código existente es aprovechar las nuevas características.

Versiones estables

La mayoría de las versiones de servicio publicadas son versiones estables. Las versiones estables son compatibles con versiones anteriores, lo que significa que cualquier código que escriba que se base en una versión de un servicio puede adoptar una versión estable más reciente sin necesidad de cambios de código para mantener la corrección o la funcionalidad existente.

Versiones de cambios importantes

Una versión de cambio importante de un servicio no es compatible con versiones anteriores. La adopción de una versión de cambio importante en el código de cliente existente puede requerir cambios en el código para asegurarse de que el cliente se comporta exactamente como hizo al dirigirse a la versión anterior.

Las versiones de cambios importantes son poco frecuentes, anunciadas a través de la documentación y suelen ir precedidas por la publicación de una versión preliminar. La publicación de una versión de cambio importante puede solicitar la retirada final de las versiones estables existentes, que permanecerán disponibles durante al menos tres años después de las versiones de cambio importantes. Para cambios importantes publicados debido a problemas de seguridad o cumplimiento, las versiones de servicio estables existentes pueden permanecer disponibles durante un año o menos en función de la gravedad del problema.

Debido a la rápida innovación y desarrollo de la inteligencia artificial, los servicios controlados por ia pueden tener una disponibilidad mínima reducida de un año. Cada servicio publicará su directiva de cambio importante.

Cualquier servicio de Azure que dependa de un componente que no sea de Microsoft puede reducir su directiva de soporte técnico para que coincida con la de la directiva del componente. Cualquier cambio importante debido a esto se vinculará a la directiva del proveedor del componente que muestra la fecha en que el componente ya no se admite.

Versiones preliminares

En ocasiones, Microsoft publica una versión preliminar de un servicio para recopilar comentarios sobre los cambios propuestos y las nuevas características. Las versiones de servicio en versión preliminar se identifican con el sufijo -preview en , api-version por ejemplo, 2022-07-07-preview.

A menos que esté pensado explícitamente para introducir un cambio importante de la versión estable anterior, las nuevas versiones preliminares incluyen todas las características de la versión estable más reciente y agregan nuevas características en versión preliminar. Sin embargo, entre versiones preliminares, un servicio puede interrumpir cualquiera de las características de versión preliminar recién agregadas.

Las versiones preliminares no están pensadas para el uso a largo plazo. Cada vez que haya disponible una nueva versión estable o preliminar de un servicio, las versiones preliminares existentes pueden dejar de estar disponibles a menos de 90 días a partir de la disponibilidad de la nueva versión. Use versiones preliminares solo en situaciones en las que esté desarrollando activamente con nuevas características de servicio y esté preparado para adoptar una nueva versión que no sea de versión preliminar poco después de su lanzamiento. Si algunas características de una versión preliminar se publican en una nueva versión estable, las características restantes todavía en versión preliminar normalmente se publicarán en una nueva versión preliminar.

SDK de cliente y versiones de servicio

Los SDK de Azure tienen como objetivo eliminar el control de versiones del servicio como un problema al escribir código. Cada SDK se compone de bibliotecas cliente, una para cada servicio y cada versión de biblioteca cliente tiene como destino una sola versión del servicio en la que se basa.

Cuando se usa un SDK para acceder a un servicio de Azure, aprovechar las nuevas versiones y características normalmente requiere la actualización de la versión de la biblioteca cliente que usa la aplicación. Las nuevas versiones estables de los servicios van acompañadas de nuevas versiones puntuales de las bibliotecas cliente. Para las nuevas versiones de cambios importantes, las nuevas bibliotecas cliente se publican como versiones de versión de punto o versiones principales. El tipo de versión depende de la naturaleza del cambio del servicio y de la forma en que la biblioteca pueda adaptarla. Solo las bibliotecas cliente de versión beta usan versiones preliminares del servicio.

Las bibliotecas cliente del SDK admiten la invalidación manual de la versión del servicio. La invalidación de la versión de servicio predeterminada de una biblioteca cliente es un escenario avanzado y puede provocar un comportamiento inesperado. Si usa esta característica, pruebe la aplicación exhaustivamente para asegurarse de que funciona según sea necesario.

Herramientas de la línea de comandos de Azure

Al igual que con los SDK, las herramientas de línea de comandos de Azure (incluida la CLI de Azure y Azure PowerShell) están diseñadas para permitir el uso de los servicios de administración de Azure sin tener en cuenta las versiones. El acceso a las nuevas características de servicio suele requerir una nueva versión de una herramienta. Las nuevas versiones de herramientas compatibles con versiones anteriores se publican mensualmente. Las versiones con cambios importantes se publican aproximadamente dos veces al año o según sea necesario para corregir problemas de seguridad críticos.

Las herramientas de línea de comandos de Azure pueden exponer ocasionalmente características en versión preliminar. Estos comandos se marcan con una Preview etiqueta y mostrarán una advertencia que indica compatibilidad limitada y posibles cambios en futuras versiones de herramientas.