Versiones de Azure API Management

SE APLICA A: Todos los niveles de API Management

Las versiones permiten presentar grupos de API relacionadas a los desarrolladores. Puede usar versiones para controlar los cambios importantes con seguridad en la API. Los clientes pueden optar por usar la nueva versión de la API cuando está lista, mientras que los clientes existentes siguen usando una versión anterior. Las versiones se diferencian a través de un identificador de versión (que es cualquier valor de cadena que elija) y un esquema de control de versiones permite a los clientes identificar qué versión de una API quieren usar. En este artículo se describe cómo usar versiones en API Management.

En la mayoría de los casos, cada versión de la API se puede considerar como su propia API independiente. Dos versiones de API diferentes pueden tener conjuntos de operaciones y directivas diferentes.

Las versiones le permiten lo siguiente:

• Publique varias versiones de la API al mismo tiempo.
• Use una ruta de acceso, una cadena de consulta o un encabezado para diferenciar entre versiones.
• Utilice cualquier valor de cadena que desee para identificar su versión. Podría ser un número, una fecha o un nombre.
• Muestre las versiones de API agrupadas en el portal para desarrolladores.
• Cree una nueva versión de una API existente (sin versiones) sin afectar a los clientes existentes.

Para empezar a trabajar con versiones, complete un tutorial.

Esquemas de control de versiones

Los diferentes desarrolladores de API tienen requisitos diferentes para el control de versiones. Azure API Management no prescribe un enfoque único para el control de versiones, sino que proporciona varias opciones.

Control de versiones basado en rutas de acceso

Cuando se utiliza el esquema de versionado de rutas, el identificador de versión debe incluirse en la ruta URL de las solicitudes de API.

Por ejemplo, https://apis.contoso.com/products/v1 y https://apis.contoso.com/products/v2 podrían hacer referencia a la misma products API, pero a las versiones v1 y v2.

El formato de una dirección URL de solicitud de API cuando usa el control de versiones basado en rutas de acceso es: https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Control de versiones basado en encabezados

Cuando se usa el esquema de control de versiones de encabezado, el identificador de versión debe incluirse en un encabezado de solicitud HTTP para las solicitudes de API. Puede especificar el nombre del encabezado de solicitud HTTP.

Por ejemplo, podría crear un encabezado personalizado denominado Api-Versiony los clientes podrían especificar v1 o v2 en el valor de este encabezado.

Control de versiones basado en cadenas de consulta

Cuando se usa el esquema de control de versiones de cadena de consulta, el identificador de versión debe incluirse en un parámetro de cadena de consulta para las solicitudes de API. Puede especificar el nombre del parámetro de cadena de consulta.

El formato de una dirección URL de solicitud de API cuando se usa el control de versiones basado en cadenas de consulta es https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Por ejemplo, https://apis.contoso.com/products?api-version=v1 y https://apis.contoso.com/products?api-version=v2 podrían hacer referencia a la misma products API, pero a las versiones v1 y v2.

Versiones originales

Si agrega una versión a una API sin versiones, se creará automáticamente una Original versión y responderá en la dirección URL predeterminada, sin un identificador de versión especificado. La versión Original garantiza que los llamadores existentes no se vean afectados por el proceso de agregar una versión. Si crea una API con las versiones habilitadas desde el principio, no se crea una versión Original.

Cómo se representan las versiones

API Management mantiene un recurso denominado conjunto de versiones, que representa un conjunto de versiones para una sola API lógica. Un conjunto de versiones contiene el nombre visible de la API versionada y el esquema de versionado que se utiliza para direccionar las solicitudes a las versiones especificadas.

Cada versión de una API se mantiene como su propio recurso de API y está asociado a un conjunto de versiones. Un conjunto de versiones puede contener API con diferentes operaciones o directivas. Es posible que realice cambios significativos entre las versiones de un conjunto.

El portal de Azure crea conjuntos de versiones para ti. Puede modificar el nombre y la descripción de un conjunto de versiones en Azure Portal.

Un conjunto de versiones se elimina automáticamente cuando se elimina la versión final.

Puede ver y administrar conjuntos de versiones directamente mediante la CLI de Azure, Azure PowerShell, las plantillas de Resource Manager o la API de Azure Resource Manager.

Migración de una API sin versiones a una API con versiones

Cuando se usa Azure Portal para habilitar el control de versiones en una API existente, se realizan los siguientes cambios en los recursos de API Management:

• Se crea un nuevo conjunto de versiones.
• La versión existente se mantiene y se configura como la versión de la API Original. La API está vinculada al conjunto de versiones, pero no es necesario especificar un identificador de versión.
• La nueva versión se crea como una NUEVA API y está vinculada al conjunto de versiones. Se debe usar un esquema de control de versiones y un identificador para acceder a la nueva API.

Versiones y revisiones

Las versiones y las revisiones son características distintas. Cada versión puede tener varias revisiones, al igual que una API sin versiones. Se pueden usar revisiones sin utilizar versiones y viceversa. Normalmente, las versiones se usan para separar las versiones de API que tienen cambios importantes y las revisiones se pueden usar para cambios menores y no importantes en una API.

Si encuentra que la revisión tiene cambios importantes o si desea convertir formalmente la revisión en una versión beta o de prueba, puede crear una versión a partir de una revisión. En Azure Portal, seleccione Crear versión en esta revisión en el menú contextual de revisión (...) en la pestaña Revisiones .

Portal para desarrolladores

El portal para desarrolladores enumera cada versión de una API por separado:

En los detalles de una API, también puede ver una lista de todas las versiones de la API. Se muestra una Original versión sin un identificador de versión: