Samouczek: debugowanie interfejsów API przy użyciu śledzenia żądań

2025-04-18

DOTYCZY: Wszystkie warstwy usługi API Management

W tym samouczku opisano sposób inspekcji (śledzenia) przetwarzania żądań w usłudze Azure API Management. Śledzenie ułatwia debugowanie i rozwiązywanie problemów z API.

Napiwek

Zespoły interfejsów API mogą używać tej funkcji w obszarach roboczych. Obszary robocze zapewniają izolowany dostęp administracyjny do interfejsów API i własne środowiska uruchomieniowe API.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

Śledzenie przykładowego wywołania w konsoli testowej
Przeglądanie kroków przetwarzania żądań
Włącz śledzenie dla interfejsu API

Wymagania wstępne

Poznaj terminologię dotyczącą usługi Azure API Management.
Wykonaj procedury przedstawione w następującym szybkim przewodniku: Tworzenie wystąpienia usługi Azure API Management.
Wykonaj czynności opisane w poniższym samouczku: Importowanie i publikowanie pierwszego interfejsu API.

Ważne

Usługa API Management nie obsługuje już subskrypcji do śledzenia ani nagłówka Ocp-Apim-Trace .
Aby poprawić bezpieczeństwo interfejsu API, śledzenie można teraz włączyć na poziomie pojedynczego interfejsu API, pobierając czasowo ograniczony token za pomocą API Management REST API i przekazując token w żądaniu do bramy. Aby uzyskać szczegółowe informacje, zobacz Włączanie śledzenia interfejsu API.
Należy zachować ostrożność podczas włączania śledzenia, ponieważ może uwidaczniać poufne informacje w danych śledzenia. Upewnij się, że masz odpowiednie środki bezpieczeństwa, aby chronić dane śledzenia.

Śledzić połączenie w portalu

Wykonaj następujące kroki, aby śledzić żądanie interfejsu API w konsoli testowej w portalu. W tym przykładzie przyjęto założenie, że zaimportowaliśmy przykładowy interfejs API w poprzednim samouczku. Możesz wykonać podobne kroki przy użyciu innego zaimportowanego interfejsu API.

Zaloguj się do witryny Azure Portal i przejdź do wystąpienia usługi API Management.
Wybierz Interfejsy API>API.
Wybierz Petstore API z listy swoich interfejsów API.
Wybierz kartę Test.
Wybierz operację Znajdź zwierzę według identyfikatora .
W parametrze petIdQuery wprowadź 1.
Opcjonalnie sprawdź wartość nagłówka Ocp-Apim-Subscription-Key używanego w żądaniu, wybierając ikonę w kształcie oka.

Napiwek

Możesz zastąpić wartość Ocp-Apim-Subscription-Key , pobierając klucz dla innej subskrypcji w portalu. Wybierz pozycję Subskrypcje i otwórz menu kontekstowe (...) dla innej subskrypcji. Wybierz pozycję Pokaż/ukryj klucze i skopiuj jeden z kluczy. W razie potrzeby można również ponownie wygenerować klucze. Następnie w konsoli testowej wybierz + Dodaj nagłówek, aby dodać nagłówek Ocp-Apim-Subscription-Key z nową wartością klucza.
Wybierz Ślad.

Przeglądanie informacji śledzenia

Po zakończeniu wywołania przejdź do karty Śledzenie w odpowiedzi HTTP.
Wybierz dowolne z poniższych linków, aby przejść do szczegółowych informacji o śledzeniu: przychodzące, zaplecze, wychodzące, przy błędzie.
- Przychodzące — pokazuje oryginalne żądanie usługi API Management odebrane od obiektu wywołującego i zasady zastosowane do żądania. Jeśli na przykład dodano zasady w artykule Samouczek: przekształcanie i ochrona interfejsu API, są one wyświetlane tutaj.
- Zaplecze — pokazuje żądania usługi API Management wysłane do zaplecza interfejsu API i odebraną odpowiedź.
- Wychodzący — pokazuje zasady zastosowane do odpowiedzi przed wysłaniem jej z powrotem do wywołującego.
- Po błędzie — pokazuje błędy, które wystąpiły podczas przetwarzania żądania i zasady zastosowane do błędów.
Napiwek

Przy każdym kroku widać również czas, jaki upłynął od odebrania żądania przez usługę API Management.

Włącz śledzenie dla interfejsu API

Następujące ogólne kroki są wymagane do włączenia śledzenia żądania do usługi API Management w przypadku korzystania z curlklienta REST, takiego jak program Visual Studio Code z rozszerzeniem klienta REST lub aplikacji klienckiej. Obecnie należy wykonać następujące kroki przy użyciu interfejsu API REST usługi API Management:

