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