Panggil integrasi backend Anda dengan $default Rute dan rute khusus di Gateway API

Bagian berikut menjelaskan cara memanggil integrasi backend Anda menggunakan $default rute atau rute khusus untuk. WebSocket API

Menggunakan rute untuk memproses pesan

Di API Gateway WebSocket APIs, pesan dapat dikirim dari klien ke layanan backend Anda dan sebaliknya. HTTPTidak seperti model permintaan/respons, di WebSocket backend dapat mengirim pesan ke klien tanpa klien mengambil tindakan apa pun.

Pesan bisa JSON atau non-JSON. Namun, hanya JSON pesan yang dapat dialihkan ke integrasi tertentu berdasarkan konten pesan. JSONNon-pesan diteruskan ke backend melalui rute. $default

catatan

APIGateway mendukung muatan pesan hingga 128 KB dengan ukuran bingkai maksimum 32 KB. Jika pesan melebihi 32 KB, Anda harus membaginya menjadi beberapa frame, masing-masing 32 KB atau lebih kecil. Jika pesan yang lebih besar (atau bingkai) diterima, koneksi ditutup dengan kode 1009.

Saat ini payload biner tidak didukung. Jika bingkai biner diterima, koneksi ditutup dengan kode 1003. Namun, dimungkinkan untuk mengonversi muatan biner menjadi teks. Lihat Jenis media biner untuk WebSocket API di API Gateway.

Dengan WebSocket APIs di API Gateway, JSON pesan dapat dirutekan untuk menjalankan layanan backend tertentu berdasarkan konten pesan. Ketika klien mengirim pesan melalui WebSocket koneksinya, ini menghasilkan permintaan rute ke file WebSocket API. Permintaan akan dicocokkan dengan rute dengan kunci rute yang sesuai di API Gateway. Anda dapat mengatur permintaan rute untuk WebSocket API di konsol API Gateway, dengan menggunakan AWS CLI, atau dengan menggunakan AWS SDK.

catatan

Di AWS CLI dan AWS SDKs, Anda dapat membuat rute sebelum atau setelah Anda membuat integrasi. Saat ini konsol tidak mendukung penggunaan kembali integrasi, jadi Anda harus membuat rute terlebih dahulu dan kemudian membuat integrasi untuk rute itu.

Anda dapat mengonfigurasi API Gateway untuk melakukan validasi pada permintaan rute sebelum melanjutkan dengan permintaan integrasi. Jika validasi gagal, API Gateway gagal permintaan tanpa memanggil backend Anda, mengirimkan respons "Bad request body" gateway yang mirip dengan yang berikut ke klien, dan menerbitkan hasil validasi di Log: CloudWatch

{"message" : "Bad request body", "connectionId": "{connectionId}", "messageId": "{messageId}"}

Ini mengurangi panggilan yang tidak perlu ke backend Anda dan memungkinkan Anda fokus pada persyaratan lain dari Anda. API

Anda juga dapat menentukan respons rute untuk rute Anda API untuk mengaktifkan komunikasi dua arah. Respons rute menjelaskan data apa yang akan dikirim ke klien Anda setelah menyelesaikan integrasi rute tertentu. Tidak perlu menentukan respons untuk rute jika, misalnya, Anda ingin klien mengirim pesan ke backend Anda tanpa menerima respons (komunikasi satu arah). Namun, jika Anda tidak memberikan respons rute, API Gateway tidak akan mengirimkan informasi apa pun tentang hasil integrasi Anda ke klien Anda.

$defaultRute

Setiap API Gateway WebSocket API dapat memiliki $default rute. Ini adalah nilai routing khusus yang dapat digunakan dengan cara-cara berikut:

• Anda dapat menggunakannya bersama dengan kunci rute yang ditentukan, untuk menentukan rute “fallback” (misalnya, integrasi tiruan generik yang mengembalikan pesan kesalahan tertentu) untuk pesan masuk yang tidak cocok dengan kunci rute yang ditentukan.

• Anda dapat menggunakannya tanpa kunci rute yang ditentukan, untuk menentukan model proxy yang mendelegasikan perutean ke komponen backend.

• Anda dapat menggunakannya untuk menentukan rute untuk JSON non-payload.

Rute khusus

Jika Anda ingin menjalankan integrasi tertentu berdasarkan konten pesan, Anda dapat melakukannya dengan membuat rute khusus.

Rute kustom menggunakan kunci rute dan integrasi yang Anda tentukan. Ketika pesan masuk berisi JSON properti, dan properti tersebut mengevaluasi nilai yang cocok dengan nilai kunci rute, API Gateway memanggil integrasi. (Untuk informasi selengkapnya, lihat Ikhtisar WebSocket APIs di API Gateway.)

