Oktatóanyag: API-k hibakeresése kérések nyomon követésével

A KÖVETKEZŐRE VONATKOZIK: Minden API Management réteg

Ez az oktatóanyag bemutatja, hogyan vizsgálhatja meg vagy követheti nyomon a kérések feldolgozását az Azure API Management rendszerben. A nyomkövetés segít az API hibakeresésében és hibaelhárításában.

Feljegyzés

Ez a funkció jelenleg nem érhető el a munkaterületeken.

Ebben az oktatóanyagban az alábbiakkal fog megismerkedni:

Példahívás nyomon követése a tesztkonzolon
Kérelemfeldolgozási lépések áttekintése
Api nyomkövetésének engedélyezése

Előfeltételek

Ismerje meg a Azure API Management terminológiát.
Végezze el a következő gyors útmutató lépéseit: Egy Azure API Management példány létrehozása.
Végezze el az alábbi oktatóanyagot: Importálja és tegye közzé az első API-t.

Fontos

API Management már nem támogatja az előfizetéseket a nyomkövetéshez vagy a Ocp-Apim-Trace fejléchez.
Az API biztonságának javítása érdekében a nyomkövetés mostantól engedélyezhető az egyes API-k szintjén. Szerezze be az időkorlátos jogkivonatot a API Management REST API használatával, és adja át a jogkivonatot egy kérésben az átjárónak. További információ: API nyomkövetésének engedélyezése.
Ügyeljen a nyomkövetés engedélyezésére. Bizalmas információkat tehet közzé a nyomkövetési adatokban. Győződjön meg arról, hogy rendelkezik a nyomkövetési adatok védelméhez szükséges biztonsági intézkedésekkel.

Hívás nyomon követése a Azure portálon

Kövesse az alábbi lépéseket egy API-kérés nyomon követéséhez a portál tesztkonzolján. Ez a példa feltételezi, hogy egy korábbi oktatóanyagban importált egy minta API-t. Hasonló lépéseket követhet egy másik, importált API-val.

Jelentkezzen be a Azure portálra, és keresse meg az API Management-példányt.
Válassza az API-kat>API-kat.
Válassza a Petstore API-t az API-listából.
Válassza a Teszt fület.
Válassza a Kisállat keresése azonosító alapján műveletet.
A petIdQuery paraméterben adja meg az 1 értéket.
Ha szeretné, ellenőrizze a kérelemben használt Ocp-Apim-Subscription-Key fejléc értékét a "szem" ikon kiválasztásával.

Tipp.

A Ocp-Apim-Subscription-Key értékét felülbírálhatja egy másik előfizetés kulcsának lekérésével a Azure portálon. Válassza az Előfizetések lehetőséget, és nyissa meg a helyi menüt (...) egy másik előfizetéshez. Válassza a Kulcsok megjelenítése/elrejtése lehetőséget, és másolja az egyik kulcsot. Szükség esetén újragenerálhatja a kulcsokat. Ezután a tesztkonzolon válassza a + Fejléc hozzáadása lehetőséget egy Ocp-Apim-Subscription-Key fejléc hozzáadásához az új kulcsértékkel.
Válassza a Nyomkövetés lehetőséget.

Nyomkövetési információk áttekintése

A hívás befejezése után lépjen a HTTP-válaszNyomkövetés lapjára.
Válassza ki az alábbi hivatkozások bármelyikét a részletes nyomkövetési információkra való ugráshoz: Bejövő, Háttér, Kimenő, Hiba esetén.
- Bejövő. Megjeleníti a hívótól kapott eredeti kérést, valamint az API Management által a kérelemre alkalmazott irányelveket. Ha például hozzád adott szabályzatokat az "Oktatóanyag: Az API átalakítása és védelme" részben, itt jelennek meg.
- Háttérrendszer. Megjeleníti az API-háttérrendszernek küldött API Management kéréseket és a kapott választ.
- Kimenő. Megjeleníti a válaszra alkalmazott szabályzatokat, mielőtt visszaküldené a hívónak.
- Hiba történt. A kérés feldolgozása során előforduló hibákat és a hibákra alkalmazott szabályzatokat jeleníti meg.
Tipp.

Minden lépés azt is megjeleníti, hogy mennyi idő telt el azóta, hogy API Management megkapja a kérést.

Api nyomkövetésének engedélyezése

A következő magas szintű lépések szükségesek az API Management felé irányuló kérések nyomon követésének engedélyezéséhez curl, REST-ügyfél, például REST-ügyfélbővítménnyel rendelkező Visual Studio Code vagy ügyfélalkalmazás használatakor. Jelenleg ezeket a lépéseket a API Management REST API:

