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

Article
05/10/2024

S’APPLIQUE À : Consommation | Développeur | Essentiel | Standard | Premium

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

Remarque

Pour le moment, le traçage des requêtes d’API n’est pas pris en charge dans les niveaux Essentiel v2 et Standard v2.

Prérequis

Apprenez la terminologie relative à Gestion des API Azure.
Suivez le guide de démarrage rapide suivant : Créer une instance du service Gestion des API Azure.
Effectuez toutes les étapes du tutoriel suivant : Importer et publier votre première API.

Important

Le traçage des requêtes du service Gestion des API en utilisant l’en-tête Ocp-Apim-Trace dans une requête et en utilisant la valeur de l’en-tête de réponse Ocp-Apim-Trace-Location est déconseillé.
Pour améliorer la sécurité, 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

Connectez-vous au portail Azure et accédez à votre instance de Gestion des API.
Sélectionnez API.
Sélectionnez Demo Conference API dans votre liste d’API.
Sélectionnez l’onglet Test.
Sélectionnez l’opération GetSpeakers.
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é.
Sélectionnez Trace.

Examiner les informations de suivi

Une fois l’appel terminé, accédez à l’onglet Trace dans la réponse HTTP.
Sélectionnez les liens suivants pour accéder aux informations de suivi détaillées : Entrant, Principal, Sortant, En cas d’erreur.
- 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

Vous pouvez activer le traçage d’une API quand vous envoyez des requêtes 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.

Activez le traçage en suivant les étapes ci-dessous, et en effectuant des appels à l’API REST du service Gestion des API.

Remarque

Les étapes suivantes nécessitent l’API REST du service 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.

Obtenez les informations d’identification de trace en appelant l’API qui permet de lister les informations d’identification de débogage. Passez l’ID de passerelle dans l’URI, ou utilisez « managed » pour la passerelle managée de l’instance dans le cloud. Par exemple, pour obtenir les informations d’identification de trace de la passerelle managée, utilisez un appel 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.
```
{
    "credentialsExpireAfter": PT1H,
    "apiId": "<API resource ID>",
    "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&p=tracing&ex=......."
}
```
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 tracer un appel à l’API de conférence de démonstration, utilisez un appel semblable à ce qui suit :
```
curl -v GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&p=tracing&ex=......."
```
Selon le jeton, la réponse contient différents en-têtes :
- Si le jeton est valide, la réponse comprend un en-tête Apim-Trace-Id dont la valeur est l’ID de trace.
- 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 API incorrecte, la réponse comprend un en-tête Apim-Debug-Authorization-WrongAPI avec un message d’erreur.
Pour récupérer la trace, passez l’ID de trace obtenu à l’étape précédente à l’API permettant de lister les traces de la passerelle. Par exemple, pour récupérer la trace de la passerelle managée, utilisez un appel 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": "<trace ID>"
}
```
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 à :

Suivre un exemple d’appel
Passer en revue les étapes du traitement des demandes
Activer le traçage pour une API

Passez au tutoriel suivant :

Utiliser des révisions

Partager via