Misalnya, Anda ingin membuat aplikasi ruang obrolan. Anda mungkin mulai dengan membuat ekspresi pemilihan rute WebSocket API yang$request.body.action. Anda kemudian dapat menentukan dua rute: joinroom dansendmessage. Aplikasi klien mungkin memanggil joinroom rute dengan mengirim pesan seperti berikut:

{"action":"joinroom","roomname":"developers"}

Dan itu mungkin memanggil sendmessage rute dengan mengirim pesan seperti berikut:

{"action":"sendmessage","message":"Hello everyone"}

Menggunakan WebSocket API integrasi API Gateway untuk terhubung ke logika bisnis Anda

Setelah menyiapkan rute untuk API Gateway WebSocket API, Anda harus menentukan integrasi yang ingin Anda gunakan. Seperti halnya rute, yang dapat memiliki permintaan rute dan respons rute, integrasi dapat memiliki permintaan integrasi dan respons integrasi. Permintaan integrasi berisi informasi yang diharapkan oleh backend Anda untuk memproses permintaan yang berasal dari klien Anda. Respons integrasi berisi data yang dikembalikan backend Anda ke API Gateway, dan yang dapat digunakan untuk membuat pesan untuk dikirim ke klien (jika respons rute ditentukan).

Untuk informasi selengkapnya tentang menyiapkan integrasi, lihatIntegrasi untuk WebSocket API di API Gateway.

Perbedaan penting antara WebSocket APIs dan REST APIs

Integrasi untuk WebSocket APIs mirip dengan integrasi untuk RESTAPIs, kecuali untuk perbedaan berikut:

• Saat ini, di konsol API Gateway Anda harus membuat rute terlebih dahulu dan kemudian membuat integrasi sebagai target rute itu. Namun, di API danCLI, Anda dapat membuat rute dan integrasi secara independen, dalam urutan apa pun.

• Anda dapat menggunakan integrasi tunggal untuk beberapa rute. Misalnya, jika Anda memiliki serangkaian tindakan yang terkait erat satu sama lain, Anda mungkin ingin semua rute tersebut menuju ke satu fungsi Lambda. Daripada mendefinisikan detail integrasi beberapa kali, Anda dapat menentukannya sekali dan menetapkannya ke setiap rute terkait.

  catatan

  Saat ini konsol tidak mendukung penggunaan kembali integrasi, jadi Anda harus membuat rute terlebih dahulu dan kemudian membuat integrasi untuk rute itu.

  Di AWS CLI dan AWS SDKs, Anda dapat menggunakan kembali integrasi dengan menyetel target rute ke nilai"integrations/{integration-id}", di {integration-id}" mana ID unik integrasi yang akan dikaitkan dengan rute.

• APIGateway menyediakan beberapa ekspresi pilihan yang dapat Anda gunakan dalam rute dan integrasi Anda. Anda tidak perlu bergantung pada jenis konten untuk memilih template input atau pemetaan output. Seperti ekspresi pemilihan rute, Anda dapat menentukan ekspresi pilihan yang akan dievaluasi oleh API Gateway untuk memilih item yang tepat. Semuanya akan kembali ke $default template jika template yang cocok tidak ditemukan.

  • Dalam permintaan integrasi, ekspresi pemilihan template mendukung $request.body.<json_path_expression> dan nilai statis.

  • Dalam tanggapan integrasi, ekspresi pemilihan template mendukung$request.body.<json_path_expression>,, $integration.response.statuscode$integration.response.header.<headerName>, dan nilai statis.

Dalam HTTP protokol, di mana permintaan dan tanggapan dikirim secara serempak; komunikasi pada dasarnya adalah satu arah. Dalam WebSocket protokol, komunikasi adalah dua arah. Respons bersifat asinkron dan tidak harus diterima oleh klien dalam urutan yang sama dengan pesan klien yang dikirim. Selain itu, backend dapat mengirim pesan ke klien.

catatan

Untuk rute yang dikonfigurasi untuk digunakan AWS_PROXY atau LAMBDA_PROXY diintegrasikan, komunikasi dilakukan satu arah, dan API Gateway tidak akan meneruskan respons backend ke respons rute secara otomatis. Misalnya, dalam kasus LAMBDA_PROXY integrasi, badan yang dikembalikan fungsi Lambda tidak akan dikembalikan ke klien. Jika Anda ingin klien menerima tanggapan integrasi, Anda harus menentukan respons rute untuk memungkinkan komunikasi dua arah.