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

Artykuł
06/23/2024

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.

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

Śledzenie żądań usługi API Management przy użyciu nagłówka Ocp-Apim-Trace w żądaniu i użycie wartości nagłówka odpowiedzi Ocp-Apim-Trace-Location jest przestarzałe.
Aby zwiększyć bezpieczeństwo, ś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

Zaloguj się do witryny Azure Portal i przejdź do wystąpienia usługi API Management.
Wybierz pozycję Interfejsy API.
Wybierz pozycję Pokazowy interfejs API konferencji z listy interfejsów API.
Wybierz kartę Test.
Wybierz operację GetSpeakers.
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, zostaną one wyświetlone 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

Śledzenie interfejsu API można włączyć podczas wprowadzania żądań do usługi API Management przy użyciu curlklienta REST, takiego jak Program Visual Studio Code z rozszerzeniem klienta REST lub aplikacji klienckiej.

Włącz śledzenie, wykonując następujące kroki przy użyciu wywołań interfejsu API REST usługi API Management.

Uwaga

Poniższe 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.

Uzyskiwanie poświadczeń śledzenia przez wywołanie interfejsu API debugowania list. Przekaż identyfikator bramy w identyfikatorze URI lub użyj polecenia "managed" dla bramy zarządzanej wystąpienia w chmurze. Aby na przykład uzyskać poświadczenia śledzenia dla bramy zarządzanej, użyj wywołania 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.
```
{
    "credentialsExpireAfter": PT1H,
    "apiId": "<API resource ID>",
    "purposes": ["tracing"]
}
```
Poświadczenie tokenu jest zwracane w odpowiedzi podobne do następujących:
```
{
      "token": "aid=api-name&p=tracing&ex=......."
}
```
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 konferencji demonstracyjnej, użyj wywołania podobnego do następującego:
```
curl -v GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&p=tracing&ex=......."
```
W zależności od tokenu odpowiedź zawiera różne nagłówki:
- Jeśli token jest prawidłowy, odpowiedź zawiera Apim-Trace-Id nagłówek, którego wartość jest identyfikatorem śledzenia.
- Jeśli token wygasł, odpowiedź zawiera Apim-Debug-Authorization-Expired nagłówek z informacjami o dacie wygaśnięcia.
- Jeśli token został uzyskany dla nieprawidłowego interfejsu API, odpowiedź zawiera Apim-Debug-Authorization-WrongAPI nagłówek z komunikatem o błędzie.
Aby pobrać ślad, przekaż identyfikator śledzenia uzyskany w poprzednim kroku do interfejsu API śledzenia listy dla bramy. Aby na przykład pobrać ślad dla bramy zarządzanej, użyj wywołania 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": "<trace ID>"
}
```
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.

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
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