Buat rute untuk WebSocket APIs di API Gateway

Dalam JSON pesan masuk Anda WebSocket API diarahkan ke integrasi backend berdasarkan rute yang Anda konfigurasikan. (JSONNon-pesan diarahkan ke $default rute yang Anda konfigurasikan.)

Rute menyertakan kunci rute, yang merupakan nilai yang diharapkan setelah ekspresi pemilihan rute dievaluasi. routeSelectionExpressionIni adalah atribut yang didefinisikan pada API tingkat. Ini menentukan JSON properti yang diharapkan hadir dalam payload pesan. Untuk informasi selengkapnya tentang ekspresi pemilihan rute, lihatEkspresi pemilihan rute.

Misalnya, jika JSON pesan Anda berisi action properti dan Anda ingin melakukan tindakan berbeda berdasarkan properti ini, ekspresi pemilihan rute Anda mungkin${request.body.action}. Tabel routing Anda akan menentukan tindakan mana yang akan dilakukan dengan mencocokkan nilai action properti terhadap nilai kunci rute kustom yang telah Anda tentukan dalam tabel.

Ada tiga rute standar yang dapat digunakan:$connect,$disconnect, dan$default. Selain itu, Anda dapat membuat rute khusus.

• APIGateway memanggil $connect rute ketika koneksi persisten antara klien dan a WebSocket API sedang dimulai.

• APIGateway memanggil $disconnect rute ketika klien atau server terputus dari. API

• APIGateway memanggil rute kustom setelah ekspresi pemilihan rute dievaluasi terhadap pesan jika rute yang cocok ditemukan; kecocokan menentukan integrasi mana yang dipanggil.

• APIGateway memanggil $default rute jika ekspresi pemilihan rute tidak dapat dievaluasi terhadap pesan atau jika tidak ada rute yang cocok ditemukan.

Ekspresi pemilihan rute

Ekspresi pemilihan rute dievaluasi saat layanan memilih rute yang akan diikuti untuk pesan masuk. Layanan menggunakan rute yang routeKey persis sama dengan nilai yang dievaluasi. Jika tidak ada yang cocok dan rute dengan kunci $default rute ada, rute itu dipilih. Jika tidak ada rute yang cocok dengan nilai yang dievaluasi dan tidak ada $default rute, layanan mengembalikan kesalahan. Untuk WebSocket berbasisAPIs, ekspresi harus dari bentuk$request.body.{path_to_body_element}.

Misalnya, Anda mengirim JSON pesan berikut:

{
    "service" : "chat",
    "action" : "join",
    "data" : {
        "room" : "room1234"
   }
}

Anda mungkin ingin memilih API perilaku Anda berdasarkan action properti. Dalam hal ini, Anda dapat menentukan ekspresi pemilihan rute berikut:

$request.body.action

Dalam contoh ini, request.body mengacu pada JSON payload pesan Anda, dan .action merupakan JSONPathekspresi. Anda dapat menggunakan ekspresi JSON jalur apa pun setelahnyarequest.body, tetapi perlu diingat bahwa hasilnya akan dirangkai. Misalnya, jika JSONPath ekspresi Anda mengembalikan array dari dua elemen, yang akan disajikan sebagai string"[item1, item2]". Untuk alasan ini, ini adalah praktik yang baik untuk membuat ekspresi Anda mengevaluasi nilai dan bukan array atau objek.

Anda cukup menggunakan nilai statis, atau Anda dapat menggunakan beberapa variabel. Tabel berikut menunjukkan contoh dan hasil evaluasi mereka terhadap muatan sebelumnya.

Ekspresi	Hasil yang dievaluasi	Deskripsi
$request.body.action	join	Variabel yang tidak dibungkus
${request.body.action}	join	Variabel yang dibungkus
${request.body.service}/${request.body.action}	chat/join	Beberapa variabel dengan nilai statis
${request.body.action}-${request.body.invalidPath}	join-	Jika JSONPath tidak ditemukan, variabel diselesaikan sebagai “”.
action	action	Nilai statis
\$default	$default	Nilai statis

