Leer en inglés

Compartir a través de


Tutorial: Publicación de varias versiones de la API

SE APLICA A: todos los niveles de API Management

A veces resulta poco práctico que todos los autores de llamadas que llaman a la API usen exactamente la misma versión. Si los autores de llamadas quieren actualizarla a una versión posterior, querrán hacerlo con un enfoque que sea fácil de comprender. Como se muestra en este tutorial, es posible proporcionar varias versiones en Azure API Management.

Para obtener información general, consulte Versiones y Revisiones.

En este tutorial, aprenderá a:

  • Agregar una nueva versión a una API existente
  • Elegir un esquema de versión
  • Agregar la versión a un producto
  • Examinar el portal para desarrolladores para ver la versión

Captura de pantalla que muestra versiones de API en Azure Portal.

Requisitos previos

Agregar una nueva versión

  1. Vaya a la instancia de API Management en Azure Portal.
  2. Seleccione API.
  3. Seleccione Swagger Petstore en la lista de API.
  4. Seleccione el menú contextual (... ) junto a Swagger Petstore.
  5. Seleccione Agregar versión.

Captura de pantalla que muestra el comando para agregar una versión en el menú contextual de la API en el portal.

Sugerencia

También se pueden habilitar las versiones cuando se crea una nueva API. En la pantalla Agregar API, seleccione ¿Definir versión de esta API? .

Elegir un esquema de control de versiones

En Azure API Management, elija cómo los autores de llamadas especifican la versión de la API seleccionando un esquema de control de versiones: ruta, encabezado o cadena de consulta. En el ejemplo siguiente, la ruta de acceso se utiliza como esquema del control de versiones.

Escriba los valores de la tabla siguiente. Luego, seleccione Crear para crear la versión.

Captura de pantalla que muestra la ventana para crear una nueva versión en el portal.

Configuración valor Descripción
Identificador de la versión v1 Indicador específico del esquema de la versión. Para Ruta de acceso, el sufijo de la ruta de acceso de la URL de la API.
Esquema de control de versiones Path La forma en que los autores de llamadas especifican la versión de la API.

Si selecciona Encabezado o Cadena de consulta, proporcione otro valor: el nombre del parámetro de encabezado o de la cadena de consulta.

Se muestra un ejemplo de uso.
Nombre de versión de la API completo swagger-petstore-v1 Nombre único de su instancia de API Management.

Dado que una versión es en realidad una nueva API basada en una revisión de la API, este valor es el nombre de la nueva API.
Productos Ilimitado (proporcionado en determinados niveles de servicio) Opcionalmente, uno o varios productos a los que está asociada la versión de la API. Para publicar la API, debe asociarla a un producto. También puede agregar la versión a un producto más adelante.

Después de crear la versión, ahora aparece debajo de Swagger Petstore en la lista de API. Ahora verá dos API: Original y v1.

Captura de pantalla de las versiones que aparecen en una API en el portal.

Nota

Si agrega una versión a una API sin control de versiones, se creará automáticamente una API Original. Esta versión responde en la dirección URL predeterminada. La creación de una versión Original garantiza que los autores de llamadas no sufran ninguna interrupción a causa del proceso de adición de la versión. Si crea una API con las versiones habilitadas desde el principio, no se creará un original.

Edición de una versión

Después de agregar la versión, ahora puede editarla y configurarla como una API independiente de un original. Los cambios en una versión no afectan a otra. Por ejemplo, agregue o quite operaciones de API o edite la especificación OpenAPI. Para obtener más información, vea Editar API.

Agregar la versión a un producto

Para que quienes realizan las llamadas vean la versión nueva, debe agregarse a un producto. Si aún no ha agregado la versión a un producto, puede hacerlo en cualquier momento.

Por ejemplo, para agregar la versión al producto Ilimitado:

  1. Vaya a la instancia de API Management en Azure Portal.
  2. Seleccione Productos>Ilimitado>API>+ Agregar.
  3. Seleccione Swagger Petstore, versión v1.
  4. Haga clic en Seleccionar.

Captura de pantalla de la adición de una versión a un producto en el portal.

Uso de conjuntos de versiones

Al crear varias versiones, Azure Portal crea un conjunto de versiones, que representa un conjunto de versiones para una única API lógica. Seleccione el nombre de una API que tenga varias versiones. Azure Portal muestra su conjunto de versiones. Puede personalizar el Nombre y la Descripción de un conjunto virtual.

Puede interactuar directamente con los conjuntos de versiones mediante la CLI de Azure:

Para ver todos los conjuntos de versiones, ejecute el comando az apim api versionset list:

az apim api versionset list --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --output table

Cuando Azure Portal crea un conjunto de versiones, asigna un nombre alfanumérico, que aparece en la columna Nombre de la lista. Use este nombre en otros comandos de la CLI de Azure.

Para ver detalles acerca de un conjunto de versiones, ejecute el comando az apim api versionset show:

az apim api versionset show --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --version-set-id 00000000000000000000000

Para más información sobre las suscripciones, consulte Versiones de Azure API Management.

Examinar el portal para desarrolladores para ver la versión

Si ha probado el portal para desarrolladores, puede ver las versiones de la API allí.

  1. Seleccione Portal para desarrolladores en el menú superior.
  2. Seleccione API y, después, Swagger Petstore.
  3. Debe ver una lista desplegable con varias versiones junto al nombre de la API.
  4. Seleccione v1.
  5. Fíjese en la Dirección URL de la solicitud de la primera operación de la lista. Refleja que la ruta de acceso de la dirección URL de la API incluye v1.

Pasos siguientes

En este tutorial, ha aprendido a:

  • Agregar una nueva versión a una API existente
  • Elegir un esquema de versión
  • Agregar la versión a un producto
  • Examinar el portal para desarrolladores para ver la versión

Avance hasta el siguiente tutorial: