Tutorial: Uso de la extensión Azure API Management para Visual Studio Code a fin de importar y administrar las API

SE APLICA A: Consumo | Desarrollador | Básico | Estándar | Premium

En este tutorial aprenderá a utilizar la extensión API Management para Visual Studio Code para realizar operaciones comunes en API Management. Utilice el entorno familiar de Visual Studio Code para importar, actualizar, probar y administrar las API.

Aprenderá a:

• Importación de una API en API Management
• Editar la API
• Aplicar las directivas de API Management
• Prueba de la API

Para ver una introducción a otras características de API Management, consulte los tutoriales de API Management mediante Azure Portal.

Requisitos previos

• Conocer la terminología de Azure API Management.
• Asegurarse de haber instalado Visual Studio Code y la extensión Azure API Management para Visual Studio Code más reciente.
• Crear una instancia de API Management.

Importación de una API

En el ejemplo siguiente se importa una especificación de OpenAPI en formato JSON a API Management. Microsoft proporciona la API de back-end usada en este ejemplo y la hospeda en Azure en https://conferenceapi.azurewebsites.net.

1. En Visual Studio Code, seleccione el icono de Azure en la barra de actividades.
2. En el panel del Explorador, expanda la instancia de API Management que haya creado.
3. Haga clic con el botón derecho en API y seleccione Import from OpenAPI Link (Importar desde el vínculo de OpenAPI).
4. Cuando se le solicite, escriba los siguientes valores:

   1. Un vínculo de OpenAPI para el contenido en formato JSON. En este ejemplo: https://conferenceapi.azurewebsites.net?format=json .

      Este archivo especifica el servicio back-end que implementa la API de ejemplo, en este caso https://conferenceapi.azurewebsites.net. API Management reenvía las solicitudes a este servicio web.

   2. Un nombre de API, como demo-conference-api, que sea único en la instancia de API Management. Este nombre solo puede contener letras, números y guiones. El primer y el último carácter deben ser alfanuméricos. Este nombre se utiliza en la ruta de acceso para llamar a la API.

Una vez que la API se haya importado correctamente, aparecerá en el panel del Explorador, y las operaciones de API disponibles se mostrarán bajo el nodo Operations (Operaciones).

Edición de la API

Puede editar la API en Visual Studio Code. Por ejemplo, edite la descripción JSON de Resource Manager de la API en la ventana del Editor a fin de quitar el protocolo http que se utiliza para acceder a la API.

Para editar el formato de OpenAPI, haga clic con el botón derecho en el nombre de la API en el panel del Explorador y seleccione Edit OpenAPI (Editar OpenAPI). Realice los cambios y después seleccione Archivo>Guardar.

Aplicación de directivas a la API

API Management proporciona directivas que puede configurar para las API. Las directivas son una colección de instrucciones. Estas instrucciones se ejecutan secuencialmente en la solicitud o respuesta de una API. Las directivas pueden ser globales, que se aplican a todas las API de la instancia de API Management, o específicas para un producto, una API o una operación de API.

En esta sección se muestra cómo aplicar directivas de salida comunes a la API, que transforman la respuesta de la API. Las directivas de este ejemplo cambian los encabezados de respuesta y ocultan las direcciones URL de back-end originales que aparecen en el cuerpo de la respuesta.

1. En el panel del Explorador, seleccione Policy (Directiva) bajo el nombre demo-conference-api que ha importado. El archivo de directivas se abre en la ventana del Editor. Este archivo configura las directivas para todas las operaciones de la API.

2. Actualice el archivo con el siguiente contenido en el elemento <outbound>:

   [...]
   <outbound>
       <set-header name="Custom" exists-action="override">
           <value>"My custom value"</value>
       </set-header>
       <set-header name="X-Powered-By" exists-action="delete" />
       <redirect-content-urls />
       <base />
   </outbound>
   [...]
   

   • La primera directiva set-header agrega un encabezado de respuesta personalizado para fines de demostración.
   • En la segunda directiva set-header se elimina el encabezado X-Powered-By, si existe. Este encabezado puede revelar la plataforma de la aplicación que se usa en el back-end de la API, y los publicadores lo suelen quitar.
   • La directiva redirect-content-urls reescribe (enmascara) los vínculos del cuerpo de la respuesta para que apunten al vinculo equivalente a través de la puerta de enlace de API Management.

3. Guarde el archivo. Si se le solicita, seleccione Cargar para cargar el archivo en la nube.

Prueba de la API

Para probar la API, obtenga una clave de suscripción y, a continuación, realice una solicitud a la puerta de enlace de API Management.

Establecimiento de la clave de suscripción

Necesita una clave de suscripción para su instancia de API Management para probar la API importada y las políticas que se aplican.

1. En el panel del Explorador, haga clic con el botón derecho en el nombre de la instancia de API Management.

2. Seleccione Copy Subscription Key (Copiar la clave de suscripción). Esta clave es para la suscripción de acceso integrada que se crea al crear una instancia de API Management.

   

   Precaución

   La suscripción de acceso completo permite el acceso a todas las API de la instancia de API Management y solo deben usarse los usuarios autorizados. Nunca la use para el acceso de API rutinario o inserte la clave de acceso completo en las aplicaciones cliente.

Prueba de una operación de API

1. En el panel del Explorador, seleccione el nodo Operations(Operaciones) bajo el nombre demo-conference-api que ha importado.
2. Seleccione una operación, como GetSpeakers, y, después, haga clic con el botón derecho en ella y seleccione Operación de prueba.
3. En la ventana del Editor, junto a Ocp-Apim-Subscription-Key, reemplace {{SubscriptionKey}} por la clave de suscripción copiada.
4. Seleccione Enviar solicitud.

Si la solicitud es correcta, el back-end responde con 200 OK y algunos datos.

Observe los siguientes detalles en la respuesta:

• El encabezado Custom se agrega a la respuesta.
• El encabezado X-Powered-by no aparece en la respuesta.
• Las direcciones URL al back-end de API se redirigen a la puerta de enlace de API Management, en este caso https://apim-hello-world.azure-api.net/demo-conference-api.

Procesamiento de solicitudes de seguimiento

Opcionalmente, puede obtener información detallada de seguimiento de solicitudes para ayudarle a depurar y solucionar problemas de la API.

Para conocer los pasos para habilitar el seguimiento de una API, consulte Habilitación del seguimiento de una API. Para limitar la divulgación no intencionada de información confidencial, el seguimiento de forma predeterminada solo se permite durante 1 hora.

Limpieza de recursos

Cuando ya no la necesite, elimine la instancia de API Management; para ello, haga clic con el botón derecho y seleccione Abrir en el portal para eliminar el servicio API Management y su grupo de recursos.

O bien, puede seleccionar Eliminar API Management para eliminar solo la instancia de API Management (esta operación no elimina su grupo de recursos).

Contenido relacionado

En este tutorial, se presentaron varias características de la extensión API Management para Visual Studio Code. Puede usar estas características para importar y administrar las API. Ha aprendido a:

• Importación de una API en API Management
• Editar la API
• Aplicar las directivas de API Management
• Prueba de la API

La extensión API Management proporciona características adicionales para trabajar con las API. Por ejemplo, depuración de directivas (disponible en el nivel de servicio del desarrollador) o creación y administración de valores con nombre.