Hasil evaluasi digunakan untuk menemukan rute. Jika ada rute dengan kunci rute yang cocok, rute dipilih untuk memproses pesan. Jika tidak ada rute yang cocok ditemukan, maka API Gateway mencoba menemukan $default rute jika tersedia. Jika $default rute tidak ditentukan, maka API Gateway mengembalikan kesalahan.

Siapkan rute untuk WebSocket API di API Gateway

Saat pertama kali membuat yang baru WebSocket API, ada tiga rute yang telah ditentukan:$connect,$disconnect, dan$default. Anda dapat membuatnya dengan menggunakan konsol,API, atau AWS CLI. Jika diinginkan, Anda dapat membuat rute khusus. Untuk informasi selengkapnya, lihat Ikhtisar WebSocket APIs di API Gateway.

catatan

Di dalamCLI, Anda dapat membuat rute sebelum atau setelah Anda membuat integrasi, dan Anda dapat menggunakan kembali integrasi yang sama untuk beberapa rute.

Buat rute menggunakan konsol API Gateway

Untuk membuat rute menggunakan konsol API Gateway

1. Masuk ke konsol API Gateway, pilihAPI, dan pilih Rute.

2. Pilih Buat rute

3. Untuk tombol Rute, masukkan nama kunci rute. Anda dapat membuat rute yang telah ditentukan ($connect,$disconnect, dan$default), atau rute khusus.

   catatan

   Saat Anda membuat rute khusus, jangan gunakan $ awalan dalam nama kunci rute. Awalan ini dicadangkan untuk rute yang telah ditentukan.

4. Pilih dan konfigurasikan jenis integrasi untuk rute. Untuk informasi selengkapnya, lihat Menyiapkan permintaan integrasi WebSocket API menggunakan konsol API Gateway.

Buat rute menggunakan AWS CLI

Untuk membuat rute menggunakan AWS CLI, panggil create-routeseperti yang ditunjukkan pada contoh berikut:

aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default

Contoh output:

{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteKey": "$default",
    "RouteId": "1122334"
}

Tentukan pengaturan permintaan rute untuk $connect

Ketika Anda mengatur $connect rute untuk AndaAPI, pengaturan opsional berikut tersedia untuk mengaktifkan otorisasi untuk AndaAPI. Untuk informasi selengkapnya, lihat $connectRute.

• Otorisasi: Jika tidak diperlukan otorisasi, Anda dapat menentukan. NONE Jika tidak, Anda dapat menentukan:

  • AWS_IAMuntuk menggunakan AWS IAM kebijakan standar untuk mengontrol akses ke AndaAPI.

  • CUSTOMuntuk menerapkan otorisasi untuk API dengan menentukan fungsi otorisasi Lambda yang telah Anda buat sebelumnya. Authorizer dapat berada di akun Anda sendiri atau AWS akun lain AWS . Untuk informasi selengkapnya tentang otorisasi Lambda, lihat. Gunakan otorisasi API Gateway Lambda

    catatan

    Di konsol API Gateway, CUSTOM pengaturan hanya terlihat setelah Anda menyiapkan fungsi otorisasi seperti yang dijelaskan dalamKonfigurasikan otorisasi Lambda (konsol).

  penting

  Pengaturan Otorisasi diterapkan ke seluruhAPI, bukan hanya $connect rute. $connectRute melindungi rute lain, karena dipanggil pada setiap koneksi.

• APIKey Required: Anda dapat secara opsional meminta API kunci untuk $connect rute. API Anda dapat menggunakan API kunci bersama dengan rencana penggunaan untuk mengontrol dan melacak akses ke AndaAPIs. Untuk informasi selengkapnya, lihat Paket penggunaan dan API kunci untuk REST APIs di API Gateway .

Siapkan permintaan $connect rute menggunakan konsol API Gateway

Untuk menyiapkan permintaan $connect rute untuk WebSocket API menggunakan konsol API Gateway:

1. Masuk ke konsol API Gateway, pilihAPI, dan pilih Rute.

2. Di bawah Rute$connect, pilih, atau buat $connect rute dengan mengikutiBuat rute menggunakan konsol API Gateway.

3. Di bagian Pengaturan permintaan rute, pilih Edit.

4. Untuk Otorisasi, pilih jenis otorisasi.

5. Untuk mewajibkan API $connect rute, pilih Memerlukan API kunci.

6. Pilih Simpan perubahan.