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

Artykuł
02/25/2025

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 interfejsu API i rozwiązywanie problemów z tym interfejsem 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łasnych środowisk środowiska uruchomieniowego interfejsu 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łączanie śledzenia dla interfejsu API

Wymagania wstępne

Poznaj terminologię dotyczącą usługi Azure API Management.
Wykonaj procedury przedstawione w następującym przewodniku Szybki start: 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 zwiększyć bezpieczeństwo interfejsu API, śledzenie można teraz włączyć na poziomie pojedynczego interfejsu API przez uzyskanie tokenu ograniczonego czasowo przy użyciu interfejsu API REST usługi API Management i przekazanie tokenu 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.

Śledzenie wywołania 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 pozycję Interfejsy API interfejsów> API.
Wybierz pozycję Interfejs API magazynu petstore z listy interfejsów API.
Wybierz kartę Test.
Wybierz operację Znajdź zwierzę według identyfikatora .
W parametrze petIdQuery wprowadź wartość 1.
Opcjonalnie sprawdź wartość nagłówka Ocp-Apim-Subscription-Key używanego w żądaniu, wybierając ikonę "oko".

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 pozycję + Dodaj nagłówek, aby dodać nagłówek Ocp-Apim-Subscription-Key z nową wartością klucza.
Wybierz pozycję Ś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 z powrotem do elementu 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łączanie śledzenia 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:

Uzyskiwanie tokenu debugowania do śledzenia.
Dodaj wartość tokenu w Apim-Debug-Authorization nagłówku żądania do bramy usługi API Management.
Uzyskaj identyfikator śledzenia w nagłówku Apim-Trace-Id odpowiedzi.
Pobierz ślad odpowiadający identyfikatorowi śledzenia.

Szczegółowe kroki należy wykonać.

Uwaga

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

Uzyskiwanie tokenu debugowania — wywoływanie interfejsu API debugowania poświadczeń debugowania bramy usługi API Management. W identyfikatorze URI wprowadź wartość "managed" dla bramy zarządzanej wystąpienia w chmurze lub identyfikator bramy dla własnej bramy. Aby na przykład uzyskać poświadczenia śledzenia dla bramy zarządzanej wystąpienia, użyj żądania podobnego do następującego:
```
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 zasobu interfejsu API, który chcesz śledzić, i określ go 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. Na przykład:
```
{
    "credentialsExpireAfter": PT1H,
    "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
Uwaga

Element apiId można ściągnąć tylko z pełnego identyfikatora zasobu, a nie 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 podobne do następującego:
```
{
      "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 interfejsu API magazynu 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 Apim-Trace-Id nagłówek, którego wartość to identyfikator śledzenia, podobny do następującego:
```
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/{{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}}"
}

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łączanie śledzenia dla interfejsu API

Przejdź do następnego samouczka:

Korzystanie z poprawek

Udostępnij za pośrednictwem

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

Wymagania wstępne

Śledzenie wywołania w portalu

Przeglądanie informacji śledzenia

Włączanie śledzenia dla interfejsu API

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

Następne kroki

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

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

Wymagania wstępne

Śledzenie wywołania w portalu

Przeglądanie informacji śledzenia

Włączanie śledzenia dla interfejsu API

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

Następne kroki

Opinia

Dodatkowe zasoby

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