Kurz: Ladění rozhraní API pomocí trasování požadavků

Článek
02/25/2025

PLATÍ PRO: Všechny úrovně služby API Management

Tento kurz popisuje, jak ve službě Azure API Management kontrolovat (trasování) zpracování požadavků. Trasování pomáhá ladit a řešit potíže s rozhraním API.

Tip

Týmy rozhraní API můžou tuto funkci používat v pracovních prostorech. Pracovní prostory poskytují izolovaný přístup pro správu k rozhraním API a vlastním prostředím runtime rozhraní API.

V tomto kurzu se naučíte:

Trasování ukázkového volání v testovací konzole
Kontrola kroků zpracování požadavků
Povolení trasování pro rozhraní API

Požadavky

Seznamte se s terminologií služby Azure API Management.
Projděte si následující rychlý start: Vytvoření instance Azure API Managementu.
Dokončete následující kurz: Import a publikování prvního rozhraní API.

Důležité

Api Management už nepodporuje předplatná pro trasování nebo hlavičku Ocp-Apim-Trace .
Pokud chcete zlepšit zabezpečení rozhraní API, můžete teď trasování povolit na úrovni jednotlivých rozhraní API získáním časově omezeného tokenu pomocí rozhraní REST API služby API Management a předáním tokenu v požadavku na bránu. Podrobnosti najdete v tématu Povolení trasování rozhraní API.
Při povolování trasování je potřeba dbát na to, jak může v datech trasování vystavit citlivé informace. Ujistěte se, že máte k ochraně dat trasování zavedená vhodná bezpečnostní opatření.

Trasování volání na portálu

Pomocí těchto kroků trasujte požadavek rozhraní API v testovací konzole na portálu. Tento příklad předpokládá, že jste naimportovali ukázkové rozhraní API v předchozím kurzu. Podobným postupem můžete použít jiné rozhraní API, které jste naimportovali.

Přihlaste se k webu Azure Portal a přejděte k vaší instanci služby API Management.
Vyberte rozhraní API>.
Ze seznamu rozhraní API vyberte rozhraní API Petstore.
Vyberte kartu Test.
Vyberte operaci Najít domácího mazlíčka podle ID.
Do parametru dotazu petId zadejte 1.
Volitelně můžete zkontrolovat hodnotu hlavičky Ocp-Apim-Subscription-Key použité v požadavku výběrem ikony oka.

Tip

Hodnotu Ocp-Apim-Subscription-Key můžete přepsat načtením klíče pro jiné předplatné na portálu. Vyberte Předplatná a otevřete místní nabídku (...) pro jiné předplatné. Vyberte Zobrazit nebo skrýt klíče a zkopírujte jeden z těchto klíčů. V případě potřeby můžete klíče znovu vygenerovat. Potom v testovací konzole vyberte + Přidat hlavičku a přidejte hlavičku Ocp-Apim-Subscription-Key s novou hodnotou klíče.
Vyberte Trasování.

Kontrola informací o trasování

Po dokončení volání přejděte v odpovědi HTTP na kartu Trasování.
Pokud chcete přejít na podrobné informace o trasování, vyberte některý z následujících odkazů: Příchozí, Back-end, Odchozí, Při chybě.
- Příchozí – zobrazuje původní požadavek služby API Management přijatý od volajícího a zásady použité na požadavek. Pokud jste například přidali zásady v kurzu: Transformace a ochrana rozhraní API, zobrazí se tady.
- Back-end – zobrazuje požadavky služby API Management odeslané do back-endu rozhraní API a přijatou odpověď.
- Odchozí – zobrazuje zásady použité na odpověď před odesláním zpět volajícímu.
- Při chybě – zobrazuje chyby, ke kterým došlo při zpracování požadavku, a zásady použité na chyby.
Tip

Každý krok také ukazuje uplynulý čas od přijetí požadavku službou API Management.

Povolení trasování pro rozhraní API

Následující základní kroky jsou nutné k povolení trasování pro požadavek služby API Management při použití curl, klienta REST, jako je Visual Studio Code s rozšířením REST Client nebo klientská aplikace. V současné době je potřeba postupovat podle těchto kroků pomocí rozhraní REST API služby API Management:

Získejte ladicí token pro trasování.
Přidejte hodnotu tokenu do Apim-Debug-Authorization hlavičky požadavku do brány služby API Management.
Získejte ID trasování v Apim-Trace-Id hlavičce odpovědi.
Načtěte trasování odpovídající ID trasování.

