`, dan nilai statis.
Dalam protokol HTTP, di mana permintaan dan tanggapan dikirim secara serempak; komunikasi pada dasarnya 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.
# WebSocket ekspresi seleksi
API Gateway menggunakan ekspresi seleksi sebagai cara untuk mengevaluasi konteks permintaan dan respons dan menghasilkan kunci. Kunci tersebut kemudian digunakan untuk memilih dari serangkaian nilai yang mungkin, biasanya disediakan oleh Anda, pengembang API. Kumpulan yang tepat dari variabel yang didukung akan bervariasi tergantung pada ekspresi tertentu. Setiap ekspresi dibahas secara lebih rinci di bawah ini.
Untuk semua ekspresi, bahasa mengikuti seperangkat aturan yang sama:
+ Variabel diawali dengan`"$"`.
+ Kurung kurawal dapat digunakan untuk secara eksplisit mendefinisikan batas variabel, misalnya,. `"${request.body.version}-beta"`
+ Beberapa variabel didukung, tetapi evaluasi hanya terjadi sekali (tidak ada evaluasi rekursif).
+ Tanda dolar (`$`) dapat lolos dengan`"\"`. Ini paling berguna saat mendefinisikan ekspresi yang memetakan ke `$default` kunci yang dicadangkan, misalnya,`"\$default"`.
+ Dalam beberapa kasus, format pola diperlukan. Dalam hal ini, ekspresi harus dibungkus dengan garis miring (`"/"`), misalnya `"/2\d\d/"` untuk mencocokkan kode `2XX` status.
**Topics**
+ [Ekspresi pemilihan respons rute](#apigateway-websocket-api-route-response-selection-expressions)
+ [Ekspresi pemilihan kunci API](#apigateway-websocket-api-apikey-selection-expressions)
+ [Ekspresi pemilihan pemetaan API](#apigateway-websocket-api-mapping-selection-expressions)
+ [WebSocket ringkasan ekspresi seleksi](#apigateway-websocket-api-selection-expression-table)
## Ekspresi pemilihan respons rute
[Respons rute](apigateway-websocket-api-route-response.md) digunakan untuk memodelkan respons dari backend ke klien. Untuk WebSocket APIs, respons rute adalah opsional. Ketika didefinisikan, ini memberi sinyal ke API Gateway bahwa ia harus mengembalikan respons ke klien setelah menerima WebSocket pesan.
Evaluasi *ekspresi pemilihan respons rute* menghasilkan kunci respons rute. Akhirnya, kunci ini akan digunakan untuk memilih dari salah satu yang [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html)terkait dengan API. Namun, saat ini hanya `$default` kunci yang didukung.
## Ekspresi pemilihan kunci API
Ekspresi ini dievaluasi ketika layanan menentukan permintaan yang diberikan harus dilanjutkan hanya jika klien menyediakan [kunci API](api-gateway-basic-concept.md#apigateway-definition-api-key) yang valid.
Saat ini hanya dua nilai yang didukung adalah `$request.header.x-api-key` dan`$context.authorizer.usageIdentifierKey`.
## Ekspresi pemilihan pemetaan API
Ekspresi ini dievaluasi untuk menentukan tahap API mana yang dipilih saat permintaan dibuat menggunakan domain kustom.
Saat ini, satu-satunya nilai yang didukung adalah `$request.basepath`.
## WebSocket ringkasan ekspresi seleksi
Tabel berikut merangkum kasus penggunaan untuk ekspresi seleksi di WebSocket APIs:
| Ekspresi seleksi | Mengevaluasi ke kunci untuk | Catatan | Contoh kasus penggunaan |
| --- | --- | --- | --- |
| Api.RouteSelectionExpression | Route.RouteKey | \$1defaultdidukung sebagai rute catch-all. | Rute WebSocket pesan berdasarkan konteks permintaan klien. |
| Route.ModelSelectionExpression | Kunci untuk Route.RequestModels | Tidak wajib. Jika disediakan untuk integrasi non-proxy, validasi model terjadi. `$default`didukung sebagai catch-all. | Lakukan validasi permintaan secara dinamis dalam rute yang sama. |
| Integration.TemplateSelectionExpression | Kunci untuk Integration.RequestTemplates | Tidak wajib. Dapat disediakan untuk integrasi non-proxy untuk memanipulasi muatan yang masuk. `${request.body.jsonPath}`dan nilai statis didukung. `$default`didukung sebagai catch-all. | Memanipulasi permintaan pemanggil berdasarkan properti dinamis permintaan. |
| Integration.IntegrationResponseSelectionExpression | IntegrationResponse.IntegrationResponseKey | Tidak wajib. Dapat disediakan untuk integrasi non-proxy. Bertindak sebagai kecocokan pola untuk pesan kesalahan (dari Lambda) atau kode status (dari integrasi HTTP). `$default`diperlukan untuk integrasi non-proxy untuk bertindak sebagai tangkapan semua untuk tanggapan yang berhasil. | Memanipulasi respons dari backend. Pilih tindakan yang akan terjadi berdasarkan respons dinamis backend (misalnya, menangani kesalahan tertentu dengan jelas). |
| IntegrationResponse.TemplateSelectionExpression | Kunci untuk IntegrationResponse.ResponseTemplates | Tidak wajib. Dapat disediakan untuk integrasi non-proxy. \$1 default didukung. | Dalam beberapa kasus, properti dinamis dari respons dapat menentukan transformasi yang berbeda dalam rute yang sama dan integrasi terkait. `${request.body.jsonPath}`,`${integration.response.statuscode}`,`${integration.response.header.headerName}`,`${integration.response.multivalueheader.headerName}`, dan nilai statis didukung. `$default`didukung sebagai catch-all. |
| Route.RouteResponseSelectionExpression | RouteResponse.RouteResponseKey | Harus disediakan untuk memulai komunikasi dua arah untuk suatu WebSocket rute. Saat ini, nilai ini dibatasi `$default` hanya untuk. | |
| RouteResponse.ModelSelectionExpression | Kunci untuk RouteResponse.RequestModels | Saat ini tidak didukung. | |
# Kembangkan WebSocket APIs di API Gateway
Bagian ini memberikan detail tentang kemampuan API Gateway yang Anda butuhkan saat mengembangkan API Gateway APIs.
Saat Anda mengembangkan API Gateway API, Anda memutuskan sejumlah karakteristik API Anda. Karakteristik ini bergantung pada kasus penggunaan API Anda. Misalnya, Anda mungkin hanya ingin mengizinkan klien tertentu untuk memanggil API Anda, atau Anda mungkin ingin itu tersedia untuk semua orang. Anda mungkin ingin panggilan API untuk menjalankan fungsi Lambda, membuat kueri database, atau memanggil aplikasi.
**Topics**
+ [Buat WebSocket APIs di API Gateway](apigateway-websocket-api-create-empty-api.md)
+ [Jenis alamat IP untuk WebSocket APIs di API Gateway](websocket-api-ip-address-type.md)
+ [Buat rute untuk WebSocket APIs di API Gateway](websocket-api-develop-routes.md)
+ [Mengontrol dan mengelola akses ke WebSocket APIs dalam API Gateway](apigateway-websocket-api-control-access.md)
+ [Integrasi untuk WebSocket APIs di API Gateway](apigateway-websocket-api-integrations.md)
+ [Minta validasi untuk WebSocket APIs di API Gateway](websocket-api-request-validation.md)
+ [Transformasi data untuk WebSocket APIs di API Gateway](websocket-api-data-transformations.md)
+ [Jenis media biner untuk WebSocket APIs di API Gateway](websocket-api-develop-binary-media-types.md)
+ [Memohon WebSocket APIs](apigateway-how-to-call-websocket-api.md)
# Buat WebSocket APIs di API Gateway
Anda dapat membuat WebSocket API di konsol API Gateway, dengan menggunakan perintah AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html), atau dengan menggunakan `CreateApi` perintah dalam SDK. AWS Prosedur berikut menunjukkan cara membuat WebSocket API baru.
**catatan**
WebSocket APIs hanya mendukung TLS 1.2 dan TLS 1.3. Versi TLS sebelumnya tidak didukung.
## Buat WebSocket API menggunakan AWS CLI perintah
Perintah [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) berikut membuat API dengan ekspresi pemilihan `$request.body.action` rute:
```
aws apigatewayv2 --region us-east-1 create-api --name "myWebSocketApi3" --protocol-type WEBSOCKET --route-selection-expression '$request.body.action'
```
Outputnya terlihat seperti berikut:
```
{
"ApiKeySelectionExpression": "$request.header.x-api-key",
"Name": "myWebSocketApi3",
"CreatedDate": "2018-11-15T06:23:51Z",
"ProtocolType": "WEBSOCKET",
"RouteSelectionExpression": "'$request.body.action'",
"ApiId": "aabbccddee"
}
```
## Membuat WebSocket API menggunakan konsol API Gateway
Anda dapat membuat WebSocket API di konsol dengan memilih WebSocket protokol dan memberi API nama.
**penting**
Setelah Anda membuat API, Anda tidak dapat mengubah protokol yang telah Anda pilih untuk itu. Tidak ada cara untuk mengubah WebSocket API menjadi REST API atau sebaliknya.
**Untuk membuat WebSocket API menggunakan konsol API Gateway**
1. Masuk ke konsol API Gateway dan pilih **Buat API**.
1. Di bawah **WebSocket API**, pilih **Build**. Hanya titik akhir Regional yang didukung.
1. Untuk **nama API**, masukkan nama API Anda.
1. Untuk **ekspresi pemilihan Rute**, masukkan nilai. Misalnya, `$request.body.action`.
Untuk informasi selengkapnya tentang ekspresi pemilihan rute, lihat[Ekspresi pemilihan rute](websocket-api-develop-routes.md#apigateway-websocket-api-route-selection-expressions).
1. Lakukan salah satu tindakan berikut:
+ Pilih **Buat API kosong** untuk membuat API tanpa rute.
+ Pilih **Berikutnya** untuk melampirkan rute ke API Anda.
Anda dapat melampirkan rute setelah membuat API.
# Jenis alamat IP untuk WebSocket APIs di API Gateway
Saat membuat API, Anda menentukan jenis alamat IP yang dapat menjalankan API Anda. Anda dapat memilih IPv4 untuk menyelesaikan IPv4 alamat untuk menjalankan API Anda, atau Anda dapat memilih dualstack untuk mengizinkan keduanya IPv4 dan IPv6 alamat menjalankan API Anda. Kami menyarankan Anda mengatur jenis alamat IP ke dualstack untuk mengurangi kelelahan ruang IP atau untuk postur keamanan Anda. [Untuk informasi selengkapnya tentang manfaat dari jenis alamat IP dualstack, lihat IPv6 di. AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)
## Pertimbangan untuk jenis alamat IP
Pertimbangan berikut dapat memengaruhi penggunaan jenis alamat IP Anda:
+ Jenis alamat IP default untuk semua WebSocket APIs adalah IPv4.
+ Jika Anda mengubah jenis alamat IP untuk API yang ada dari IPv4 ke dualstack, konfirmasikan bahwa kebijakan apa pun yang mengontrol akses ke Anda APIs telah diperbarui untuk IPv6 memperhitungkan panggilan. Ketika Anda mengubah jenis alamat IP, perubahan akan segera berlaku.
+ API Anda dapat dipetakan ke nama domain khusus dengan jenis alamat IP yang berbeda dari API Anda. Jika Anda menonaktifkan titik akhir API default, hal ini dapat memengaruhi cara penelepon dapat menjalankan API Anda.
## Mengubah jenis alamat IP WebSocket API
Anda dapat mengubah jenis alamat IP dengan memperbarui konfigurasi API. Anda dapat memperbarui konfigurasi API dengan menggunakan Konsol Manajemen AWS, the AWS CLI CloudFormation, atau AWS SDK. Jika Anda mengubah jenis alamat IP API, Anda tidak menerapkan ulang API agar perubahan diterapkan.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengubah jenis alamat IP WebSocket API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih WebSocket API.
1. Pilih **pengaturan API**, lalu pilih **Edit**.
1. Untuk jenis alamat IP, pilih salah satu **IPv4**atau **Dualstack**.
1. Pilih **Simpan**.
Perubahan pada konfigurasi API Anda akan segera berlaku.
------
#### [ AWS CLI ]
Perintah [update-api berikut memperbarui API](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) agar memiliki tipe alamat IP dualstack:
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
Outputnya akan terlihat seperti berikut:
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-WebSocket-API",
"ProtocolType": "WEBSOCKET",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# 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).
# Mengontrol dan mengelola akses ke WebSocket APIs dalam API Gateway
API Gateway mendukung beberapa mekanisme untuk mengontrol dan mengelola akses ke WebSocket API Anda.
Anda dapat menggunakan mekanisme berikut untuk otentikasi dan otorisasi:
+ **Peran dan kebijakan AWS IAM standar** menawarkan kontrol akses yang fleksibel dan kuat. Anda dapat menggunakan peran dan kebijakan IAM untuk mengontrol siapa yang dapat membuat dan mengelola Anda APIs, serta siapa yang dapat memanggilnya. Untuk informasi selengkapnya, lihat [Kontrol akses WebSocket APIs dengan otorisasi IAM](apigateway-websocket-control-access-iam.md).
+ **Tag IAM** dapat digunakan bersama dengan kebijakan IAM untuk mengontrol akses. Untuk informasi selengkapnya, lihat [Menggunakan tag untuk mengontrol akses ke sumber daya API API Gateway REST API](apigateway-tagging-iam-policy.md).
+ **Lambda Authorizer adalah** fungsi Lambda yang mengontrol akses ke. APIs Untuk informasi selengkapnya, lihat [Kontrol akses WebSocket APIs dengan otorisasi AWS Lambda REQUEST](apigateway-websocket-api-lambda-auth.md).
Untuk meningkatkan postur keamanan Anda, kami sarankan Anda mengonfigurasi otorisasi untuk `$connect` rute di semua rute Anda WebSocket APIs. Anda mungkin perlu melakukan ini untuk mematuhi berbagai kerangka kerja kepatuhan. Untuk informasi selengkapnya, lihat [kontrol Amazon API Gateway](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) di *Panduan AWS Security Hub Pengguna*.
**Topics**
+ [Kontrol akses WebSocket APIs dengan otorisasi IAM](apigateway-websocket-control-access-iam.md)
+ [Kontrol akses WebSocket APIs dengan otorisasi AWS Lambda REQUEST](apigateway-websocket-api-lambda-auth.md)
# Kontrol akses WebSocket APIs dengan otorisasi IAM
Otorisasi IAM di WebSocket APIs mirip dengan yang untuk [REST APIs](api-gateway-control-access-using-iam-policies-to-invoke-api.md), dengan pengecualian berikut:
+ `execute-api`Tindakan mendukung `ManageConnections` selain tindakan yang ada (`Invoke`,`InvalidateCache`). `ManageConnections`mengontrol akses ke @connections API.
+ WebSocket rute menggunakan format ARN yang berbeda:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/route-key
```
+ `@connections`API menggunakan format ARN yang sama dengan REST: APIs
```
arn:aws:execute-api:region:account-id:api-id/stage-name/POST/@connections
```
**penting**
Ketika Anda menggunakan [otorisasi IAM](#apigateway-websocket-control-access-iam), Anda harus menandatangani permintaan dengan [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html).
Misalnya, Anda dapat menyiapkan kebijakan berikut ke klien. Contoh ini memungkinkan setiap orang untuk mengirim pesan (`Invoke`) untuk semua rute kecuali untuk rute rahasia di `prod` panggung dan mencegah semua orang mengirim pesan kembali ke klien yang terhubung (`ManageConnections`) untuk semua tahapan.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/prod/*"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/prod/secret"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:ManageConnections"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/*"
]
}
]
}
```
------
# Kontrol akses WebSocket APIs dengan otorisasi AWS Lambda REQUEST
Fungsi otorisasi Lambda di mirip dengan WebSocket APIs yang untuk [REST APIs](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create), dengan pengecualian berikut:
+ Anda hanya dapat menggunakan fungsi otorisasi Lambda untuk rute tersebut. `$connect`
+ Anda tidak dapat menggunakan variabel jalur (`event.pathParameters`), karena jalurnya sudah diperbaiki.
+ `event.methodArn`berbeda dari setara REST API-nya, karena tidak memiliki metode HTTP. Dalam kasus`$connect`, `methodArn` diakhiri dengan`"$connect"`:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/$connect
```
+ Variabel konteks `event.requestContext` berbeda dari variabel untuk REST APIs.
Contoh berikut menunjukkan input ke `REQUEST` authorizer untuk WebSocket API:
```
{
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/default/$connect",
"headers": {
"Connection": "upgrade",
"content-length": "0",
"HeaderAuth1": "headerValue1",
"Host": "abcdef123.execute-api.us-east-1.amazonaws.com",
"Sec-WebSocket-Extensions": "permessage-deflate; client_max_window_bits",
"Sec-WebSocket-Key": "...",
"Sec-WebSocket-Version": "13",
"Upgrade": "websocket",
"X-Amzn-Trace-Id": "...",
"X-Forwarded-For": "...",
"X-Forwarded-Port": "443",
"X-Forwarded-Proto": "https"
},
"multiValueHeaders": {
"Connection": [
"upgrade"
],
"content-length": [
"0"
],
"HeaderAuth1": [
"headerValue1"
],
"Host": [
"abcdef123.execute-api.us-east-1.amazonaws.com"
],
"Sec-WebSocket-Extensions": [
"permessage-deflate; client_max_window_bits"
],
"Sec-WebSocket-Key": [
"..."
],
"Sec-WebSocket-Version": [
"13"
],
"Upgrade": [
"websocket"
],
"X-Amzn-Trace-Id": [
"..."
],
"X-Forwarded-For": [
"..."
],
"X-Forwarded-Port": [
"443"
],
"X-Forwarded-Proto": [
"https"
]
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"multiValueQueryStringParameters": {
"QueryString1": [
"queryValue1"
]
},
"stageVariables": {},
"requestContext": {
"routeKey": "$connect",
"eventType": "CONNECT",
"extendedRequestId": "...",
"requestTime": "19/Jan/2023:21:13:26 +0000",
"messageDirection": "IN",
"stage": "default",
"connectedAt": 1674162806344,
"requestTimeEpoch": 1674162806345,
"identity": {
"sourceIp": "..."
},
"requestId": "...",
"domainName": "abcdef123.execute-api.us-east-1.amazonaws.com",
"connectionId": "...",
"apiId": "abcdef123"
}
}
```
Contoh berikut fungsi Lambda authorizer adalah WebSocket versi dari fungsi Lambda authorizer untuk REST di: APIs [Contoh tambahan fungsi otorisasi Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create)
------
#### [ Node.js ]
```
// A simple REQUEST authorizer example to demonstrate how to use request
// parameters to allow or deny a request. In this example, a request is
// authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter
// in the request context match the specified values of
// of 'headerValue1' and 'queryValue1' respectively.
export const handler = function(event, context, callback) {
console.log('Received event:', JSON.stringify(event, null, 2));
// Retrieve request parameters from the Lambda function input:
var headers = event.headers;
var queryStringParameters = event.queryStringParameters;
var stageVariables = event.stageVariables;
var requestContext = event.requestContext;
// Parse the input for the parameter values
var tmp = event.methodArn.split(':');
var apiGatewayArnTmp = tmp[5].split('/');
var awsAccountId = tmp[4];
var region = tmp[3];
var ApiId = apiGatewayArnTmp[0];
var stage = apiGatewayArnTmp[1];
var route = apiGatewayArnTmp[2];
// Perform authorization to return the Allow policy for correct parameters and
// the 'Unauthorized' error, otherwise.
var authResponse = {};
var condition = {};
condition.IpAddress = {};
if (headers.HeaderAuth1 === "headerValue1"
&& queryStringParameters.QueryString1 === "queryValue1") {
callback(null, generateAllow('me', event.methodArn));
} else {
callback(null, generateDeny('me', event.methodArn));
}
}
// Helper function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
// Required output:
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17 '; // default version
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke'; // default action
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
var generateAllow = function(principalId, resource) {
return generatePolicy(principalId, 'Allow', resource);
}
var generateDeny = function(principalId, resource) {
return generatePolicy(principalId, 'Deny', resource);
}
```
------
#### [ Python ]
```
# A simple REQUEST authorizer example to demonstrate how to use request
# parameters to allow or deny a request. In this example, a request is
# authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter
# in the request context match the specified values of
# of 'headerValue1' and 'queryValue1' respectively.
import json
def lambda_handler(event, context):
print(event)
# Retrieve request parameters from the Lambda function input:
headers = event['headers']
queryStringParameters = event['queryStringParameters']
stageVariables = event['stageVariables']
requestContext = event['requestContext']
# Parse the input for the parameter values
tmp = event['methodArn'].split(':')
apiGatewayArnTmp = tmp[5].split('/')
awsAccountId = tmp[4]
region = tmp[3]
ApiId = apiGatewayArnTmp[0]
stage = apiGatewayArnTmp[1]
route = apiGatewayArnTmp[2]
# Perform authorization to return the Allow policy for correct parameters
# and the 'Unauthorized' error, otherwise.
authResponse = {}
condition = {}
condition['IpAddress'] = {}
if (headers['HeaderAuth1'] ==
"headerValue1" and queryStringParameters["QueryString1"] == "queryValue1"):
response = generateAllow('me', event['methodArn'])
print('authorized')
return json.loads(response)
else:
response = generateDeny('me', event['methodArn'])
print('unauthorized')
return json.loads(response)
# Help function to generate IAM policy
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17 '
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
authResponse_JSON = json.dumps(authResponse)
return authResponse_JSON
def generateAllow(principalId, resource):
return generatePolicy(principalId, 'Allow', resource)
def generateDeny(principalId, resource):
return generatePolicy(principalId, 'Deny', resource)
```
------
[Untuk mengonfigurasi fungsi Lambda sebelumnya sebagai fungsi `REQUEST` otorisasi untuk WebSocket API, ikuti prosedur yang sama seperti REST. APIs](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console)
Untuk mengonfigurasi `$connect` rute untuk menggunakan otorisasi Lambda ini di konsol, pilih atau buat rute. `$connect` Di bagian **Pengaturan permintaan rute**, pilih **Edit**. **Pilih otorisasi Anda di menu tarik-turun **Otorisasi**, lalu pilih Simpan perubahan.**
Untuk menguji otorisasi, Anda perlu membuat koneksi baru. Mengubah otorisasi `$connect` tidak memengaruhi klien yang sudah terhubung. Saat Anda terhubung ke WebSocket API, Anda perlu memberikan nilai untuk sumber identitas yang dikonfigurasi. Misalnya, Anda dapat terhubung dengan mengirimkan string kueri dan header yang valid menggunakan `wscat` seperti pada contoh berikut:
```
wscat -c 'wss://myapi.execute-api.us-east-1.amazonaws.com/beta?QueryString1=queryValue1' -H HeaderAuth1:headerValue1
```
Jika Anda mencoba untuk terhubung tanpa nilai identitas yang valid, Anda akan menerima `401` tanggapan:
```
wscat -c wss://myapi.execute-api.us-east-1.amazonaws.com/beta
error: Unexpected server response: 401
```
# Integrasi untuk WebSocket APIs di API Gateway
Setelah menyiapkan rute API, Anda harus mengintegrasikannya dengan titik akhir di backend. Endpoint backend juga disebut sebagai titik akhir integrasi dan dapat berupa fungsi Lambda, titik akhir HTTP, atau tindakan layanan. AWS Integrasi API memiliki permintaan integrasi dan respons integrasi.
Di bagian ini, Anda dapat mempelajari cara menyiapkan permintaan integrasi dan respons integrasi untuk WebSocket API Anda.
**Topics**
+ [Menyiapkan permintaan integrasi WebSocket API di API Gateway](apigateway-websocket-api-integration-requests.md)
+ [Menyiapkan respons integrasi WebSocket API di API Gateway](apigateway-websocket-api-integration-responses.md)
# Menyiapkan permintaan integrasi WebSocket API di API Gateway
Menyiapkan permintaan integrasi melibatkan hal-hal berikut:
+ Memilih kunci rute untuk diintegrasikan ke backend.
+ Menentukan titik akhir backend untuk dipanggil. WebSocket APIs mendukung jenis integrasi berikut:
+ `AWS_PROXY`
+ `AWS`
+ `HTTP_PROXY`
+ `HTTP`
+ `MOCK`
Untuk informasi selengkapnya tentang jenis integrasi, lihat [IntegrationType](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)di API REST API Gateway V2.
+ Mengkonfigurasi cara mengubah data permintaan rute, jika perlu, menjadi data permintaan integrasi dengan menentukan satu atau beberapa templat permintaan.
## Menyiapkan permintaan integrasi WebSocket API menggunakan konsol API Gateway
**Untuk menambahkan permintaan integrasi ke rute di WebSocket API menggunakan konsol API Gateway**
1. Masuk ke konsol API Gateway, pilih API, dan pilih **Rute**.
1. Di bawah **Rute**, pilih rute.
1. Pilih tab **Permintaan integrasi**, dan kemudian di bagian **Pengaturan permintaan integrasi**, pilih **Edit**.
1. Untuk **jenis Integrasi**, pilih salah satu dari berikut ini:
+ Pilih **fungsi Lambda** hanya jika API Anda akan diintegrasikan dengan AWS Lambda fungsi yang telah Anda buat di akun ini atau di akun lain.
**Untuk membuat fungsi Lambda baru di AWS Lambda, untuk menetapkan izin sumber daya pada fungsi Lambda, atau untuk melakukan tindakan layanan Lambda lainnya, pilih Layanan sebagai gantinya.AWS **
+ Pilih **HTTP** jika API Anda akan terintegrasi dengan titik akhir HTTP yang ada. Untuk informasi selengkapnya, lihat [Integrasi HTTP untuk REST APIs di API Gateway](setup-http-integrations.md).
+ Pilih **Mock** jika Anda ingin menghasilkan respons API dari API Gateway secara langsung, tanpa perlu backend integrasi. Untuk informasi selengkapnya, lihat [Integrasi tiruan untuk REST APIs di API Gateway](how-to-mock-integration.md).
+ Pilih **AWS layanan** jika API Anda akan terintegrasi dengan AWS layanan.
+ Pilih **tautan VPC** jika API Anda akan menggunakan titik akhir integrasi `VpcLink` sebagai pribadi. Untuk informasi selengkapnya, lihat [Siapkan integrasi pribadi](set-up-private-integration.md).
1. Jika Anda memilih **fungsi Lambda**, lakukan hal berikut:
1. [Untuk **Menggunakan integrasi proxy Lambda**, pilih kotak centang jika Anda ingin menggunakan integrasi proxy Lambda [atau integrasi proxy Lambda](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy) lintas akun.](apigateway-cross-account-lambda-integrations.md)
1. Untuk **fungsi Lambda**, tentukan fungsi dengan salah satu cara berikut:
+ Jika fungsi Lambda Anda berada di akun yang sama, masukkan nama fungsi dan kemudian pilih fungsi dari daftar dropdown.
**catatan**
Nama fungsi secara opsional dapat menyertakan alias atau spesifikasi versinya, seperti dalam, `HelloWorld``HelloWorld:1`, atau. `HelloWorld:alpha`
+ Jika fungsinya ada di akun yang berbeda, masukkan ARN untuk fungsi tersebut.
1. Untuk menggunakan nilai batas waktu default 29 detik, tetap aktifkan **batas waktu default**. Untuk menetapkan batas waktu kustom, pilih Batas **waktu default** dan masukkan nilai batas waktu antara `50` dan milidetik. `29000`
1. Jika Anda memilih **HTTP**, ikuti petunjuk di langkah 4 dari[Menyiapkan permintaan integrasi API menggunakan konsol API Gateway](how-to-method-settings-console.md).
1. Jika Anda memilih **Mock**, lanjutkan ke langkah **Permintaan Template**.
1. Jika Anda memilih **AWS layanan**, ikuti instruksi pada langkah 6 dari[Menyiapkan permintaan integrasi API menggunakan konsol API Gateway](how-to-method-settings-console.md).
1. Jika Anda memilih **tautan VPC**, lakukan hal berikut:
1. Untuk **integrasi proxy VPC**, pilih kotak centang jika Anda ingin permintaan Anda diproksi ke titik akhir Anda. `VPCLink`
1. Untuk **metode HTTP**, pilih jenis metode HTTP yang paling cocok dengan metode di backend HTTP.
1. Dari daftar dropdown **tautan VPC**, pilih tautan VPC. Anda dapat memilih `[Use Stage Variables]` dan memasukkan **\$1\$1stageVariables.vpcLinkId\$1** dalam kotak teks di bawah daftar.
Anda dapat menentukan variabel `vpcLinkId` stage setelah menerapkan API ke tahap dan menetapkan nilainya ke ID. `VpcLink`
1. Untuk **URL Endpoint**, masukkan URL backend HTTP yang ingin digunakan integrasi ini.
1. Untuk menggunakan nilai batas waktu default 29 detik, tetap aktifkan **batas waktu default**. Untuk menetapkan batas waktu kustom, pilih Batas **waktu default** dan masukkan nilai batas waktu antara `50` dan milidetik. `29000`
1. Pilih **Simpan perubahan**.
1. Di bawah **templat Permintaan**, lakukan hal berikut:
1. Untuk memasukkan **ekspresi pemilihan Template**, di bawah **Permintaan template**, pilih **Edit**.
1. Masukkan **ekspresi pemilihan Template**. Gunakan ekspresi yang dicari API Gateway di payload pesan. Jika ditemukan, itu dievaluasi, dan hasilnya adalah nilai kunci template yang digunakan untuk memilih template pemetaan data yang akan diterapkan ke data dalam payload pesan. Anda membuat template pemetaan data di langkah berikutnya. Pilih **Edit** untuk menyimpan perubahan Anda.
1. Pilih **Buat template** untuk membuat template pemetaan data. Untuk **kunci Template**, masukkan nilai kunci template yang digunakan untuk memilih template pemetaan data yang akan diterapkan ke data dalam payload pesan. Kemudian, masukkan template pemetaan. Pilih **Buat templat**.
Untuk informasi tentang ekspresi pemilihan templat, lihat[Ekspresi pemilihan template](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions).
## Siapkan permintaan integrasi menggunakan AWS CLI
Anda dapat menyiapkan permintaan integrasi untuk rute di WebSocket API dengan menggunakan AWS CLI seperti pada contoh berikut, yang membuat integrasi tiruan:
1. Buat file bernama`integration-params.json`, dengan konten berikut:
```
{"PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "RequestTemplates": {"application/json": "{\"statusCode\":200}"}, "IntegrationType": "MOCK"}
```
1. Gunakan perintah [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) berikut untuk membuat integrasi tiruan.
```
aws apigatewayv2 --region us-east-1 create-integration --api-id aabbccddee --cli-input-json file://integration-params.json
```
Outputnya akan terlihat seperti berikut:
```
{
"PassthroughBehavior": "WHEN_NO_MATCH",
"TimeoutInMillis": 29000,
"ConnectionType": "INTERNET",
"IntegrationResponseSelectionExpression": "${response.statuscode}",
"RequestTemplates": {
"application/json": "{\"statusCode\":200}"
},
"IntegrationId": "0abcdef",
"IntegrationType": "MOCK"
}
```
Atau, Anda dapat mengatur permintaan integrasi untuk integrasi proxy dengan menggunakan AWS CLI.
1. Buat fungsi Lambda di konsol Lambda dan berikan peran eksekusi Lambda dasar.
1. Gunakan perintah [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) berikut untuk membuat integrasi.
```
aws apigatewayv2 create-integration --api-id aabbccddee --integration-type AWS_PROXY --integration-method POST --integration-uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations
```
Outputnya akan terlihat seperti berikut:
```
{
"PassthroughBehavior": "WHEN_NO_MATCH",
"IntegrationMethod": "POST",
"TimeoutInMillis": 29000,
"ConnectionType": "INTERNET",
"IntegrationUri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations",
"IntegrationId": "abcdefg",
"IntegrationType": "AWS_PROXY"
}
```
## Format input fungsi Lambda untuk integrasi proxy untuk WebSocket APIs
Dalam integrasi proxy Lambda, API Gateway memetakan seluruh permintaan klien ke `event` parameter input fungsi Lambda backend. Contoh berikut menunjukkan struktur peristiwa masukan dari `$connect` rute dan peristiwa masukan dari rute yang dikirimkan API Gateway ke integrasi proxy Lambda. `$disconnect`
------
#### [ Input from the \$1connect route ]
```
{
headers: {
Host: 'abcd123.execute-api.us-east-1.amazonaws.com',
'Sec-WebSocket-Extensions': 'permessage-deflate; client_max_window_bits',
'Sec-WebSocket-Key': '...',
'Sec-WebSocket-Version': '13',
'X-Amzn-Trace-Id': '...',
'X-Forwarded-For': '192.0.2.1',
'X-Forwarded-Port': '443',
'X-Forwarded-Proto': 'https'
},
multiValueHeaders: {
Host: [ 'abcd123.execute-api.us-east-1.amazonaws.com' ],
'Sec-WebSocket-Extensions': [ 'permessage-deflate; client_max_window_bits' ],
'Sec-WebSocket-Key': [ '...' ],
'Sec-WebSocket-Version': [ '13' ],
'X-Amzn-Trace-Id': [ '...' ],
'X-Forwarded-For': [ '192.0.2.1' ],
'X-Forwarded-Port': [ '443' ],
'X-Forwarded-Proto': [ 'https' ]
},
requestContext: {
routeKey: '$connect',
eventType: 'CONNECT',
extendedRequestId: 'ABCD1234=',
requestTime: '09/Feb/2024:18:11:43 +0000',
messageDirection: 'IN',
stage: 'prod',
connectedAt: 1707502303419,
requestTimeEpoch: 1707502303420,
identity: { sourceIp: '192.0.2.1' },
requestId: 'ABCD1234=',
domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
connectionId: 'AAAA1234=',
apiId: 'abcd1234'
},
isBase64Encoded: false
}
```
------
#### [ Input from the \$1disconnect route ]
```
{
headers: {
Host: 'abcd1234.execute-api.us-east-1.amazonaws.com',
'x-api-key': '',
'X-Forwarded-For': '',
'x-restapi': ''
},
multiValueHeaders: {
Host: [ 'abcd1234.execute-api.us-east-1.amazonaws.com' ],
'x-api-key': [ '' ],
'X-Forwarded-For': [ '' ],
'x-restapi': [ '' ]
},
requestContext: {
routeKey: '$disconnect',
disconnectStatusCode: 1005,
eventType: 'DISCONNECT',
extendedRequestId: 'ABCD1234=',
requestTime: '09/Feb/2024:18:23:28 +0000',
messageDirection: 'IN',
disconnectReason: 'Client-side close frame status not set',
stage: 'prod',
connectedAt: 1707503007396,
requestTimeEpoch: 1707503008941,
identity: { sourceIp: '192.0.2.1' },
requestId: 'ABCD1234=',
domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
connectionId: 'AAAA1234=',
apiId: 'abcd1234'
},
isBase64Encoded: false
}
```
------
# Menyiapkan respons integrasi WebSocket API di API Gateway
Bagian berikut memberikan gambaran singkat tentang respons integrasi untuk WebSocket API dan cara menyiapkan respons integrasi untuk WebSocket API.
**Topics**
+ [Ikhtisar tanggapan integrasi](#apigateway-websocket-api-integration-response-overview)
+ [Respons integrasi untuk komunikasi dua arah](#apigateway-websocket-api-integration-response-for-two-way-communication)
+ [Menyiapkan respons integrasi menggunakan konsol API Gateway](#apigateway-websocket-api-integration-response-using-console)
+ [Siapkan respons integrasi menggunakan AWS CLI](#apigateway-websocket-api-integration-response-using-awscli)
## Ikhtisar tanggapan integrasi
Respons integrasi API Gateway adalah cara memodelkan dan memanipulasi respons dari layanan backend. Ada beberapa perbedaan dalam penyiapan REST API versus respons integrasi WebSocket API, tetapi secara konseptual perilakunya sama.
WebSocket rute dapat dikonfigurasi untuk komunikasi dua arah atau satu arah.
+ Saat rute dikonfigurasi untuk komunikasi dua arah, respons integrasi memungkinkan Anda mengonfigurasi transformasi pada muatan pesan yang dikembalikan, mirip dengan respons integrasi untuk REST. APIs
+ Jika rute dikonfigurasi untuk komunikasi satu arah, maka terlepas dari konfigurasi respons integrasi apa pun, tidak ada respons yang akan dikembalikan melalui WebSocket saluran setelah pesan diproses.
API Gateway tidak akan meneruskan respons backend ke respons rute, kecuali jika Anda menyiapkan respons rute. Untuk mempelajari cara menyiapkan respons rute, lihat[Siapkan respons rute untuk WebSocket APIs di API Gateway](apigateway-websocket-api-route-response.md).
## Respons integrasi untuk komunikasi dua arah
Integrasi dapat dibagi menjadi integrasi *proxy* dan integrasi *non-proxy*.
**penting**
Untuk *integrasi proxy*, API Gateway secara otomatis meneruskan output backend ke pemanggil sebagai muatan lengkap. Tidak ada respon integrasi.
Untuk *integrasi non-proxy*, Anda harus menyiapkan setidaknya satu respons integrasi:
+ Idealnya, salah satu tanggapan integrasi Anda harus bertindak sebagai tangkapan semua ketika tidak ada pilihan eksplisit yang dapat dibuat. Kasus default ini diwakili dengan menyetel kunci respons integrasi dari`$default`.
+ Dalam semua kasus lain, kunci respons integrasi berfungsi sebagai ekspresi reguler. Ini harus mengikuti format`"/expression/"`.
Untuk integrasi HTTP non-proxy:
+ API Gateway akan mencoba mencocokkan kode status HTTP dari respons backend. Tombol respons integrasi akan berfungsi sebagai ekspresi reguler dalam kasus ini. Jika kecocokan tidak dapat ditemukan, `$default` maka dipilih sebagai respons integrasi.
+ Ekspresi pemilihan template, seperti dijelaskan di atas, berfungsi secara identik. Contoh:
+ `/2\d\d/`: Menerima dan mengubah tanggapan yang berhasil
+ `/4\d\d/`: Menerima dan mengubah kesalahan permintaan yang buruk
+ `$default`: Menerima dan mengubah semua tanggapan tak terduga
Untuk informasi selengkapnya tentang ekspresi pemilihan templat, lihat[Ekspresi pemilihan template](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions).
## Menyiapkan respons integrasi menggunakan konsol API Gateway
Untuk menyiapkan respons integrasi rute untuk WebSocket API menggunakan konsol API Gateway:
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih WebSocket API Anda dan pilih rute Anda.
1. Pilih tab **Permintaan integrasi**, dan kemudian di bagian **Pengaturan respons integrasi**, pilih **Buat respons integrasi**.
1. Untuk **tombol Respons**, masukkan nilai yang akan ditemukan di kunci respons dalam pesan keluar setelah mengevaluasi ekspresi pemilihan respons. Misalnya, Anda dapat memasukkan **/4\$1d\$1d/** untuk menerima dan mengubah kesalahan permintaan buruk atau masuk **\$1default** untuk menerima dan mengubah semua respons yang cocok dengan ekspresi pemilihan templat.
1. Untuk **ekspresi pemilihan Template**, masukkan ekspresi seleksi untuk mengevaluasi pesan keluar.
1. Pilih **Buat respons**.
1. Anda juga dapat menentukan template pemetaan untuk mengonfigurasi transformasi payload pesan yang dikembalikan. Pilih **Buat templat**.
1. Masukkan nama kunci. Jika Anda memilih ekspresi pemilihan template default, masukkan**\$1\$1default**.
1. Untuk **template Response**, masukkan template pemetaan Anda di editor kode.
1. Pilih **Buat templat**.
1. Pilih **Deploy API** untuk menerapkan API Anda.
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
```
Saat Anda memanggil rute Anda, muatan pesan yang dikembalikan akan kembali.
## Siapkan respons integrasi menggunakan AWS CLI
[create-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration-response.html)Perintah berikut menciptakan respons `$default` integrasi:
```
aws apigatewayv2 create-integration-response \
--api-id vaz7da96z6 \
--integration-id a1b2c3 \
--integration-response-key '$default'
```
# Minta validasi untuk WebSocket APIs di API Gateway
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 gateway “Badan permintaan buruk” ke klien, dan menerbitkan hasil validasi di Log. CloudWatch Menggunakan validasi dengan cara ini mengurangi panggilan yang tidak perlu ke backend API Anda.
## Ekspresi pemilihan model
Anda dapat menggunakan ekspresi pemilihan model untuk memvalidasi permintaan secara dinamis dalam rute yang sama. Validasi model terjadi jika Anda memberikan ekspresi pemilihan model untuk integrasi proxy atau non-proxy. Anda mungkin perlu mendefinisikan `$default` model sebagai fallback ketika tidak ada model yang cocok ditemukan. Jika tidak ada model yang cocok dan `$default` tidak ditentukan, validasi gagal. Ekspresi seleksi terlihat seperti `Route.ModelSelectionExpression` dan mengevaluasi kunci untuk`Route.RequestModels`.
Saat menentukan rute untuk WebSocket API, Anda dapat menentukan *ekspresi pemilihan model* secara opsional. Ekspresi ini dievaluasi untuk memilih model yang akan digunakan untuk validasi tubuh ketika permintaan diterima. Ekspresi mengevaluasi ke salah satu entri dalam rute. [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels)
Sebuah model dinyatakan sebagai [skema JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) dan menggambarkan struktur data dari badan permintaan. Sifat ekspresi seleksi ini memungkinkan Anda memilih model secara dinamis untuk divalidasi saat runtime untuk rute tertentu. Untuk informasi tentang cara membuat model, lihat[Model data untuk REST APIs](models-mappings-models.md).
## Menyiapkan validasi permintaan menggunakan konsol API Gateway
Contoh berikut menunjukkan cara mengatur validasi permintaan pada rute.
Pertama, Anda membuat model, dan kemudian Anda membuat rute. Selanjutnya, Anda mengonfigurasi validasi permintaan pada rute yang baru saja Anda buat. Terakhir, Anda menerapkan dan menguji API Anda. Untuk menyelesaikan tutorial ini, Anda memerlukan WebSocket API dengan `$request.body.action` ekspresi pemilihan rute dan titik akhir integrasi untuk rute baru Anda.
Anda juga `wscat` perlu terhubung ke API Anda. Untuk informasi selengkapnya, lihat [Gunakan `wscat` untuk terhubung ke WebSocket API dan mengirim pesan ke sana](apigateway-how-to-call-websocket-api-wscat.md).
**Untuk membuat model**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih WebSocket API.
1. Di panel navigasi utama, pilih **Model**.
1. Pilih **Buat model**.
1. Untuk **Nama**, masukkan **emailModel**.
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **skema Model**, masukkan model berikut:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type" : "object",
"required" : [ "address"],
"properties" : {
"address": {
"type": "string"
}
}
}
```
Model ini mengharuskan permintaan berisi alamat email.
1. Pilih **Simpan**.
Pada langkah ini, Anda membuat rute untuk WebSocket API Anda.
**Untuk membuat rute**
1. Di panel navigasi utama, pilih **Rute**.
1. Pilih **Buat rute**.
1. Untuk **kunci Rute**, masukkan**sendMessage**.
1. Pilih jenis integrasi dan tentukan titik akhir integrasi. Untuk mengetahui informasi selengkapnya, lihat [Integrasi untuk WebSocket APIs di API Gateway](apigateway-websocket-api-integrations.md).
1. Pilih **Buat rute**.
Pada langkah ini, Anda menyiapkan validasi permintaan untuk `sendMessage` rute tersebut.
**Untuk mengatur validasi permintaan**
1. Pada tab **Permintaan rute**, di bawah **Pengaturan permintaan rute**, pilih **Edit**.
1. Untuk **ekspresi pemilihan Model**, masukkan**\$1\$1request.body.messageType\$1**.
API Gateway menggunakan `messageType` properti untuk memvalidasi permintaan yang masuk.
1. Pilih **Tambahkan model permintaan**.
1. Untuk **kunci Model**, masukkan**email**.
1. Untuk **Model**, pilih **EmailModel**.
API Gateway memvalidasi pesan masuk dengan `messageType` properti yang disetel ke `email` terhadap model ini.
**catatan**
Jika API Gateway tidak dapat mencocokkan ekspresi pemilihan model dengan kunci model, maka ia memilih `$default` model. Jika tidak ada `$default` model, maka validasi gagal. Untuk produksi APIs, kami sarankan Anda membuat `$default` model.
1. Pilih **Simpan perubahan**.
Pada langkah ini, Anda menerapkan dan menguji API Anda.
**Untuk menerapkan dan menguji API Anda**
1. Pilih **Deploy API**.
1. Pilih tahap yang diinginkan dari daftar dropdown atau masukkan nama tahap baru.
1. Pilih **Deploy**.
1. Di panel navigasi utama, pilih **Tahapan**.
1. Salin WebSocket URL API Anda. URL akan terlihat seperti `wss://abcdef123.execute-api.us-east-2.amazonaws.com/production`.
1. Buka terminal baru dan jalankan **wscat** perintah dengan parameter berikut.
```
wscat -c wss://abcdef123.execute-api.us-west-2.amazonaws.com/production
```
```
Connected (press CTRL+C to quit)
```
1. Gunakan perintah berikut untuk menguji API Anda.
```
{"action": "sendMessage", "messageType": "email"}
```
```
{"message": "Invalid request body", "connectionId":"ABCD1=234", "requestId":"EFGH="}
```
API Gateway akan gagal permintaan.
Gunakan perintah berikutnya untuk mengirim permintaan yang valid ke API Anda.
```
{"action": "sendMessage", "messageType": "email", "address": "mary_major@example.com"}
```
# Transformasi data untuk WebSocket APIs di API Gateway
Di API Gateway, permintaan metode WebSocket API dapat mengambil payload dalam format yang berbeda dari payload permintaan integrasi yang sesuai, seperti yang diperlukan di backend. Demikian pula, backend dapat mengembalikan payload respons integrasi yang berbeda dari payload respons metode, seperti yang diharapkan oleh frontend.
API Gateway memungkinkan Anda menggunakan transformasi template pemetaan untuk memetakan payload dari permintaan metode ke permintaan integrasi yang sesuai dan dari respons integrasi ke respons metode yang sesuai. Anda membuat template pemetaan dan Anda menentukan ekspresi pemilihan template untuk menentukan template mana yang akan digunakan untuk melakukan transformasi data yang diperlukan.
Anda dapat menggunakan pemetaan data untuk memetakan data dari [permintaan rute ke integrasi](api-gateway-basic-concept.md#apigateway-definition-route-request) backend. Untuk mempelajari selengkapnya, lihat [Mengatur pemetaan data WebSocket APIs di API Gateway](websocket-api-data-mapping.md).
## Memetakan template dan model
*Template pemetaan* [adalah skrip yang dinyatakan dalam [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) dan diterapkan pada payload menggunakan ekspresi. JSONPath ](https://goessner.net/articles/JsonPath/) Untuk informasi selengkapnya tentang template pemetaan API Gateway, lihat[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
Muatan dapat memiliki *model data* sesuai dengan rancangan [skema JSON 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04). Anda tidak perlu mendefinisikan model untuk membuat template pemetaan. Namun, model dapat membantu Anda membuat template karena API Gateway menghasilkan cetak biru template berdasarkan model yang disediakan. Untuk informasi selengkapnya tentang model API Gateway, lihat[Model data untuk REST APIs](models-mappings-models.md).
## Ekspresi pemilihan template
Untuk mengubah payload dengan template pemetaan, Anda menentukan ekspresi pemilihan template WebSocket API dalam [permintaan integrasi atau respons](apigateway-websocket-api-integration-requests.md) [integrasi](apigateway-websocket-api-integration-responses.md). Ekspresi ini dievaluasi untuk menentukan template input atau output (jika ada) yang akan digunakan untuk mengubah badan permintaan menjadi badan permintaan integrasi (melalui template input) atau badan respons integrasi ke badan respons rute (melalui template keluaran).
`Integration.TemplateSelectionExpression`mendukung `${request.body.jsonPath}` dan nilai statis.
`IntegrationResponse.TemplateSelectionExpression`mendukung`${request.body.jsonPath}`,`${integration.response.statuscode}`,`${integration.response.header.headerName}`,`${integration.response.multivalueheader.headerName}`, dan nilai-nilai statis.
## Ekspresi pemilihan respons integrasi
Saat [menyiapkan respons integrasi](apigateway-websocket-api-integration-responses.md) untuk WebSocket API, Anda dapat menentukan ekspresi pemilihan respons integrasi secara opsional. Ekspresi ini menentukan apa yang `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` harus dipilih ketika integrasi kembali. Nilai ekspresi ini saat ini dibatasi oleh API Gateway, seperti yang didefinisikan di bawah ini. Sadarilah bahwa ekspresi ini hanya relevan untuk *integrasi non-proxy; integrasi* proxy hanya meneruskan payload respons kembali ke pemanggil tanpa pemodelan atau modifikasi.
Tidak seperti ekspresi seleksi sebelumnya lainnya, ekspresi ini saat ini mendukung format *pencocokan pola*. Ekspresi harus dibungkus dengan garis miring ke depan.
Saat ini nilainya tetap tergantung pada`[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`:
+ Untuk integrasi berbasis Lambda, memang demikian. `$integration.response.body.errorMessage`
+ Untuk `HTTP` dan `MOCK` integrasi, itu`$integration.response.statuscode`.
+ Untuk `HTTP_PROXY` dan`AWS_PROXY`, ungkapan tidak digunakan karena Anda meminta agar payload diteruskan ke penelepon.
# Mengatur pemetaan data WebSocket APIs di API Gateway
*Pemetaan data* memungkinkan Anda memetakan data dari [permintaan rute ke integrasi](api-gateway-basic-concept.md#apigateway-definition-route-request) backend.
**catatan**
Pemetaan data untuk WebSocket APIs tidak didukung di. Konsol Manajemen AWS Anda harus menggunakan AWS CLI, AWS CloudFormation, atau SDK untuk mengonfigurasi pemetaan data.
**Topics**
+ [Petakan data permintaan rute ke parameter permintaan integrasi](#websocket-mapping-request-parameters)
+ [Contoh](#websocket-data-mapping-examples)
## Petakan data permintaan rute ke parameter permintaan integrasi
Parameter permintaan integrasi dapat dipetakan dari parameter permintaan rute yang ditentukan, badan permintaan, [`context`atau [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference)](api-gateway-mapping-template-reference.md#context-variable-reference)variabel, dan nilai statis.
Tabel berikut menunjukkan ekspresi pemetaan data permintaan integrasi. Dalam tabel, *`PARAM_NAME`* adalah nama parameter permintaan rute dari jenis parameter yang diberikan. Itu harus cocok dengan ekspresi reguler`'^[a-zA-Z0-9._$-]+$]'`. *JSONPath\$1EXPRESSION*adalah JSONPath ekspresi untuk bidang JSON dari badan permintaan.
| Sumber data yang dipetakan | Ekspresi pemetaan |
| --- | --- |
| Minta string kueri (hanya didukung untuk \$1connect rute) | route.request.querystring.PARAM\$1NAME |
| Permintaan header (didukung hanya untuk \$1connect rute) | route.request.header.PARAM\$1NAME |
| String kueri permintaan multi-nilai (hanya didukung untuk \$1connect rute) | route.request.multivaluequerystring.PARAM\$1NAME |
| Header permintaan multi-nilai (hanya didukung untuk \$1connect rute) | route.request.multivalueheader.PARAM\$1NAME |
| Isi permintaan | route.request.body.JSONPath\$1EXPRESSION |
| Variabel tahap | stageVariables.VARIABLE\$1NAME |
| Variabel konteks | context.VARIABLE\$1NAMEyang harus menjadi salah satu [variabel konteks yang didukung](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Nilai statis | 'STATIC\$1VALUE'. STATIC\$1VALUEIni adalah string literal dan harus diapit dalam tanda kutip tunggal. |
Saat Anda membuat pemetaan data, gunakan AWS CLI pastikan untuk mengikuti format yang benar untuk menggunakan literal dengan string di. AWS CLI*Untuk informasi selengkapnya, lihat [Menggunakan tanda kutip dan literal dengan string AWS CLI di Panduan](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) Pengguna.AWS Command Line Interface *
## Contoh
AWS CLI Contoh berikut mengkonfigurasi pemetaan data. Untuk contoh CloudFormation template, lihat [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip).
### Memetakan ConnectionId klien ke header dalam permintaan integrasi
Perintah [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) berikut memetakan klien `connectionId` ke `connectionId` header dalam permintaan ke integrasi backend:
```
aws apigatewayv2 update-integration \
--integration-id abc123 \
--api-id a1b2c3d4 \
--request-parameters 'integration.request.header.connectionId'='context.connectionId'
```
### Petakan parameter string kueri ke header dalam permintaan integrasi
Contoh berikut memetakan parameter string `authToken` query ke `authToken` header dalam permintaan integrasi.
1. Gunakan perintah [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) berikut untuk menambahkan parameter string `authToken` kueri ke parameter permintaan rute.
```
aws apigatewayv2 update-route --route-id 0abcdef \
--api-id a1b2c3d4 \
--request-parameters '{"route.request.querystring.authToken": {"Required": false}}'
```
1. Gunakan perintah [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) berikut untuk memetakan parameter string query ke `authToken` header dalam permintaan untuk integrasi backend.
```
aws apigatewayv2 update-integration \
--integration-id abc123 \
--api-id a1b2c3d4 \
--request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken'
```
1. (Opsional) Jika perlu, gunakan yang berikut ini [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html)untuk menghapus parameter string `authToken` kueri dari parameter permintaan rute.
```
aws apigatewayv2 delete-route-request-parameter \
--route-id 0abcdef \
--api-id a1b2c3d4 \
--request-parameter-key 'route.request.querystring.authToken'
```
# WebSocket Referensi template pemetaan API untuk API Gateway
Bagian ini merangkum kumpulan variabel yang saat ini didukung WebSocket APIs di API Gateway.
| Parameter | Deskripsi |
| --- | --- |
| \$1context.connectionId | ID unik untuk koneksi yang dapat digunakan untuk membuat callback ke klien. |
| \$1context.connectedAt | Waktu koneksi yang diformat [Epoch](https://en.wikipedia.org/wiki/Unix_time). |
| \$1context.domainName | Nama domain untuk WebSocket API. Ini dapat digunakan untuk membuat callback ke klien (bukan nilai hard-code). |
| \$1context.eventType | Jenis acara:`CONNECT`,`MESSAGE`, atau`DISCONNECT`. |
| \$1context.messageId | ID sisi server unik untuk pesan. Hanya tersedia ketika `$context.eventType` ada`MESSAGE`. |
| \$1context.routeKey | Kunci rute yang dipilih. |
| \$1context.requestId | Sama seperti`$context.extendedRequestId`. |
| \$1context.extendedRequestId | ID yang dibuat secara otomatis untuk panggilan API, yang berisi informasi yang lebih berguna untuk debugging/pemecahan masalah. |
| \$1context.apiId | API Gateway identifier ditetapkan ke API Anda. |
| \$1context.authorizer.principalId | Identifikasi pengguna utama yang terkait dengan token yang dikirim oleh klien dan dikembalikan dari fungsi Lambda Lambda API Gateway (sebelumnya dikenal sebagai otorisasi khusus). |
| \$1context.authorizer.property | Nilai stringifikasi dari pasangan nilai kunci `context` peta yang ditentukan dikembalikan dari fungsi otorisasi API Gateway Lambda. Misalnya, jika otorisasi mengembalikan `context` peta berikut: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} memanggil `$context.authorizer.key` mengembalikan `"value"` string, memanggil `$context.authorizer.numKey` mengembalikan `"1"` string, dan memanggil `$context.authorizer.boolKey` mengembalikan `"true"` string. |
| \$1context.error.messageString | Nilai yang dikutip dari\$1context.error.message, yaitu"\$1context.error.message". |
| \$1context.error.validationErrorString | Sebuah string yang berisi pesan kesalahan validasi rinci. |
| \$1context.identity.accountId | ID AWS akun yang terkait dengan permintaan. |
| \$1context.identity.apiKey | Kunci pemilik API yang terkait dengan permintaan API berkemampuan kunci. |
| \$1context.identity.apiKeyId | ID kunci API yang terkait dengan permintaan API berkemampuan kunci |
| \$1context.identity.caller | Pengidentifikasi utama penelepon yang membuat permintaan. |
| \$1context.identity.cognitoAuthenticationProvider | Daftar dipisahkan koma dari semua penyedia otentikasi Amazon Cognito yang digunakan oleh penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Misalnya, untuk identitas dari kumpulan pengguna Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` *Untuk informasi tentang penyedia autentikasi Amazon Cognito yang tersedia, lihat [Menggunakan Identitas Federasi di Panduan Pengembang](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) Amazon Cognito.* |
| \$1context.identity.cognitoAuthenticationType | Jenis otentikasi Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Nilai yang mungkin termasuk `authenticated` untuk identitas yang diautentikasi dan `unauthenticated` untuk identitas yang tidak diautentikasi. |
| \$1context.identity.cognitoIdentityId | ID identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID kumpulan identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. |
| \$1context.identity.sourceIp | Alamat IP sumber koneksi TCP langsung membuat permintaan ke titik akhir API Gateway. |
| \$1context.identity.user | Pengidentifikasi utama pengguna yang membuat permintaan. |
| \$1context.identity.userAgent | Agen Pengguna pemanggil API. |
| \$1context.identity.userArn | Nama Sumber Daya Amazon (ARN) dari pengguna efektif yang diidentifikasi setelah otentikasi. |
| \$1context.requestTime | Waktu permintaan yang diformat [CLF](https://httpd.apache.org/docs/current/logs.html#common) (). dd/MMM/yyyy:HH:mm:ss \$1-hhmm |
| \$1context.requestTimeEpoch | Waktu permintaan yang diformat [Epoch](https://en.wikipedia.org/wiki/Unix_time), dalam milidetik. |
| \$1context.stage | Tahap penerapan panggilan API (misalnya, Beta atau Prod). |
| \$1context.status | Status respons. |
| \$1input.body | Mengembalikan payload mentah sebagai string. |
| \$1input.json(x) | Fungsi ini mengevaluasi JSONPath ekspresi dan mengembalikan hasil sebagai string JSON. Misalnya, `$input.json('$.pets')` akan mengembalikan string JSON yang mewakili struktur hewan peliharaan. Untuk informasi selengkapnya tentang JSONPath, lihat [JSONPath](https://goessner.net/articles/JsonPath/)atau [JSONPath untuk Java](https://github.com/json-path/JsonPath). |
| \$1input.path(x) | Mengambil JSONPath ekspresi string (`x`) dan mengembalikan representasi objek JSON dari hasil. Ini memungkinkan Anda untuk mengakses dan memanipulasi elemen payload secara native di [Apache Velocity Template](https://velocity.apache.org/engine/devel/vtl-reference.html) Language (VTL). Misalnya, jika ekspresi `$input.path('$.pets')` mengembalikan objek seperti ini: [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').count()`akan kembali`"3"`. Untuk informasi selengkapnya tentang JSONPath, lihat [JSONPath](http://goessner.net/articles/JsonPath/)atau [JSONPath untuk Java](https://github.com/jayway/JsonPath). |
| \$1stageVariables. | **merupakan nama variabel tahap. |
| \$1stageVariables[''] | **mewakili setiap nama variabel tahap. |
| \$1\$1stageVariables['']\$1 | **mewakili setiap nama variabel tahap. |
| \$1util.escapeJavaScript() | Melarikan diri dari karakter dalam string menggunakan aturan JavaScript string. Fungsi ini akan mengubah tanda kutip tunggal biasa (`'`) menjadi yang keluar (`\'`). Namun, tanda kutip tunggal yang lolos tidak valid di JSON. Jadi, ketika output dari fungsi ini digunakan dalam properti JSON, Anda harus mengubah tanda kutip tunggal yang diloloskan (`\'`) kembali ke tanda kutip tunggal biasa (`'`). Ini ditunjukkan dalam contoh berikut: $util.escapeJavaScript(data).replaceAll("\\'","'") |
| \$1util.parseJson() | Mengambil “stringified” JSON dan mengembalikan representasi objek dari hasilnya. Anda dapat menggunakan hasil dari fungsi ini untuk mengakses dan memanipulasi elemen payload secara native di Apache Velocity Template Language (VTL). Misalnya, jika Anda memiliki muatan berikut: {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} dan gunakan template pemetaan berikut #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Anda akan mendapatkan output sebagai berikut: {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | Mengkonversi string ke dalam format “aplikasi/x-www-form-urlencoded”. |
| \$1util.urlDecode() | Mendekode string “aplikasi/x-www-form-urlencoded”. |
| \$1util.base64Encode() | Mengkodekan data ke dalam string yang dikodekan base64. |
| \$1util.base64Decode() | Mendekode data dari string yang dikodekan base64. |
# Jenis media biner untuk WebSocket APIs di API Gateway
API Gateway saat ini WebSocket APIs tidak mendukung bingkai biner dalam muatan pesan masuk. Jika aplikasi klien mengirimkan bingkai biner, API Gateway menolaknya dan memutus klien dengan kode 1003.
Ada solusi untuk perilaku ini. Jika klien mengirimkan data biner yang disandikan teks (misalnya, base64) sebagai bingkai teks, Anda dapat mengatur `contentHandlingStrategy` properti integrasi untuk mengonversi muatan dari string yang dikodekan base64 `CONVERT_TO_BINARY` ke biner.
Untuk mengembalikan respons rute untuk muatan biner dalam integrasi non-proxy, Anda dapat menyetel `contentHandlingStrategy` properti respons integrasi untuk mengonversi payload dari string biner `CONVERT_TO_TEXT` ke string berenkode base64.
# Memohon WebSocket APIs
Setelah menerapkan WebSocket API, aplikasi klien dapat terhubung dan mengirim pesan ke API itu—dan layanan backend Anda dapat mengirim pesan ke aplikasi klien yang terhubung:
+ Anda dapat menggunakan `wscat` untuk menyambung ke WebSocket API Anda dan mengirim pesan ke sana untuk mensimulasikan perilaku klien. Lihat [Gunakan `wscat` untuk terhubung ke WebSocket API dan mengirim pesan ke sana](apigateway-how-to-call-websocket-api-wscat.md).
+ Anda dapat menggunakan @connections API dari layanan backend Anda untuk mengirim pesan callback ke klien yang terhubung, mendapatkan informasi koneksi, atau memutuskan sambungan klien. Lihat [Gunakan `@connections` perintah di layanan backend Anda](apigateway-how-to-call-websocket-api-connections.md).
+ Aplikasi klien dapat menggunakan WebSocket pustaka sendiri untuk menjalankan WebSocket API Anda.
# Gunakan `wscat` untuk terhubung ke WebSocket API dan mengirim pesan ke sana
`[wscat](https://www.npmjs.com/package/wscat)`Utilitas adalah alat yang nyaman untuk menguji WebSocket API yang telah Anda buat dan gunakan di API Gateway. Anda dapat menginstal dan menggunakan `wscat` sebagai berikut:
1. Unduh `wscat` dari [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat).
1. Instal `wscat` dengan menjalankan perintah berikut:
```
npm install -g wscat
```
1. Untuk terhubung ke API Anda, jalankan `wscat` perintah seperti yang ditunjukkan pada contoh berikut. Perhatikan bahwa contoh ini mengasumsikan bahwa `Authorization` pengaturannya adalah`NONE`.
```
wscat -c wss://aabbccddee.execute-api.us-east-1.amazonaws.com/test/
```
Anda perlu mengganti `aabbccddee` dengan ID API yang sebenarnya, yang ditampilkan di konsol API Gateway atau dikembalikan oleh AWS CLI [https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html)perintah.
Selain itu, jika API Anda berada di Wilayah selain`us-east-1`, Anda perlu mengganti Region yang benar.
1. Untuk menguji API Anda, masukkan pesan seperti berikut saat terhubung:
```
{"{jsonpath-expression}":"{route-key}"}
```
di mana *\$1jsonpath-expression\$1* adalah JSONPath ekspresi dan *\$1route-key\$1* merupakan kunci rute untuk API. Contoh:
```
{"action":"action1"}
{"message":"test response body"}
```
Untuk informasi selengkapnya tentang JSONPath, lihat [JSONPath](https://goessner.net/articles/JsonPath/)atau [JSONPath untuk Java](https://github.com/json-path/JsonPath).
1. Untuk memutuskan sambungan dari API Anda, masukkan`ctrl-C`.
# Gunakan `@connections` perintah di layanan backend Anda
Layanan backend Anda dapat menggunakan permintaan HTTP WebSocket koneksi berikut untuk mengirim pesan callback ke klien yang terhubung, mendapatkan informasi koneksi, atau memutuskan sambungan klien.
**penting**
Permintaan ini menggunakan [otorisasi IAM](apigateway-websocket-control-access-iam.md), jadi Anda harus menandatanganinya dengan [Sigv4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Untuk melakukan ini, Anda dapat menggunakan API Gateway Management API. Untuk informasi selengkapnya, lihat [ApiGatewayManagementApi](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigatewaymanagementapi.html).
Pada perintah berikut, Anda perlu mengganti `{api-id}` dengan ID API yang sebenarnya, yang ditampilkan di konsol API Gateway atau dikembalikan oleh perintah AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html). Anda harus membuat koneksi sebelum menggunakan perintah ini.
Untuk mengirim pesan callback ke klien, gunakan:
```
POST https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Anda dapat menguji permintaan ini dengan menggunakan `[Postman](https://www.postman.com/)` atau dengan memanggil `[awscurl](https://github.com/okigan/awscurl)` seperti pada contoh berikut:
```
awscurl --service execute-api -X POST -d "hello world" https://{prefix}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Anda perlu mengkodekan URL perintah seperti pada contoh berikut:
```
awscurl --service execute-api -X POST -d "hello world" https://aabbccddee.execute-api.us-east-1.amazonaws.com/prod/%40connections/R0oXAdfD0kwCH6w%3D
```
Untuk mendapatkan status koneksi terbaru klien, gunakan:
```
GET https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Untuk memutuskan sambungan klien, gunakan:
```
DELETE https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Anda dapat membuat URL callback secara dinamis dengan menggunakan `$context` variabel dalam integrasi Anda. Misalnya, jika Anda menggunakan integrasi proxy Lambda dengan fungsi `Node.js` Lambda, Anda dapat membuat URL dan mengirim pesan ke klien yang terhubung sebagai berikut:
```
import {
ApiGatewayManagementApiClient,
PostToConnectionCommand,
} from "@aws-sdk/client-apigatewaymanagementapi";
export const handler = async (event) => {
const domain = event.requestContext.domainName;
const stage = event.requestContext.stage;
const connectionId = event.requestContext.connectionId;
const callbackUrl = `https://${domain}/${stage}`;
const client = new ApiGatewayManagementApiClient({ endpoint: callbackUrl });
const requestParams = {
ConnectionId: connectionId,
Data: "Hello!",
};
const command = new PostToConnectionCommand(requestParams);
try {
await client.send(command);
} catch (error) {
console.log(error);
}
return {
statusCode: 200,
};
};
```
Jika Anda menggunakan nama domain khusus untuk WebSocket API Anda, hapus `stage` variabel dari kode fungsi Anda.
Saat mengirim pesan panggilan balik, fungsi Lambda Anda harus memiliki izin untuk memanggil API Gateway Management API. Anda mungkin menerima kesalahan yang berisi `GoneException` jika Anda memposting pesan sebelum koneksi dibuat, atau setelah klien terputus.
# Publikasikan WebSocket APIs untuk pelanggan untuk dipanggil
Cukup membuat dan mengembangkan API Gateway API tidak secara otomatis membuatnya dapat dipanggil oleh pengguna Anda. Untuk membuatnya dapat dipanggil, Anda harus menerapkan API Anda ke sebuah panggung. Selain itu, Anda mungkin ingin menyesuaikan URL yang akan digunakan pengguna Anda untuk mengakses API Anda. Anda dapat memberikan domain yang konsisten dengan merek Anda atau lebih mudah diingat daripada URL default untuk API Anda.
Di bagian ini, Anda dapat mempelajari cara menerapkan API dan menyesuaikan URL yang Anda berikan kepada pengguna untuk mengaksesnya.
**catatan**
Untuk meningkatkan keamanan API Gateway Anda APIs, `execute-api.{region}.amazonaws.com` domain terdaftar di [Daftar Akhiran Publik (PSL](https://publicsuffix.org/)). Untuk keamanan lebih lanjut, kami menyarankan Anda menggunakan cookie dengan `__Host-` awalan jika Anda perlu mengatur cookie sensitif di nama domain default untuk API Gateway APIs Anda. Praktik ini akan membantu mempertahankan domain Anda dari upaya pemalsuan permintaan lintas situs (CSRF). Untuk informasi selengkapnya, lihat halaman [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) di Jaringan Pengembang Mozilla.
**Topics**
+ [Buat tahapan untuk WebSocket APIs di API Gateway](websocket-api-stages.md)
+ [Terapkan WebSocket APIs di API Gateway](apigateway-set-up-websocket-deployment.md)
+ [Kebijakan keamanan untuk WebSocket APIs di API Gateway](websocket-api-ciphers.md)
+ [Nama domain khusus untuk WebSocket APIs di API Gateway](websocket-api-custom-domain-names.md)
# Buat tahapan untuk WebSocket APIs di API Gateway
Tahap API adalah referensi logis ke status siklus hidup API Anda (misalnya,,, `dev` `prod``beta`, atau`v2`). Tahapan API diidentifikasi oleh ID API dan nama stage mereka, dan mereka disertakan dalam URL yang Anda gunakan untuk memanggil API. Setiap tahap adalah referensi bernama untuk deployment API dan dibuat tersedia bagi aplikasi klien untuk dipanggil.
Deployment adalah snapshot dari konfigurasi API Anda. Setelah Anda menerapkan API ke tahap, itu tersedia bagi klien untuk dipanggil. Anda harus menerapkan API agar perubahan diterapkan.
## Variabel tahap
Variabel tahap adalah pasangan nilai kunci yang dapat Anda tentukan untuk tahap API. WebSocket Mereka bertindak seperti variabel lingkungan dan dapat digunakan dalam pengaturan API Anda.
Misalnya, Anda dapat menentukan variabel tahap, dan kemudian menetapkan nilainya sebagai titik akhir HTTP untuk integrasi proxy HTTP. Kemudian, Anda dapat mereferensikan titik akhir dengan menggunakan nama variabel tahap terkait. Dengan melakukan ini, Anda dapat menggunakan penyiapan API yang sama dengan titik akhir yang berbeda di setiap tahap. Demikian pula, Anda dapat menggunakan variabel tahap untuk menentukan integrasi AWS Lambda fungsi yang berbeda untuk setiap tahap API Anda.
**catatan**
Variabel tahap tidak dimaksudkan untuk digunakan untuk data sensitif, seperti kredensional. Untuk meneruskan data sensitif ke integrasi, gunakan AWS Lambda otorisasi. Anda dapat meneruskan data sensitif ke integrasi dalam output otorisasi Lambda. Untuk mempelajari selengkapnya, lihat [Format respons otorisasi Lambda](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response).
### Contoh
Untuk menggunakan variabel tahap untuk menyesuaikan titik akhir integrasi HTTP, Anda harus terlebih dahulu mengatur nama dan nilai variabel tahap (misalnya,`url`) dengan nilai`example.com`. Selanjutnya, siapkan integrasi proxy HTTP. Alih-alih memasukkan URL titik akhir, Anda dapat memberi tahu API Gateway untuk menggunakan nilai variabel stage,**http://\$1\$1stageVariables.url\$1**. Nilai ini memberi tahu API Gateway untuk mengganti variabel stage Anda `${}` saat runtime, tergantung pada tahap API Anda.
Anda dapat mereferensikan variabel tahap dengan cara yang sama untuk menentukan nama fungsi Lambda atau peran AWS ARN.
Saat menentukan nama fungsi Lambda sebagai nilai variabel tahap, Anda harus mengonfigurasi izin pada fungsi Lambda secara manual. Perintah [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) berikut menambahkan izin yang diperlukan:
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
## Referensi variabel tahap API Gateway
### Integrasi HTTP URIs
Anda dapat menggunakan variabel tahap sebagai bagian dari URI integrasi HTTP, seperti yang ditunjukkan pada contoh berikut.
+ URI lengkap tanpa protokol — `http://${stageVariables.}`
+ Domain lengkap — `http://${stageVariables.}/resource/operation`
+ Sebuah subdomain — `http://${stageVariables.}.example.com/resource/operation`
+ Sebuah jalan — `http://example.com/${stageVariables.}/bar`
+ Sebuah string kueri - `http://example.com/foo?q=${stageVariables.}`
### Fungsi Lambda
Anda dapat menggunakan variabel tahap di tempat nama fungsi Lambda atau alias, seperti yang ditunjukkan dalam contoh berikut.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**catatan**
Untuk menggunakan variabel stage untuk fungsi Lambda, fungsi tersebut harus berada di akun yang sama dengan API. Variabel tahap tidak mendukung fungsi Lambda lintas akun.
### AWS kredensi integrasi
Anda dapat menggunakan variabel tahap sebagai bagian dari ARN kredensi AWS pengguna atau peran, seperti yang ditunjukkan pada contoh berikut.
+ `arn:aws:iam:::${stageVariables.}`
# Terapkan WebSocket APIs di API Gateway
Setelah membuat WebSocket API Anda, Anda harus menerapkannya agar tersedia bagi pengguna Anda untuk dipanggil.
[Untuk menerapkan API, Anda membuat [penerapan API](api-gateway-basic-concept.md#apigateway-definition-api-deployment) dan mengaitkannya dengan sebuah panggung.](api-gateway-basic-concept.md#apigateway-definition-api-stage) Setiap tahap adalah snapshot dari API dan tersedia untuk aplikasi klien untuk dipanggil.
**penting**
Setiap kali Anda memperbarui API, Anda harus menerapkannya kembali. Perubahan pada apa pun selain pengaturan tahap memerlukan pemindahan, termasuk modifikasi pada sumber daya berikut:
Rute
Integrasi
Pengotorisasi
Secara default, Anda dibatasi hingga 10 tahap untuk setiap API. Kami menyarankan Anda menggunakan kembali tahapan untuk penerapan Anda.
Untuk memanggil WebSocket API yang diterapkan, klien mengirim pesan ke URL API. URL ditentukan oleh nama host dan nama panggung API.
**catatan**
API Gateway akan mendukung payload hingga 128 KB dengan ukuran frame maksimal 32 KB. Jika pesan melebihi 32 KB, itu harus dibagi menjadi beberapa frame, masing-masing 32 KB atau lebih kecil.
Menggunakan nama domain default API, URL (misalnya) WebSocket API dalam tahap tertentu (`{stageName}`) adalah dalam format berikut:
```
wss://{api-id}.execute-api.{region}.amazonaws.com/{stageName}
```
Untuk membuat URL WebSocket API lebih user-friendly, Anda dapat membuat nama domain kustom (misalnya,`api.example.com`) untuk mengganti nama host default API. Proses konfigurasi sama dengan REST APIs. Untuk informasi selengkapnya, lihat [Nama domain khusus untuk REST publik APIs di API Gateway](how-to-custom-domains.md).
Tahapan memungkinkan kontrol versi yang kuat dari API Anda. Misalnya, Anda dapat menerapkan API ke `test` stage dan `prod` stage, dan menggunakan `test` stage sebagai test build dan menggunakan `prod` stage sebagai build stabil. Setelah pembaruan lulus tes, Anda dapat mempromosikan `test` panggung ke `prod` panggung. Promosi dapat dilakukan dengan memindahkan API ke panggung. `prod` Untuk detail lebih lanjut tentang tahapan, lihat[Siapkan panggung untuk REST API di API Gateway](set-up-stages.md).
**Topics**
+ [Membuat penerapan WebSocket API menggunakan AWS CLI](#apigateway-create-websocket-deployment-using-awscli)
+ [Membuat penerapan WebSocket API menggunakan konsol API Gateway](#apigateway-create-websocket-deployment-using-console)
## Membuat penerapan WebSocket API menggunakan AWS CLI
Perintah [create-deployment berikut membuat deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html):
```
aws apigatewayv2 --region us-east-1 create-deployment --api-id aabbccddee
```
Outputnya akan terlihat seperti berikut:
```
{
"DeploymentId": "fedcba",
"DeploymentStatus": "DEPLOYED",
"CreatedDate": "2018-11-15T06:49:09Z"
}
```
API yang diterapkan tidak dapat dipanggil sampai Anda mengaitkan penerapan dengan tahapan. Anda dapat membuat tahap baru atau menggunakan kembali tahap yang telah Anda buat sebelumnya.
Perintah [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-stage.html) berikut membuat tahap baru dan mengaitkannya dengan penerapan:
```
aws apigatewayv2 --region us-east-1 create-stage --api-id aabbccddee --deployment-id fedcba --stage-name test
```
Outputnya terlihat seperti berikut:
```
{
"StageName": "test",
"CreatedDate": "2018-11-15T06:50:28Z",
"DeploymentId": "fedcba",
"DefaultRouteSettings": {
"MetricsEnabled": false,
"ThrottlingBurstLimit": 5000,
"DataTraceEnabled": false,
"ThrottlingRateLimit": 10000.0
},
"LastUpdatedDate": "2018-11-15T06:50:28Z",
"StageVariables": {},
"RouteSettings": {}
}
```
Anda juga dapat menggunakan kembali tahap yang ada dengan memperbarui `deploymentId` properti stage dengan ID penerapan () *deployment-id* yang baru dibuat. Perintah [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) berikut memperbarui ID penyebaran tahap:
```
aws apigatewayv2 update-stage --region region \
--api-id api-id \
--stage-name stage-name \
--deployment-id deployment-id
```
## Membuat penerapan WebSocket API menggunakan konsol API Gateway
Untuk menggunakan konsol API Gateway untuk membuat penerapan WebSocket API:
1. Masuk ke konsol API Gateway dan pilih API.
1. Pilih **Deploy API**.
1. Pilih tahap yang diinginkan dari daftar dropdown atau masukkan nama tahap baru.
# Kebijakan keamanan untuk WebSocket APIs di API Gateway
API Gateway memberlakukan kebijakan keamanan `TLS_1_2` untuk semua titik akhir WebSocket API.
*Kebijakan keamanan* adalah kombinasi standar dari versi TLS minimum dan cipher suite yang ditawarkan oleh Amazon API Gateway. Protokol TLS mengatasi masalah keamanan jaringan seperti gangguan dan penyadapan antara klien dan server. Ketika klien Anda membuat jabat tangan TLS ke API Anda melalui domain kustom, kebijakan keamanan memberlakukan versi TLS dan pilihan cipher suite yang dapat dipilih klien Anda untuk digunakan. Kebijakan keamanan ini menerima lalu lintas TLS 1.2 dan TLS 1.3 dan menolak lalu lintas TLS 1.0.
## Protokol dan cipher TLS yang didukung untuk WebSocket APIs
Tabel berikut menjelaskan protokol TLS yang didukung untuk. WebSocket APIs
| **Protokol TLS** | **Kebijakan keamanan TLS\$11\$12** |
| --- | --- |
| TLSv1.3 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| TLSv1.2 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
Tabel berikut menjelaskan cipher TLS yang tersedia untuk kebijakan keamanan TLS 1\$12 untuk. WebSocket APIs
| **Cipher TLS** | **Kebijakan keamanan TLS\$11\$12** |
| --- | --- |
| TLS\$1AES\$1128\$1GCM\$1 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| TLS\$1AES\$1256\$1GCM\$1 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| TLS\$1 \$1 \$1 CHACHA20 POLY1305 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-ECDSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-RSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-ECDSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-RSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-ECDSA- -GCM- AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-RSA- -GCM- AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-ECDSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-RSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| AES128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| AES256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
## Nama sandi OpenSSL dan RFC
OpenSSL dan IETF RFC 5246, menggunakan nama yang berbeda untuk cipher yang sama. Untuk daftar nama sandi, lihat. [Nama sandi OpenSSL dan RFC](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names)
## Informasi tentang REST APIs dan HTTP APIs
Untuk informasi lebih lanjut tentang REST APIs dan HTTP APIs, lihat [Pilih kebijakan keamanan untuk domain kustom Anda di API Gateway](apigateway-custom-domain-tls-version.md) dan[Kebijakan keamanan untuk HTTP APIs di API Gateway](http-api-ciphers.md).
# Nama domain khusus untuk WebSocket APIs di API Gateway
*Nama domain khusus* lebih sederhana dan lebih intuitif URLs yang dapat Anda berikan kepada pengguna API Anda.
Setelah menerapkan API Anda, Anda (dan pelanggan Anda) dapat memanggil API menggunakan URL dasar default dari format berikut:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
dimana *api-id* dihasilkan oleh API Gateway, *region* adalah AWS Region, dan *stage* ditentukan oleh Anda saat menerapkan API.
Bagian nama host dari URL, `api-id.execute-api.region.amazonaws.com` mengacu pada titik akhir API. Nama endpoint API default dibuat secara acak, sulit diingat, dan tidak ramah pengguna.
Dengan nama domain khusus, Anda dapat mengatur nama host API Anda, dan memilih jalur dasar (misalnya,`myservice`) untuk memetakan URL alternatif ke API Anda. Misalnya, URL dasar API yang lebih ramah pengguna dapat menjadi:
```
https://api.example.com/myservice
```
## Pertimbangan
Pertimbangan berikut dapat memengaruhi penggunaan nama domain kustom Anda.
+ Jika Anda memetakan nama domain kustom ke WebSocket API, Anda tidak dapat memetakannya ke REST API atau HTTP API.
+ Hanya nama domain kustom Regional yang didukung.
+ Untuk versi TLS minimum, hanya TLS 1.2 yang didukung.
+ Anda harus membuat atau memperbarui catatan sumber daya penyedia DNS Anda untuk dipetakan ke titik akhir API Anda. Tanpa pemetaan seperti itu, permintaan API yang terikat untuk nama domain khusus tidak dapat mencapai API Gateway.
+ Anda dapat mendukung jumlah nama domain yang hampir tak terbatas tanpa melebihi kuota default dengan menggunakan sertifikat wildcard. Untuk informasi selengkapnya, lihat [Nama domain kustom wildcard](http-api-custom-domain-names.md#http-wildcard-custom-domain-names).
## Prasyarat
Berikut ini adalah prasyarat untuk nama domain kustom.
### Daftarkan nama domain
Anda harus memiliki nama domain internet terdaftar untuk mengatur nama domain khusus untuk Anda APIs. Anda dapat mendaftarkan nama domain internet Anda menggunakan [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) atau menggunakan registrar domain pihak ketiga pilihan Anda. Nama domain kustom Anda dapat berupa nama subdomain atau domain root (juga dikenal sebagai “zone apex”) dari domain internet terdaftar.
Nama domain Anda harus mengikuti spesifikasi [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) dan dapat memiliki maksimum 63 oktet per label dan total 255 oktet.
### Sertifikat untuk nama domain kustom
Sebelum menyiapkan nama domain khusus untuk API, Anda harus memiliki sertifikat SSL/TLS yang siap di ACM. Jika ACM tidak tersedia di AWS Wilayah tempat Anda membuat nama domain kustom, Anda harus mengimpor sertifikat ke API Gateway di Wilayah tersebut.
Untuk mengimpor badan SSL/TLS certificate, you must provide the PEM-formatted SSL/TLS sertifikat, kunci pribadinya, dan rantai sertifikat untuk nama domain kustom.
Setiap sertifikat yang disimpan dalam ACM diidentifikasi oleh ARN-nya. Dengan sertifikat yang dikeluarkan oleh ACM, Anda tidak perlu khawatir mengekspos detail sertifikat sensitif apa pun, seperti kunci pribadi. Untuk menggunakan sertifikat AWS terkelola untuk nama domain, Anda cukup mereferensikan ARN-nya.
Jika aplikasi Anda menggunakan pinning sertifikat, kadang-kadang dikenal sebagai penyematan SSL, untuk menyematkan sertifikat ACM, aplikasi mungkin tidak dapat terhubung ke domain Anda setelah AWS memperbarui sertifikat. Untuk informasi selengkapnya, lihat [Masalah penyematan sertifikat](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) di *Panduan AWS Certificate Manager Pengguna*.
## Nama domain kustom wildcard
Dengan nama domain khusus wildcard, Anda dapat mendukung jumlah nama domain yang hampir tak terbatas tanpa melebihi kuota [default](limits.md). Misalnya, Anda bisa memberi setiap pelanggan Anda nama domain mereka sendiri`customername.api.example.com`.
Untuk membuat nama domain kustom wildcard, tentukan wildcard (`*`) sebagai subdomain pertama dari domain kustom yang mewakili semua kemungkinan subdomain dari domain root.
Misalnya, nama domain kustom wildcard `*.example.com` menghasilkan subdomain seperti`a.example.com`,, dan `b.example.com``c.example.com`, yang semuanya merutekan ke domain yang sama.
Nama domain kustom wildcard mendukung konfigurasi yang berbeda dari nama domain kustom standar API Gateway. Misalnya, dalam satu AWS akun, Anda dapat mengkonfigurasi `*.example.com` dan `a.example.com` berperilaku berbeda.
Anda dapat menggunakan variabel `$context.domainName` dan `$context.domainPrefix` konteks untuk menentukan nama domain yang digunakan klien untuk memanggil API Anda. Untuk mempelajari lebih lanjut tentang variabel konteks, lihat[Variabel untuk transformasi data untuk API Gateway](api-gateway-mapping-template-reference.md).
Untuk membuat nama domain kustom wildcard, Anda harus memberikan sertifikat yang dikeluarkan oleh ACM yang telah divalidasi menggunakan DNS atau metode validasi email.
**catatan**
Anda tidak dapat membuat nama domain khusus wildcard jika AWS akun lain telah membuat nama domain kustom yang bertentangan dengan nama domain kustom wildcard. Misalnya, jika akun A telah dibuat`a.example.com`, maka akun B tidak dapat membuat nama `*.example.com` domain khusus wildcard.
Jika akun A dan akun B berbagi pemilik, Anda dapat menghubungi [Pusat AWS Dukungan](https://console.aws.amazon.com/support/home#/) untuk meminta pengecualian.
## Langkah selanjutnya untuk nama domain kustom
Untuk menyiapkan nama domain kustom untuk API HTTP, Anda menggunakan dokumentasi dari bagian REST API dari Panduan Pengembang API Gateway.
Pertama, tentukan sertifikat untuk nama domain kustom Anda. Untuk informasi selengkapnya, lihat [Siapkan sertifikat AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Selanjutnya, Anda membuat nama domain kustom Regional. Lihat informasi yang lebih lengkap di [Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
# Memetakan tahapan API ke nama domain khusus untuk WebSocket APIs
Anda menggunakan pemetaan API untuk menghubungkan tahapan API ke nama domain kustom. Setelah Anda membuat nama domain dan mengonfigurasi catatan DNS, Anda menggunakan pemetaan API untuk mengirim lalu lintas ke Anda APIs melalui nama domain kustom Anda.
Pemetaan API menentukan API, tahap, dan jalur opsional yang akan digunakan untuk pemetaan. Misalnya, Anda dapat memetakan `production` tahap API ke`wss://api.example.com/orders`.
Sebelum membuat pemetaan API, Anda harus memiliki API, panggung, dan nama domain khusus. Untuk mempelajari selengkapnya tentang membuat nama domain kustom, lihat[Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
## Pembatasan
+ Dalam pemetaan API, nama domain khusus dan dipetakan APIs harus berada di akun yang sama AWS .
+ Pemetaan API harus hanya berisi huruf, angka, dan karakter berikut:. `$-_.+!*'()`
+ Panjang maksimum jalur dalam pemetaan API adalah 300 karakter.
+ Anda tidak dapat memetakan WebSocket APIs ke nama domain kustom yang sama dengan HTTP API atau REST API.
+ Jika Anda membuat pemetaan API dengan beberapa level, API Gateway mengonversi semua nama header menjadi huruf kecil.
## Buat pemetaan API
Untuk membuat pemetaan API, Anda harus terlebih dahulu membuat nama domain kustom, API, dan stage. Untuk informasi tentang membuat nama domain kustom, lihat[Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
------
#### [ Konsol Manajemen AWS ]
**Untuk membuat pemetaan API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Nama domain khusus**.
1. Pilih nama domain khusus yang telah Anda buat.
1. Pilih **pemetaan API**.
1. Pilih **Konfigurasi pemetaan API**.
1. Pilih **Tambahkan pemetaan baru**.
1. Masukkan **API**, **Stage**, dan secara opsional **Path**.
1. Pilih **Simpan**.
------
#### [ AWS CLI ]
[create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html)Perintah berikut membuat pemetaan API. Dalam contoh ini, API Gateway mengirimkan permintaan `api.example.com/v1` ke API dan tahap yang ditentukan.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1 \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
CloudFormation Contoh berikut membuat pemetaan API.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'v1'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Jenis alamat IP untuk nama domain khusus untuk WebSocket APIs
Saat Anda membuat nama domain khusus, Anda menentukan jenis alamat IP yang dapat memanggil domain Anda. Anda dapat memilih IPv4 untuk menyelesaikan IPv4 alamat untuk memanggil domain Anda, atau Anda dapat memilih dualstack untuk mengizinkan keduanya IPv4 dan IPv6 alamat memanggil domain Anda. Kami menyarankan Anda mengatur jenis alamat IP ke dualstack untuk mengurangi kelelahan ruang IP atau untuk postur keamanan Anda. [Untuk informasi selengkapnya tentang manfaat dari jenis alamat IP dualstack, lihat IPv6 di. AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)
## Pertimbangan untuk jenis alamat IP
Pertimbangan berikut dapat memengaruhi penggunaan jenis alamat IP Anda.
+ Jenis alamat IP default untuk nama domain kustom API Gateway adalah IPv4.
+ Nama domain kustom Anda tidak perlu memiliki jenis alamat IP yang sama untuk semua yang APIs dipetakan ke sana. Jika Anda menonaktifkan titik akhir API default, hal ini dapat memengaruhi cara penelepon dapat menjalankan API Anda.
## Mengubah jenis alamat IP dari nama domain kustom
Anda dapat mengubah jenis alamat IP dengan memperbarui konfigurasi titik akhir nama domain. Anda dapat memperbarui konfigurasi titik akhir dengan menggunakan Konsol Manajemen AWS,, AWS CLI CloudFormation, atau AWS SDK.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengubah jenis alamat IP dari nama domain kustom**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih nama domain kustom publik.
1. Pilih **konfigurasi Endpoint**.
1. Untuk jenis alamat IP, pilih salah satu **IPv4**atau **Dualstack**.
1. Pilih **Simpan**.
------
#### [ AWS CLI ]
[update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)Perintah berikut memperbarui API untuk memiliki tipe alamat IP dualstack:
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
Outputnya akan terlihat seperti berikut:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# Nonaktifkan titik akhir default untuk WebSocket APIs
Secara default, klien dapat memanggil API Anda dengan menggunakan `execute-api` titik akhir yang dihasilkan API Gateway untuk API Anda. Untuk memastikan bahwa klien dapat mengakses API Anda hanya dengan menggunakan nama domain khusus, nonaktifkan `execute-api` titik akhir default. Saat Anda menonaktifkan titik akhir default, itu memengaruhi semua tahapan API.
Prosedur berikut menunjukkan cara menonaktifkan titik akhir default untuk WebSocket API.
------
#### [ Konsol Manajemen AWS ]
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih WebSocket API.
1. Pilih **setelan API**.
1. Pada **detail API**, pilih **Edit**.
1. Untuk **titik akhir Default**, pilih **Tidak** Aktif.
1. Pilih **Simpan perubahan**.
1. Pada panel navigasi utama, pilih **Rute**.
1. Pilih **Deploy**, lalu terapkan ulang API Anda atau buat tahap baru agar perubahan diterapkan.
------
#### [ AWS CLI ]
Perintah [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) berikut menonaktifkan titik akhir default untuk API: WebSocket
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Setelah menonaktifkan titik akhir default, Anda harus menerapkan API agar perubahan diterapkan.
AWS CLI Perintah berikut membuat penyebaran.
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Lindungi Anda WebSocket APIs di API Gateway
API Gateway menyediakan sejumlah cara untuk melindungi API Anda dari ancaman tertentu, seperti pengguna jahat atau lonjakan lalu lintas. Anda dapat melindungi API menggunakan strategi seperti membuat sertifikat SSL atau menetapkan target pelambatan. Untuk informasi selengkapnya tentang membuat sertifikat SSL, lihat[Buat dan konfigurasikan sertifikat SSL untuk otentikasi backend di API Gateway](getting-started-client-side-ssl-authentication.md). Sisa bagian ini mencakup pengaturan target pelambatan.
Anda dapat mengonfigurasi pembatasan APIs untuk membantu melindungi mereka dari kewalahan oleh terlalu banyak permintaan. Throttle diterapkan atas dasar upaya terbaik dan harus dianggap sebagai target daripada plafon permintaan yang dijamin.
API Gateway membatasi permintaan ke API Anda menggunakan algoritme token bucket, tempat token diperhitungkan untuk permintaan. Secara khusus, API Gateway memeriksa tarif dan ledakan pengiriman permintaan terhadap semua yang ada APIs di akun Anda, per Wilayah. Dalam algoritma token bucket, burst dapat memungkinkan overrun yang telah ditentukan sebelumnya dari batas-batas tersebut, tetapi faktor lain juga dapat menyebabkan batas dikuasai dalam beberapa kasus.
Jika pengiriman permintaan melebihi tingkat permintaan kondisi tunak dan batas burst, API Gateway mulai membatasi permintaan. Klien mungkin menerima tanggapan `429 Too Many Requests` kesalahan pada saat ini. Setelah menangkap pengecualian tersebut, klien dapat mengirimkan kembali permintaan yang gagal dengan cara yang membatasi tarif.
Sebagai pengembang API, Anda dapat menetapkan batas target untuk setiap tahapan atau rute API untuk meningkatkan kinerja keseluruhan APIs di semua akun Anda.
## Pelambatan tingkat akun per Wilayah
Secara default, API Gateway membatasi permintaan kondisi tunak per detik (RPS) APIs di semua AWS akun, per Wilayah. Ini juga membatasi burst (yaitu, ukuran bucket maksimum) di semua APIs dalam AWS akun, per Wilayah. Di API Gateway, batas burst mewakili jumlah maksimum target pengiriman permintaan bersamaan yang akan dipenuhi API Gateway sebelum mengembalikan respons `429 Too Many Requests` kesalahan. Untuk informasi lebih lanjut tentang pembatasan kuota, lihat. [Kuota Amazon API Gateway](limits.md)
Batas per akun diterapkan ke semua akun APIs di Wilayah tertentu. Batas tingkat tingkat akun dapat ditingkatkan berdasarkan permintaan - batas yang lebih tinggi dimungkinkan dengan batas waktu APIs yang lebih pendek dan muatan yang lebih kecil. [Untuk meminta peningkatan batas pembatasan tingkat akun per Wilayah, hubungi Pusat Dukungan.AWS](https://console.aws.amazon.com/support/home#/) Untuk informasi selengkapnya, lihat [Kuota Amazon API Gateway](limits.md). Perhatikan bahwa batas ini tidak boleh lebih tinggi dari batas AWS pelambatan.
## Pelambatan tingkat rute
Anda dapat menyetel pembatasan tingkat rute untuk mengganti batas pembatasan permintaan tingkat akun untuk tahap tertentu atau untuk rute individual di API Anda. Batas pembatasan rute default tidak dapat melebihi batas tingkat akun.
Anda dapat mengonfigurasi pelambatan tingkat rute dengan menggunakan file. AWS CLI Perintah [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) berikut mengonfigurasi pelambatan kustom untuk tahap dan rute API yang ditentukan:
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"messages":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# Pantau WebSocket APIs di API Gateway
Anda dapat menggunakan CloudWatch metrik dan CloudWatch Log untuk memantau WebSocket APIs. Dengan menggabungkan log dan metrik, Anda dapat mencatat kesalahan dan memantau kinerja API Anda.
**catatan**
API Gateway mungkin tidak menghasilkan log dan metrik dalam kasus berikut:
413 Kesalahan Permintaan Entitas Terlalu Besar
Berlebihan 429 Terlalu Banyak Kesalahan Permintaan
400 error seri dari permintaan yang dikirim ke domain kustom yang tidak memiliki pemetaan API
500 kesalahan seri yang disebabkan oleh kegagalan internal
**Topics**
+ [Pantau eksekusi WebSocket API dengan CloudWatch metrik](apigateway-websocket-api-logging.md)
+ [Konfigurasikan logging untuk WebSocket APIs di API Gateway](websocket-api-logging.md)
# Pantau eksekusi WebSocket API dengan CloudWatch metrik
Anda dapat menggunakan CloudWatch metrik [Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) untuk memantau WebSocket APIs. Konfigurasinya mirip dengan yang digunakan untuk REST APIs. Untuk informasi selengkapnya, lihat [Pantau eksekusi REST API dengan CloudWatch metrik Amazon](monitoring-cloudwatch.md).
Metrik berikut didukung untuk WebSocket APIs:
| Metrik | Deskripsi |
| --- | --- |
| ConnectCount | Jumlah pesan yang dikirim ke integrasi \$1connect rute. |
| MessageCount | Jumlah pesan yang dikirim ke WebSocket API, baik dari atau ke klien. |
| IntegrationError | Jumlah permintaan yang mengembalikan respons 4XX/5XX dari integrasi. |
| ClientError | Jumlah permintaan yang memiliki respons 4XX yang dikembalikan oleh API Gateway sebelum integrasi dipanggil. |
| ExecutionError | Kesalahan yang terjadi saat memanggil integrasi. |
| IntegrationLatency | Perbedaan waktu antara API Gateway mengirimkan permintaan ke integrasi dan API Gateway menerima respons dari integrasi. Ditekan untuk panggilan balik dan integrasi tiruan. |
Anda dapat menggunakan dimensi dalam tabel berikut untuk memfilter metrik API Gateway.
| Dimensi | Deskripsi |
| --- | --- |
| ApiId | Memfilter metrik API Gateway untuk API dengan ID API yang ditentukan. |
| ApiId, Panggung | Memfilter metrik API Gateway untuk tahap API dengan ID API dan ID tahap yang ditentukan. |
| ApiId, Metode, Sumber Daya, Panggung | Memfilter metrik API Gateway untuk metode API dengan ID API, ID tahap, jalur sumber daya, dan ID rute yang ditentukan. API Gateway tidak akan mengirimkan metrik ini kecuali Anda telah mengaktifkan metrik terperinci secara eksplisit. CloudWatch Anda dapat melakukan ini dengan memanggil [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html)aksi API Gateway V2 REST API untuk memperbarui `detailedMetricsEnabled` properti ke`true`. Atau, Anda dapat memanggil AWS CLI perintah [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) untuk memperbarui properti ke. `DetailedMetricsEnabled` `true` Mengaktifkan metrik tersebut akan dikenakan biaya tambahan ke akun Anda. Untuk informasi harga, lihat [ CloudWatchHarga Amazon](https://aws.amazon.com/cloudwatch/pricing/). |
# Konfigurasikan logging untuk WebSocket APIs di API Gateway
Anda dapat mengaktifkan logging untuk menulis log ke CloudWatch Log. Ada dua jenis log masuk API CloudWatch: logging eksekusi dan logging akses. Dalam pencatatan eksekusi, API Gateway mengelola CloudWatch Log. Prosesnya mencakup pembuatan grup log dan aliran log, dan pelaporan ke aliran log permintaan dan tanggapan pemanggil apa pun.
Untuk meningkatkan postur keamanan Anda, kami sarankan Anda menggunakan pencatatan eksekusi di `INFO` tingkat `ERROR` atau. Anda mungkin perlu melakukan ini untuk mematuhi berbagai kerangka kerja kepatuhan. Untuk informasi selengkapnya, lihat [kontrol Amazon API Gateway](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) di *Panduan AWS Security Hub Pengguna*.
Dalam pencatatan akses, Anda, sebagai pengembang API, ingin mencatat siapa yang telah mengakses API Anda dan bagaimana pemanggil mengakses API. Anda dapat membuat grup log Anda sendiri atau memilih grup log yang sudah ada yang dapat dikelola oleh API Gateway. Untuk menentukan rincian akses, Anda memilih `$context` variabel (dinyatakan dalam format pilihan Anda) dan memilih grup log sebagai tujuan.
Untuk petunjuk tentang cara mengatur CloudWatch logging, lihat[Siapkan pencatatan CloudWatch API menggunakan konsol API Gateway](set-up-logging.md#set-up-access-logging-using-console).
Saat Anda menentukan **Format Log**, Anda dapat memilih variabel konteks mana yang akan dicatat. Variabel berikut didukung.
| Parameter | Deskripsi |
| --- | --- |
| \$1context.apiId | API Gateway identifier ditetapkan ke API Anda. |
| \$1context.authorize.error | Pesan kesalahan otorisasi. |
| \$1context.authorize.latency | Latensi otorisasi di ms. |
| \$1context.authorize.status | Kode status dikembalikan dari upaya otorisasi. |
| \$1context.authorizer.error | Pesan kesalahan dikembalikan dari otorisasi. |
| \$1context.authorizer.integrationLatency | Latensi otorisasi Lambda di ms. |
| \$1context.authorizer.integrationStatus | Kode status dikembalikan dari otorisasi Lambda. |
| \$1context.authorizer.latency | Latensi otorisasi di ms. |
| \$1context.authorizer.requestId | ID permintaan AWS titik akhir. |
| \$1context.authorizer.status | Kode status dikembalikan dari otorisasi. |
| \$1context.authorizer.principalId | Identifikasi pengguna utama yang dikaitkan dengan token yang dikirim oleh klien dan dikembalikan dari fungsi Lambda otorisasi API Gateway Lambda. (Authorizer Lambda sebelumnya dikenal sebagai otorisasi khusus.) |
| \$1context.authorizer.property | Nilai stringifikasi dari pasangan nilai kunci yang ditentukan dari `context` peta dikembalikan dari fungsi otorisasi API Gateway Lambda. Misalnya, jika otorisasi mengembalikan `context` peta berikut: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} memanggil `$context.authorizer.key` mengembalikan `"value"` string, memanggil `$context.authorizer.numKey` mengembalikan `"1"` string, dan memanggil `$context.authorizer.boolKey` mengembalikan `"true"` string. |
| \$1context.authenticate.error | Pesan kesalahan dikembalikan dari upaya otentikasi. |
| \$1context.authenticate.latency | Latensi otentikasi di ms. |
| \$1context.authenticate.status | Kode status dikembalikan dari upaya otentikasi. |
| \$1context.connectedAt | Waktu koneksi yang diformat [Epoch](https://en.wikipedia.org/wiki/Unix_time). |
| \$1context.connectionId | ID unik untuk koneksi yang dapat digunakan untuk membuat callback ke klien. |
| \$1context.domainName | Sebuah nama domain untuk WebSocket API. Ini dapat digunakan untuk membuat panggilan balik ke klien (bukan nilai hardcode). |
| \$1context.error.message | String yang berisi pesan kesalahan API Gateway. |
| \$1context.error.messageString | Nilai yang dikutip dari\$1context.error.message, yaitu"\$1context.error.message". |
| \$1context.error.responseType | Jenis respons kesalahan. |
| \$1context.error.validationErrorString | Sebuah string yang berisi pesan kesalahan validasi rinci. |
| \$1context.eventType | Jenis acara:`CONNECT`,`MESSAGE`, atau`DISCONNECT`. |
| \$1context.extendedRequestId | Setara dengan\$1context.requestId. |
| \$1context.identity.accountId | ID AWS akun yang terkait dengan permintaan. |
| \$1context.identity.apiKey | Kunci pemilik API yang terkait dengan permintaan API berkemampuan kunci. |
| \$1context.identity.apiKeyId | ID kunci API yang terkait dengan permintaan API berkemampuan kunci |
| \$1context.identity.caller | Pengenal utama penelepon yang menandatangani permintaan. Didukung untuk rute yang menggunakan otorisasi IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Daftar dipisahkan koma dari semua penyedia otentikasi Amazon Cognito yang digunakan oleh penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Misalnya, untuk identitas dari kumpulan pengguna Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` *Untuk informasi tentang penyedia autentikasi Amazon Cognito yang tersedia, lihat [Menggunakan Identitas Federasi di Panduan Pengembang](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) Amazon Cognito.* |
| \$1context.identity.cognitoAuthenticationType | Jenis otentikasi Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Nilai yang mungkin termasuk `authenticated` untuk identitas yang diautentikasi dan `unauthenticated` untuk identitas yang tidak diautentikasi. |
| \$1context.identity.cognitoIdentityId | ID identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID kumpulan identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. |
| \$1context.identity.principalOrgId | [ID AWS organisasi](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Didukung untuk rute yang menggunakan otorisasi IAM. |
| \$1context.identity.sourceIp | Alamat IP sumber koneksi TCP membuat permintaan ke API Gateway. |
| \$1context.identity.user | Pengidentifikasi utama pengguna yang akan diotorisasi terhadap akses sumber daya. Didukung untuk rute yang menggunakan otorisasi IAM. |
| \$1context.identity.userAgent | Agen pengguna pemanggil API. |
| \$1context.identity.userArn | Nama Sumber Daya Amazon (ARN) dari pengguna efektif yang diidentifikasi setelah otentikasi. |
| \$1context.integration.error | Pesan kesalahan dikembalikan dari integrasi. |
| \$1context.integration.integrationStatus | Untuk integrasi proxy Lambda, kode status dikembalikan dari AWS Lambda, bukan dari kode fungsi Lambda backend. |
| \$1context.integration.latency | Latensi integrasi dalam ms. Setara dengan\$1context.integrationLatency. |
| \$1context.integration.requestId | ID permintaan AWS titik akhir. Setara dengan\$1context.awsEndpointRequestId. |
| \$1context.integration.status | Kode status dikembalikan dari integrasi. Untuk integrasi proxy Lambda, ini adalah kode status yang dikembalikan oleh kode fungsi Lambda Anda. Setara dengan\$1context.integrationStatus. |
| \$1context.integrationLatency | Latensi integrasi dalam ms, hanya tersedia untuk pencatatan akses. |
| \$1context.messageId | ID sisi server unik untuk pesan. Hanya tersedia ketika `$context.eventType` ada`MESSAGE`. |
| \$1context.requestId | Sama seperti`$context.extendedRequestId`. |
| \$1context.requestTime | Waktu permintaan yang diformat [CLF](https://httpd.apache.org/docs/current/logs.html#common) (). dd/MMM/yyyy:HH:mm:ss \$1-hhmm |
| \$1context.requestTimeEpoch | Waktu permintaan yang diformat [Epoch](https://en.wikipedia.org/wiki/Unix_time), dalam milidetik. |
| \$1context.routeKey | Kunci rute yang dipilih. |
| \$1context.stage | Tahap penerapan panggilan API (misalnya, beta atau prod). |
| \$1context.status | Status respon. |
| \$1context.waf.error | Pesan kesalahan dikembalikan dari AWS WAF. |
| \$1context.waf.latency | AWS WAF Latensi dalam ms. |
| \$1context.waf.status | Kode status dikembalikan dari AWS WAF. |
Contoh beberapa format log akses yang umum digunakan ditampilkan di konsol API Gateway dan dicantumkan sebagai berikut.
+ `CLF`([Format Log Umum](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp $context.identity.caller \
$context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId
```
Karakter kelanjutan (`\`) dimaksudkan sebagai alat bantu visual. Format log harus satu baris. Anda dapat menambahkan karakter baris baru (`\n`) di akhir format log untuk menyertakan baris baru di akhir setiap entri log.
+ `JSON`:
```
{
"requestId":"$context.requestId", \
"ip": "$context.identity.sourceIp", \
"caller":"$context.identity.caller", \
"user":"$context.identity.user", \
"requestTime":"$context.requestTime", \
"eventType":"$context.eventType", \
"routeKey":"$context.routeKey", \
"status":"$context.status", \
"connectionId":"$context.connectionId"
}
```
Karakter kelanjutan (`\`) dimaksudkan sebagai alat bantu visual. Format log harus satu baris. Anda dapat menambahkan karakter baris baru (`\n`) di akhir format log untuk menyertakan baris baru di akhir setiap entri log.
+ `XML`:
```
\
$context.identity.sourceIp \
$context.identity.caller \
$context.identity.user \
$context.requestTime \
$context.eventType \
$context.routeKey \
$context.status \
$context.connectionId \
```
Karakter kelanjutan (`\`) dimaksudkan sebagai alat bantu visual. Format log harus satu baris. Anda dapat menambahkan karakter baris baru (`\n`) di akhir format log untuk menyertakan baris baru di akhir setiap entri log.
+ `CSV`(nilai yang dipisahkan koma):
```
$context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId
```
Karakter kelanjutan (`\`) dimaksudkan sebagai alat bantu visual. Format log harus satu baris. Anda dapat menambahkan karakter baris baru (`\n`) di akhir format log untuk menyertakan baris baru di akhir setiap entri log.