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

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

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

1. Zaloguj się do witryny Azure Portal i przejdź do wystąpienia usługi API Management.

2. Wybierz pozycję Interfejsy API interfejsów> API.

3. Wybierz pozycję Interfejs API magazynu petstore z listy interfejsów API.

4. Wybierz kartę Test.

5. Wybierz operację Znajdź zwierzę według identyfikatora .

6. W parametrze petId Query wprowadź wartość 1.

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

8. Wybierz pozycję Ślad.

Przeglądanie informacji śledzenia

1. Po zakończeniu wywołania przejdź do karty Śledzenie w odpowiedzi HTTP.

2. 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:

1. Uzyskiwanie poświadczeń tokenu do śledzenia.
2. Dodaj wartość tokenu w Apim-Debug-Authorization nagłówku żądania do bramy usługi API Management.
3. Uzyskaj identyfikator śledzenia w nagłówku Apim-Trace-Id odpowiedzi.
4. 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.

1. Uzyskiwanie poświadczeń tokenu — 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/{apiName}",
       "purposes": ["tracing"]
   }
   

   Poświadczenie tokenu jest zwracane w odpowiedzi podobne do następujących:

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

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

3. W zależności od tokenu odpowiedź zawiera jeden z następujących nagłówków:

   • Jeśli token jest prawidłowy, odpowiedź zawiera Apim-Trace-Id nagłówek, którego wartość jest identyfikatorem śledzenia, podobnie jak poniżej:

     Apim-Trace-Id: 0123456789abcdef....
     

   • 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 innego interfejsu API, odpowiedź zawiera Apim-Debug-Authorization-WrongAPI nagłówek z komunikatem o błędzie.

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

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 testowym conosle
• Przeglądanie kroków przetwarzania żądań
• Włączanie śledzenia dla interfejsu API

Przejdź do następnego samouczka:

Korzystanie z poprawek