Penanganan error, pembatasan kapasitas, dan pengelolaan kuota

Saat Anda membuat kueri Developer Knowledge API atau server MCP Developer Knowledge di aplikasi produksi dan agen AI, harus ada penanganan error dan pengelolaan kuota untuk mencapai performa tinggi.

Dalam panduan ini Anda akan mempelajari cara:

  • Terapkan backoff eksponensial terpotong dengan jitter untuk respons HTTP 429.
  • Tangani kode error gRPC kanonis (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED).
  • Kelola waktu tunggu koneksi MCP dan logika percobaan ulang.
  • Terapkan praktik terbaik pengelolaan kuota dan caching.

Pembatasan kapasitas HTTP 429 dan backoff eksponensial

Jika kecepatan permintaan melebihi kuota API default, layanan akan menampilkan error HTTP 429 Too Many Requests. Aplikasi harus menerapkan logika percobaan ulang menggunakan backoff eksponensial terpotong dengan jitter untuk menghindari kelebihan beban pada layanan.

Backoff eksponensial terpotong

Hitung penundaan percobaan ulang menggunakan formula berikut:

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

Gunakan parameter berikut untuk menghitung penundaan percobaan ulang:

  • initial_delay: penundaan percobaan ulang awal (misalnya, 1,0 detik).
  • max_delay: batas penundaan maksimum (misalnya, 32,0 detik).
  • attempt: jumlah percobaan ulang saat ini (0, 1, 2, ...).
  • jitter: nilai acak antara 0 dan 1,0 detik untuk mencegah lonjakan sinkronisasi thread (masalah thundering herd).

Penanganan error gRPC

Aplikasi yang mengakses layanan melalui gRPC harus memeriksa nilai kanonis grpc.StatusCode.

Kode status gRPC standar

Tabel berikut mencantumkan kode status gRPC kanonis yang ditampilkan oleh layanan dan penanganan klien yang direkomendasikan:

Kode status gRPC Status HTTP Akar masalah Tindakan yang disarankan
INVALID_ARGUMENT 400 Bad Request String kueri salah format, format parameter tidak valid, atau mask kolom tidak valid. Jangan coba lagi. Perbaiki parameter permintaan sebelum mengulangi.
UNAUTHENTICATED 401 Unauthorized Kunci API atau token OAuth Bearer tidak ada, sudah tidak berlaku, atau salah format. Jangan coba lagi. Muat ulang kredensial atau buat kunci API yang valid.
PERMISSION_DENIED 403 Forbidden Kunci API tidak memiliki izin atau Developer Knowledge API dinonaktifkan di project. Jangan coba lagi. Pastikan API diaktifkan di konsol Google Cloud.
NOT_FOUND 404 Not Found Jalur dokumen parent yang ditentukan tidak ada. BatchGetDocuments gagal secara atomik jika ada dokumen yang diminta tidak ditemukan. Jangan coba lagi. Verifikasi nama resource dokumen.
RESOURCE_EXHAUSTED 429 Too Many Requests Batas frekuensi atau batas kuota project terlampaui. Coba lagi menggunakan backoff eksponensial dengan jitter.
UNAVAILABLE 503 Service Unavailable Koneksi jaringan terputus sementara atau server dimulai ulang. Coba lagi dengan backoff eksponensial.
DEADLINE_EXCEEDED 504 Gateway Timeout Permintaan melampaui batas waktu RPC yang dikonfigurasi sebelum selesai. Coba lagi dengan waktu tunggu RPC klien yang lebih lama.

Pengelolaan error dan waktu tunggu koneksi MCP habis

Server MCP Pengetahuan Developer adalah layanan jarak jauh yang dihosting di https://developerknowledge.googleapis.com/mcp yang diakses melalui HTTPS (menggunakan HTTP POST atau Peristiwa yang Dikirim Server). Host dan agen AI harus mengelola waktu tunggu koneksi dan error alat dengan baik.

Waktu tunggu eksekusi alat

Saat agen memanggil search_documents, get_documents, atau answer_query, panggilan alat dapat melampaui periode tunggu (misalnya, 30 detik) jika koneksi jaringan tertunda.

Untuk menangani waktu tunggu eksekusi alat:

  • Konfigurasi waktu tunggu klien: tetapkan waktu tunggu eksekusi alat menjadi 30–60 detik dalam konfigurasi klien host MCP Anda.
  • Menangani gangguan jaringan: coba lagi permintaan HTTP yang gagal dengan backoff eksponensial saat mengalami gangguan jaringan sementara atau respons HTTP 503.
  • Periksa pesan error: mengurai pesan error JSON-RPC standar atau kode status error HTTP untuk membedakan argumen yang tidak valid dari habisnya kuota.

Praktik terbaik pengelolaan kuota

Ikuti praktik terbaik berikut untuk mempertahankan penggunaan API yang optimal dan menghindari batas kapasitas yang tidak terduga:

  1. Cache konten dokumen yang diambil: menyimpan dokumen Markdown yang diambil secara lokal atau dalam cache (seperti Redis) saat membangun aplikasi yang sering mengakses halaman yang sama.
  2. Gunakan pengambilan batch: gunakan documents.batchGet, bukan mengeksekusi beberapa permintaan documents.get berurutan.
  3. Mengoptimalkan kolom kueri: minta hanya kolom respons yang diperlukan menggunakan masker kolom selektif (fields=results(parent,content)).
  4. Pantau penggunaan kuota: lacak kecepatan permintaan API di dasbor API Konsol Google Cloud.

Konten terkait