Zelfstudie: Fouten opsporen in uw API's met behulp van tracering van aanvragen
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 curl
een 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
alstracing
. 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: