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

Menentukan sumber respons error API

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

  1. Buka halaman Logs Explorer dan 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 region Google Cloud 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", respons error berasal dari backend Anda dan Anda harus memecahkan masalah backend secara langsung. Jika nilainya berbeda, respons error berasal dari Gateway; lihat bagian berikut dalam dokumen ini untuk 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 alasan tertentu.

API yang di-deploy memiliki izin yang terkait dengan peran yang diberikan ke akun layanan yang Anda gunakan saat membuat konfigurasi API. Biasanya, alasan 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, atau peran yang diperlukan untuk mengakses layanan backend. Misalnya, jika layanan backend diimplementasikan menggunakan Cloud Run Functions, pastikan akun layanan memiliki peran Cloud Function Invoker yang ditetapkan ke akun tersebut.

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 dalam 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 bahwa 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 ditetapkan ke "via_upstream" di jsonPayload entri log, ini menunjukkan bahwa menghapus atau menonaktifkan akun layanan adalah penyebab error.

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

Jika backend untuk permintaan yang gagal adalah API Google Cloud lain (seperti bigquery.googleapis.com), Anda akan melihat respons HTTP 401 di log gateway dengan kolom jsonPayload.responseDetails ditetapkan ke "via_upstream". Hal ini karena Gateway API melakukan autentikasi ke backend dengan Token ID, sedangkan 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 ada lagi untuk API. Di gateway gRPC, kegagalan yang sama ditampilkan sebagai kode status gRPC Internal.

Mengonfirmasi penyebabnya di log gateway Anda

  1. Buka halaman Logs Explorer dan 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 akan menghasilkan nilai yang sama dengan httpRequest.status dari 429.

  3. Periksa kolom jsonPayload.apiConfig dan jsonPayload.apiMethod dari setiap entri yang cocok. Pesan 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 akan menggantikan metrik dan batas yang dideklarasikan oleh konfigurasi API sebelumnya. Hanya nilai dari konfigurasi API yang terakhir dibuat yang diterapkan.

Sebaliknya, metrik yang digunakan oleh setiap metode ditentukan dalam konfigurasi API yang disajikan oleh 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 dalam API. Jika metrik tidak ada, panggilan alokasi akan gagal, dan gateway akan menolak permintaan.

Misalnya, urutan berikut membuat gateway pertama rusak:

  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 menerapkan batas kuota.
  • Mengubah metrik yang disebutkan dalam biaya kuota per metode (x-google-quota untuk dokumen OpenAPI, atau quota.metric_rules untuk konfigurasi layanan gRPC).

Mengubah nilai batas saja tidak akan 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. Cantumkan gateway Anda dan konfigurasi API yang disajikan oleh masing-masing gateway:

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

  2. Cantumkan konfigurasi API dari API yang terpengaruh, yang paling 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 flag --format seperti yang ditunjukkan: perintah ini tidak mendukung flag --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 berada dalam konfigurasi layanan, bukan dalam 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 ditampilkan langkah 1 sebagai masih di-deploy ke gateway.

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

Memulihkan konfigurasi kuota yang valid

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

  • Update setiap gateway API untuk menggunakan konfigurasi API yang terakhir dibuat, seperti yang dijelaskan dalam Mengupdate 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, pastikan nama metrik tetap konsisten di seluruh konfigurasi API dari sebuah 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 tidak menerima traffic selama 15 hingga 20 menit, permintaan yang dibuat ke gateway Anda dalam 10 hingga 15 detik pertama 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 Library API, masukkan nama API yang diperlukan ke 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.