Obsługa błędów, ograniczanie liczby żądań i zarządzanie limitami

Podczas wysyłania zapytań do interfejsu Developer Knowledge API lub serwera Developer Knowledge MCP w aplikacjach produkcyjnych i agentach AI należy stosować obsługę błędów i zarządzanie limitami, aby osiągnąć wysoką wydajność.

Z tego przewodnika dowiesz się, jak:

  • Wdrażanie obciętego wzrastającego czasu do ponowienia z zakłóceniami w przypadku odpowiedzi HTTP 429.
  • Obsługa kanonicznych kodów błędów gRPC (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED).
  • Zarządzaj limitami czasu połączenia MCP i logiką ponawiania.
  • Stosuj sprawdzone metody zarządzania limitami i pamięcią podręczną.

Ograniczanie liczby żądań HTTP 429 i wzrastający czas do ponowienia

Gdy liczba żądań przekracza domyślny limit interfejsu API, usługa zwraca błąd HTTP 429 Too Many Requests. Aplikacje muszą implementować logikę ponawiania prób z użyciem skróconego wzrastającego czasu do ponowienia z losowym opóźnieniem, aby uniknąć przeciążenia usługi.

Obcięty wzrastający czas do ponowienia

Oblicz opóźnienia ponownych prób za pomocą tego wzoru:

retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)

Do obliczania opóźnień ponownych prób używaj tych parametrów:

  • initial_delay: początkowe opóźnienie ponownej próby (np.1, 0 sekundy).
  • max_delay: maksymalny czas do ponowienia (np.32, 0 sekundy).
  • attempt: bieżąca liczba ponownych prób (0, 1, 2 itd.).
  • jitter: losowa wartość z zakresu od 0 do 1,0 sekundy, aby zapobiec skokom synchronizacji wątków (problem z gromadzeniem się żądań).

Obsługa błędów gRPC

Aplikacje uzyskujące dostęp do usługi przez gRPC muszą sprawdzać wartości canonical grpc.StatusCode.

Standardowe kody stanu gRPC

W tabeli poniżej znajdziesz kanoniczne kody stanu gRPC zwracane przez usługę oraz zalecane działania klienta:

Kod stanu gRPC Stan HTTP Główna przyczyna Zalecane działanie
INVALID_ARGUMENT 400 Bad Request Nieprawidłowy ciąg zapytania, nieprawidłowy format parametru lub nieprawidłowa maska pola. Nie ponawiaj próby. Przed powtórzeniem popraw parametry żądania.
UNAUTHENTICATED 401 Unauthorized Brakujący, przedawniony lub nieprawidłowy klucz interfejsu API lub token OAuth Bearer. Nie ponawiaj próby. Odśwież dane logowania lub wygeneruj prawidłowy klucz interfejsu API.
PERMISSION_DENIED 403 Forbidden Klucz interfejsu API nie ma uprawnień lub interfejs Developer Knowledge API jest wyłączony w projekcie. Nie ponawiaj próby. Sprawdź, czy interfejs API jest włączony w konsoli Google Cloud.
NOT_FOUND 404 Not Found Podana ścieżka dokumentu parent nie istnieje. BatchGetDocuments kończy się niepowodzeniem w sposób niepodzielny, jeśli nie można znaleźć żadnego z żądanych dokumentów. Nie ponawiaj próby. Sprawdź nazwę zasobu dokumentu.
RESOURCE_EXHAUSTED 429 Too Many Requests Przekroczono limit częstotliwości lub limit projektu. Ponów próbę ze wzrastającym czasem do ponowienia z losowym opóźnieniem.
UNAVAILABLE 503 Service Unavailable Chwilowe odłączenie od sieci lub ponowne uruchomienie serwera. Ponów próbę ze wzrastającym czasem do ponowienia.
DEADLINE_EXCEEDED 504 Gateway Timeout Żądanie przekroczyło skonfigurowany limit czasu RPC przed zakończeniem. Spróbuj ponownie, zwiększając limit czasu RPC klienta.

Zarządzanie czasem oczekiwania na połączenie z MCP i błędami

Serwer MCP Developer Knowledge to usługa zdalna hostowana pod adresem https://developerknowledge.googleapis.com/mcp, do której dostęp uzyskuje się przez HTTPS (za pomocą HTTP POST lub zdarzeń wysyłanych przez serwer). Prezenterzy i agenci AI muszą odpowiednio zarządzać limitami czasu połączenia i błędami narzędzi.

Przekroczenia limitu czasu wykonania narzędzia

Gdy agent wywoła search_documents, get_documents lub answer_query, wywołania narzędzi mogą przekroczyć limit czasu (np. 30 sekund), jeśli połączenia sieciowe są opóźnione.

Aby obsługiwać przekroczenia limitu czasu wykonania narzędzia:

  • Skonfiguruj limity czasu klienta: ustaw limity czasu wykonywania narzędzia na 30–60 sekund w konfiguracji klienta hosta MCP.
  • Obsługa przerw w działaniu sieci: ponawiaj nieudane żądania HTTP z wykorzystaniem wzrastającego czasu do ponowienia, gdy występują przejściowe przerwy w działaniu sieci lub odpowiedzi HTTP 503.
  • Sprawdzanie komunikatów o błędach: analizuj standardowe komunikaty o błędach JSON-RPC lub kody stanu błędów HTTP, aby odróżnić nieprawidłowe argumenty od wyczerpania limitu.

Sprawdzone metody zarządzania limitami

Aby utrzymać optymalne wykorzystanie interfejsu API i uniknąć nieoczekiwanych limitów szybkości, postępuj zgodnie z tymi sprawdzonymi metodami:

  1. Buforowanie pobranej zawartości dokumentu: podczas tworzenia aplikacji, które często uzyskują dostęp do tych samych stron, przechowuj pobrane dokumenty Markdown lokalnie lub w pamięci podręcznej (np. Redis).
  2. Używaj pobierania zbiorczego: używaj documents.batchGet zamiast wykonywać wiele kolejnych żądań documents.get.
  3. Optymalizuj pola zapytań: żądaj tylko wymaganych pól odpowiedzi, używając selektywnych masek pól (fields=results(parent,content)).
  4. Monitorowanie wykorzystania limitu: śledź liczbę żądań do interfejsu API w panelu interfejsów API w konsoli Google Cloud.

Powiązane artykuły