Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Variabel untuk transformasi data untuk API Gateway Saat Anda membuat pemetaan parameter, Anda dapat menggunakan variabel konteks sebagai sumber data Anda. Saat Anda membuat transformasi template pemetaan, Anda dapat menggunakan variabel konteks, input, dan variabel util dalam skrip yang Anda tulis di [Velocity Template](https://velocity.apache.org/engine/devel/vtl-reference.html) Language (VTL). Misalnya template pemetaan yang menggunakan variabel referensi ini, lihat[Contoh menggunakan variabel untuk memetakan transformasi template untuk API Gateway](api-gateway-mapping-variable-examples.md). Untuk daftar variabel referensi untuk pencatatan akses, lihat[Variabel untuk pencatatan akses untuk API Gateway](api-gateway-variables-for-access-logging.md). ## Variabel konteks untuk transformasi data Anda dapat menggunakan `$context` variabel case-sensitive berikut untuk transformasi data. | Parameter | Deskripsi | | --- | --- | | \$1context.accountId | ID AWS akun pemilik API. | | \$1context.apiId | API Gateway identifier ditetapkan ke API Anda. | | \$1context.authorizer.claims.property | Properti klaim yang dikembalikan dari kumpulan pengguna Amazon Cognito setelah pemanggil metode berhasil diautentikasi. Untuk informasi selengkapnya, lihat [Kontrol akses ke REST APIs menggunakan kumpulan pengguna Amazon Cognito sebagai otorisasi](apigateway-integrate-with-cognito.md). Memanggil `$context.authorizer.claims` mengembalikan null. | | \$1context.authorizer.principalId | Identifikasi pengguna utama yang terkait dengan token yang dikirim oleh klien dan dikembalikan dari otorisasi API Gateway Lambda (sebelumnya dikenal sebagai otorisasi khusus). Untuk informasi selengkapnya, lihat [Gunakan otorisasi API Gateway Lambda](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.property | Nilai stringifikasi dari pasangan nilai kunci yang ditentukan dari `context` peta dikembalikan dari fungsi otorisasi API Gateway Lambda. Misalnya, jika otorisasi mengembalikan `context` peta berikut: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
Memanggil `$context.authorizer.key` mengembalikan `"value"` string, memanggil `$context.authorizer.numKey` mengembalikan `"1"` string, dan memanggil `$context.authorizer.boolKey` mengembalikan `"true"` string. Sebab*property*, satu-satunya karakter khusus yang didukung adalah `(_)` karakter garis bawah. Untuk informasi selengkapnya, lihat [Gunakan otorisasi API Gateway Lambda](apigateway-use-lambda-authorizer.md). | | \$1context.awsEndpointRequestId | ID permintaan AWS titik akhir. | | \$1context.deploymentId | ID penerapan API. | | \$1context.domainName | Nama domain lengkap yang digunakan untuk memanggil API. Ini harus sama dengan `Host` header yang masuk. | | \$1context.domainPrefix | Label pertama dari`$context.domainName`. | | \$1context.error.message | String yang berisi pesan kesalahan API Gateway. Variabel ini hanya dapat digunakan untuk substitusi variabel sederhana dalam template [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)pemetaan tubuh, yang tidak diproses oleh mesin Velocity Template Language, dan dalam logging akses. Untuk informasi selengkapnya, lihat [Pantau eksekusi WebSocket API dengan CloudWatch metrik](apigateway-websocket-api-logging.md) dan [Menyiapkan respons gateway untuk menyesuaikan respons kesalahan](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.messageString | Nilai yang dikutip dari\$1context.error.message, yaitu"\$1context.error.message". | | \$1context.error.responseType | Sebuah [jenis [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType). Variabel ini hanya dapat digunakan untuk substitusi variabel sederhana dalam template [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)pemetaan tubuh, yang tidak diproses oleh mesin Velocity Template Language, dan dalam logging akses. Untuk informasi selengkapnya, lihat [Pantau eksekusi WebSocket API dengan CloudWatch metrik](apigateway-websocket-api-logging.md) dan [Menyiapkan respons gateway untuk menyesuaikan respons kesalahan](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.validationErrorString | Sebuah string yang berisi pesan kesalahan validasi rinci. | | \$1context.extendedRequestId | ID tambahan yang dibuat dan ditetapkan API Gateway ke permintaan API. ID permintaan yang diperluas berisi informasi yang berguna untuk debugging dan pemecahan masalah. | | \$1context.httpMethod | Metode HTTP yang digunakan. Nilai yang valid meliputi: `DELETE``GET`,,`HEAD`,`OPTIONS`,`PATCH`,`POST`, dan`PUT`. | | \$1context.identity.accountId | ID AWS akun yang terkait dengan permintaan. | | \$1context.identity.apiKey | Untuk metode API yang memerlukan kunci API, variabel ini adalah kunci API yang terkait dengan permintaan metode. Untuk metode yang tidak memerlukan kunci API, variabel ini adalah null. Untuk informasi selengkapnya, lihat [Paket penggunaan dan kunci API untuk REST APIs di API Gateway](api-gateway-api-usage-plans.md). | | \$1context.identity.apiKeyId | ID kunci API yang terkait dengan permintaan API yang memerlukan kunci API. | | \$1context.identity.caller | Pengidentifikasi utama penelepon yang menandatangani permintaan. Didukung untuk sumber daya yang menggunakan otorisasi IAM. | | \$1context.identity.cognitoAuthenticationProvider | Daftar dipisahkan koma dari semua penyedia otentikasi Amazon Cognito yang digunakan oleh penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Misalnya, untuk identitas dari kumpulan pengguna Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` *Untuk informasi tentang penyedia autentikasi Amazon Cognito yang tersedia, lihat [Menggunakan Identitas Federasi di Panduan Pengembang](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) Amazon Cognito.* | | \$1context.identity.cognitoAuthenticationType | Jenis otentikasi Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Nilai yang mungkin termasuk `authenticated` untuk identitas yang diautentikasi dan `unauthenticated` untuk identitas yang tidak diautentikasi. | | \$1context.identity.cognitoIdentityId | ID identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. | | \$1context.identity.cognitoIdentityPoolId | ID kumpulan identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. | | \$1context.identity.principalOrgId | [ID AWS organisasi](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). | | \$1context.identity.sourceIp | Alamat IP sumber dari koneksi TCP langsung membuat permintaan ke titik akhir API Gateway. | | \$1context.identity.clientCert.clientCertPem | Sertifikat klien yang dikodekan PEM yang disajikan klien selama otentikasi TLS timbal balik. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. | | \$1context.identity.clientCert.subjectDN | Nama yang dibedakan dari subjek sertifikat yang disajikan klien. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. | | \$1context.identity.clientCert.issuerDN | Nama terhormat dari penerbit sertifikat yang disajikan klien. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. | | \$1context.identity.clientCert.serialNumber | Nomor seri sertifikat. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. | | \$1context.identity.clientCert.validity.notBefore | Tanggal sebelum sertifikat tidak valid. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. | | \$1context.identity.clientCert.validity.notAfter | Tanggal setelah sertifikat tidak valid. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. | | \$1context.identity.vpcId | ID VPC VPC membuat permintaan ke titik akhir API Gateway. | | \$1context.identity.vpceId | ID titik akhir VPC dari titik akhir VPC membuat permintaan ke titik akhir API Gateway. Hadir hanya ketika Anda memiliki API pribadi. | | \$1context.identity.user | Pengidentifikasi utama pengguna yang akan diotorisasi terhadap akses sumber daya. Didukung untuk sumber daya yang menggunakan otorisasi IAM. | | \$1context.identity.userAgent | [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)Header pemanggil API. | | \$1context.identity.userArn | Nama Sumber Daya Amazon (ARN) dari pengguna efektif yang diidentifikasi setelah otentikasi. Untuk informasi selengkapnya, lihat [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). | | \$1context.isCanaryRequest | Mengembalikan `true` jika permintaan diarahkan ke kenari dan `false` jika permintaan tidak diarahkan ke kenari. Hadir hanya ketika Anda mengaktifkan kenari. | | \$1context.path | Jalur permintaan. Misalnya, untuk URL permintaan non-proxy darihttps://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, \$1context.path nilainya adalah/\$1stage\$1/root/child. | | \$1context.protocol | Protokol permintaan, misalnya,HTTP/1.1. API Gateway APIs dapat menerima permintaan HTTP/2, tetapi API Gateway mengirimkan permintaan ke integrasi backend menggunakan HTTP/1.1. Akibatnya, protokol permintaan dicatat sebagai HTTP/1.1 bahkan jika klien mengirim permintaan yang menggunakan HTTP/2. | | \$1context.requestId | ID untuk permintaan. Klien dapat mengganti ID permintaan ini. Gunakan `$context.extendedRequestId` untuk ID permintaan unik yang dihasilkan API Gateway. | | \$1context.requestOverride.header.header\$1name | Header permintaan menimpa. Jika parameter ini didefinisikan, ini berisi header yang akan digunakan alih-alih **Header HTTP** yang didefinisikan di panel **Permintaan Integrasi**. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.path.path\$1name | Jalur permintaan menimpa. Jika parameter ini ditentukan, parameter ini berisi jalur permintaan yang akan digunakan, bukan **Parameter Jalur URL** yang ditentukan di panel **Permintaan Integrasi**. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.querystring.querystring\$1name | Permintaan query string override. Jika parameter ini didefinisikan, parameter ini berisi string permintaan permintaan yang akan digunakan, bukan **Parameter String Kueri URL** yang didefinisikan di panel **Permintaan Integrasi**. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.header.header\$1name | Header respon menimpa. Jika parameter ini didefinisikan, ini berisi header yang akan dikembalikan, bukan header Response yang didefinisikan sebagai pemetaan Default di panel Integration Response. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.status | Kode status respons menimpa. Jika parameter ini didefinisikan, ini berisi kode status yang akan dikembalikan, bukan status respons Metode yang didefinisikan sebagai pemetaan Default di panel Respons Integrasi. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). | | \$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.resourceId | Pengidentifikasi yang ditetapkan API Gateway ke sumber daya Anda. | | \$1context.resourcePath | Jalan menuju sumber daya Anda. Misalnya, untuk URI permintaan non-proxy dari`https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, `$context.resourcePath` Nilainya adalah`/root/child`. Untuk informasi selengkapnya, lihat [Tutorial: Membuat REST API dengan integrasi non-proxy HTTP](api-gateway-create-api-step-by-step.md). | | \$1context.stage | Tahap penerapan permintaan API (misalnya, `Beta` atau`Prod`). | | \$1context.wafResponseCode | Tanggapan yang diterima dari [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` atau`WAF_BLOCK`. Tidak akan diatur jika tahap tidak terkait dengan ACL web. Untuk informasi selengkapnya, lihat [Gunakan AWS WAF untuk melindungi REST Anda APIs di API Gateway](apigateway-control-access-aws-waf.md). | | \$1context.webaclArn | ARN lengkap dari ACL web yang digunakan untuk memutuskan apakah akan mengizinkan atau memblokir permintaan. Tidak akan diatur jika tahap tidak terkait dengan ACL web. Untuk informasi selengkapnya, lihat [Gunakan AWS WAF untuk melindungi REST Anda APIs di API Gateway](apigateway-control-access-aws-waf.md). | ## Variabel masukan Anda dapat menggunakan `$input` variabel case-sensitive berikut untuk merujuk ke metode permintaan payload dan parameter permintaan metode. Fungsi-fungsi berikut tersedia: | Variabel dan fungsi | Deskripsi | | --- | --- | | \$1input.body | Mengembalikan payload permintaan mentah sebagai string. Anda dapat menggunakan `$input.body` untuk mempertahankan seluruh nomor floating point, seperti`10.00`. | | \$1input.json(x) | Fungsi ini mengevaluasi JSONPath ekspresi dan mengembalikan hasil sebagai string JSON. Misalnya, `$input.json('$.pets')` mengembalikan string JSON yang mewakili `pets` struktur. Untuk informasi selengkapnya tentang JSONPath, lihat [JSONPath](https://goessner.net/articles/JsonPath/)atau [JSONPath untuk Java](https://github.com/json-path/JsonPath). | | \$1input.params() | Mengembalikan peta dari semua parameter permintaan. Kami menyarankan Anda menggunakan `$util.escapeJavaScript` untuk membersihkan hasilnya untuk menghindari potensi serangan injeksi. Untuk kontrol penuh sanitasi permintaan, gunakan integrasi proxy tanpa templat dan tangani sanitasi permintaan dalam integrasi Anda. | | \$1input.params(x) | Mengembalikan nilai parameter permintaan metode dari path, query string, atau nilai header (dicari dalam urutan itu), diberikan string `x` nama parameter. Kami menyarankan Anda menggunakan `$util.escapeJavaScript` untuk membersihkan parameter untuk menghindari potensi serangan injeksi. Untuk kontrol penuh sanitasi parameter, gunakan integrasi proxy tanpa templat dan tangani sanitasi permintaan dalam integrasi Anda. | | \$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').size()`akan kembali`"3"`. Untuk informasi selengkapnya tentang JSONPath, lihat [JSONPath](https://goessner.net/articles/JsonPath/)atau [JSONPath untuk Java](https://github.com/json-path/JsonPath). | ## Variabel tahap Anda dapat menggunakan variabel tahap berikut sebagai placeholder untuk ARNs dan URLs dalam integrasi metode. Untuk informasi selengkapnya, lihat [Menggunakan variabel stage untuk REST API di API Gateway](stage-variables.md). | Sintaksis | Deskripsi | | --- | --- | | \$1stageVariables.variable\$1name,\$1stageVariables['variable\$1name'], atau \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*merupakan nama variabel tahap. | ## Variabel Util Anda dapat menggunakan `$util` variabel case-sensitive berikut untuk menggunakan fungsi utilitas untuk memetakan template. Kecuali ditentukan lain, set karakter default adalah UTF-8. | Fungsi | Deskripsi | | --- | --- | | \$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: 
 "input" : "$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. |