Template pemetaan API Gateway dan referensi variabel pencatatan akses

Bagian ini menyediakan informasi referensi untuk variabel dan fungsi yang didefinisikan Amazon API Gateway untuk digunakan dengan model data, otorisasi, templat pemetaan, dan CloudWatch pencatatan akses. Untuk informasi rinci tentang cara menggunakan variabel dan fungsi ini, lihatTemplate pemetaan untuk REST APIs. Untuk informasi lebih lanjut tentang Velocity Template Language (VTL), lihat Referensi VTL.

catatan

Untuk $method dan $integration variabel, lihatReferensi pemetaan data permintaan dan respons API Amazon API Gateway.

$contextVariabel untuk model data, otorisasi, templat pemetaan, dan CloudWatch pencatatan akses

$contextVariabel berikut dapat digunakan dalam model data, otorisasi, templat pemetaan, dan logging CloudWatch akses. API Gateway mungkin menambahkan variabel konteks tambahan.

Untuk $context variabel yang hanya dapat digunakan dalam pencatatan CloudWatch akses, lihat$contextVariabel untuk akses logging saja.

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 API 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 WebSocket API eksekusi 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	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 WebSocket API eksekusi 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 Menggunakan template pemetaan untuk mengganti parameter permintaan dan respons API serta kode status.
$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 Menggunakan template pemetaan untuk mengganti parameter permintaan dan respons API serta kode status.
$context.requestOverride.querystring.querystring_name	Permintaan query string override. Jika parameter ini didefinisikan, ini berisi string permintaan permintaan yang akan digunakan alih-alih Parameter String Kueri URL yang didefinisikan di panel Permintaan Integrasi. Untuk informasi selengkapnya, lihat Menggunakan template pemetaan untuk mengganti parameter permintaan dan respons API serta kode status.
$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 Menggunakan template pemetaan untuk mengganti parameter permintaan dan respons API serta kode status.
$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 Menggunakan template pemetaan untuk mengganti parameter permintaan dan respons API serta kode status.
$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: Buat REST API dengan integrasi HTTP non-proxy.
$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.

$contextContoh template variabel

Anda mungkin ingin menggunakan $context variabel dalam template pemetaan jika metode API Anda meneruskan data terstruktur ke backend yang mengharuskan data berada dalam format tertentu.

Contoh berikut menunjukkan template pemetaan yang memetakan $context variabel masuk ke variabel backend dengan nama yang sedikit berbeda dalam payload permintaan integrasi:

catatan

Salah satu variabelnya adalah kunci API. Contoh ini mengasumsikan bahwa metode tersebut memerlukan kunci API.

{
    "stage" : "$context.stage",
    "request_id" : "$context.requestId",
    "api_id" : "$context.apiId",
    "resource_path" : "$context.resourcePath",
    "resource_id" : "$context.resourceId",
    "http_method" : "$context.httpMethod",
    "source_ip" : "$context.identity.sourceIp",
    "user-agent" : "$context.identity.userAgent",
    "account_id" : "$context.identity.accountId",
    "api_key" : "$context.identity.apiKey",
    "caller" : "$context.identity.caller",
    "user" : "$context.identity.user",
    "user_arn" : "$context.identity.userArn"
}

Output dari template pemetaan ini akan terlihat seperti berikut:

{
  stage: 'prod',
  request_id: 'abcdefg-000-000-0000-abcdefg',
  api_id: 'abcd1234',
  resource_path: '/',
  resource_id: 'efg567',
  http_method: 'GET',
  source_ip: '192.0.2.1',
  user-agent: 'curl/7.84.0',
  account_id: '111122223333',
  api_key: 'MyTestKey',
  caller: 'ABCD-0000-12345',
  user: 'ABCD-0000-12345',
  user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}

$contextVariabel untuk akses logging saja

$contextVariabel berikut hanya tersedia untuk logging akses. Untuk informasi selengkapnya, lihat Siapkan CloudWatch logging untuk REST APIs di API Gateway. (Untuk WebSocket APIs, lihatPantau WebSocket API eksekusi dengan CloudWatch metrik.)

