Zelfstudie: Fouten opsporen in uw API's met behulp van tracering van aanvragen

Artikel
05/07/2024

VAN TOEPASSING OP: Verbruik | Ontwikkelaar | Basic | Standaard | Premium

In deze zelfstudie wordt beschreven hoe u de verwerking van aanvragen (traceren) controleert in Azure API Management. Tracering helpt u bij het opsporen van fouten en het oplossen van problemen met uw API.

In deze zelfstudie leert u het volgende:

Een voorbeeldaanroep traceren in de testconsole
Aanvraagverwerkingsstappen controleren
Tracering inschakelen voor een API

Notitie

Op dit moment wordt het traceren van API-aanvragen niet ondersteund in de lagen Basic v2 en Standard v2.

Vereisten

Leer de terminologie van Azure API Management.
Lees de volgende snelstartgids: Een Azure API Management-exemplaar maken.
Voltooi de volgende zelfstudie: Uw eerste API importeren en publiceren.

Belangrijk

Tracering van API Management-aanvragen kan niet meer worden ingeschakeld door de Header Ocp-Apim-Trace in een aanvraag in te stellen en de waarde van de Header Ocp-Apim-Trace-Location in het antwoord op te halen om de trace op te halen.
Om de beveiliging te verbeteren, wordt tracering nu ingeschakeld op het niveau van een afzonderlijke API door een tijdsgebonden token te verkrijgen met behulp van de API Management REST API en het token door te geven in een aanvraag aan de gateway. Zie verderop in deze zelfstudie voor meer informatie.
Zorg ervoor dat bij het inschakelen van tracering gevoelige informatie wordt weergegeven in de traceringsgegevens. Zorg ervoor dat u over de juiste beveiligingsmaatregelen beschikt om de traceringsgegevens te beveiligen.

Een oproep traceren in de portal

Meld u aan bij Azure Portal en ga naar uw API Management-exemplaar.
Selecteer API's.
Selecteer Demo Conference-API in uw lijst met API's.
Selecteer het tabblad Testen.
Selecteer de bewerking GetSpeakers.
Controleer eventueel de waarde voor de header Ocp-Apim-Subscription-Key die in de aanvraag wordt gebruikt door het pictogram 'oog' te selecteren.

Tip

U kunt de waarde van Ocp-Apim-Subscription-Key overschrijven door een sleutel voor een ander abonnement op te halen in de portal. Selecteer Abonnementen en open het contextmenu (...) voor een ander abonnement. Selecteer Sleutels weergeven/verbergen en een van de sleutels kopiëren. U kunt sleutels indien nodig ook opnieuw genereren. Selecteer vervolgens in de testconsole + Header toevoegen om een Ocp-Apim-Subscription-Key-header toe te voegen met de nieuwe sleutelwaarde.
Selecteer Traceren.

Traceringsgegevens controleren

Nadat de aanroep is voltooid, gaat u naar het tabblad Trace in het HTTP-antwoord.
Selecteer een van de volgende koppelingen om naar gedetailleerde traceringsgegevens te gaan: Binnenkomend, Back-end, Uitgaand, On-fout.
- Inkomend: Toont de oorspronkelijke aanvraag die API Management van de aanroepende functie heeft ontvangen en de beleidsregels die op de aanvraag worden toegepast. Als u bijvoorbeeld beleidsregels hebt toegevoegd in de zelfstudie: Uw API transformeren en beveiligen, worden deze hier weergegeven.
- Back-end: Toont de aanvragen die API Management naar de API-back-end heeft verzonden en het antwoord daarop.
- Uitgaand: Toont de beleidsregels die op het antwoord worden toegepast voordat het naar de aanroepende functie wordt teruggestuurd.
- Bij fout : toont de fouten die zijn opgetreden tijdens de verwerking van de aanvraag en het beleid dat op de fouten is toegepast.
Tip

Bij elke stap wordt ook de verstreken tijd weergegeven vanaf dat de aanvraag is ontvangen door de API Management.

Tracering inschakelen voor een API

U kunt tracering inschakelen voor een API bij het indienen van aanvragen bij API Management met behulp van curleen REST-client, zoals Visual Studio Code met de REST-clientextensie of een client-app.

Schakel tracering in door de volgende stappen uit te voeren met behulp van aanroepen naar de REST API van API Management.

Notitie

Voor de volgende stappen is REST API-versie 2023-05-01-preview of hoger van API Management vereist. U moet de rol Inzender of hoger hebben toegewezen aan het API Management-exemplaar om de REST API aan te roepen.

Haal traceringsreferenties op door de API voor foutopsporingsreferenties voor lijst aan te roepen. Geef de gateway-id door in de URI of gebruik 'beheerd' voor de beheerde gateway van het exemplaar in de cloud. Als u bijvoorbeeld traceringsreferenties voor de beheerde gateway wilt verkrijgen, gebruikt u een aanroep die vergelijkbaar is met de volgende:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
Geef in de aanvraagbody de volledige resource-id van de API door die u wilt traceren en geef deze op purposes als tracing. Standaard verloopt de tokenreferentie die in het antwoord wordt geretourneerd na 1 uur, maar u kunt een andere waarde opgeven in de nettolading.
```
{
    "credentialsExpireAfter": PT1H,
    "apiId": "<API resource ID>",
    "purposes: ["tracing"]
}
```
De tokenreferentie wordt geretourneerd in het antwoord, vergelijkbaar met het volgende:
```
{
      "token": "aid=api-name&p=tracing&ex=......."
}
```
Als u tracering voor een aanvraag naar de API Management-gateway wilt inschakelen, verzendt u de tokenwaarde in een Apim-Debug-Authorization header. Als u bijvoorbeeld een aanroep naar de demovergadering-API wilt traceren, gebruikt u een aanroep die vergelijkbaar is met de volgende:
```
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=......."
```
Afhankelijk van het token bevat het antwoord verschillende headers:
- Als het token geldig is, bevat het antwoord een Apim-Trace-Id header waarvan de waarde de tracerings-id is.
- Als het token is verlopen, bevat het antwoord een Apim-Debug-Authorization-Expired header met informatie over de vervaldatum.
- Als het token is verkregen voor een verkeerde API, bevat het antwoord een Apim-Debug-Authorization-WrongAPI header met een foutbericht.
Als u de tracering wilt ophalen, geeft u de tracerings-id die u in de vorige stap hebt verkregen door aan de API voor de lijsttracering voor de gateway. Als u bijvoorbeeld de tracering voor de beheerde gateway wilt ophalen, gebruikt u een aanroep die vergelijkbaar is met de volgende:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
```
Geef in de aanvraagbody de tracerings-id door die in de vorige stap is verkregen.
```
{
    "traceId": "<trace ID>"
}
```
De hoofdtekst van het antwoord bevat de traceringsgegevens voor de vorige API-aanvraag naar de gateway. De tracering is vergelijkbaar met de tracering die u kunt zien door een aanroep te traceren in de testconsole van de portal.

Zie het traceringsbeleid voor informatie over het aanpassen van traceringsinformatie .

Volgende stappen

In deze zelfstudie heeft u het volgende geleerd:

Een voorbeeld van een aanroep traceren
Aanvraagverwerkingsstappen controleren
Tracering inschakelen voor een API

Ga door naar de volgende zelfstudie:

Revisies gebruiken