Ringkasan pemecahan masalah

Halaman ini memberikan informasi pemecahan masalah umum untuk Gateway API.

Tidak dapat menjalankan perintah "gcloud api-gateway"

Untuk menjalankan perintah gcloud api-gateway ..., Anda harus mengupdate Google Cloud CLI dan mengaktifkan layanan Google yang diperlukan. Lihat Mengonfigurasi lingkungan pengembangan Anda untuk mengetahui informasi selengkapnya.

Perintah "gcloud api-gateway api-configs create" menyatakan bahwa akun layanan tidak ada

Jika Anda menjalankan perintah gcloud api-gateway api-configs create ... dan menerima error dalam bentuk:

ERROR: (gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION:
Service Account "projects/-/serviceAccounts/service_account_email" does not exist

Jalankan kembali perintah, tetapi kali ini sertakan opsi --backend-auth-service-account untuk menentukan alamat email akun layanan yang akan digunakan secara eksplisit:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

Pastikan Anda telah menetapkan izin yang diperlukan ke akun layanan seperti yang dijelaskan dalam Mengonfigurasi lingkungan pengembangan Anda.

Menentukan sumber respons error API

Jika permintaan ke API yang di-deploy menghasilkan error (kode status HTTP 400 hingga 599), tidak jelas dari respons itu sendiri apakah error berasal dari Gateway atau dari backend Anda. Untuk menentukannya:

  1. Buka halaman Logs Explorer, lalu pilih project Anda.

    Buka Logs Explorer

  2. Filter ke resource gateway yang relevan menggunakan kueri Log berikut:

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"

    Dengan:

    • GATEWAY_ID menentukan nama gateway.
    • GCP_REGION adalah Google Cloud region untuk gateway yang di-deploy.

  3. Temukan entri log yang cocok dengan respons error HTTP yang ingin Anda selidiki. Misalnya, filter menurut httpRequest.status.

  4. Periksa konten kolom jsonPayload.responseDetails.

Jika nilai kolom jsonPayload.responseDetails adalah "via_upstream", maka respons error berasal dari backend Anda dan Anda harus memecahkan masalah backend Anda secara langsung. Jika nilai lainnya, respons error berasal dari Gateway; lihat bagian berikut dalam dokumen ini untuk mengetahui tips pemecahan masalah lebih lanjut.

Permintaan API menampilkan error HTTP 403

Jika permintaan ke API yang di-deploy menampilkan error HTTP 403 ke klien API, artinya URL yang diminta valid, tetapi akses dilarang karena beberapa alasan.

API yang di-deploy memiliki izin yang terkait dengan peran yang diberikan ke akun layanan yang Anda gunakan saat membuat konfigurasi API. Biasanya, alasan terjadinya error HTTP 403 adalah akun layanan tidak memiliki izin yang diperlukan untuk mengakses layanan backend.

Jika Anda menentukan API dan layanan backend dalam Project Google Cloud yang sama, pastikan akun layanan memiliki peran Editor yang ditetapkan untuknya, atau peran yang diperlukan untuk mengakses layanan backend. Misalnya, jika layanan backend diimplementasikan menggunakan Cloud Run Functions, pastikan akun layanan telah diberi peran Cloud Function Invoker.

Permintaan API menampilkan error HTTP 401 atau 500

Jika permintaan ke API yang di-deploy menampilkan error HTTP 401 atau 500 ke klien API, mungkin ada masalah saat menggunakan akun layanan yang digunakan saat Anda membuat konfigurasi API untuk memanggil layanan backend.

API yang di-deploy memiliki izin yang terkait dengan peran yang diberikan ke akun layanan yang Anda gunakan saat membuat konfigurasi API. Akun layanan diperiksa untuk memastikan akun tersebut ada dan dapat digunakan oleh gateway API saat API di-deploy.

Jika akun layanan dihapus atau dinonaktifkan setelah gateway di-deploy, urutan peristiwa berikut dapat terjadi:

  1. Segera setelah akun layanan dihapus atau dinonaktifkan, Anda mungkin melihat respons HTTP 401 di log gateway. Jika kolom jsonPayload.responseDetails disetel ke "via_upstream" di jsonPayload entri log, hal ini menunjukkan bahwa error disebabkan oleh penghapusan atau penonaktifan akun layanan.

  2. Anda juga dapat melihat error HTTP 500 tanpa entri log yang sesuai di log API Gateway. Jika tidak ada permintaan ke gateway Anda segera setelah akun layanan dihapus atau dinonaktifkan, Anda mungkin tidak melihat respons HTTP 401, tetapi error HTTP 500 tanpa log gateway API yang sesuai menunjukkan bahwa akun layanan gateway mungkin tidak lagi aktif.

Jika backend untuk permintaan yang gagal adalah Google Cloud API lain (seperti bigquery.googleapis.com), Anda akan melihat respons HTTP 401 di log gateway dengan kolom jsonPayload.responseDetails disetel ke "via_upstream". Hal ini karena Gateway API melakukan autentikasi ke backend dengan token ID, sementara API Google Cloud lainnya memerlukan token akses.

Permintaan API menampilkan error HTTP 500 untuk metode yang menerapkan kuota

Jika Anda menerima error berikut, gateway tidak dapat mengalokasikan kuota untuk permintaan Anda:

HTTP/2 500
{"code":500,"message":"Failed to call Service Control Quota."}

Error ini biasanya terjadi saat Anda memanggil metode yang memiliki kuota yang dikonfigurasi, tetapi metrik kuota tidak lagi ada untuk API. Di gateway gRPC, kegagalan yang sama ditampilkan sebagai kode status gRPC Internal.

Konfirmasi penyebabnya di log gateway Anda

  1. Buka halaman Logs Explorer, lalu pilih project Anda.

    Buka Logs Explorer

  2. Jalankan kueri log berikut:

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
jsonPayload.responseDetails="service_control_quota_error"
httpRequest.status=500

    Dengan GATEWAY_ID menentukan nama gateway.

    Kueri memfilter kode status serta jsonPayload.responseDetails karena Gateway API menggunakan nilai responseDetails yang sama untuk setiap penolakan kuota. Permintaan yang secara sah melebihi kuotanya menghasilkan nilai yang sama dengan httpRequest.status 429.

  3. Periksa kolom jsonPayload.apiConfig dan jsonPayload.apiMethod dari entri yang cocok. Error ini mengidentifikasi konfigurasi API dan metode yang konfigurasi kuotanya tidak valid.

Alasan konfigurasi API dapat memiliki konfigurasi kuota yang tidak valid

Anda menentukan metrik dan batas kuota dalam konfigurasi API, tetapi Gateway API menerapkannya ke seluruh API. Setiap kali Anda membuat konfigurasi API, metrik dan batas yang dideklarasikannya menggantikan metrik dan batas yang dideklarasikan oleh konfigurasi API sebelumnya. Hanya nilai dari konfigurasi API yang baru dibuat yang diterapkan.

Sebaliknya, metrik yang digunakan oleh setiap metode ditentukan dalam konfigurasi API yang ditayangkan gateway. Jika gateway menjalankan konfigurasi API yang lebih lama, gateway akan meminta Service Control untuk mengalokasikan kuota terhadap metrik yang ada dalam konfigurasinya sendiri, tetapi mungkin tidak ada di API. Jika metrik tidak ada, panggilan alokasi akan gagal, dan gateway akan menolak permintaan.

Misalnya, urutan berikut akan merusak gateway pertama:

  1. Anda membuat konfigurasi API config-v1, yang mendeklarasikan metrik quota-metric-v1, dan men-deploy-nya ke gateway-1.
  2. Anda membuat konfigurasi API config-v2 untuk API yang sama, yang mendeklarasikan metrik quota-metric-v2, dan men-deploy-nya ke gateway-2.

gateway-2 berfungsi, tetapi permintaan ke metode gateway-1 yang menerapkan kuota mulai gagal, karena quota-metric-v1 tidak lagi ditentukan untuk API.

Perubahan berikut dapat menyebabkan error untuk gateway apa pun yang masih di-deploy dengan konfigurasi API sebelumnya:

  • Mengganti nama atau menghapus metrik.
  • Mengubah metrik yang batas kuotanya berlaku.
  • Mengubah metrik yang diberi nama dalam biaya kuota per metode (x-google-quota untuk dokumen OpenAPI, atau quota.metric_rules untuk konfigurasi layanan gRPC).

Mengubah hanya nilai batas tidak menyebabkan error. Namun, karena batas juga diterapkan di level API, nilai baru akan diterapkan di setiap gateway API tersebut, termasuk gateway yang di-deploy dengan konfigurasi API sebelumnya.

Membandingkan konfigurasi kuota yang di-deploy

  1. Mencantumkan gateway dan konfigurasi API yang ditayangkan oleh setiap gateway:

    gcloud api-gateway gateways list \
 --format="table(name.basename(),apiConfig)"

  2. Mencantumkan konfigurasi API dari API yang terpengaruh, yang baru dibuat terlebih dahulu:

    gcloud api-gateway api-configs list --api=API_ID \
 --format="table(name.basename(),createTime:sort=1:reverse)"

    Entri pertama adalah konfigurasi API yang metrik dan batas kuotanya diterapkan untuk seluruh API. Urutkan dengan tanda --format seperti yang ditunjukkan: perintah ini tidak mendukung tanda --sort-by, dan tidak menampilkan konfigurasi API dalam urutan yang dapat diprediksi.

  3. Menampilkan definisi API yang digunakan untuk membuat konfigurasi API:

    gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID \
 --view=FULL --format="value(openapiDocuments[0].document.contents)" \
 | tr '_-' '/+' | base64 --decode

    Perintah tr diperlukan karena kolom contents dienkode base64url, yang tidak dapat dibaca langsung oleh base64 --decode.

    Untuk gRPC API, konfigurasi kuota ada di konfigurasi layanan, bukan di dokumen OpenAPI, jadi ganti openapiDocuments[0].document.contents dengan managedServiceConfigs[0].contents.

  4. Jalankan perintah di langkah 3 untuk konfigurasi API di bagian atas daftar dari langkah 2, lalu untuk setiap konfigurasi API lainnya yang ditunjukkan langkah 1 sebagai masih di-deploy ke gateway.

  5. Bandingkan hasilnya. Setiap metrik yang dikenai biaya metode oleh konfigurasi API yang lebih lama juga harus ditentukan dalam konfigurasi API yang baru dibuat. Jika metrik tidak ada dalam konfigurasi tersebut, gateway yang melayani konfigurasi API yang lebih lama akan gagal.

Memulihkan konfigurasi kuota yang valid

Audit metrik dan batas kuota Anda untuk memastikan bahwa metrik dan batas tersebut konsisten di semua konfigurasi aktif. Untuk melakukannya, lakukan salah satu tindakan berikut:

  • Perbarui setiap gateway API untuk menggunakan konfigurasi API yang baru dibuat, seperti yang dijelaskan dalam Memperbarui gateway.
  • Buat konfigurasi API baru yang mendeklarasikan setiap metrik yang digunakan oleh konfigurasi API yang masih di-deploy, dan pertahankan gateway yang ada pada konfigurasi API saat ini.

Untuk menghindari error alokasi, pertahankan konsistensi nama metrik di seluruh konfigurasi API dari suatu API. Saat Anda mengubah kuota, ubah nilai batas, bukan nama metrik.

Permintaan API dengan latensi tinggi

Seperti Cloud Run dan Cloud Run Functions, Gateway API tunduk pada latensi "cold start". Jika gateway Anda belum menerima traffic selama 15 hingga 20 menit, permintaan yang dibuat ke gateway Anda dalam 10 hingga 15 detik pertama saat cold start akan mengalami latensi 3 hingga 5 detik.

Jika masalah berlanjut setelah periode "pemanasan" awal, periksa log permintaan layanan backend yang Anda konfigurasi di Konfigurasi API. Misalnya, jika layanan backend diimplementasikan menggunakan Cloud Run Functions, periksa entri Cloud Logging dari log permintaan Cloud Function terkait.

Tidak dapat melihat informasi log

Jika API Anda merespons dengan benar, tetapi log tidak berisi data, biasanya berarti Anda belum mengaktifkan semua layanan Google yang diperlukan oleh Gateway API.

Gateway API mengharuskan Anda mengaktifkan layanan Google Cloud berikut:

Nama Nama layanan
API Gateway API apigateway.googleapis.com
Service Management API servicemanagement.googleapis.com
Service Control API servicecontrol.googleapis.com

Untuk mengaktifkan layanan yang diperlukan:

Konsol Google Cloud

  1. Di konsol Google Cloud , buka halaman APIs & Services > API Library.

    Buka Library API

  2. Di halaman API Library, masukkan nama API yang diperlukan ke dalam kotak penelusuran.
  3. Di hasil penelusuran, pilih halaman API.
  4. Di halaman API, klik Enable.
  5. Ulangi langkah-langkah ini untuk setiap layanan yang tercantum dalam tabel sebelumnya.

Google Cloud CLI

Gunakan perintah berikut untuk mengaktifkan layanan:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Untuk mengetahui informasi selengkapnya tentang layanan gcloud, lihat Layanan gcloud.