Parameter	Deskripsi
$context.authorize.error	Pesan kesalahan otorisasi.
$context.authorize.latency	Latensi otorisasi di ms.
$context.authorize.status	Kode status dikembalikan dari upaya otorisasi.
$context.authorizer.error	Pesan kesalahan dikembalikan dari otorisasi.
$context.authorizer.integrationLatency	Latensi integrasi otorisasi di ms.
$context.authorizer.integrationStatus	Kode status dikembalikan dari otorisasi Lambda.
$context.authorizer.latency	Latensi otorisasi di ms.
$context.authorizer.requestId	ID permintaan AWS titik akhir.
$context.authorizer.status	Kode status dikembalikan dari otorisasi.
$context.authenticate.error	Pesan kesalahan dikembalikan dari upaya otentikasi.
$context.authenticate.latency	Latensi otentikasi di ms.
$context.authenticate.status	Kode status dikembalikan dari upaya otentikasi.
$context.customDomain.basePathMatched	Jalur untuk pemetaan API yang cocok dengan permintaan masuk. Berlaku ketika klien menggunakan nama domain khusus untuk mengakses API. Misalnya jika klien mengirim permintaan kehttps://api.example.com/v1/orders/1234, dan permintaan tersebut cocok dengan pemetaan API dengan jalurv1/orders, nilainya adalahv1/orders. Untuk mempelajari selengkapnya, lihat Memetakan tahapan API ke nama domain khusus untuk REST APIs.
$context.endpointType	Jenis titik akhir API.
$context.integration.error	Pesan kesalahan dikembalikan dari integrasi.
$context.integration.integrationStatus	Untuk integrasi proxy Lambda, kode status dikembalikan dari AWS Lambda, bukan dari kode fungsi Lambda backend.
$context.integration.latency	Latensi integrasi dalam ms. Setara dengan$context.integrationLatency.
$context.integration.requestId	ID permintaan AWS titik akhir. Setara dengan$context.awsEndpointRequestId.
$context.integration.status	Kode status dikembalikan dari integrasi. Untuk integrasi proxy Lambda, ini adalah kode status yang dikembalikan oleh kode fungsi Lambda Anda.
$context.integrationLatency	Latensi integrasi dalam ms.
$context.integrationStatus	Untuk integrasi proxy Lambda, parameter ini mewakili kode status yang dikembalikan dari AWS Lambda, bukan dari kode fungsi Lambda backend.
$context.responseLatency	Latensi respons dalam ms.
$context.responseLength	Panjang payload respon dalam byte.
$context.status	Status respons metode.
$context.waf.error	Pesan kesalahan dikembalikan dari AWS WAF.
$context.waf.latency	AWS WAF Latensi dalam ms.
$context.waf.status	Kode status dikembalikan dari AWS WAF.
$context.xrayTraceId	ID jejak untuk jejak X-Ray. Untuk informasi selengkapnya, lihat Siapkan AWS X-Ray dengan API Gateway REST APIs.

$inputVariabel

$inputVariabel mewakili payload permintaan metode dan parameter yang akan diproses oleh template pemetaan. Ini menyediakan fungsi-fungsi berikut:

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.

$inputContoh template variabel

Contoh berikut menunjukkan cara menggunakan $input variabel dalam template pemetaan. Anda dapat menggunakan integrasi tiruan atau integrasi non-proxy Lambda yang mengembalikan peristiwa input kembali ke API Gateway untuk mencoba contoh ini.

Contoh template pemetaan parameter

Contoh berikut meneruskan semua parameter permintaan, termasukpath,querystring, danheader, ke titik akhir integrasi melalui payload JSON:

#set($allParams = $input.params())
{
  "params" : {
    #foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
    "$type" : {
      #foreach($paramName in $params.keySet())
      "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
      #if($foreach.hasNext),#end
      #end
    }
    #if($foreach.hasNext),#end
    #end
  }
}

Untuk permintaan yang mencakup parameter input berikut:

• Parameter jalur bernama myparam

• Parameter string kueri querystring1=value1,value2&querystring2=value3

• Header"header1" : "value1","header2" : "value2","header3" : "value3".

Output dari template pemetaan ini akan terlihat seperti berikut:

{
  "params" : {
        "path" : {
            "path" : "myparam"
                }
    ,        "querystring" : {
            "querystring1" : "value1,value2"
      ,            "querystring2" : "value3"
                }
    ,        "header" : {
            "header3" : "value3"
      ,            "header2" : "value2"
      ,            "header1" : "value1"
                }
          }
}

Contoh template pemetaan JSON

Anda mungkin ingin menggunakan $input variabel untuk mendapatkan string kueri dan badan permintaan dengan atau tanpa menggunakan model. Anda mungkin juga ingin mendapatkan parameter dan payload, atau subbagian dari payload. Tiga contoh berikut menunjukkan bagaimana melakukan ini.

Contoh berikut menggunakan template pemetaan untuk mendapatkan subbagian dari payload. Contoh ini mendapatkan parameter input name dan kemudian seluruh badan POST:

{
    "name" : "$input.params('name')",
    "body" : $input.json('$') 
}

Untuk permintaan yang menyertakan parameter string kueri name=Bella&type=dog dan isi berikut:

{
    "Price" : "249.99",
    "Age": "6"
}

Output dari template pemetaan ini akan terlihat seperti berikut:

{
    "name" : "Bella",
    "body" : {"Price":"249.99","Age":"6"}
}

Jika input JSON berisi karakter unescaped yang tidak dapat diuraikan, API JavaScript Gateway mungkin menampilkan respons 400. Terapkan $util.escapeJavaScript($input.json('$')) untuk memastikan input JSON dapat diurai dengan benar.

Contoh sebelumnya dengan $util.escapeJavaScript($input.json('$')) diterapkan adalah sebagai berikut:

{
    "name" : "$input.params('name')",
    "body" : $util.escapeJavaScript($input.json('$'))
}

Dalam hal ini, output dari template pemetaan ini akan terlihat seperti berikut:

{
    "name" : "Bella",
    "body": {\"Price\":\"249.99\",\"Age\":\"6\"}
}

JSONPath contoh ekspresi

Contoh berikut menunjukkan bagaimana untuk meneruskan JSONPath ekspresi ke json() metode. Anda juga dapat membaca subbagian dari objek badan permintaan Anda dengan menggunakan titik,., untuk menentukan properti:

{
    "name" : "$input.params('name')",
    "body" : $input.json('$.Age')  
}

Untuk permintaan yang menyertakan parameter string kueri name=Bella&type=dog dan isi berikut:

{
    "Price" : "249.99",
    "Age": "6"
}

Output dari template pemetaan ini akan terlihat seperti berikut:

{
    "name" : "Bella",
    "body" : "6"
}

Jika payload permintaan metode berisi karakter unescaped yang tidak dapat diuraikan, API JavaScript Gateway mungkin menampilkan respons. 400 Terapkan $util.escapeJavaScript() untuk memastikan input JSON dapat diurai dengan benar.

Contoh sebelumnya dengan $util.escapeJavaScript($input.json('$.Age')) diterapkan adalah sebagai berikut:

{
    "name" : "$input.params('name')",
    "body" : "$util.escapeJavaScript($input.json('$.Age'))" 
}

Dalam hal ini, output dari template pemetaan ini akan terlihat seperti berikut:

{
    "name" : "Bella",
    "body": "\"6\""
}

Contoh permintaan dan respons

Contoh berikut menggunakan$input.params(),$input.path(), dan $input.json() untuk sumber daya dengan jalur/things/{id}:

{
    "id" : "$input.params('id')",
    "count" : "$input.path('$.things').size()",
    "things" : $input.json('$.things')"
}

Untuk permintaan yang menyertakan parameter jalur 123 dan isi berikut:

{
      "things": {
            "1": {},
            "2": {},
            "3": {}
      }
}

Output dari template pemetaan ini akan terlihat seperti berikut:

{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}

Jika payload permintaan metode berisi karakter unescaped yang tidak dapat diuraikan, API JavaScript Gateway mungkin menampilkan respons. 400 Terapkan $util.escapeJavaScript() untuk memastikan input JSON dapat diurai dengan benar.

Contoh sebelumnya dengan $util.escapeJavaScript($input.json('$.things')) diterapkan adalah sebagai berikut:

{
     "id" : "$input.params('id')",
     "count" : "$input.path('$.things').size()",
     "things" : "$util.escapeJavaScript($input.json('$.things'))"
}

Output dari template pemetaan ini akan terlihat seperti berikut:

{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}

Untuk contoh pemetaan lainnya, lihatTemplate pemetaan untuk REST APIs.

$stageVariables

Variabel tahap dapat digunakan dalam pemetaan parameter dan pemetaan template dan sebagai placeholder dalam ARNs dan URLs digunakan 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_name>merupakan nama variabel tahap.

$utilVariabel

$utilVariabel berisi fungsi utilitas untuk digunakan dalam template pemetaan.

catatan

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.