Ringkasan pemecahan masalah

Halaman ini memberikan informasi pemecahan masalah umum untuk API Gateway.

Tidak dapat menjalankan perintah "gcloud api-gateway"

Untuk menjalankan perintah gcloud api-gateway ..., Anda harus telah 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 \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

Pastikan Anda telah menetapkan izin yang diperlukan ke akun layanan seperti yang dijelaskan di 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 keterangan:

    • 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", respons error berasal dari backend dan Anda harus memecahkan masalah backend secara langsung. Jika nilainya adalah nilai lain, 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 403 HTTP 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 error HTTP 403 adalah akun layanan tidak memiliki izin yang diperlukan untuk mengakses layanan backend.

Jika Anda menentukan API dan layanan backend di 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 diterapkan menggunakan fungsi Cloud Run, pastikan akun layanan memiliki peran Cloud Function Invoker yang ditetapkan.

Permintaan API menampilkan error HTTP 401 atau 500

Jika permintaan ke API yang di-deploy menampilkan error 401 atau 500 HTTP 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 response_code_details ditetapkan ke "via_upstream" di jsonPayload entri log, hal ini menunjukkan bahwa menghapus atau menonaktifkan akun layanan adalah penyebab error.

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

Permintaan API dengan latensi tinggi

Seperti Cloud Run dan fungsi Cloud Run, API Gateway tunduk pada latensi "cold start". Jika gateway Anda belum menerima traffic selama 15 hingga 20 menit, permintaan yang dibuat ke gateway 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 konfigurasikan di Konfigurasi API. Misalnya, jika layanan backend diterapkan menggunakan fungsi Cloud Run, 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 API Gateway.

API Gateway mengharuskan Anda mengaktifkan layanan Google berikut:

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

Untuk mengonfirmasi bahwa layanan yang diperlukan telah diaktifkan:

gcloud services list

Jika Anda tidak melihat layanan yang diperlukan tercantum, aktifkan layanan tersebut:

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.