Hibakeresési jogkivonat beszerzése nyomkövetéshez.
Adja hozzá a jogkivonat értékét egy Apim-Debug-Authorization kérelemfejléchez az API Management átjáróhoz.
Szerezze be a nyomkövetési azonosítót a Apim-Trace-Id válaszfejlécben.
Kérje le a nyomkövetést a nyomkövetési azonosító szerint.

Részletes lépések következnek.

Feljegyzés

Ezekhez a lépésekhez API Management REST API 2023-05-01-preview vagy újabb verziójára van szükség.
Önnek rendelnie kell egy közreműködői vagy annál magasabb szerepkört az API Management példányához, vagy azzal egyenértékű írási engedélyekkel kell rendelkeznie az API-n a hibakeresési jogkivonat beszerzéséhez.
A REST API-ra való hitelesítésről további információt a Azure REST API-referencia talál.

Hibakeresési token beszerzése. Hívja meg az API Management átjáró Hibakeresési hitelesítő adatok listája API-t. Az URI-ban adja meg a példány felügyelt átjárójának felügyelt átjáróját a felhőben, vagy egy saját üzemeltetésű átjáró átjáróazonosítóját. Ha például a példány felügyelt átjárójának nyomkövetési hitelesítő adatait szeretné lekérni, használjon az alábbi példához hasonló kérést.
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
A kérelem törzsében adja meg a nyomon követni kívánt API teljes erőforrás-azonosítóját. Adja meg a purposes mint tracing. Alapértelmezés szerint a válaszban visszaadott jogkivonat hitelesítő adatai 1 óra elteltével lejárnak. A hasznos adatokban megadhat egy másik értéket. A lejárati idő legfeljebb 1 óra lehet. Például:
```
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
Feljegyzés

A apiId csak a teljes erőforrás-azonosítóból lehet lekérni, az Azure portálon megjelenő névből nem.

ApiId lekérése:
```
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
```
A hibakeresési hitelesítő adatokat a rendszer a következő példához hasonlóan adja vissza a válaszban:
```
{
      "token": "aid=api-name&......."
}
```
Adja hozzá a token értékét a kérés fejlécéhez. Ha engedélyezni szeretné egy kérés nyomkövetését az API Management átjáró számára, küldje el a jogkivonat értékét egy Apim-Debug-Authorization fejlécben. Az előző oktatóanyagban importált Petstore API-ra irányuló hívás nyomon követéséhez például az alábbi példához hasonló kérést használhat:
```
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&......."
```

Értékelje ki a választ. A válasz a hibakeresési jogkivonat állapotától függően az alábbi fejlécek egyikét tartalmazhatja:

Fejléc a válaszban	Explanation
`Apim-Trace-Id`	Érvényes hibakeresési jogkivonat. Az érték a nyomkövetési azonosító, például: `Apim-Trace-Id: 0123456789abcdef....`
`Apim-Debug-Authorization-Expired`	A token lejárt. A fejléc tartalmazza a lejárati dátummal kapcsolatos információkat.
`Apim-Debug-Authorization-WrongAPI`	Egy másik API-hoz beszerzett token. A fejléc tartalmaz egy hibaüzenetet.

Kérje le a nyomkövetést. Adja át az előző lépésben beszerzett nyomkövetési azonosítót az átjáró List trace API-jának. A felügyelt átjáró nyomkövetésének lekéréséhez például használjon egy, a következő példához hasonló kérést:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
```
A kérelem törzsében adja át az előző lépésben beszerzett nyomkövetési azonosítót.
```
{
    "traceId": "0123456789abcdef...."
}
```
A válasz törzse tartalmazza az átjáróra irányuló előző API-kérés nyomkövetési adatait. A nyomkövetés hasonló ahhoz a nyomkövetéshez, amelyet egy hívás nyomon követésével láthat a portál tesztkonzolján.

Példa HTTP-fájl a VS Code REST-ügyfélkiterjesztésére

Ha szeretné automatizálni ezeket a lépéseket a Visual Studio Code REST-ügyfél kiterjesztéssel, használja az alábbi .http fájlt:

@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
@apiId = // Api Id for which trace log is to be generated.

# @name login 
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
POST {{apiEndPoint}} HTTP/1.1
Host: {{externalHost}}
Apim-Debug-Authorization: {{debugToken}}
Ocp-Apim-Subscription-Key: {{subscriptionKey}}
Content-Type: application/json

{{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}}"
}

A nyomkövetési információk testreszabásával kapcsolatos információkért tekintse meg a nyomkövetési szabályzatot.

Összefoglalás

Ez az oktatóanyag bemutatta, hogyan végezheti el az alábbi műveleteket:

Példahívás nyomon követése a tesztkonzolon
Kérelemfeldolgozási lépések áttekintése
Api nyomkövetésének engedélyezése

Következő lépés

Folytassa a következő oktatóanyaggal:

Változatok használata

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-04-18