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

Artikel
02/25/2025

VAN TOEPASSING OP: Alle API Management-lagen

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.

Tip

API-teams kunnen deze functie gebruiken in werkruimten. Werkruimten bieden geïsoleerde beheerderstoegang tot API's en hun eigen API-runtimeomgevingen.

In deze zelfstudie leert u het volgende:

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

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

API Management ondersteunt geen abonnementen meer voor tracering of de Ocp-Apim-Trace-header .
Om de API-beveiliging te verbeteren, kan tracering nu worden 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 Tracering van een API inschakelen 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

Volg deze stappen om een API-aanvraag te traceren in de testconsole in de portal. In dit voorbeeld wordt ervan uitgegaan dat u in een vorige zelfstudie een voorbeeld-API hebt geïmporteerd . U kunt vergelijkbare stappen volgen met een andere API die u hebt geïmporteerd.

Meld u aan bij Azure Portal en ga naar uw API Management-exemplaar.
API's >selecteren.
Selecteer Petstore-API in uw API-lijst.
Selecteer het tabblad Testen.
Selecteer de bewerking Huisdier zoeken op id .
Voer 1 in de parameter petId-queryin.
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

De volgende stappen op hoog niveau zijn vereist om tracering in te schakelen voor een aanvraag naar API Management wanneer u curleen REST-client gebruikt, zoals Visual Studio Code met de REST-clientextensie of een client-app. Deze stappen moeten momenteel worden gevolgd met behulp van de API Management REST API:

Haal een token voor foutopsporing op voor tracering.
Voeg de tokenwaarde in een Apim-Debug-Authorization aanvraagheader toe aan de API Management-gateway.
Haal een tracerings-id op in de Apim-Trace-Id antwoordheader.
Haal de tracering op die overeenkomt met de tracerings-id.

Gedetailleerde stappen volgen.

Notitie

Voor deze 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.
Zie azure REST API-naslaginformatie voor meer informatie over verificatie bij de REST API.

Haal een foutopsporingstoken op: roep de api voor foutopsporingsreferenties van de API van de API Management-gateway aan. Voer in de URI 'beheerd' in voor de beheerde gateway van het exemplaar in de cloud of de gateway-id voor een zelf-hostende gateway. Als u bijvoorbeeld traceringsreferenties wilt verkrijgen voor de beheerde gateway van het exemplaar, gebruikt u een aanvraag 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. Bijvoorbeeld:
```
{
    "credentialsExpireAfter": PT1H,
    "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
Notitie

De apiId id kan alleen worden opgehaald uit de volledige resource-id, niet de naam die wordt weergegeven in de portal.

ApiId ophalen:
```
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
```
De referentie voor foutopsporing wordt geretourneerd in het antwoord, vergelijkbaar met het volgende:
```
{
      "token": "aid=api-name&......."
}
```
Voeg de tokenwaarde toe in een aanvraagheader : 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 wilt traceren naar de Petstore-API die u in een vorige zelfstudie hebt geïmporteerd, kunt u een aanvraag gebruiken die vergelijkbaar is met de volgende:
```
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&......."
```
Evalueer het antwoord: het antwoord kan een van de volgende headers bevatten, afhankelijk van de status van het token voor foutopsporing:
- Als het token voor foutopsporing geldig is, bevat het antwoord een Apim-Trace-Id header waarvan de waarde de tracerings-id is, vergelijkbaar met de volgende:
```
Apim-Trace-Id: 0123456789abcdef....
```
- Als het token voor foutopsporing is verlopen, bevat het antwoord een Apim-Debug-Authorization-Expired header met informatie over de vervaldatum.
- Als het token voor foutopsporing is verkregen voor een andere API, bevat het antwoord een Apim-Debug-Authorization-WrongAPI header met een foutbericht.
Haal de tracering op: geef de tracerings-id die u in de vorige stap hebt verkregen door aan de api voor lijsttracering van de gateway. Als u bijvoorbeeld de tracering voor de beheerde gateway wilt ophalen, gebruikt u een aanvraag 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": "0123456789abcdef...."
}
```
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.

Voorbeeldbestand `.http` voor VS Code REST Client-extensie

Als u deze stappen wilt automatiseren met de Visual Studio Code REST-clientextensie , kunt u het volgende voorbeeldbestand .http gebruiken:

@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
 
POST https://login.microsoftonline.com/{{tenandId}}/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
curl -k -H "Apim-Debug-Authorization: {{debugToken}}" -H 'Host: {{externalHost}}' -H 'Ocp-Apim-Subscription-Key: {{subscriptionKey}}' -H 'Content-Type: application/json' '{{apiEndPoint}}' -d '{{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}}"
}

Zie het traceringsbeleid voor informatie over het aanpassen van traceringsinformatie .

Volgende stappen

In deze zelfstudie heeft u het volgende geleerd:

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

Ga door naar de volgende zelfstudie:

Revisies gebruiken

Delen via

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

Vereisten

Een oproep traceren in de portal

Traceringsgegevens controleren

Tracering inschakelen voor een API

Voorbeeldbestand `.http` voor VS Code REST Client-extensie

Volgende stappen

Feedback

Aanvullende resources

Delen via

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

Vereisten

Een oproep traceren in de portal

Traceringsgegevens controleren

Tracering inschakelen voor een API

Voorbeeldbestand .http voor VS Code REST Client-extensie

Volgende stappen

Feedback

Aanvullende resources

Voorbeeldbestand `.http` voor VS Code REST Client-extensie