Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# 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.