Sdílet prostřednictvím

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

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á s debugováním a odstraňováním potíží s rozhraním API.

Návod

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

V tomto kurzu se naučíte:

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

Snímek obrazovky znázorňující inspektor rozhraní API

Požadavky

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í buďte opatrní, protože v datech trasování mohou být odhaleny citlivé informace. Ujistěte se, že máte k ochraně dat trasování zavedená vhodná bezpečnostní opatření.

Sledování hovoru v 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.

  1. Přihlaste se k webu Azure Portal a přejděte k vaší instanci služby API Management.

  2. Vyberte rozhraní API>rozhraní API.

  3. Ze seznamu rozhraní API vyberte Petstore API.

  4. Vyberte kartu Test.

  5. Vyberte operaci Najít domácího mazlíčka podle ID.

  6. Do parametru dotazu petId zadejte 1.

  7. Volitelně můžete zkontrolovat hodnotu hlavičky Ocp-Apim-Subscription-Key použité v požadavku výběrem ikony oka.

    Návod

    Hodnotu Ocp-Apim-Subscription-Key můžete přepsat tím, že na portálu získáte klíč pro jiné předplatné. 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.

  8. Vyberte Trasování.

Kontrola informací o trasování

  1. Po dokončení volání přejděte na kartu Trasování v odpovědi HTTP.

  2. Pokud chcete přejít na podrobné informace o trasování, vyberte některý z následujících odkazů: Příchozí, Backend, Odchozí, Při chybě.

    Revize sledování odpovědí

    • 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í – ukazuje zásady, které byly uplatněny na odpověď před jejím 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.

    Návod

    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:

  1. Získejte ladicí token pro trasování.
  2. Přidejte hodnotu tokenu do Apim-Debug-Authorization hlavičky požadavku do brány služby API Management.
  3. Získejte sledovací ID v Apim-Trace-Id hlavičce odpovědi.
  4. Načtěte sledování odpovídající ID sledová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.

  1. Získání ladicího tokenu – Vyvolejte rozhraní API brány API Management s názvem List debug credentials. 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 těle 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. Všimněte si, že doba vypršení platnosti je omezená na maximálně 1 hodinu. Příklad:

    {
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}

    Poznámka:

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

    Získat ApiId:

    az apim api list --resource-group <resource-group> --service-name <service-name> -o table

    Odpověď obsahuje debugovací pověření, podobně jako v následujícím příkladu:

    {
      "token": "aid=api-name&......."
}

  2. 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&......."

  3. 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ěď zahrnuje hlavičku Apim-Trace-Id, kde se nachází sledovací ID, 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.

  4. Načtěte trasování – Předejte ID trasování získané v předchozím kroku do rozhraní API seznamu trasování 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 trasovací data pro předchozí požadavek API na bránu. Stopa je podobná té, kterou můžete vidět sledováním hovoru v testovací konzoli portálu.

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

K automatizaci těchto kroků můžete pomocí rozšíření Visual Studio Code REST Client 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/{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}}"
}

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:

  • Proveďte 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í

  • Last updated on