Comparteix via

Guía: Depura tus API utilizando el seguimiento de solicitudes

SE APLICA A: Todos los niveles de API Management

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

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:

  • 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 de la API, el seguimiento ahora se puede habilitar en el nivel de una API individual. Obtenga un token de tiempo limitado mediante la API REST de API Management y pase el token en una solicitud a la puerta de enlace. Para más información, consulte Habilitación del seguimiento de una API.
  • Tenga cuidado al habilitar el seguimiento. 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 Azure Portal

Siga estos pasos para realizar un seguimiento de una solicitud de API en la consola de prueba del portal. En este ejemplo se supone 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 APIs>APIs.

  3. Seleccione Petstore API en la lista de API.

  4. Seleccione la pestaña Prueba .

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

  6. En el petIdparámetro Query, introduzca 1.

  7. Opcionalmente, compruebe el valor del encabezado Ocp-Apim-Subscription-Key que se usa en la solicitud seleccionando el icono "ojo".

    Sugerencia

    Puede invalidar el valor de Ocp-Apim-Subscription-Key mediante la recuperación de una clave para otra suscripción en Azure Portal. Seleccione Suscripciones y abra el menú contextual (...) para 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 completada la llamada, vaya a la pestaña Seguimiento en la respuesta HTTP.

  2. Seleccione cualquiera de los vínculos siguientes para saltar a información detallada de seguimiento: Entrante, Backend, Saliente, En caso de error.

    Captura de pantalla que muestra el seguimiento de la respuesta de revisión.

    • Entrante. Muestra la petición original de API Management recibida del llamante y las directivas aplicadas a la petición. Por ejemplo, si ha agregado directivas en Tutorial: Transformación y protección de la API, aparecen aquí.
    • Backend. Muestra las solicitudes de API Management enviadas al back-end de API y la respuesta que recibió.
    • Saliente. Muestra las directivas aplicadas a la respuesta antes de devolverlas al autor de la 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 también muestra 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 REST de API Management:

  1. Obtenga un token de depuración 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. Debes tener asignado el rol de Colaborador o superior en la instancia de API Management para llamar a la API REST.
  • Para más información sobre la autenticación en la API REST, consulte Referencia de la API REST de Azure.

  1. Consiga un token de depuración. Llame a la API Enumerar credenciales de depuración de la puerta de enlace de API Management. En el URI, escriba administrado para 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 credenciales de seguimiento para la puerta de enlace administrada de la instancia, use una solicitud similar al ejemplo 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. Especifique purposes como tracing. De forma predeterminada, la credencial del token devuelta en la respuesta expira después de 1 hora. Puede especificar un valor diferente en la carga útil. El tiempo de expiración se limita a un máximo de 1 hora. Por ejemplo:

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

    Nota:

    El apiId solo se puede extraer del identificador de recurso completo, no del nombre que se muestra en el portal de Azure.

    Obtener apiId:

    az apim api list --resource-group <resource-group> --service-name <service-name> -o table

    La credencial de depuración se devuelve en la respuesta, similar al ejemplo siguiente:

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

  2. Agregue el valor del token en un encabezado de solicitud. Para habilitar el seguimiento de una solicitud al gateway 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 al ejemplo 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. Evalúe la respuesta. La respuesta puede contener uno de los siguientes encabezados en función del estado del token de depuración:

    Encabezado en respuesta Explanation
    Apim-Trace-Id Token de depuración válido. El valor es el identificador de seguimiento, como: Apim-Trace-Id: 0123456789abcdef....
    Apim-Debug-Authorization-Expired El token ha expirado. El encabezado incluye información sobre la fecha de expiración.
    Apim-Debug-Authorization-WrongAPI Token obtenido para una API diferente. El encabezado incluye un mensaje de error.

  4. Recupere la traza. Pase el identificador de seguimiento obtenido en el paso anterior a la API List trace de la puerta de enlace. Por ejemplo, para recuperar el seguimiento de la puerta de enlace administrada, use una solicitud similar al ejemplo 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.

Archivo HTTP de ejemplo para la extensión de cliente REST de VS Code

Para ayudar a automatizar estos pasos con la extensión cliente REST de Visual Studio Code , puede usar el siguiente archivo de ejemplo .http :

@subscriptionId = // Your subscription ID
@resourceGroup = // Your resource group
@apimName = // Your API Management service name
@clientId = // Client ID from an app registration for authentication
@clientSecret = // Client secret from app registration
@externalHost = // The host name of the App Gateway or the fully qualified gateway URL
@subscriptionKey = // API Management subscription key
@apiEndPoint = // API URL
@requestBody = // Data to send
@tenantId = // Tenant ID
@apiId = // Api Id for which trace log is to be generated.

# @name login 
POST https://login.microsoftonline.com/{{tenantId}}/oauth2/token
content-type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}&resource=https%3A%2F%2Fmanagement.azure.com%2F
 
###
@authToken = {{login.response.body.$.access_token}}
###
# @name listDebugCredentials
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
Authorization: Bearer {{authToken}}

Content-Type: application/json
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/apis/{{apiId}}",
    "purposes": ["tracing"]
}
 
###
@debugToken = {{listDebugCredentials.response.body.$.token}}
 
###
# @name callApi
POST {{apiEndPoint}} HTTP/1.1
Host: {{externalHost}}
Apim-Debug-Authorization: {{debugToken}}
Ocp-Apim-Subscription-Key: {{subscriptionKey}}
Content-Type: application/json

{{requestBody}}
 
###
@traceId = {{callApi.response.headers.Apim-Trace-Id}}
 
###
# @name getTrace
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listTrace?api-version=2024-06-01-preview
Authorization: Bearer {{authToken}}
Content-Type: application/json
 
{
    "traceId": "{{traceId}}"
}

Para obtener información sobre cómo personalizar la información de seguimiento, consulte la directiva de seguimiento .

Resumen

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

Paso siguiente

Avance hasta el siguiente tutorial:

Uso de revisiones

  • Last updated on