Partage via

Tutoriel : Déboguer vos API à l’aide du suivi des demandes

  • Article

S’APPLIQUE À : Tous les niveaux de Gestion des API

Ce tutoriel explique comment inspecter (tracer) le traitement des requêtes dans le service Gestion des API Azure. Le traçage vous aide à résoudre les bogues et les problèmes liés à votre API.

Dans ce tutoriel, vous allez apprendre à :

  • Tracer un exemple d’appel dans la console de test
  • Passer en revue les étapes du traitement des demandes
  • Activer le traçage pour une API

Capture d'écran montrant l'inspecteur d'API.

Prérequis

Important

  • Gestion des API ne prend plus en charge les abonnements pour le traçage ou l’en-tête Ocp-Apim-Trace.
  • Pour améliorer la sécurité des API, le traçage peut désormais être activé au niveau d’une API individuelle en obtenant un jeton d’une durée limitée avec l’API REST de Gestion des API, et en passant le jeton à la passerelle dans une requête. Pour plus d’informations, consultez Activer le traçage d’une API.
  • Soyez prudent quand vous activez le traçage, car il peut exposer des informations sensibles dans les données de traçage. Veillez à mettre en place les mesures de sécurité appropriées pour protéger les données de trace.

Tracer un appel dans le portail

Suivez ces étapes pour suivre une demande d’API dans la console de test dans le portail. Cet exemple suppose que vous avez importé un exemple d’API dans un précédent didacticiel. Vous pouvez suivre des étapes similaires avec une autre API que vous avez importée.

  1. Connectez-vous au portail Azure et accédez à votre instance de Gestion des API.

  2. Sélectionnez APIs>APIs.

  3. Sélectionnez Petstore API dans votre liste d’API.

  4. Sélectionnez l’onglet Test.

  5. Sélectionnez l’opération Find pet by ID.

  6. Pour petId, dans le paramètre de requête, entrez 1.

  7. Si vous le souhaitez, vérifiez la valeur de l’en-tête Ocp-Apim-Subscription-Key utilisé dans la demande en sélectionnant l’icône « œil ».

    Conseil

    Vous pouvez remplacer la valeur Ocp-Apim-Subscription-Key en récupérant une clé pour un autre abonnement dans le portail. Sélectionnez Abonnements, puis ouvrez le menu contextuel (...) pour un autre abonnement. Sélectionnez Afficher/masquer les clés et copiez l’une des clés. Vous pouvez également regénérer les clés si nécessaire. Ensuite, dans la console de test, sélectionnez + Ajouter un en-tête pour ajouter un en-tête Ocp-Apim-Subscription-Key avec la nouvelle valeur de clé.

  8. Sélectionnez Trace.

Examiner les informations de suivi

  1. Une fois l’appel terminé, accédez à l’onglet Trace dans la réponse HTTP.

  2. Sélectionnez les liens suivants pour accéder aux informations de suivi détaillées : Entrant, Principal, Sortant, En cas d’erreur.

    Vérifier le suivi de la réponse

    • Entrant : affiche la demande d’origine reçue par le service Gestion des API de l’appelant et les stratégies appliquées à la demande. Par exemple, si vous avez ajouté des stratégies dans le Tutoriel : Transformer et protéger votre API, ces stratégies s’affichent ici.

    • Principal : affiche les demandes envoyées par le service Gestion des API au backend d’API et la réponse qu’il a reçue.

    • Sortant : affiche toutes les stratégies appliquées à la réponse avant son envoi à l’appelant.

    • En cas d’erreur : affiche les erreurs qui se sont produites pendant le traitement de la demande et les stratégies appliquées aux erreurs.

    Conseil

    Chaque étape indique également le temps écoulé depuis la réception de la demande par le service Gestion des API.

Activer le traçage pour une API

Les étapes générales suivantes sont requises pour activer le traçage d’une requête au service Gestion des API à l’aide de curl, d’un client REST tel que Visual Studio Code avec l’extension Client REST ou d’une application cliente. Actuellement, vous devez suivre ces étapes à l’aide de l’API REST Gestion des API :

  1. Obtenez des informations d’identification de jeton pour le traçage.
  2. Ajoutez la valeur du jeton dans un en-tête de demande Apim-Debug-Authorization auprès de la passerelle Gestion des API.
  3. Obtenez un ID de trace dans l’en-tête de réponse Apim-Trace-Id.
  4. Récupérez la trace correspondant à l’ID de trace.

Voici les étapes détaillées.

Remarque

  • Ces étapes nécessitent l’API REST Gestion des API version 2023-05-01-preview ou ultérieure. Vous devez disposer du rôle Contributeur ou d’un rôle supérieur sur l’instance de Gestion des API pour appeler l’API REST.
  • Pour plus d’informations sur l’authentification auprès de l’API REST, consultez Référence de l'API REST Azure.

  1. Obtenir des informations d’identification de jeton : appelez l’API List debug credentials de la passerelle Gestion des API. Dans l’URI, entrez « managed » pour la passerelle managée de l’instance dans le cloud ou l’ID de passerelle pour une passerelle auto-hébergée. Par exemple, pour obtenir les informations d’identification de trace de la passerelle managée de l'instance, utilisez une requête semblable à ce qui suit :

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

    Dans le corps de la requête, passez l’ID de ressource complet de l’API dont vous souhaitez effectuer le traçage, puis spécifiez purposes en tant que tracing. Par défaut, les informations d’identification de jeton retournées dans la réponse expirent au bout d’une heure, mais vous pouvez spécifier une autre valeur dans la charge utile. Par exemple :

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

    Les informations d’identification du jeton sont retournées dans la réponse, de manière similaire à ce qui suit :

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

  2. Ajouter la valeur du jeton dans un en-tête de demande : pour activer le traçage d’une requête adressée à la passerelle du service Gestion des API, envoyez la valeur du jeton dans un en-tête Apim-Debug-Authorization. Par exemple, pour suivre un appel à l’API Petstore que vous avez importée dans un précédent didacticiel, vous pouvez utiliser une requête semblable à ce qui suit :

    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. Selon le jeton, la réponse contient l’un des en-têtes suivants :

    • Si le jeton est valide, la réponse comprend un en-tête Apim-Trace-Id dont la valeur est l’ID de trace, comme suit :

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

    • Si le jeton a expiré, la réponse comprend un en-tête Apim-Debug-Authorization-Expired avec des informations sur la date d’expiration.

    • Si le jeton a été obtenu pour une autre API, la réponse comprend un en-tête Apim-Debug-Authorization-WrongAPI avec un message d’erreur.

  4. Récupérer la trace : passez l’ID de trace obtenu à l’étape précédente à l’API List trace de la passerelle. Par exemple, pour récupérer la trace de la passerelle managée, utilisez une requête semblable à ce qui suit :

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

    Dans le corps de la requête, passez l’ID de trace obtenu à l’étape précédente.

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

    Le corps de la réponse contient les données de trace de la requête d’API précédente envoyée à la passerelle. La trace est similaire à celle que vous pouvez consulter en traçant un appel dans la console de test du portail.

Pour plus d’informations sur la personnalisation des informations de suivi, consultez la stratégie trace.

Étapes suivantes

Dans ce didacticiel, vous avez appris à :

  • Tracer un exemple d’appel dans la console de test
  • Passer en revue les étapes du traitement des demandes
  • Activer le traçage pour une API

Passez au tutoriel suivant :

Utiliser des révisions