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 Language (VTL). Misalnya template pemetaan yang menggunakan variabel referensi ini, lihatContoh menggunakan variabel untuk memetakan transformasi template untuk API Gateway.

Untuk daftar variabel referensi untuk pencatatan akses, lihatVariabel untuk pencatatan akses untuk API Gateway.

Variabel konteks untuk transformasi data

Anda dapat menggunakan $context variabel berikut untuk transformasi data.

Parameter	Deskripsi
$context.accountId	ID AWS akun pemilik API.
$context.apiId	API Gateway identifier ditetapkan ke API Anda.
$context.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. catatan Memanggil $context.authorizer.claims mengembalikan null.
$context.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.
$context.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. Sebabproperty, satu-satunya karakter khusus yang didukung adalah (_) karakter garis bawah. Untuk informasi selengkapnya, lihat Gunakan otorisasi API Gateway Lambda.
$context.awsEndpointRequestId	ID permintaan AWS titik akhir.
$context.deploymentId	ID penerapan API.
$context.domainName	Nama domain lengkap yang digunakan untuk memanggil API. Ini harus sama dengan Host header yang masuk.
$context.domainPrefix	Label pertama dari$context.domainName.
$context.error.message	String yang berisi pesan kesalahan API Gateway. Variabel ini hanya dapat digunakan untuk substitusi variabel sederhana dalam template GatewayResponsepemetaan tubuh, yang tidak diproses oleh mesin Velocity Template Language, dan dalam logging akses. Untuk informasi selengkapnya, silakan lihat Pantau eksekusi WebSocket API dengan CloudWatch metrik dan Menyiapkan respons gateway untuk menyesuaikan respons kesalahan.
$context.error.messageString	Nilai yang dikutip dari$context.error.message, yaitu"$context.error.message".
$context.error.responseType	Sebuah jenis GatewayResponse. Variabel ini hanya dapat digunakan untuk substitusi variabel sederhana dalam template GatewayResponsepemetaan tubuh, yang tidak diproses oleh mesin Velocity Template Language, dan dalam logging akses. Untuk informasi selengkapnya, silakan lihat Pantau eksekusi WebSocket API dengan CloudWatch metrik dan Menyiapkan respons gateway untuk menyesuaikan respons kesalahan.
$context.error.validationErrorString	Sebuah string yang berisi pesan kesalahan validasi rinci.
$context.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.
$context.httpMethod	Metode HTTP yang digunakan. Nilai yang valid meliputi: DELETEGET,,HEAD,OPTIONS,PATCH,POST, danPUT.
$context.identity.accountId	ID AWS akun yang terkait dengan permintaan.
$context.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.
$context.identity.apiKeyId	ID kunci API yang terkait dengan permintaan API yang memerlukan kunci API.
$context.identity.caller	Pengenal utama penelepon yang menandatangani permintaan. Didukung untuk sumber daya yang menggunakan otorisasi IAM.
$context.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 Amazon Cognito.
$context.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.
$context.identity.cognitoIdentityId	ID identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito.
$context.identity.cognitoIdentityPoolId	ID kumpulan identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito.
$context.identity.principalOrgId	ID AWS organisasi.
$context.identity.sourceIp	Alamat IP sumber dari koneksi TCP langsung membuat permintaan ke titik akhir API Gateway.
$context.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.
$context.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.
$context.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.
$context.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.
$context.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.
$context.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.
$context.identity.vpcId	ID VPC VPC membuat permintaan ke titik akhir API Gateway.
$context.identity.vpceId	ID titik akhir VPC dari titik akhir VPC membuat permintaan ke titik akhir API Gateway. Hadir hanya ketika Anda memiliki API pribadi.
$context.identity.user	Pengidentifikasi utama pengguna yang akan diotorisasi terhadap akses sumber daya. Didukung untuk sumber daya yang menggunakan otorisasi IAM.
$context.identity.userAgent	User-AgentHeader pemanggil API.
$context.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.
$context.isCanaryRequest	Mengembalikan true jika permintaan diarahkan ke kenari dan false jika permintaan tidak diarahkan ke kenari. Hadir hanya ketika Anda mengaktifkan kenari.
$context.path	Jalur permintaan. Misalnya, untuk URL permintaan non-proxy darihttps://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child, $context.path nilainya adalah/{stage}/root/child.
$context.protocol	Protokol permintaan, misalnya,HTTP/1.1. catatan 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.
$context.requestId	ID untuk permintaan. Klien dapat mengganti ID permintaan ini. Gunakan $context.extendedRequestId untuk ID permintaan unik yang dihasilkan API Gateway.
$context.requestOverride.header.header_name	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.
$context.requestOverride.path.path_name	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.
$context.requestOverride.querystring.querystring_name	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.
$context.responseOverride.header.header_name	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.
$context.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.
$context.requestTime	Waktu permintaan yang diformat CLF (). dd/MMM/yyyy:HH:mm:ss +-hhmm
$context.requestTimeEpoch	Waktu permintaan yang diformat Epoch, dalam milidetik.
$context.resourceId	Pengidentifikasi yang ditetapkan API Gateway ke sumber daya Anda.
$context.resourcePath	Jalan menuju sumber daya Anda. Misalnya, untuk URI permintaan non-proxy darihttps://{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.
$context.stage	Tahap penerapan permintaan API (misalnya, Beta atauProd).
$context.wafResponseCode	Tanggapan yang diterima dari AWS WAF: WAF_ALLOW atauWAF_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.
$context.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.

Variabel masukan

Anda dapat menggunakan $input variabel berikut untuk merujuk ke payload permintaan metode dan parameter permintaan metode. Fungsi-fungsi berikut tersedia:

Variabel dan fungsi	Deskripsi
$input.body	Mengembalikan payload permintaan mentah sebagai string. Anda dapat menggunakan $input.body untuk mempertahankan seluruh nomor floating point, seperti10.00.
$input.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 JSONPathatau JSONPath untuk Java.
$input.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.
$input.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.
$input.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 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 JSONPathatau JSONPath untuk Java.

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.

Sintaks	Deskripsi
$stageVariables.variable_name,$stageVariables['variable_name'], atau ${stageVariables['variable_name']}	variable_namemerupakan nama variabel tahap.

Variabel Util

Anda dapat menggunakan $util variabel berikut untuk menggunakan fungsi utilitas untuk memetakan template. Kecuali ditentukan lain, set karakter default adalah UTF-8.

Fungsi	Deskripsi
$util.escapeJavaScript()	Melarikan diri dari karakter dalam string menggunakan aturan JavaScript string. catatan 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("\\'","'")"
$util.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 }
$util.urlEncode()	Mengkonversi string ke dalam format “aplikasi/x-www-form-urlencoded”.
$util.urlDecode()	Mendekode string “aplikasi/x-www-form-urlencoded”.
$util.base64Encode()	Mengkodekan data ke dalam string yang dikodekan base64.
$util.base64Decode()	Mendekode data dari string yang dikodekan base64.