API Gateway：Menangani masalah yang terjadi selama debugging API

1. Ikhtisar

Konsol API Gateway memungkinkan Anda men-debug API yang telah diterbitkan. Jika terjadi masalah selama proses debugging, Anda dapat mengidentifikasi dan menyelesaikan masalah tersebut berdasarkan informasi kesalahan. Topik ini menjelaskan cara melakukannya menggunakan fitur debug API yang disediakan oleh Konsol API Gateway.

2. Memperoleh informasi kesalahan

API Gateway mengembalikan respons untuk setiap permintaan yang diterima. Anda dapat melihat informasi yang dikembalikan oleh API Gateway dari header respons. Atribut yang dimulai dengan X-Ca dikembalikan oleh API Gateway. Fokuskan perhatian pada informasi berikut:

• X-Ca-Error-Code: kode kesalahan sistem. Atribut ini dikembalikan jika permintaan memiliki kesalahan dan ditolak oleh API Gateway.

• X-Ca-Request-Id: ID unik dari permintaan. Ketika API Gateway menerima permintaan, ia menghasilkan ID permintaan dan mengembalikan ID tersebut dalam header X-Ca-Request-Id. Kami sarankan Anda mencatat ID permintaan baik di klien maupun layanan backend Anda untuk tujuan pelacakan dan penyelesaian masalah.

• X-Ca-Error-Message: pesan kesalahan yang dikembalikan oleh API Gateway. Jika permintaan gagal, API Gateway mengembalikan pesan kesalahan dalam header X-Ca-Error-Message.

2.1 Gunakan X-Ca-Request-Id untuk menanyakan lebih banyak informasi panggilan API

Anda dapat memperoleh informasi dasar tentang kegagalan panggilan dari header X-Ca-Error-Code dan X-Ca-Error-Message dalam respons. Jika Anda memerlukan lebih banyak informasi, Anda dapat menggunakan header X-Ca-Request-Id untuk menanyakan log permintaan di Layanan Log Sederhana dan hasil permintaan di Konsol API Gateway. Anda juga dapat memberikan header X-Ca-Request-Id kepada insinyur dukungan teknis untuk penyelesaian masalah lebih lanjut.

Untuk menanyakan log panggilan di Konsol API Gateway, lakukan langkah-langkah berikut:

1. Masuk ke Konsol API Gateway.

2. Di panel navigasi di sebelah kiri, pilih Call APIs > Troubleshooting. Di halaman yang muncul, tentukan wilayah dan X-Ca-Request-Id dari API, lalu klik Query untuk melihat log yang sesuai.

2.1.1 Kesalahan yang dilaporkan oleh API Gateway

Jika header X-Ca-Error-Code tidak kosong, permintaan ditolak oleh API Gateway. Kode kesalahan adalah string enam karakter. Bersama dengan kode kesalahan, pesan kesalahan dan deskripsi singkat penyebab kesalahan juga dikembalikan (X-Ca-Error-Message). Anda dapat menangani kesalahan berdasarkan informasi tersebut. Untuk informasi lebih lanjut tentang kode kesalahan, lihat Kode kesalahan.

2.1.2 Kesalahan yang dilaporkan oleh layanan backend

Jika kode status HTTP bukan 200 dan header X-Ca-Error-Code kosong, API Gateway telah meneruskan permintaan ke layanan backend Anda, yang kemudian memproses permintaan dan mengembalikan kode status non-200. Dalam kasus ini, Anda harus memeriksa logika bisnis layanan backend Anda. Jika Anda membeli API dari Alibaba Cloud Marketplace, Anda harus menghubungi penyedia layanan di Alibaba Cloud Marketplace.

2.1.3 Sukses

Jika kode status HTTP adalah 200, API Gateway telah meneruskan permintaan ke layanan backend, dan layanan backend mengembalikan respons sukses setelah memproses permintaan.

3. Memperoleh log jejak

Jika Anda memilih Record Trace, Anda dapat melihat permintaan yang diterima oleh API Gateway, informasi pemrosesan, permintaan yang diteruskan oleh API Gateway ke layanan backend, respons yang diterima oleh API Gateway, serta respons yang diteruskan oleh API Gateway ke klien dalam log jejak.

Jika Anda menggunakan Pengguna Resource Access Management (RAM) atau Peran RAM, pastikan bahwa akun Alibaba Cloud telah memberikan izin untuk operasi AcquireGatewayToken pada instance tempat API berada. Contoh kode berikut menunjukkan implementasinya. Untuk informasi lebih lanjut, lihat Gunakan RAM untuk mengelola izin pada sumber daya API.

{
 "Version": "1",
 "Statement": [
 {
 "Effect": "ALLOW",
 "Action": "apigateway:AcquireGatewayToken",
 "Resource": "acs:apigateway:{#regionId}:{#accountId}:instance/{#InstanceId}"
 }
 ]
}
# {#} menunjukkan variabel yang harus Anda ganti dengan nilai aktual.

4. Menganalisis penyebab

Di bagian Informasi Panggilan tab Diagnostik, Anda dapat melihat beberapa log dari panggilan ini. Anda dapat menangani masalah berdasarkan log jika panggilan Anda gagal. Dua bidang berikut dapat digunakan untuk dengan cepat menemukan masalah:

• TotalLatency: durasi dari saat API Gateway menerima permintaan hingga klien menerima respons.

• ServiceLatency: durasi dari saat API Gateway meneruskan permintaan hingga API Gateway menerima respons dari layanan backend.

Jika nilai ServiceLatency adalah 0, permintaan ditolak oleh API Gateway. Jika nilai ServiceLatency bukan 0, permintaan diteruskan ke layanan backend. Selain itu, titik-titik input/output (I/O) dalam waktu dari seluruh tautan permintaan dicatat dalam log:

• FrontRequestStart: titik waktu ketika API Gateway mulai menerima permintaan klien.

• FrontRequestEnd: titik waktu ketika API Gateway selesai menerima permintaan klien.

• BackendRequestStart: titik waktu ketika API Gateway mulai meneruskan permintaan ke layanan backend.

• BackendRequestEnd: titik waktu ketika API Gateway selesai meneruskan permintaan ke layanan backend.

• BackendResponseStart: titik waktu ketika API Gateway mulai menerima respons dari layanan backend.

• BackendResponseEnd: titik waktu ketika API Gateway selesai menerima respons dari layanan backend.

• FrontResponseStart: titik waktu ketika API Gateway mulai mengirim respons ke klien.

• FrontResponseEnd: titik waktu ketika API Gateway selesai mengirim respons ke klien.

Penggunaan log yang tepat dapat membantu Anda dengan cepat menyelesaikan masalah. Untuk informasi lebih lanjut tentang bidang-bidang dalam log, lihat Gunakan Layanan Log Sederhana untuk Mengelola Log Panggilan API.