Tutorial: Uso de revisiones para realizar cambios de API que no provoquen interrupciones de forma segura

SE APLICA A: Todos los niveles de API Management

Cuando los desarrolladores utilizan su API, eventualmente necesitará realizar cambios en esa API sin interrumpir a los usuarios de su API. También resulta útil informar a los desarrolladores de los cambios realizados.

En Azure API Management, use las revisiones para realizar cambios de API sin provocar interrupciones. Puede modelar y probar los cambios de forma segura. Cuando esté listo, finalice la revisión y reemplace la versión actual de la API.

Para obtener más información, consulte Versiones y revisiones.

Sugerencia

Los equipos de API pueden usar esta característica en áreas de trabajo. Las áreas de trabajo proporcionan acceso administrativo aislado a las API y sus propios entornos de tiempo de ejecución de API.

En este tutorial, aprenderá a:

• Agregar una nueva revisión
• Realizar cambios en la revisión que no provoquen interrupciones
• 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.
• Completar la guía de inicio rápido siguiente: Creación de una instancia de Azure API Management.
• Complete 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 Swagger Petstore en la lista de API o una API diferente a la que quiera 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 la nueva revisión y para ayudar a recordar para qué se usa.

7. Seleccione Crear.

   Ya tenemos creada la revisión.

   Nota:

   La API original permanece en Revisión 1. Esta es la revisión que los usuarios siguen utilizando, hasta que decida hacer actual una revisión diferente.

Realizar cambios en la revisión que no provoquen interrupciones

1. Seleccione Swagger Petstore en la lista de API.

2. Seleccione Diseño cerca de la parte superior de la pantalla.

   El selector de revisión situado encima de la pestaña diseño muestra la revisión 2 como seleccionada actualmente.

   Sugerencia

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

3. Seleccione + Agregar operación.

4. Establezca la nueva operación como POST y configure los valores de Nombre para mostrar, Nombre y URL de la operación test.

5. Guarde la nueva operación.

   

   Ya ha hecho un cambio en Revisión 2.

6. Use el selector de revisión junto a la parte superior de la página para volver a Revisión 1.

   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. En el menú situado cerca de la parte superior de la página, seleccione Revisiones.

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

3. Seleccione Convertir en actual.

4. Si desea publicar notas sobre este cambio, seleccione Publicar en Registro de cambios público para esta API. Especifique una descripción del cambio que puedan ver los desarrolladores, por ejemplo: Revisiones de prueba. Se agregó una nueva operación de "prueba".

   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 Introducción a 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, consulte 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. Para finalizar el proceso de autenticación, siga los pasos que aparecen en su terminal. Para ver otras opciones de inicio de sesión, consulte Autenticación en Azure mediante 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 obtener más información sobre las extensiones, consulte Uso y administración de extensiones con la CLI de Azure.

  • Ejecute la versión de zona de disponibilidad para encontrar 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 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 swagger-petstore --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 swagger-petstore --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 swagger-petstore --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 swagger-petstore --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

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

Si prueba el portal para desarrolladores, puede revisar los cambios de la API y el registro de cambios allí.

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, Swagger Petstore.
5. Observe que la nueva operación prueba ahora aparece disponible.
6. Seleccione Cambiar registro 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. Para acceder a una revisión concreta de esa API, agregue ;rev={revisionNumber} al final de la ruta de la dirección URL de la API, pero antes de la cadena de consulta. Por ejemplo, puede usar una dirección URL similar a la siguiente para acceder a la revisión 2 de la API de Swagger Petstore:

https://apim-hello-world.azure-api.net/store/pet/1;rev=2/

Puede encontrar las rutas de las direcciones 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 la API sin la cadena ;rev, además de la dirección URL completa que anexa ;rev={revisionNumber} a la ruta de la API.

Resumen

En este tutorial, ha aprendido a:

• Agregar una nueva revisión
• Realizar cambios en la revisión que no provoquen interrupciones
• 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

Paso siguiente

Avance hasta el siguiente tutorial:

Publicación de varias versiones de la API