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

2025-02-25

VAN TOEPASSING OP: Alle API Management niveaus

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.

Advies

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.
Voltooi de volgende snelstart: 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 u voorzichtig bent bij het inschakelen van tracering, omdat dit gevoelige informatie in de traceringsgegevens kan blootleggen. 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.
Selecteer API's>API's.
Selecteer Petstore-API in uw API-lijst.
Selecteer het tabblad Testen.
Selecteer de bewerking Huisdier zoeken op id .
Voer in de petId-queryparameter1 in.
Controleer eventueel de waarde voor de header Ocp-Apim-Subscription-Key die in de aanvraag wordt gebruikt door het pictogram 'oog' te selecteren.

Advies

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. Ga dan in de testconsole naar + 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 oproeper verzonden wordt.
- Bij fout : toont de fouten die zijn opgetreden tijdens de verwerking van de aanvraag en het beleid dat op de fouten is toegepast.
Advies

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 trace-ID op in de Apim-Trace-Id responseheader.
Haal de trace op die overeenkomt met de trace-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 Medewerker of hoger hebben toegewezen aan de API Management-instantie om de REST API aan te roepen.
Zie de Azure REST API-referentie voor meer informatie over authenticatie bij de REST API.

Verkrijg een foutopsporingstoken - Roep de API Management-gateway's API voor het lijst debug-gegevens aan. Voer in de URI 'beheerd' in voor de beheerde gateway van het exemplaar in de cloud of de gateway-id voor een zelfgehoste gateway. Als u bijvoorbeeld traceerreferenties wilt verkrijgen voor de beheerde gateway van het exemplaar, gebruikt u een verzoek dat vergelijkbaar is met het volgende:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
In het aanvraaglichaam geeft u de volledige resource-id van de API door die u wilt traceren en specificeert u 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. Houd er rekening mee dat de verlooptijd is beperkt tot maximaal 1 uur. 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 trace op - Geef de tracerings-id die u in de vorige stap hebt verkregen door aan de List trace API 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 sporen zijn vergelijkbaar met de sporen die u kunt zien wanneer u een oproep volgt in de testconsole van het portaal.

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/{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
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 tutorial.

Revisies gebruiken

Delen via