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

A KÖVETKEZŐKRE VONATKOZIK: Minden API-kezelési szint

Ez az oktatóanyag bemutatja, hogyan vizsgálhatja meg (nyomon) a kérelmek feldolgozását az Azure API Managementben. A nyomkövetés segít az API hibakeresésében és hibaelhárításában.

Tipp.

Az API-csapatok használhatják ezt a funkciót a munkaterületeken. A munkaterületek elkülönített rendszergazdai hozzáférést biztosítanak az API-khoz és saját API-futtatókörnyezetükhöz.

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 az Azure API Management terminológiát.
Végezze el a következő rövid útmutatót: 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

Az API Management már nem támogatja a nyomkövetési előfizetéseket vagy az Ocp-Apim-Trace fejlécet.
Az API biztonságának javítása érdekében a nyomkövetés mostantól engedélyezhető az egyes API-k szintjén egy korlátozott idejű jogkivonat beszerzésével az API Management REST API használatával, és a jogkivonat átadásával 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, mivel 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 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 az Azure Portalra, é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.

Az Ocp-Apim-Subscription-Key értékét felülbírálhatja egy másik előfizetés kulcsának beolvasásával a 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 adatok megtekintéséhez: Bejövő, Háttér, Kimenő, Hiba esetén.
- Bejövő – Megjeleníti a hívótól kapott eredeti KÉRÉS API Managementet és a kérelemre alkalmazott szabályzatokat. 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érelmeket és a kapott választ.
- Kimenő – Megmutatja a válaszon alkalmazott szabályzatokat, mielőtt azt visszaküldik a hívónak.
- Hiba esetén – A kérés feldolgozása során előforduló hibákat és a hibákra alkalmazott szabályzatokat jeleníti meg.
Tipp.

Az egyes lépések a hívás az API Management által való fogadása óta eltelt időt is mutatják.

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

A következő magas szintű lépések szükségesek ahhoz, hogy engedélyezhető legyen egy kérés nyomkövetése az API Management számára a curl, a REST-ügyfél, például a Visual Studio Code REST Client bővítménnyel vagy egy ügyfélalkalmazás használatakor. Jelenleg ezeket a lépéseket kell követni az API Management REST API használatával:

Hibakeresési jogkivonat beszerzése nyomkövetéshez.
Adja hozzá a token értékét egy Apim-Debug-Authorization kérés fejlécébe 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 az API Management REST API 2023-05-01-preview vagy újabb verziója szükséges. Az API Management-példányban Közreműködő vagy magasabb szintű szerepkörrel kell rendelkeznie a REST API meghívásához.
A REST API-ra való hitelesítésről további információt az Azure REST API-referenciában talál.

Hibakeresési jogkivonat beszerzése – Hívja meg az API Management átjáró List debug credentials API-ját. Az URI-ban adja meg a "felügyelt" értéket a példány felügyelt átjárója számára 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é megszerezni, alkalmazzon az alábbihoz 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, és adja meg purposes mint tracing. A válaszban visszaadott jogkivonat alapértelmezés szerint 1 óra elteltével lejár, de az üzenetben megadhat egy másik értéket. Vegye figyelembe, hogy a lejárati idő legfeljebb 1 órára korlátozódik. Például:
```
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
Feljegyzés

Ez apiId csak a teljes erőforrás-azonosítóból húzható le, a portálon megjelenített 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őhöz hasonlóan adja vissza a válaszban:
```
{
      "token": "aid=api-name&......."
}
```
Adja hozzá a jogkivonat értékét egy kérelemfejléchez – Ha engedélyezni szeretné egy kérés nyomkövetését az API Management-átjárón, küldje el a jogkivonat értékét egy Apim-Debug-Authorization fejlécben. Egy korábbi oktatóanyagban importált Petstore API-hívás nyomon követéséhez például az alábbihoz 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&......."
```
A válasz kiértékelése – A válasz a hibakeresési jogkivonat állapotától függően az alábbi fejlécek egyikét tartalmazhatja:
- Ha a hibakeresési jogkivonat érvényes, a válasz tartalmaz egy Apim-Trace-Id fejlécet, amelynek értéke a nyomkövetési azonosító, hasonlóan az alábbiakhoz:
```
Apim-Trace-Id: 0123456789abcdef....
```
- Ha a hibakeresési jogkivonat lejárt, a válasz tartalmaz egy Apim-Debug-Authorization-Expired fejlécet, amely tartalmazza a lejárati dátummal kapcsolatos információkat.
- Ha a hibakeresési jogkivonatot egy másik API-hoz szerezték be, a válasz tartalmaz egy Apim-Debug-Authorization-WrongAPI hibaüzenetet tartalmazó fejlécet.
A nyomkövetés lekérése – 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 az alábbihoz 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éldafájl `.http` a VS Code REST-ügyfélbővítményéhez

A Lépések a Visual Studio Code REST-ügyfélbővítménnyel való automatizálásához a következő példafájlt .http használhatja:

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

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

Következő lépések

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

Folytassa a következő oktatóanyaggal:

Változatok használata

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-04-24