Compartir a través de

Tutorial: Depuración de las API con el seguimiento de solicitudes

  • Artículo

SE APLICA A: todos los niveles de API Management

En este tutorial se describe cómo inspeccionar, o realizar el seguimiento, del procesamiento de solicitudes en Azure API Management. El seguimiento le ayuda a depurar y solucionar problemas de la API.

En este tutorial, aprenderá a:

  • Seguimiento de una llamada de ejemplo en la consola de prueba
  • Revisar los pasos del procesamiento de solicitudes
  • Habilitación del seguimiento de una API

Captura de pantalla que muestra el inspector de API.

Requisitos previos

Importante

  • API Management ya no admite suscripciones para el seguimiento o el encabezado Ocp-Apim-Trace.
  • Para mejorar la seguridad, ahora se puede habilitar el seguimiento en el nivel de una API individual al obtener un token de tiempo limitado mediante la API de REST de API Management y pasar el token en una solicitud a la puerta de enlace. Para más información, vea Habilitación del seguimiento de una API.
  • Tenga cuidado al habilitar el seguimiento, ya que puede exponer información confidencial en los datos de seguimiento. Asegúrese de que tiene las medidas de seguridad adecuadas para proteger los datos de seguimiento.

Seguimiento de una llamada en el portal

Siga estos pasos para realizar un seguimiento de una solicitud de API en la consola de prueba del portal. En este ejemplo, se da por supuesto que importó una API de ejemplo en un tutorial anterior. Puede seguir pasos similares con una API diferente que haya importado.

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

  2. Seleccione API>API.

  3. Seleccione API de Petstore en la lista de API.

  4. Seleccione la pestaña Prueba.

  5. Seleccione la operación Buscar mascota por identificador.

  6. En el parámetro de consulta petId, escriba 1.

  7. Tiene la opción de comprobar el valor del encabezado Ocp-Apim-Subscription-Key que se usa en la solicitud seleccionando el icono de ojo.

    Sugerencia

    Puede reemplazar el valor de Ocp-Apim-Subscription-Key mediante la recuperación de una clave de otra suscripción del portal. Seleccione Suscripciones y abra el menú contextual (...) de otra suscripción. Seleccione Mostrar u ocultar claves y copie una de las claves. También puede regenerar claves si es necesario. A continuación, en la consola de prueba, seleccione + Agregar encabezado para agregar un encabezado Ocp-Apim-Subscription-Key con el nuevo valor de clave.

  8. Seleccione Seguimiento.

Revisión de la información de seguimiento

  1. Una vez finalizada la llamada, vaya a la pestaña Seguimiento en Respuesta HTTP.

  2. Seleccione cualquiera de los siguientes vínculos para saltar ainformación de seguimiento detallada: Entrada, Back-end, Salida, En caso de error.

    Revisión del seguimiento de respuestas

    • Entrada: muestra la solicitud original API Management recibida del autor de llamada y las directivas aplicadas a la solicitud. Por ejemplo, si agregó directivas en Tutorial: Transformación y protección de la API, aparecerán aquí.

    • Back-end: muestra las solicitudes que API Management envió al back-end de la API y la respuesta que recibió.

    • Salida: muestra todas las directivas que se aplican a la respuesta antes de enviarla de vuelta al autor de llamada.

    • En caso de error : muestra los errores que se produjeron durante el procesamiento de la solicitud y las directivas aplicadas a los errores.

    Sugerencia

    Cada paso muestra también el tiempo transcurrido desde que API Management recibe la solicitud.

Habilitación del seguimiento de una API

Se requieren los siguientes pasos de alto nivel para habilitar el seguimiento de una solicitud a API Management al usar curl, un cliente REST como Visual Studio Code con la extensión de cliente REST o una aplicación cliente. Actualmente, se deben seguir estos pasos mediante la API de REST de API Management:

  1. Obtenga una credencial de token para el seguimiento.
  2. Agregue el valor del token en un encabezado de solicitud Apim-Debug-Authorization a la puerta de enlace de API Management.
  3. Obtenga un identificador de seguimiento en el encabezado de respuesta Apim-Trace-Id.
  4. Recupere el seguimiento correspondiente del identificador de seguimiento.

A continuación, se indican los pasos detallados.

Nota:

  • Estos pasos requieren la versión 2023-05-01-preview o posterior de la API de REST de API Management. Debe tener asignado el rol Colaborador o superior en la instancia de API Management para llamar a la API de REST.
  • Para obtener información sobre la autenticación en la API de REST, consulte Referencia de API de REST de Azure.

  1. Obtener una credencial de token: llame a la API enumeración de credenciales de depuración de la puerta de enlace de API Management. En el URI, escriba "administrado" en la puerta de enlace administrada de la instancia en la nube o el identificador de puerta de enlace de una puerta de enlace autohospedada. Por ejemplo, para obtener los credenciales de seguimiento de la puerta de enlace administrada de la instancia, use una solicitud similar a la siguiente:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview

    En el cuerpo de la solicitud, pase el identificador de recurso completo de la API que desea realizar el seguimiento y especifique purposes como tracing. De manera predeterminada, la credencial del token devuelta en la respuesta expira después de 1 hora, pero puede especificar un valor diferente en la carga. Por ejemplo:

    {
    "credentialsExpireAfter": PT1H,
    "apiId": ""/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiName}",
    "purposes": ["tracing"]
}

    La credencial del token se devuelve en la respuesta, similar a la siguiente:

    {
      "token": "aid=api-name&......."
}

  2. Agregar el valor del token en un encabezado de solicitud: para habilitar el seguimiento de una solicitud para la puerta de enlace de API Management, envíe el valor del token en un encabezado Apim-Debug-Authorization. Por ejemplo, para realizar un seguimiento de una llamada a la API de Petstore que importó en un tutorial anterior, podría usar una solicitud similar a la siguiente:

    curl -v https://apim-hello-world.azure-api.net/pet/1 HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&......."

  3. Según el token, la respuesta contiene uno de los siguientes encabezados:

    • Si el token es válido, la respuesta incluye un encabezado Apim-Trace-Id cuyo valor es el identificador de seguimiento, parecido al siguiente:

      Apim-Trace-Id: 0123456789abcdef....

    • Si el token ha expirado, la respuesta incluye un encabezado Apim-Debug-Authorization-Expired con información sobre la fecha de expiración.

    • Si el token se obtuvo para una API diferente, la respuesta incluye un encabezado Apim-Debug-Authorization-WrongAPI con un mensaje de error.

  4. Recuperar el seguimiento: pase el identificador de seguimiento obtenido en el paso anterior a la API enumeración de seguimiento de la puerta de enlace. Por ejemplo, para recuperar el seguimiento de la puerta de enlace administrada, use una solicitud similar a la siguiente:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview

    En el cuerpo de la solicitud, pase el identificador de seguimiento obtenido en el paso anterior.

    {
    "traceId": "0123456789abcdef...."
}

    El cuerpo de la respuesta contiene los datos de seguimiento de la solicitud de API anterior a la puerta de enlace. El seguimiento es similar al seguimiento que puede ver mediante el seguimiento de una llamada en la consola de prueba del portal.

Para más información sobre cómo personalizar la información de seguimiento, consulte la directiva de seguimiento.

Pasos siguientes

En este tutorial ha aprendido a:

  • Seguimiento de una llamada de ejemplo en la consola de prueba
  • Revisar los pasos del procesamiento de solicitudes
  • Habilitación del seguimiento de una API

Avance hasta el siguiente tutorial:

Uso de revisiones