Tutorial: Uso de revisiones para realizar cambios de API que no producen interrupciones 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, use revisiones para realizar cambios de API que no producen interrupciones para que pueda modelar y probar los cambios de forma segura. Cuando esté listo, puede hacer una revisión actualizada y reemplazar la API actual.

Para más información, consulte Versiones y revisiones y Control de versiones con Azure API Management.

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

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. Seleccione API.

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. Incluya una descripción de la nueva revisión y que así los usuarios puedan saber para qué va a servir.

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 la nueva operación como POST y especifique test como nombre, nombre para mostrar y dirección URL de la operación.

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. En Azure Portal, seleccione API.
2. Seleccione Portal para desarrolladores en el menú superior.
3. En el portal para desarrolladores, seleccione API y, después, Demo Conference API.
4. Observe que la nueva operación prueba ahora aparece disponible.
5. Seleccione Registro de cambios cerca del nombre de la API.
6. Tenga en cuenta que la entrada en el registro de cambios aparece en esta lista.

Pasos siguientes

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

Avance hasta el siguiente tutorial:

Publicación de varias versiones de la API