Postupujte podle podrobných kroků.

Poznámka:

Tyto kroky vyžadují rozhraní REST API služby API management verze 2023-05-01-preview nebo novější. Abyste mohli volat rozhraní REST API, musíte mít v instanci služby API Management přiřazenou roli Přispěvatel nebo vyšší.
Informace o ověřování v rozhraní REST API najdete v referenčních informacích k rozhraní Azure REST API.

Získání ladicího tokenu – Volání rozhraní API pro výpis přihlašovacích údajů pro ladění brány SLUŽBY API Management Do identifikátoru URI zadejte "managed" pro spravovanou bránu instance v cloudu nebo ID brány pro bránu v místním prostředí. Pokud například chcete získat přihlašovací údaje trasování pro spravovanou bránu instance, použijte požadavek podobný následujícímu:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
V textu požadavku předejte úplné ID prostředku rozhraní API, které chcete trasovat, a zadejte purposes jako tracing. Ve výchozím nastavení vyprší platnost přihlašovacích údajů tokenu vrácených v odpovědi po 1 hodině, ale v datové části můžete zadat jinou hodnotu. Příklad:
```
{
    "credentialsExpireAfter": PT1H,
    "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
Poznámka:

Dá apiId se načíst pouze z úplného ID prostředku, nikoli z názvu zobrazeného na portálu.

Získat apiId:
```
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
```
V odpovědi se vrátí přihlašovací údaje ladění, podobně jako v následujícím příkladu:
```
{
      "token": "aid=api-name&......."
}
```
Přidejte hodnotu tokenu do hlavičky požadavku – pokud chcete povolit trasování požadavku do brány služby API Management, odešlete hodnotu tokenu Apim-Debug-Authorization v hlavičce. Pokud například chcete trasovat volání rozhraní API petstore, které jste naimportovali v předchozím kurzu, můžete použít požadavek podobný tomuto:
```
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&......."
```
Vyhodnocení odpovědi – Odpověď může obsahovat jednu z následujících hlaviček v závislosti na stavu tokenu ladění:
- Pokud je token ladění platný, odpověď obsahuje hlavičku Apim-Trace-Id , jejíž hodnota je ID trasování, podobně jako v následujícím příkladu:
```
Apim-Trace-Id: 0123456789abcdef....
```
- Pokud vypršela platnost tokenu ladění, odpověď obsahuje hlavičku Apim-Debug-Authorization-Expired s informacemi o datu vypršení platnosti.
- Pokud byl token ladění získán pro jiné rozhraní API, odpověď obsahuje hlavičku Apim-Debug-Authorization-WrongAPI s chybovou zprávou.
Načtení trasování – Předejte ID trasování získané v předchozím kroku do rozhraní API trasování seznamu brány. Pokud chcete například načíst trasování pro spravovanou bránu, použijte požadavek podobný následujícímu:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
```
V textu požadavku předejte ID trasování získané v předchozím kroku.
```
{
    "traceId": "0123456789abcdef...."
}
```
Tělo odpovědi obsahuje data trasování pro předchozí požadavek rozhraní API na bránu. Trasování je podobné trasování, které můžete zobrazit trasováním volání v testovací konzole portálu.

Ukázkový `.http` soubor pro rozšíření REST Client VS Code

K automatizaci těchto kroků pomocí rozšíření REST Client editoru Visual Studio Code můžete použít následující ukázkový .http soubor:

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

Informace o přizpůsobení informací o trasování najdete v zásadách trasování .

Další kroky

V tomto kurzu jste se naučili, jak:

Trasování ukázkového volání v testovací konzole
Kontrola kroků zpracování požadavků
Povolení trasování pro rozhraní API

Přejděte k dalšímu kurzu:

Použití revizí

Sdílet prostřednictvím

Kurz: Ladění rozhraní API pomocí trasování požadavků

Požadavky

Trasování volání na portálu

Kontrola informací o trasování

Povolení trasování pro rozhraní API

Ukázkový `.http` soubor pro rozšíření REST Client VS Code

Další kroky

Váš názor

Další materiály

Sdílet prostřednictvím

Kurz: Ladění rozhraní API pomocí trasování požadavků

Požadavky

Trasování volání na portálu

Kontrola informací o trasování

Povolení trasování pro rozhraní API

Ukázkový .http soubor pro rozšíření REST Client VS Code

Další kroky

Váš názor

Další materiály

Ukázkový `.http` soubor pro rozšíření REST Client VS Code