Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Buat rute untuk WebSocket APIs di API Gateway Di WebSocket API Anda, pesan JSON yang masuk diarahkan ke integrasi backend berdasarkan rute yang Anda konfigurasikan. (Pesan non-JSON diarahkan ke `$default` rute yang Anda konfigurasikan.) *Rute* menyertakan *kunci rute*, yang merupakan nilai yang diharapkan setelah *ekspresi pemilihan rute* dievaluasi. `routeSelectionExpression`Ini adalah atribut yang didefinisikan pada tingkat API. Ini menentukan properti JSON yang diharapkan hadir dalam payload pesan. Untuk informasi selengkapnya tentang ekspresi pemilihan rute, lihat[Ekspresi pemilihan rute](#apigateway-websocket-api-route-selection-expressions). Misalnya, jika pesan JSON 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. + API Gateway memanggil `$connect` rute saat koneksi persisten antara klien dan WebSocket API sedang dimulai. + API Gateway memanggil `$disconnect` rute saat klien atau server terputus dari API. + API Gateway memanggil rute kustom setelah ekspresi pemilihan rute dievaluasi terhadap pesan jika rute yang cocok ditemukan; kecocokan menentukan integrasi mana yang dipanggil. + API Gateway memanggil `$default` rute jika ekspresi pemilihan rute tidak dapat dievaluasi terhadap pesan atau jika tidak ditemukan rute yang cocok. ## 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 berbasis APIs, ekspresi harus dari bentuk`$request.body.{path_to_body_element}`. Misalnya, Anda mengirim pesan JSON berikut: ``` { "service" : "chat", "action" : "join", "data" : { "room" : "room1234" } } ``` Anda mungkin ingin memilih perilaku API berdasarkan `action` properti. Dalam hal ini, Anda dapat menentukan ekspresi pemilihan rute berikut: ``` $request.body.action ``` Dalam contoh ini, `request.body` mengacu pada payload JSON pesan Anda, dan `.action` merupakan [JSONPath](https://goessner.net/articles/JsonPath/)ekspresi. Anda dapat menggunakan ekspresi jalur JSON apa pun setelahnya`request.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 | | --- | --- | --- | | \$1request.body.action | join | Variabel yang tidak dibungkus | | \$1\$1request.body.action\$1 | join | Variabel yang dibungkus | | \$1\$1request.body.service\$1/\$1\$1request.body.action\$1 | chat/join | Beberapa variabel dengan nilai statis | | \$1\$1request.body.action\$1-\$1\$1request.body.invalidPath\$1 | join- | Jika JSONPath tidak ditemukan, variabel diselesaikan sebagai “”. | | action | action | Nilai statis | | \$1\$1default | \$1default | Nilai statis | Hasil evaluasi digunakan untuk menemukan rute. Jika ada rute dengan kunci rute yang cocok, rute dipilih untuk memproses pesan. Jika tidak ditemukan rute yang cocok, API Gateway mencoba menemukan `$default` rute jika tersedia. Jika `$default` rute tidak ditentukan, maka API Gateway mengembalikan kesalahan. ## Mengatur rute untuk WebSocket API di API Gateway Saat pertama kali membuat WebSocket API baru, 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](apigateway-websocket-api-overview.md). **catatan** Di CLI, Anda dapat membuat rute sebelum atau setelah Anda membuat integrasi, dan Anda dapat menggunakan kembali integrasi yang sama untuk beberapa rute. ### Membuat rute menggunakan konsol API Gateway **Untuk membuat rute menggunakan konsol API Gateway** 1. Masuk ke konsol API Gateway, pilih API, dan pilih **Rute**. 1. Pilih **Buat rute** 1. 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 sebelumnya. 1. Pilih dan konfigurasikan jenis integrasi untuk rute. Untuk informasi selengkapnya, lihat [Menyiapkan permintaan integrasi WebSocket API menggunakan konsol API Gateway](apigateway-websocket-api-integration-requests.md#apigateway-websocket-api-integration-request-using-console). ### Buat rute menggunakan AWS CLI Perintah [create-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route.html) berikut membuat rute: ``` aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default ``` Outputnya akan terlihat seperti berikut: ``` { "ApiKeyRequired": false, "AuthorizationType": "NONE", "RouteKey": "$default", "RouteId": "1122334" } ``` ### Tentukan pengaturan permintaan rute untuk `$connect` Saat Anda menyiapkan `$connect` rute untuk API Anda, pengaturan opsional berikut tersedia untuk mengaktifkan otorisasi API Anda. Untuk informasi selengkapnya, lihat [`$connect`Rute](apigateway-websocket-api-route-keys-connect-disconnect.md#apigateway-websocket-api-routes-about-connect). + **Otorisasi**: Jika tidak diperlukan otorisasi, Anda dapat menentukan. `NONE` Jika tidak, Anda dapat menentukan: + `AWS_IAM`untuk menggunakan kebijakan AWS IAM standar untuk mengontrol akses ke API Anda. + `CUSTOM`untuk 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](apigateway-use-lambda-authorizer.md) **catatan** Di konsol API Gateway, `CUSTOM` pengaturan hanya terlihat setelah Anda menyiapkan fungsi otorisasi seperti yang dijelaskan dalam[Konfigurasikan otorisasi Lambda (konsol)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console). **penting** Pengaturan **Otorisasi** diterapkan ke seluruh API, bukan hanya `$connect` rute. `$connect`Rute melindungi rute lain, karena dipanggil pada setiap koneksi. + **Kunci API diperlukan**: Anda dapat secara opsional meminta kunci API untuk `$connect` rute API. Anda dapat menggunakan kunci API bersama dengan rencana penggunaan untuk mengontrol dan melacak akses ke Anda APIs. Untuk informasi selengkapnya, lihat [Paket penggunaan dan kunci API untuk REST APIs di API Gateway](api-gateway-api-usage-plans.md). ### Siapkan permintaan `$connect` rute menggunakan konsol API Gateway Untuk menyiapkan permintaan `$connect` rute WebSocket API menggunakan konsol API Gateway: 1. Masuk ke konsol API Gateway, pilih API, dan pilih **Rute**. 1. Di bawah **Rute**`$connect`, pilih, atau buat `$connect` rute dengan mengikuti[Membuat rute menggunakan konsol API Gateway](#apigateway-websocket-api-route-using-console). 1. Di bagian **Pengaturan permintaan rute**, pilih **Edit**. 1. Untuk **Otorisasi**, pilih jenis otorisasi. 1. Untuk mewajibkan API untuk `$connect` rute tersebut, pilih **Memerlukan kunci API**. 1. Pilih **Simpan perubahan**. # Siapkan respons rute untuk WebSocket APIs di API Gateway WebSocket rute dapat dikonfigurasi untuk komunikasi dua arah atau satu arah. API Gateway tidak akan meneruskan respons backend ke respons rute, kecuali jika Anda menyiapkan respons rute. **catatan** Anda hanya dapat menentukan respons `$default` rute untuk WebSocket APIs. Anda dapat menggunakan respons integrasi untuk memanipulasi respons dari layanan backend. Untuk informasi selengkapnya, lihat [Ikhtisar tanggapan integrasi](apigateway-websocket-api-integration-responses.md#apigateway-websocket-api-integration-response-overview). Anda dapat mengonfigurasi respons rute dan ekspresi pemilihan respons menggunakan konsol API Gateway atau SDK AWS CLI atau AWS SDK. Untuk informasi selengkapnya tentang ekspresi pemilihan respons rute, lihat[Ekspresi pemilihan respons rute](apigateway-websocket-api-selection-expressions.md#apigateway-websocket-api-route-response-selection-expressions). **Topics** + [Mengatur respons rute menggunakan konsol API Gateway](#apigateway-websocket-api-route-response-using-console) + [Siapkan respons rute menggunakan AWS CLI](#apigateway-websocket-api-route-response-using-awscli) ## Mengatur respons rute menggunakan konsol API Gateway Setelah membuat WebSocket API dan melampirkan fungsi Lambda proxy ke rute default, Anda dapat mengatur respons rute menggunakan konsol API Gateway: 1. Masuk ke konsol API Gateway, pilih WebSocket API dengan integrasi fungsi Lambda proxy pada `$default` rute. 1. Di bawah **Rute**, pilih `$default` rute. 1. Pilih **Aktifkan komunikasi dua arah**. 1. Pilih **Deploy API**. 1. Menerapkan API Anda ke panggung. Gunakan perintah [wscat](https://www.npmjs.com/package/wscat) berikut untuk terhubung ke API Anda. Untuk informasi selengkapnya tentang `wscat`, lihat [Gunakan `wscat` untuk terhubung ke WebSocket API dan mengirim pesan ke sana](apigateway-how-to-call-websocket-api-wscat.md). ``` wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test ``` Tekan tombol enter untuk memanggil rute default. Tubuh fungsi Lambda Anda harus kembali. ## Siapkan respons rute menggunakan AWS CLI [create-route-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route-response.html)Perintah berikut membuat respon rute untuk `$default` rute. Anda dapat mengidentifikasi ID API dan ID rute dengan menggunakan perintah [get-apis dan [get-routes](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-routes.html)](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-apis.html). ``` aws apigatewayv2 create-route-response \ --api-id aabbccddee \ --route-id 1122334 \ --route-response-key '$default' ``` Outputnya akan terlihat seperti berikut: ``` { "RouteResponseId": "abcdef", "RouteResponseKey": "$default" } ``` # Siapkan `$connect` rute yang membutuhkan WebSocket subprotokol Klien dapat menggunakan `Sec-WebSocket-Protocol` bidang untuk meminta [WebSocket subprotokol](https://datatracker.ietf.org/doc/html/rfc6455#page-12) selama koneksi ke WebSocket API Anda. Anda dapat menyiapkan integrasi untuk `$connect` rute untuk mengizinkan koneksi hanya jika klien meminta subprotokol yang didukung API Anda. Contoh berikut fungsi Lambda mengembalikan `Sec-WebSocket-Protocol` header ke klien. Fungsi ini membuat koneksi ke API Anda hanya jika klien menentukan subprotokol. `myprotocol` Untuk CloudFormation template yang membuat contoh integrasi proxy API dan Lambda ini, lihat. [samples/ws-subprotocol.zip](samples/ws-subprotocol.zip) ``` export const handler = async (event) => { if (event.headers != undefined) { const headers = toLowerCaseProperties(event.headers); if (headers['sec-websocket-protocol'] != undefined) { const subprotocolHeader = headers['sec-websocket-protocol']; const subprotocols = subprotocolHeader.split(','); if (subprotocols.indexOf('myprotocol') >= 0) { const response = { statusCode: 200, headers: { "Sec-WebSocket-Protocol" : "myprotocol" } }; return response; } } } const response = { statusCode: 400 }; return response; }; function toLowerCaseProperties(obj) { var wrapper = {}; for (var key in obj) { wrapper[key.toLowerCase()] = obj[key]; } return wrapper; } ``` Anda dapat menggunakan [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat)untuk menguji apakah API Anda mengizinkan koneksi hanya jika klien meminta subprotokol yang didukung API Anda. Perintah berikut menggunakan `-s` bendera untuk menentukan subprotokol selama koneksi. Perintah berikut mencoba koneksi dengan subprotokol yang tidak didukung. Karena klien menentukan `chat1` subprotokol, integrasi Lambda mengembalikan kesalahan 400, dan koneksi tidak berhasil. ``` wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1 error: Unexpected server response: 400 ``` Perintah berikut mencakup subprotokol yang didukung dalam permintaan koneksi. Integrasi Lambda memungkinkan koneksi. ``` wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1,myprotocol connected (press CTRL+C to quit) ``` Untuk mempelajari lebih lanjut tentang pemanggilan WebSocket APIs, lihat[Memohon WebSocket APIs](apigateway-how-to-call-websocket-api.md).