Uzyskaj token debugowania do śledzenia.
Dodaj wartość tokenu w nagłówku żądania Apim-Debug-Authorization do bramy zarządzania API.
Pobierz identyfikator śledzenia z nagłówka odpowiedzi Apim-Trace-Id.
Pobierz ślad odpowiadający identyfikatorowi śledzenia.

Szczegółowe kroki są przedstawione poniżej.

Uwaga

Kroki te wymagają użycia wersji 2023-05-01-preview lub nowszej interfejsu API REST usługi zarządzania API. Aby wywołać interfejs API REST w wystąpieniu zarządzania API, musisz mieć przypisaną rolę Współautor lub wyższą.
Aby uzyskać informacje na temat uwierzytelniania w interfejsie API REST, zobacz Dokumentacja interfejsu API REST platformy Azure.

Uzyskaj token debugowania – Wywołaj interfejs API „List debug credentials” bramy zarządzania API. W identyfikatorze URI, wprowadź "managed" dla zarządzanej bramy w chmurze lub identyfikator bramy dla własnej, samoobsługowej bramy. Aby na przykład uzyskać dane uwierzytelniające do śledzenia dla zarządzanej bramy wystąpienia, użyj żądania podobnego do tego:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
W treści żądania przekaż pełny identyfikator API zasobu, który chcesz monitorować, i określ purposes jako tracing. Domyślnie poświadczenie tokenu zwrócone w odpowiedzi wygasa po 1 godzinie, ale można określić inną wartość w ładunku. Należy pamiętać, że czas wygaśnięcia jest ograniczony do maksymalnie 1 godziny. Na przykład:
```
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
Uwaga

Element apiId można uzyskać tylko z pełnego identyfikatora zasobu, a nie z nazwy wyświetlanej w portalu.

Pobierz identyfikator apiId:
```
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
```
Poświadczenie debugowania jest zwracane w odpowiedzi, tak jak poniżej:
```
{
      "token": "aid=api-name&......."
}
```
Dodaj wartość tokenu w nagłówku żądania — aby włączyć śledzenie żądania do bramy usługi API Management, wyślij wartość tokenu w nagłówku Apim-Debug-Authorization . Aby na przykład prześledzić wywołanie API Petstore zaimportowanego w poprzednim samouczku, możesz użyć żądania podobnego do następującego:
```
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&......."
```
Oceń odpowiedź — odpowiedź może zawierać jeden z następujących nagłówków w zależności od stanu tokenu debugowania:
- Jeśli token debugowania jest prawidłowy, odpowiedź zawiera nagłówek Apim-Trace-Id, którego wartość to identyfikator śledzenia, podobny do przedstawionego poniżej:
```
Apim-Trace-Id: 0123456789abcdef....
```
- Jeśli token debugowania wygasł, odpowiedź zawiera Apim-Debug-Authorization-Expired nagłówek z informacjami o dacie wygaśnięcia.
- Jeśli token debugowania został uzyskany dla innego interfejsu API, odpowiedź zawiera Apim-Debug-Authorization-WrongAPI nagłówek z komunikatem o błędzie.
Pobierz ślad — przekaż identyfikator śledzenia uzyskany w poprzednim kroku do interfejsu API śledzenia listy bramy. Aby na przykład pobrać ślad dla bramy zarządzanej, użyj żądania podobnego do następującego:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
```
W treści żądania przekaż identyfikator śledzenia uzyskany w poprzednim kroku.
```
{
    "traceId": "0123456789abcdef...."
}
```
Treść odpowiedzi zawiera dane śledzenia dla poprzedniego żądania interfejsu API do bramy. Ślad jest podobny do śladu, który można zobaczyć, śledząc wywołanie w konsoli testowej portalu.

Przykładowy `.http` plik rozszerzenia klienta REST programu VS Code

Aby zautomatyzować te kroki za pomocą rozszerzenia klienta REST programu Visual Studio Code, możesz użyć następującego przykładowego .http pliku:

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

Aby uzyskać informacje na temat dostosowywania informacji śledzenia, zobacz zasady śledzenia .

Następne kroki

W tym samouczku zawarto informacje na temat wykonywania następujących czynności:

Śledzenie przykładowego wywołania w konsoli testowej
Przeglądanie kroków przetwarzania żądań
Włącz śledzenie dla interfejsu API

Przejdź do następnego samouczka:

Użyj poprawek

Udostępnij za pośrednictwem