Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Memetakan transformasi template untuk REST APIs di API Gateway
Transformasi template pemetaan menggunakan template pemetaan untuk memodifikasi permintaan integrasi atau respons integrasi Anda. *Template pemetaan* adalah skrip yang dinyatakan dalam [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) dan diterapkan ke payload menggunakan [JSONPath ](https://goessner.net/articles/JsonPath/)berdasarkan header. `Content-type` Anda menggunakan templat pemetaan saat menggunakan transformasi templat pemetaan. Bagian ini menjelaskan informasi konseptual yang terkait dengan templat pemetaan.
Diagram berikut menunjukkan siklus hidup permintaan untuk `POST /pets` sumber daya yang memiliki integrasi dengan titik akhir PetStore integrasi. Di API ini, pengguna mengirim data tentang hewan peliharaan dan titik akhir integrasi mengembalikan biaya adopsi yang terkait dengan hewan peliharaan. Dalam siklus hidup permintaan ini, transformasi templat pemetaan memfilter badan permintaan ke titik akhir integrasi dan memfilter badan respons dari titik akhir integrasi.
![\[Contoh siklus hidup permintaan\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/mapping-template-transforms.png)
Bagian berikut menjelaskan siklus hidup permintaan dan respons.
## Permintaan metode dan permintaan integrasi
Pada contoh sebelumnya, jika ini adalah badan permintaan yang dikirim ke permintaan metode:
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
Badan permintaan ini tidak dalam format yang benar untuk digunakan oleh titik akhir integrasi, sehingga API Gateway melakukan transformasi template pemetaan. API Gateway hanya melakukan transformasi template pemetaan karena ada template pemetaan yang ditentukan untuk Content-Type. `application/json` Jika Anda tidak mendefinisikan template pemetaan untuk Content-Type, secara default, API Gateway meneruskan isi melalui permintaan integrasi ke titik akhir integrasi. Untuk mengubah perilaku ini, lihat[Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md).
Template pemetaan berikut mengubah data permintaan metode dalam permintaan integrasi sebelum dikirim ke titik akhir integrasi:
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. `$inputRoot`Variabel mewakili objek root dalam data JSON asli dari bagian sebelumnya. Arahan dimulai dengan `#` simbol.
1. `dog`Ini adalah gabungan dari pengguna `id` dan nilai string.
1. `Age`berasal dari badan permintaan metode.
Kemudian, output berikut diteruskan ke titik akhir integrasi:
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## Respon integrasi dan respons metode
Setelah permintaan berhasil ke titik akhir integrasi, titik akhir mengirimkan respons ke respons integrasi API Gateway. Berikut ini adalah contoh data output dari endpoint integrasi:
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
Respons metode mengharapkan muatan yang berbeda dari apa yang dikembalikan oleh respons integrasi. API Gateway melakukan transformasi template pemetaan. API Gateway hanya melakukan transformasi template pemetaan karena ada template pemetaan yang ditentukan untuk Content-Type. `application/json` Jika Anda tidak mendefinisikan template pemetaan untuk Content-Type, secara default, API Gateway meneruskan isi melalui respons integrasi ke respons metode. Untuk mengubah perilaku ini, lihat[Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md).
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
Output berikut dikirim ke respon metode:
```
{"adoptionFee": 19.95}
```
Ini melengkapi contoh transformasi template pemetaan. Sebaiknya jika memungkinkan, alih-alih menggunakan transformasi templat pemetaan, Anda menggunakan integrasi proxy untuk mengubah data Anda. Untuk informasi selengkapnya, lihat [Pilih jenis integrasi API Gateway API](api-gateway-api-integration-types.md).
# Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway
Jika permintaan metode Anda memiliki payload dan Anda tidak memiliki template pemetaan yang ditentukan untuk `Content-Type` header, Anda dapat memilih untuk meneruskan payload permintaan yang disediakan klien melalui permintaan integrasi ke backend tanpa transformasi. Proses ini dikenal sebagai integrasi passthrough.
Perilaku passthrough aktual dari permintaan yang masuk ditentukan oleh pengaturan ini. Ada tiga opsi:
**Bila tidak ada template yang cocok dengan header Content-Type permintaan**
Pilih opsi ini jika Anda ingin badan permintaan metode melewati permintaan integrasi ke backend tanpa transformasi ketika jenis konten permintaan metode tidak cocok dengan jenis konten apa pun yang terkait dengan templat pemetaan.
Saat memanggil API Gateway API, Anda memilih opsi ini dengan menetapkan `WHEN_NO_MATCH` sebagai nilai `passthroughBehavior` properti pada [Integrasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Ketika tidak ada templat yang ditentukan (disarankan)**
Pilih opsi ini jika Anda ingin badan permintaan metode melewati permintaan integrasi ke backend tanpa transformasi ketika tidak ada templat pemetaan yang ditentukan dalam permintaan integrasi. Jika templat ditentukan saat opsi ini dipilih, permintaan metode dengan jenis muatan dan konten yang tidak cocok dengan templat pemetaan yang ditentukan akan ditolak dengan respons Jenis Media Tidak Didukung HTTP 415.
Saat memanggil API Gateway API, Anda memilih opsi ini dengan menetapkan `WHEN_NO_TEMPLATES` sebagai nilai `passthroughBehavior` properti pada [Integrasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Tidak pernah**
Pilih opsi ini jika Anda tidak ingin badan permintaan metode melewati permintaan integrasi ke backend tanpa transformasi ketika tidak ada templat pemetaan yang ditentukan dalam permintaan integrasi. Jika templat ditentukan saat opsi ini dipilih, permintaan metode dari jenis konten yang tidak dipetakan akan ditolak dengan respons Jenis Media Tidak Didukung HTTP 415.
Saat memanggil API Gateway API, Anda memilih opsi ini dengan menetapkan `NEVER` sebagai nilai `passthroughBehavior` properti pada [Integrasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
Contoh berikut menunjukkan kemungkinan perilaku passthrough.
Contoh 1: Satu template pemetaan didefinisikan dalam permintaan integrasi untuk jenis `application/json` konten.
| Tipe konten | Opsi passthrough | Perilaku |
| --- | --- | --- |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1MATCH | Muatan permintaan diubah menggunakan templat. |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1TEMPLATES | Muatan permintaan diubah menggunakan templat. |
| Tidak ada API Gateway default ke `application/json` | NEVER | Muatan permintaan diubah menggunakan templat. |
| application/json | WHEN\$1NO\$1MATCH | Muatan permintaan diubah menggunakan templat. |
| application/json | WHEN\$1NO\$1TEMPLATES | Muatan permintaan diubah menggunakan templat. |
| application/json | NEVER | Muatan permintaan diubah menggunakan templat. |
| application/xml | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/xml | WHEN\$1NO\$1TEMPLATES | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/xml | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
Contoh 2: Satu template pemetaan didefinisikan dalam permintaan integrasi untuk jenis `application/xml` konten.
| Tipe konten | Opsi passthrough | Perilaku |
| --- | --- | --- |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1TEMPLATES | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| Tidak ada API Gateway default ke `application/json` | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/json | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/json | WHEN\$1NO\$1TEMPLATES | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/json | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/xml | WHEN\$1NO\$1MATCH | Muatan permintaan diubah menggunakan templat. |
| application/xml | WHEN\$1NO\$1TEMPLATES | Muatan permintaan diubah menggunakan templat. |
| application/xml | NEVER | Muatan permintaan diubah menggunakan templat. |
Contoh 3: Tidak ada templat pemetaan yang ditentukan dalam permintaan integrasi.
| Tipe konten | Opsi passthrough | Perilaku |
| --- | --- | --- |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1TEMPLATES | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| Tidak ada API Gateway default ke `application/json` | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/json | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/json | WHEN\$1NO\$1TEMPLATES | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/json | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/xml | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/xml | WHEN\$1NO\$1TEMPLATES | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/xml | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
# Contoh template pemetaan tambahan untuk REST APIs di API Gateway
Contoh berikut menunjukkan API album foto di API Gateway yang menggunakan templat pemetaan untuk mengubah permintaan integrasi dan data respons integrasi. Ini juga menggunakan model data untuk menentukan permintaan metode dan muatan respons integrasi. Untuk informasi selengkapnya tentang model data, lihat[Model data untuk REST APIs](models-mappings-models.md).
## Permintaan metode dan permintaan integrasi
Berikut ini adalah model yang mendefinisikan badan permintaan metode. Model input ini mengharuskan penelepon mengunggah satu halaman foto, dan membutuhkan minimal 10 foto untuk setiap halaman. Anda dapat menggunakan model input ini untuk menghasilkan SDK atau menggunakan validasi permintaan untuk API Anda. Saat menggunakan validasi permintaan, jika badan permintaan metode tidak mematuhi struktur data model, API Gateway gagal permintaan.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
Berikut ini adalah contoh badan permintaan metode yang mematuhi struktur data dari model data sebelumnya.
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
Dalam contoh ini, jika badan permintaan metode sebelumnya dikirimkan oleh klien, maka template pemetaan ini mengubah payload agar sesuai dengan format yang diperlukan oleh titik akhir integrasi.
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
Contoh berikut adalah data output dari transformasi:
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Data ini dikirim ke permintaan integrasi, dan kemudian ke titik akhir integrasi.
## Respon integrasi dan respons metode
Berikut ini adalah contoh model keluaran untuk data foto dari titik akhir integrasi. Anda dapat menggunakan model ini untuk model respons metode, yang diperlukan saat Anda membuat SDK yang diketik kuat untuk API. Hal ini menyebabkan output dilemparkan ke kelas yang sesuai di Java atau Objective-C.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
Titik akhir integrasi mungkin tidak merespons dengan respons yang mematuhi struktur data model ini. Misalnya, respons integrasi mungkin terlihat seperti berikut:
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
Contoh template pemetaan berikut mengubah data respons integrasi ke dalam format yang diharapkan oleh respons metode:
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
Contoh berikut adalah data output dari transformasi:
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Data ini dikirim ke respons metode dan kemudian kembali ke klien.
# Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway
Anda dapat menggunakan transformasi templat pemetaan untuk mengganti semua jenis parameter permintaan, header respons, atau kode status respons. Anda menggunakan template pemetaan untuk melakukan hal berikut:
+ Lakukan pemetaan many-to-one parameter
+ Ganti parameter setelah pemetaan API Gateway standar diterapkan
+ Parameter peta kondisional berdasarkan konten tubuh atau nilai parameter lainnya
+ Buat parameter baru secara terprogram
+ Ganti kode status yang dikembalikan oleh titik akhir integrasi Anda
Override adalah final. Override hanya dapat diterapkan ke setiap parameter satu kali. Jika Anda mencoba mengganti parameter yang sama beberapa kali, API Gateway mengembalikan `5XX` respons. Jika Anda harus mengganti parameter yang sama beberapa kali di seluruh template, kami sarankan membuat variabel dan menerapkan override di akhir template. Template diterapkan hanya setelah seluruh template diurai.
## Contoh 1: Ganti kode status berdasarkan badan integrasi
Contoh berikut menggunakan [API contoh](api-gateway-create-api-from-example.md) untuk mengganti kode status berdasarkan badan respons integrasi.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengganti kode status berdasarkan badan respons integrasi**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Buat API**.
1. Untuk **REST API**, pilih **Build**.
1. Untuk **detail API**, pilih **API Contoh**.
1. Pilih **Buat API**.
API Gateway membuat contoh API toko hewan peliharaan. Untuk mengambil informasi tentang hewan peliharaan, Anda menggunakan permintaan metode API`GET /pets/{petId}`, di mana `{petId}` parameter jalur yang sesuai dengan nomor ID untuk hewan peliharaan.
Dalam contoh ini, Anda mengganti kode respons `GET` metode `400` saat kondisi kesalahan terdeteksi.
1. Di pohon **Resources**, pilih `GET` metode di bawah`/{petId}`.
1. Pertama, Anda menguji implementasi API saat ini.
Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
1. **Untuk **PeTiD**, masukkan**-1**, lalu pilih Test.**
**Badan Respons** menunjukkan out-of-range kesalahan:
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Selain itu, baris terakhir di bawah **Log** diakhiri dengan:`Method completed with status: 200`.
Integrasi berhasil diselesaikan, tetapi ada kesalahan. Sekarang Anda akan mengganti kode status berdasarkan respons integrasi.
1. Pada tab **Respons Integrasi**, untuk **Default - Respons**, pilih **Edit**.
1. Pilih **template Pemetaan**.
1. Pilih **Tambahkan templat pemetaan**.
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **badan Template**, masukkan yang berikut ini:
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
Template pemetaan ini menggunakan `$context.responseOverride.status` variabel untuk mengganti kode status `400` jika respons integrasi berisi string. `error`
1. Pilih **Simpan**.
1. Pilih tab **Uji**.
1. Untuk **PeTiD, masukkan**. **-1**
1. Dalam hasilnya, **Response Body** menunjukkan out-of-range kesalahan:
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Namun, baris terakhir di bawah **Log** sekarang berakhir dengan:`Method completed with status: 400`.
------
#### [ CloudFormation ]
Dalam contoh ini, Anda menggunakan properti [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) untuk mengimpor file definisi OpenAPI ke API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
Definisi OpenAPI berikut membuat `GET pets/{petId}` sumber daya dan mengganti kode status berdasarkan badan integrasi.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## Contoh 2: Ganti header permintaan dan buat header baru
Contoh berikut menggunakan [API contoh](api-gateway-create-api-from-example.md) untuk mengganti header permintaan dan membuat header baru.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengganti header permintaan metode dengan membuat header baru**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih contoh API yang Anda buat di tutorial sebelumnya. Nama API seharusnya **PetStore**.
1. Di pohon **Resources**, pilih `GET` metode di bawah`/pet`.
1. Pada tab **Permintaan metode**, untuk **pengaturan permintaan Metode**, pilih **Edit**.
1. Pilih **header permintaan HTTP**, lalu pilih **Tambah header**.
1. Untuk **Nama**, masukkan **header1**.
1. Pilih **Tambahkan header**, lalu buat header kedua yang disebut**header2**.
1. Pilih **Simpan**.
Sekarang, Anda menggabungkan header ini menjadi satu nilai header menggunakan template pemetaan.
1. Pada tab **Permintaan integrasi**, untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
1. Untuk **Request body passthrough**, pilih **Bila tidak ada templat yang ditentukan (disarankan)**.
1. Pilih **template Pemetaan**, lalu lakukan hal berikut:
1. Pilih **Tambahkan templat pemetaan**.
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **badan Template**, masukkan yang berikut ini:
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
Template pemetaan ini diganti `header1` dengan string `pets` dan membuat header multi-nilai yang disebut `$header3Value` yang menggabungkan dan. `header1` `header2`
1. Pilih **Simpan**.
1. Pilih tab **Uji**.
1. Di bawah **Header**, salin kode berikut:
```
header1:header1Val
header2:header2Val
```
1. Pilih **Uji**.
Di **Log**, Anda akan melihat entri yang menyertakan teks ini:
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
Dalam contoh ini, Anda menggunakan properti [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) untuk mengimpor file definisi OpenAPI ke API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
Definisi OpenAPI berikut membuat `GET pets` sumber daya dan mengganti header permintaan dan membuat header baru.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
Untuk menggunakan penggantian template pemetaan, tambahkan satu atau beberapa variabel berikut`$context`. Untuk daftar `$context` variabel, lihat[Variabel konteks untuk transformasi data](api-gateway-mapping-template-reference.md#context-variable-reference).
# Tutorial: Memodifikasi permintaan integrasi dan respon untuk integrasi ke layanan AWS
Tutorial berikut menunjukkan cara menggunakan transformasi template pemetaan untuk mengatur template pemetaan untuk mengubah permintaan integrasi dan tanggapan menggunakan konsol dan CLI. AWS
**Topics**
+ [
## Mengatur transformasi data menggunakan konsol API Gateway
](#mapping-example-console)
+ [
## Mengatur transformasi data menggunakan AWS CLI
](#mapping-example-cli)
+ [
## CloudFormation Templat transformasi data yang lengkap
](#api-gateway-data-transformations-full-cfn-stack)
## Mengatur transformasi data menggunakan konsol API Gateway
[Dalam tutorial ini, Anda akan membuat tabel API dan DynamoDB yang tidak lengkap menggunakan file.zip berikut.zip. data-transformation-tutorial-console](samples/data-transformation-tutorial-console.zip) API yang tidak lengkap ini memiliki `/pets` sumber daya dengan `GET` dan `POST` metode.
+ `GET`Metode ini akan mendapatkan data dari titik akhir `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP. Data keluaran akan diubah sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
+ `POST`Metode ini akan memungkinkan pengguna untuk menyimpan informasi `POST` ke tabel Amazon DynamoDB menggunakan template pemetaan.
Unduh dan unzip [template pembuatan aplikasi untuk CloudFormation](samples/data-transformation-tutorial-console.zip). Anda akan menggunakan template ini untuk membuat tabel DynamoDB untuk memposting informasi hewan peliharaan dan API yang tidak lengkap. Anda akan menyelesaikan langkah-langkah lainnya di konsol API Gateway.
**Untuk membuat CloudFormation tumpukan**
1. Buka CloudFormation konsol di [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Pilih **Buat tumpukan** kemudian pilih **Dengan sumber daya baru (standar)**.
1. Untuk **Tentukan templat**, pilih **Unggah file templat**.
1. Pilih template yang Anda unduh.
1. Pilih **Berikutnya**.
1. Untuk **nama Stack**, masukkan **data-transformation-tutorial-console** dan kemudian pilih **Berikutnya**.
1. Untuk **opsi Konfigurasi tumpukan**, pilih **Berikutnya**.
1. Untuk **Kemampuan**, akui bahwa CloudFormation dapat membuat sumber daya IAM di akun Anda.
1. Pilih **Berikutnya**, lalu pilih **Kirim**.
CloudFormation ketentuan sumber daya yang ditentukan dalam template. Diperlukan beberapa menit untuk menyelesaikan penyediaan sumber daya Anda. Ketika status CloudFormation tumpukan Anda adalah **CREATE\$1COMPLETE**, Anda siap untuk melanjutkan ke langkah berikutnya.
**Untuk menguji respon `GET` integrasi**
1. Pada tab **Sumber Daya** CloudFormation tumpukan untuk**data-transformation-tutorial-console**, pilih ID fisik API Anda.
1. Di panel navigasi utama, pilih **Resources**, lalu pilih metode **GET**.
1. Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
Output dari tes akan menunjukkan yang berikut:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Anda akan mengubah output ini sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
**Untuk mengubah respon `GET` integrasi**
1. Pilih tab **Respons Integrasi**.
Saat ini, tidak ada template pemetaan yang ditentukan, sehingga respons integrasi tidak akan diubah.
1. Untuk **Default - Respons**, pilih **Edit**.
1. Pilih **template Pemetaan**, lalu lakukan hal berikut:
1. Pilih **Tambahkan templat pemetaan**.
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **badan Template**, masukkan yang berikut ini:
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
Pilih **Simpan**.
**Untuk menguji respon `GET` integrasi**
+ Pilih tab **Test**, lalu pilih **Test**.
Output dari tes akan menunjukkan respons yang diubah.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Untuk mengubah data masukan dari `POST` metode**
1. Pilih metode **POST**.
1. Pilih tab **Permintaan integrasi**, dan kemudian untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
CloudFormation Template telah mengisi beberapa bidang permintaan integrasi.
+ Jenis integrasi adalah Layanan AWS.
+ Layanan AWS Ini adalah DynamoDB.
+ Metode HTTP adalah`POST`.
+ Tindakan adalah`PutItem`.
+ Peran Eksekusi yang memungkinkan API Gateway untuk menempatkan item ke dalam tabel DynamoDB adalah. `data-transformation-tutorial-console-APIGatewayRole` CloudFormation membuat peran ini untuk memungkinkan API Gateway memiliki izin minimal untuk berinteraksi dengan DynamoDB.
Nama tabel DynamoDB belum ditentukan. Anda akan menentukan nama dalam langkah-langkah berikut.
1. Untuk **Request body passthrough**, pilih **Never**.
Ini berarti bahwa API akan menolak data dengan Content-Types yang tidak memiliki template pemetaan.
1. Pilih **template Pemetaan**.
1. **Jenis Konten** diatur ke`application/json`. Ini berarti jenis konten yang tidak application/json akan ditolak oleh API. Untuk informasi selengkapnya tentang perilaku passthrough integrasi, lihat [Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md)
1. Masukkan kode berikut ke dalam editor teks.
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
Template ini menentukan tabel sebagai `data-transformation-tutorial-console-ddb` dan menetapkan item sebagai`id`,`type`, dan`price`. Item akan berasal dari tubuh `POST` metode. Anda juga dapat menggunakan model data untuk membantu membuat template pemetaan. Untuk informasi selengkapnya, lihat [Minta validasi untuk REST APIs di API Gateway](api-gateway-method-request-validation.md).
1. Pilih **Simpan** untuk menyimpan template pemetaan Anda.
**Untuk menambahkan metode dan respons integrasi dari `POST` metode**
CloudFormation Membuat metode kosong dan respons integrasi. Anda akan mengedit tanggapan ini untuk memberikan informasi lebih lanjut. Untuk informasi selengkapnya tentang cara mengedit tanggapan, lihat[Contoh pemetaan parameter untuk REST APIs di API Gateway](request-response-data-mappings.md).
1. Pada tab **Respons Integrasi**, untuk **Default - Respons**, pilih **Edit**.
1. Pilih **Templat pemetaan**, lalu pilih **Tambahkan templat pemetaan**.
1. Untuk **tipe Konten, masukkan**. **application/json**
1. Di editor kode, masukkan template pemetaan keluaran berikut untuk mengirim pesan output:
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
Untuk informasi lebih lanjut tentang variabel konteks, lihat[Variabel konteks untuk transformasi data](api-gateway-mapping-template-reference.md#context-variable-reference).
1. Pilih **Simpan** untuk menyimpan template pemetaan Anda.
**Uji `POST` metodenya**
Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
1. Di badan permintaan, masukkan contoh berikut.
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. Pilih **Uji**.
Output harus menunjukkan pesan sukses Anda.
Anda dapat membuka konsol DynamoDB [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)di untuk memverifikasi bahwa item contoh ada di tabel Anda.
**Untuk menghapus CloudFormation tumpukan**
1. Buka CloudFormation konsol di [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Pilih CloudFormation tumpukan Anda.
1. Pilih **Hapus** dan kemudian konfirmasikan pilihan Anda.
## Mengatur transformasi data menggunakan AWS CLI
[Dalam tutorial ini, Anda akan membuat tabel API dan DynamoDB yang tidak lengkap menggunakan file.zip berikut.zip. data-transformation-tutorial-cli](samples/data-transformation-tutorial-cli.zip) API yang tidak lengkap ini memiliki `/pets` sumber daya dengan `GET` metode yang terintegrasi dengan titik akhir `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP. Anda akan membuat `POST` metode untuk terhubung ke tabel DynamoDB dan menggunakan template pemetaan untuk memasukkan data ke dalam tabel DynamoDB.
+ Anda akan mengubah data keluaran sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
+ Anda akan membuat `POST` metode untuk memungkinkan pengguna untuk menyimpan informasi ke `POST` tabel Amazon DynamoDB menggunakan template pemetaan.
**Untuk membuat CloudFormation tumpukan**
Unduh dan unzip [template pembuatan aplikasi untuk CloudFormation](samples/data-transformation-tutorial-cli.zip).
Untuk menyelesaikan tutorial berikut, Anda memerlukan [AWS Command Line Interface (AWS CLI) versi 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Untuk perintah panjang, karakter escape (`\`) digunakan untuk memisahkan perintah menjadi beberapa baris.
**catatan**
Di Windows, beberapa perintah Bash CLI yang biasa Anda gunakan (`zip`seperti) tidak didukung oleh terminal bawaan sistem operasi. Untuk mendapatkan versi terintegrasi Windows dari Ubuntu dan Bash, [instal Windows Subsystem untuk](https://learn.microsoft.com/en-us/windows/wsl/install) Linux. Contoh perintah CLI dalam panduan ini menggunakan pemformatan Linux. Perintah yang menyertakan dokumen JSON sebaris harus diformat ulang jika Anda menggunakan CLI Windows.
1. Gunakan perintah berikut untuk membuat CloudFormation tumpukan.
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation ketentuan sumber daya yang ditentukan dalam template. Diperlukan beberapa menit untuk menyelesaikan penyediaan sumber daya Anda. Gunakan perintah berikut untuk melihat status CloudFormation tumpukan Anda.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. Ketika status CloudFormation tumpukan Anda`StackStatus: "CREATE_COMPLETE"`, gunakan perintah berikut untuk mengambil nilai output yang relevan untuk langkah-langkah masa depan.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
Nilai output adalah sebagai berikut:
+ ApiRole, yang merupakan nama peran yang memungkinkan API Gateway untuk menempatkan item dalam tabel DynamoDB. Untuk tutorial ini, nama perannya adalah`data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`.
+ DDBTableNama, yang merupakan nama tabel DynamoDB. Untuk tutorial ini, nama tabelnya adalah `data-transformation-tutorial-cli-ddb`
+ ResourceId, yang merupakan ID untuk sumber daya hewan peliharaan tempat `POST` metode `GET` dan diekspos. Untuk tutorial ini, Resource ID adalah `efg456`
+ ApiId, yang merupakan ID untuk API. Untuk tutorial ini, ID API adalah`abc123`.
**Untuk menguji `GET` metode sebelum transformasi data**
+ Gunakan perintah berikut untuk menguji `GET` metode.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
Output dari tes akan menunjukkan yang berikut ini.
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Anda akan mengubah output ini sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
**Untuk mengubah respon `GET` integrasi**
+ Gunakan perintah berikut untuk memperbarui respons integrasi untuk `GET` metode ini. Ganti *rest-api-id* dan *resource-id* dengan nilai-nilai Anda.
Gunakan perintah berikut untuk membuat respons integrasi.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**Untuk menguji `GET` metode**
+ Gunakan perintah berikut untuk menguji `GET` metode.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
Output dari tes akan menunjukkan respons yang diubah.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Untuk membuat `POST` metode**
1. Gunakan perintah berikut untuk membuat metode baru pada `/pets` sumber daya.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
Metode ini akan memungkinkan Anda untuk mengirim informasi hewan peliharaan ke tabel DynamoDB yang Anda buat di tumpukan. CloudFormation
1. Gunakan perintah berikut untuk membuat Layanan AWS integrasi pada `POST` metode.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. Gunakan perintah berikut untuk membuat respons metode untuk panggilan `POST` metode yang berhasil.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. Gunakan perintah berikut untuk membuat respons integrasi untuk panggilan `POST` metode yang berhasil.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**Untuk menguji `POST` metode**
+ Gunakan perintah berikut untuk menguji `POST` metode.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
Output akan menampilkan pesan yang berhasil.
**Untuk menghapus CloudFormation tumpukan**
+ Gunakan perintah berikut untuk menghapus CloudFormation sumber daya Anda.
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## CloudFormation Templat transformasi data yang lengkap
Contoh berikut adalah CloudFormation template lengkap, yang membuat API dan tabel DynamoDB dengan sumber daya `/pets` `GET` dengan dan metode. `POST`
+ `GET`Metode ini akan mendapatkan data dari titik akhir `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP. Data keluaran akan diubah sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
+ `POST`Metode ini akan memungkinkan pengguna untuk menyimpan informasi `POST` ke tabel DynamoDB menggunakan template pemetaan.
### Contoh CloudFormation template
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# Contoh menggunakan variabel untuk memetakan transformasi template untuk API Gateway
Contoh berikut menunjukkan cara menggunakan`$context`,`input`, dan `util` variabel dalam template pemetaan. Anda dapat menggunakan integrasi tiruan atau integrasi non-proxy Lambda yang mengembalikan peristiwa input kembali ke API Gateway. Untuk daftar semua variabel yang didukung untuk transformasi data, lihat[Variabel untuk transformasi data untuk API Gateway](api-gateway-mapping-template-reference.md).
## Contoh 1: Berikan beberapa `$context` variabel ke titik akhir integrasi
Contoh berikut menunjukkan template pemetaan yang memetakan `$context` variabel masuk ke variabel backend dengan nama yang sedikit berbeda dalam payload permintaan integrasi:
```
{
"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'
}
```
Salah satu variabelnya adalah kunci API. Contoh ini mengasumsikan bahwa metode tersebut memerlukan kunci API.
## Contoh 2: Teruskan semua parameter permintaan ke titik akhir integrasi melalui payload JSON
Contoh berikut meneruskan semua parameter permintaan, termasuk`path`,`querystring`, dan `header` parameter, 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
}
}
```
Jika permintaan memiliki parameter input berikut:
+ Parameter jalur bernama `myparam`
+ Parameter string kueri `querystring1=value1,value2`
+ Header. `"header1" : "value1"`
Output dari template pemetaan ini akan terlihat seperti berikut:
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## Contoh 3: Lulus subbagian dari permintaan metode ke titik akhir integrasi
Contoh berikut menggunakan parameter input `name` untuk mengambil hanya `name` parameter dan parameter input `input.json('$')` untuk mengambil seluruh isi permintaan metode:
```
{
"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"}
}
```
Template pemetaan ini menghapus parameter `type=dog` string kueri.
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"}
}
```
## Contoh 4: Gunakan JSONPath ekspresi untuk meneruskan subbagian dari permintaan metode ke titik akhir integrasi
Contoh berikut menggunakan JSONPath ekspresi untuk mengambil hanya parameter input `name` dan `Age` dari badan permintaan:
```
{
"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"
}
```
Template pemetaan ini menghapus parameter string kueri `type=dog` dan `Price` bidang dari badan.
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 5: Gunakan JSONPath ekspresi untuk meneruskan informasi tentang permintaan metode ke titik akhir integrasi
Contoh berikut menggunakan`$input.params()`,`$input.path()`, dan `$input.json()` untuk mengirim informasi tentang permintaan metode ke titik akhir integrasi. Template pemetaan ini menggunakan `size()` metode untuk memberikan jumlah elemen dalam daftar.
```
{
"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\":{}}"}
```