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

  • Artículo

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

Captura de pantalla de la API en la extensión de API Management

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

Requisitos previos

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).

Captura de pantalla de la API importada en el panel del Explorador

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.

Captura de pantalla de la edición de la descripción JSON en Visual Studio Code

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.

    Captura de pantalla del comando Copiar clave de suscripción en Visual Studio Code

    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. Junto a Ocp-Apim-Trace, escriba false. Esta configuración deshabilita el seguimiento de solicitudes.
  5. Seleccione Enviar solicitud.

Captura de pantalla del envío de una solicitud de API desde Visual Studio Code

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

Captura de pantalla de la respuesta de prueba de API en Visual Studio Code

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 realizar un seguimiento del procesamiento de solicitudes, primero habilite la opción Permitir seguimiento en la suscripción usada para depurar la API. Para conocer los pasos para habilitar esta configuración mediante el portal, consulte Comprobación del valor Permitir seguimiento. Para limitar la divulgación no intencionada de información confidencial, el seguimiento solo se permite durante 1 hora.

Después de permitir el seguimiento con la suscripción, siga estos pasos:

  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 que desea usar.
  4. Junto a Ocp-Apim-Trace, escriba true. Esta configuración habilita el seguimiento para esta solicitud.
  5. Seleccione Enviar solicitud.

Cuando la solicitud se realiza correctamente, la respuesta de back-end incluye un encabezado Ocp-APIM-Trace-Location.

Captura de pantalla de la ubicación de seguimiento en la respuesta de prueba de API en Visual Studio Code

Seleccione el vínculo situado junto a Ocp-APIM-Trace-Location para ver la información de seguimiento entrante, saliente y de back-end. La información de seguimiento le ayuda a determinar dónde se producen los problemas después de realizar la solicitud.

Sugerencia

Al probar las operaciones de API, la extensión API Management permite la depuración de directivas opcional (disponible solo en el nivel de servicio del desarrollador).

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).

Captura de pantalla de la eliminación de la instancia de API Management de Visual Studio Code

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.