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
Requisitos previos
- Conocer la terminología de API Management de Azure.
- Complete el siguiente inicio rápido: Creación de una instancia de Azure API Management.
- Además, completar el tutorial siguiente: Importación y publicación de la primera API.
Agregar una nueva versión
- Vaya a la instancia de API Management en Azure Portal.
- Seleccione API.
- Seleccione Demo Conference API en la lista de API.
- Seleccione el menú contextual ( ... ) junto a Demo Conference API.
- Seleccione Agregar versión.
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.
| Configuración | valor | Descripción |
|---|---|---|
| Nombre | demo-conference-api-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. |
| Esquema de control de versiones | Path | La forma en que los autores de llamadas especifican la versión de la API. |
| 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. Si selecciona Encabezado o Cadena de consulta, proporcione un valor más: el nombre del parámetro de encabezado o de la cadena de consulta. Se muestra un ejemplo de uso. |
| Productos | Sin límite | 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 Demo Conference API en la lista de API. Ahora verá dos API: Original y v1.
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:
- Vaya a la instancia de API Management en Azure Portal.
- Seleccione Productos>Ilimitado>API>+ Agregar.
- Seleccione Demo Conference API, versión v1.
- Haga clic en Seleccionar.
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:
Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.
Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.
Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.
En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.
Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.
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í.
- Seleccione Portal para desarrolladores en el menú superior.
- Seleccione API y, después, Demo Conference API.
- Debe ver una lista desplegable con varias versiones junto al nombre de la API.
- Seleccione v1.
- 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: