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

Platí pro: Všechny úrovně API Management

Tento kurz popisuje, jak zkontrolovat nebo sledovat zpracování požadavků v Azure API Management. Trasování pomáhá s debugováním a odstraňováním potíží s rozhraním API.

Poznámka:

V současné době tato funkce není dostupná v pracovních prostorech.

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.
  • Kvůli zlepšení zabezpečení rozhraní API je teď možné trasování povolit na úrovni jednotlivých rozhraní API. Získejte token s časovým omezením pomocí rozhraní API MANAGEMENT REST API a předejte token v požadavku na bránu. Podrobnosti najdete v tématu Povolení trasování rozhraní API.
  • Při povolování sledování buďte obezřetní. Může zveřejnit citlivé informace v datech trasování. Ujistěte se, že máte k ochraně dat trasování zavedená vhodná bezpečnostní opatření.

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

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 portálu Azure 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 načtením klíče pro jiné předplatné na portálu Azure. 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ě.

    Snímek obrazovky zobrazující trasování odpovědi recenze

    • Příchozí. Zobrazuje původní požadavek API Management přijatý od volajícího a zásady použité na žádost. Pokud jste například přidali zásady v kurzu: Transformace a ochrana rozhraní API, zobrazí se tady.
    • Backend Zobrazuje požadavky 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 během zpracování požadavku, a zásady použité na chyby.

    Návod

    Každý krok také zobrazuje uplynulý čas od API Management obdrží požadavek.

Povolení trasování pro rozhraní API

Následující základní kroky jsou potřeba 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 KLIENTA REST nebo klientskou aplikací. V současné době je potřeba postupovat podle těchto kroků pomocí rozhraní API Management REST API:

  1. Získejte ladicí token pro trasování.
  2. Do brány API Management přidejte hodnotu tokenu v hlavičce požadavku Apim-Debug-Authorization.
  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í REST API verze API Management 2023-05-01-preview nebo novější.
  • Abyste mohli získat debug token, musíte mít v instanci služby API Management přiřazenou roli Přispěvatel nebo vyšší, nebo mít ekvivalentní oprávnění k zápisu.
  • Informace o ověřování v rozhraní REST API najdete v referenčních informacích k rozhraní REST API Azure.

  1. Získejte token ladění. Zavolejte API List debug credentials u brány API Management. V identifikátoru URI zadejte 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, můžete použít požadavek jako v následujícím příkladu:

    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. 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ě. V datové části můžete zadat jinou hodnotu. 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:

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

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

  2. Přidejte hodnotu tokenu do hlavičky požadavku. Pokud chcete povolit trasování požadavku na bránu API Management, odešlete hodnotu tokenu v hlavičce Apim-Debug-Authorization. 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ý následujícímu příkladu:

    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. Vyhodnoťte odpověď. Odpověď může obsahovat jednu z následujících hlaviček v závislosti na stavu tokenu ladění:

    Hlavička v odpovědi Explanation
    Apim-Trace-Id Platnost tokenu ladění je potvrzena. Hodnota je ID trasování, například: Apim-Trace-Id: 0123456789abcdef....
    Apim-Debug-Authorization-Expired Platnost tokenu vypršela. Záhlaví obsahuje informace o datu vypršení platnosti.
    Apim-Debug-Authorization-WrongAPI Token získaný pro jiné rozhraní API Záhlaví obsahuje chybovou zprávu.

  4. Načtěte trasování. Předejte ID sledování získané v předchozím kroku do rozhraní API brány Seznam sledování. Pokud například chcete načíst trasování pro spravovanou bránu, použijte požadavek podobný následujícímu příkladu:

    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.

Příklad souboru HTTP pro rozšíření VS Code REST Client

Pokud chcete tento postup automatizovat pomocí rozšíření Visual Studio Code REST Client, můžete použít následující příklad souboru .http:

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

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

Shrnutí

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

Další krok

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

Použití revizí

  • Last updated on