Tutorial: Uso de revisiones para realizar cambios de API sin interrupción de forma segura

SE APLICA A: todos los niveles de API Management

Cuando la API esté lista y los desarrolladores empiecen a usarla, tendrá que realizar cambios en dicha API y, al mismo tiempo, no interrumpir a quienes la llaman. También resulta útil informar a los desarrolladores de los cambios realizados.

En Azure API Management, utiliza las revisiones para hacer cambios en la API que no sean de ruptura, de modo que puedas modelar y probar los cambios con seguridad. Cuando esté listo, puede hacer una revisión actualizada y reemplazar la API actual.

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

En este tutorial, aprenderá a:

• Agregar una nueva revisión
• Realizar cambios que no producen interrupciones en la revisión
• Convertir la revisión en actual y agregar una entrada en el registro de cambios
• Examinar el portal para desarrolladores para ver los cambios y registro de cambios
• Acceso a una revisión de API

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, realice el siguiente tutorial: Importación y publicación de la primera API.

Agregar una nueva revisión

1. Inicie sesión en Azure Portal y vaya a la instancia de API Management.

2. En el menú de la izquierda, en API, seleccioneAPI.

3. Seleccione Demo Conference API en la lista de API (u otra API a la que desee agregar revisiones).

4. Seleccione la pestaña Revisiones.

5. Seleccione + Agregar revisión.

   

   Sugerencia

   También puede seleccionar Agregar revisión en el menú contextual ( ... ) de la API.

6. Proporcione una descripción para tu nueva revisión, para ayudar a recordar para qué se utiliza.

7. Seleccione Crear.

8. Ya tenemos creada la revisión.

   Nota

   La API original permanece en Revisión 1. Esta es la revisión que los usuarios siguen llamando hasta que decida convertir otra en actual.

Realizar cambios que no producen interrupciones en la revisión

1. Seleccione Demo Conference API en la lista de API.

2. Seleccione la pestaña Diseño situada junto a la parte superior de la pantalla.

3. Fíjese en que el selector de revisiones (que está inmediatamente encima de la pestaña de diseño) muestra que la revisión seleccionada es Revisión 2.

   Sugerencia

   Use el selector de revisión para alternar entre las revisiones con las que vaya a trabajar.

4. Seleccione + Agregar operación.

5. Establezca su nueva operación como POST, y el Nombre para mostrar, Nombre, y URL de la operación como prueba.

6. Guarde la nueva operación.

   

7. Ya ha hecho un cambio en Revisión 2. Use el selector de revisión junto a la parte superior de la página para volver a Revisión 1.

8. Observe que la nueva operación no figura en Revisión 1.

Convertir la revisión en actual y agregar una entrada en el registro de cambios

Portal

1. Seleccione la pestaña Revisiones en el menú junto a la parte superior de la página.

2. Abra el menú contextual (...) de Revisión 2.

3. Seleccione Convertir en actual.

4. Seleccione la casilla Post to Public Change log for this API (Publicar en el registro de cambios público de esta API), si quiere publicar notas sobre este cambio. Especifique una descripción del cambio que puedan ver los desarrolladores, por ejemplo: Revisiones de prueba. Se agregó una nueva operación de "prueba".

5. Revisión 2 es ahora la revisión actual.

   

CLI de Azure

Para empezar a usar 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.

Utilice este procedimiento para crear y actualizar una versión.

1. Ejecute el comando az apim api list para ver los identificadores de API:

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

   El identificador de API que se usará en el siguiente comando es el valor Name. La revisión de la API está en la columna ApiRevision.

2. Para crear la versión, con una nota de la versión, ejecute el comando az apim api release create:

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   La revisión que se publica se convierte en la revisión actual.

3. Para ver las versiones, use el comando az apim api release list:

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id echo-api --service-name apim-hello-world --output table
   

   Las notas que especifique aparecen en el registro de cambios. Puede verlas en la salida del comando anterior.

4. Cuando crea una versión, el parámetro --notes es opcional. Puede agregar o cambiar las notas más adelante mediante el comando az apim api release update:

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   Use el valor de la columna Name como identificador de la versión.

Puede quitar cualquier versión ejecutando el comando az apim api release delete :

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Examinar el portal para desarrolladores para ver los cambios y registro de cambios

Si ha probado el portal para desarrolladores, puede revisar los cambios de la API y el registro de cambios ahí.

1. Vaya a la instancia de API Management en Azure Portal.
2. En el menú de la izquierda, en API, seleccioneAPI.
3. Seleccione Portal para desarrolladores en el menú superior.
4. En el portal para desarrolladores, seleccione API y, después, Demo Conference API.
5. Observe que la nueva operación prueba ahora aparece disponible.
6. Seleccione Registro de cambios cerca del nombre de la API.
7. Tenga en cuenta que la entrada en el registro de cambios aparece en esta lista.

Acceso a una revisión de API

Para acceder a todas las revisiones de una API se puede usar una dirección URL con un formato especial. Agregue ;rev={revisionNumber} al final de la ruta URL de su API, pero antes de la cadena de consulta, para acceder a una revisión específica de esa API. Por ejemplo, podría utilizar esta URL para acceder a la revisión 2 de la API de la Conferencia de Demostración:

https://apim-hello-world.azure-api.net/conf;rev=2/speakers

Puede encontrar las rutas de acceso de dirección URL de las revisiones de la API en la pestaña Revisiones de Azure Portal.

Sugerencia

Puede acceder a la revisión actual de la API mediante la ruta de acceso de API sin la ;rev cadena, además de la dirección URL completa que se ;rev={revisionNumber} anexa a la ruta de acceso de la API.

Resumen

En este tutorial ha aprendido a:

• Agregar una nueva revisión
• Realizar cambios que no producen interrupciones en la revisión
• Convertir la revisión en actual y agregar una entrada en el registro de cambios
• Examinar el portal para desarrolladores para ver los cambios y registro de cambios
• Acceso a una revisión de API

Pasos siguientes

Avance hasta el siguiente tutorial:

Publicación de varias versiones de la API