Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Transformasi data untuk REST APIs di API Gateway
**catatan**
Bagian ini menjelaskan fitur yang Anda gunakan dengan integrasi non-proxy. Namun, kami menyarankan jika memungkinkan, Anda menggunakan integrasi proxy untuk REST API Anda. Integrasi proxy memiliki pengaturan integrasi yang efisien dan dapat berkembang dengan backend tanpa harus meruntuhkan pengaturan yang ada. Untuk informasi selengkapnya, lihat [Pilih jenis integrasi API Gateway API](api-gateway-api-integration-types.md).
Jika Anda menggunakan integrasi non-proxy, Anda dapat menggunakan dua fitur API Gateway untuk mengubah permintaan metode dan respons integrasi Anda. Anda dapat mengubah permintaan metode jika membutuhkan format payload yang berbeda dari payload permintaan integrasi. Anda dapat mengubah respons integrasi Anda jika mengembalikan format payload yang berbeda dari format yang perlu Anda kembalikan dalam respons metode. Untuk informasi selengkapnya tentang siklus hidup permintaan, lihat. [Contoh sumber daya untuk REST API](rest-api-develop.md#rest-api-develop-example)
Contoh berikut menunjukkan transformasi data di mana untuk header`"x-version:beta"`, parameter `x-version` header diubah menjadi parameter `app-version` header. Transformasi data dari `x-version` ke `app-version` terjadi dalam permintaan integrasi. Dengan begitu, titik akhir integrasi menerima nilai parameter header yang diubah. Ketika titik akhir integrasi mengembalikan kode status, kode status diubah dari `200` ke `204` sebelum respons metode.
![\[Diagram transformasi data API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/develop-non-proxy.png)
Untuk membuat transformasi data, Anda dapat menggunakan fitur berikut:
**Pemetaan parameter**
Dalam pemetaan parameter, Anda dapat mengubah parameter jalur URL permintaan integrasi, parameter string kueri URL, atau nilai header HTTP, tetapi Anda tidak dapat mengubah payload permintaan integrasi. Anda juga dapat memodifikasi nilai header respons HTTP. Gunakan pemetaan parameter untuk membuat nilai header statis untuk berbagi sumber daya lintas asal (CORS).
Anda dapat menggunakan pemetaan parameter dalam permintaan integrasi untuk integrasi proxy dan non-proxy, tetapi untuk menggunakan pemetaan parameter untuk respons integrasi, Anda memerlukan integrasi non-proxy. Pemetaan parameter tidak memerlukan skrip apa pun di [Velocity Template Language (](https://velocity.apache.org/engine/devel/vtl-reference.html)VTL). Untuk informasi selengkapnya, lihat [Pemetaan parameter untuk REST APIs di API Gateway](rest-api-parameter-mapping.md).
**Pemetaan transformasi template**
Dalam transformasi template pemetaan, Anda menggunakan template pemetaan untuk memetakan parameter jalur URL, parameter string kueri URL, header HTTP, dan permintaan integrasi atau badan respons integrasi. *Template pemetaan* adalah skrip yang dinyatakan dalam [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) menggunakan [JSONPath ekspresi](https://goessner.net/articles/JsonPath/) dan diterapkan pada payload berdasarkan header. `Content-type`
Dengan template pemetaan, Anda dapat melakukan hal berikut:
+ Pilih data mana yang akan dikirim menggunakan integrasi Layanan AWS, seperti fungsi Amazon DynamoDB atau Lambda, atau titik akhir HTTP. Untuk informasi selengkapnya, lihat [Tutorial: Memodifikasi permintaan integrasi dan respon untuk integrasi ke layanan AWS](set-up-data-transformations-in-api-gateway.md).
+ Ganti permintaan integrasi API dan parameter respons integrasi secara kondisional, buat nilai header baru, dan ganti kode status. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md).
Anda juga dapat menentukan perilaku API Anda ketika badan permintaan integrasi memiliki `Content-type` header tanpa templat pemetaan yang cocok. Ini disebut perilaku passthrough integrasi. Untuk informasi selengkapnya, lihat [Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md).
## Pilih antara pemetaan parameter dan transformasi template pemetaan
Kami menyarankan Anda menggunakan pemetaan parameter untuk mengubah data Anda bila memungkinkan. Jika API Anda mengharuskan Anda mengubah isi, atau mengharuskan Anda melakukan penggantian dan modifikasi bersyarat berdasarkan permintaan integrasi atau respons integrasi yang masuk, dan Anda tidak dapat menggunakan integrasi proxy, gunakan transformasi templat pemetaan.
# Pemetaan parameter untuk REST APIs di API Gateway
**catatan**
Jika Anda menggunakan API HTTP, lihat[Mengubah permintaan dan tanggapan API untuk HTTP APIs di API Gateway](http-api-parameter-mapping.md).
Dalam pemetaan parameter, Anda memetakan parameter permintaan atau respons. Anda dapat memetakan parameter menggunakan ekspresi pemetaan parameter atau nilai statis. Untuk daftar ekspresi pemetaan, lihat[Referensi sumber pemetaan parameter untuk REST APIs di API Gateway](rest-api-parameter-mapping-sources.md). Anda dapat menggunakan pemetaan parameter dalam permintaan integrasi untuk integrasi proxy dan non-proxy, tetapi untuk menggunakan pemetaan parameter untuk respons integrasi, Anda memerlukan integrasi non-proxy.
Misalnya, Anda dapat memetakan parameter header permintaan metode `puppies` ke parameter header permintaan integrasi`DogsAge0`. Kemudian, jika klien mengirim header `puppies:true` ke API Anda, permintaan integrasi mengirimkan header permintaan `DogsAge0:true` ke titik akhir integrasi. Diagram berikut menunjukkan siklus hidup permintaan dari contoh ini.
![\[Diagram contoh pemetaan parameter API Gateway untuk permintaan\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
Untuk membuat contoh ini menggunakan API Gateway, lihat[Contoh 1: Petakan parameter permintaan metode ke parameter permintaan integrasi](request-response-data-mappings.md#request-response-data-mappings-example-1).
Sebagai contoh lain, Anda juga dapat memetakan parameter header respons integrasi `kittens` ke parameter header respons metode`CatsAge0`. Kemudian, jika titik akhir integrasi kembali`kittens:false`, klien menerima header`CatsAge0:false`. Diagram berikut menunjukkan siklus hidup permintaan dari contoh ini.
![\[Diagram contoh pemetaan parameter API Gateway untuk respons\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [Contoh pemetaan parameter untuk REST APIs di API Gateway](request-response-data-mappings.md)
+ [Referensi sumber pemetaan parameter untuk REST APIs di API Gateway](rest-api-parameter-mapping-sources.md)
# Contoh pemetaan parameter untuk REST APIs di API Gateway
Contoh berikut menunjukkan cara membuat ekspresi pemetaan parameter menggunakan konsol API Gateway, OpenAPI, CloudFormation dan template. Untuk contoh cara menggunakan pemetaan parameter untuk membuat header CORS yang diperlukan, lihat. [CORS untuk REST APIs di API Gateway](how-to-cors.md)
## Contoh 1: Petakan parameter permintaan metode ke parameter permintaan integrasi
Contoh berikut memetakan parameter header permintaan metode `puppies` ke parameter header permintaan integrasi`DogsAge0`.
------
#### [ Konsol Manajemen AWS ]
**Untuk memetakan parameter permintaan metode**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih metode.
Metode Anda harus memiliki integrasi non-proxy.
1. Untuk **pengaturan permintaan Metode**, pilih **Edit**.
1. Pilih **header permintaan HTTP**.
1. Pilih **Tambahkan header**.
1. Untuk **Nama**, masukkan **puppies**.
1. Pilih **Simpan**.
1. Pilih tab **Permintaan integrasi**, dan kemudian untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
Konsol Manajemen AWS Secara otomatis menambahkan pemetaan parameter dari `method.request.header.puppies ` ke `puppies` untuk Anda, tetapi Anda perlu mengubah **Nama** agar sesuai dengan parameter header permintaan yang diharapkan oleh titik akhir integrasi Anda.
1. Untuk **Nama**, masukkan **DogsAge0**.
1. Pilih **Simpan**.
1. Menerapkan ulang API Anda agar perubahan diterapkan.
Langkah-langkah berikut menunjukkan cara memverifikasi bahwa pemetaan parameter Anda berhasil.
**(Opsional) Uji pemetaan parameter Anda**
1. Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
1. Untuk header, masukkan**puppies:true**.
1. Pilih **Uji**.
1. Dalam **Log**, hasilnya akan terlihat seperti berikut:
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
Parameter header permintaan telah berubah dari `puppies` menjadi`DogsAge0`.
------
#### [ 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: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
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 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## Contoh 2: Petakan beberapa parameter permintaan metode ke parameter permintaan integrasi yang berbeda
Contoh berikut memetakan parameter string permintaan metode multi-nilai `methodRequestQueryParam` ke parameter string kueri permintaan integrasi `integrationQueryParam` dan memetakan parameter header permintaan metode `methodRequestHeaderParam` ke parameter `integrationPathParam` jalur permintaan integrasi.
------
#### [ Konsol Manajemen AWS ]
**Untuk memetakan parameter permintaan metode**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih metode.
Metode Anda harus memiliki integrasi non-proxy.
1. Untuk **pengaturan permintaan Metode**, pilih **Edit**.
1. Pilih **parameter string kueri URL**.
1. Pilih **Tambahkan string kueri**.
1. Untuk **Nama**, masukkan **methodRequestQueryParam**.
1. Pilih **header permintaan HTTP**.
1. Pilih **Tambahkan header**.
1. Untuk **Nama**, masukkan **methodRequestHeaderParam**.
1. Pilih **Simpan**.
1. Pilih tab **Permintaan integrasi**, dan kemudian untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
1. Pilih **parameter jalur URL**.
1. Pilih **Tambahkan parameter jalur**.
1. Untuk **Nama**, masukkan **integrationPathParam**.
1. Untuk **Dipetakan dari**, masukkan**method.request.header.methodRequestHeaderParam**.
Ini memetakan header permintaan metode yang Anda tentukan dalam permintaan metode ke parameter jalur permintaan integrasi baru.
1. Pilih **parameter string kueri URL**.
1. Pilih **Tambahkan string kueri**.
1. Untuk **Nama**, masukkan **integrationQueryParam**.
1. Untuk **Dipetakan dari**, masukkan**method.request.multivaluequerystring.methodRequestQueryParam**.
Ini memetakan parameter string kueri multivalue ke parameter string kueri permintaan integrasi bernilai tunggal baru.
1. Pilih **Simpan**.
1. Menerapkan ulang API Anda agar perubahan diterapkan.
------
#### [ 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.
Definisi OpenAPI berikut membuat pemetaan parameter berikut untuk integrasi HTTP:
+ Header permintaan metode, bernama`methodRequestHeaderParam`, ke dalam parameter jalur permintaan integrasi, bernama `integrationPathParam`
+ Metode multi-nilai meminta string kueri, bernama`methodRequestQueryParam`, ke dalam string permintaan permintaan integrasi, bernama `integrationQueryParam`
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
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 pemetaan parameter berikut untuk integrasi HTTP:
+ Header permintaan metode, bernama`methodRequestHeaderParam`, ke dalam parameter jalur permintaan integrasi, bernama `integrationPathParam`
+ Metode multi-nilai meminta string kueri, bernama`methodRequestQueryParam`, ke dalam string permintaan permintaan integrasi, bernama `integrationQueryParam`
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Contoh 3: Memetakan bidang dari badan permintaan JSON ke parameter permintaan integrasi
Anda juga dapat memetakan parameter permintaan integrasi dari bidang di badan permintaan JSON menggunakan [JSONPath ekspresi](http://goessner.net/articles/JsonPath/index.html#e2). Contoh berikut memetakan badan permintaan metode ke header permintaan integrasi bernama `body-header` dan memetakan bagian dari badan permintaan, seperti yang dinyatakan oleh ekspresi JSON ke header permintaan integrasi bernama`pet-price`.
Untuk menguji contoh ini, berikan masukan yang berisi kategori harga, seperti berikut ini:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ Konsol Manajemen AWS ]
**Untuk memetakan parameter permintaan metode**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih`POST`,, `PUT``PATCH`, atau `ANY` metode.
Metode Anda harus memiliki integrasi non-proxy.
1. Untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
1. Pilih **parameter header permintaan URL**.
1. Pilih **Tambahkan parameter header permintaan**.
1. Untuk **Nama**, masukkan **body-header**.
1. Untuk **Dipetakan dari**, masukkan**method.request.body**.
Ini memetakan badan permintaan metode ke parameter header permintaan integrasi baru.
1. Pilih **Tambahkan parameter header permintaan**.
1. Untuk **Nama**, masukkan **pet-price**.
1. Untuk **Dipetakan dari**, masukkan** method.request.body[0].price**.
Ini memetakan bagian dari badan permintaan metode ke parameter header permintaan integrasi baru.
1. Pilih **Simpan**.
1. Menerapkan ulang API Anda agar perubahan diterapkan.
------
#### [ 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: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
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 ]
Parameter permintaan integrasi peta definisi OpenAPI berikut dari bidang di badan permintaan JSON.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Contoh 4: Petakan respons integrasi terhadap respons metode
Anda juga dapat memetakan respons integrasi ke respons metode. Contoh berikut memetakan badan respons integrasi ke header respons metode bernama`location`, memetakan header respons integrasi `x-app-id` ke header respons metode`id`, dan memetakan header respons integrasi multi-nilai `item` ke header `items` respons metode.
------
#### [ Konsol Manajemen AWS ]
**Untuk memetakan respon integrasi**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih metode.
Metode Anda harus memiliki integrasi non-proxy.
1. Pilih tab **respons Metode**, dan kemudian untuk **Respons 200**, pilih **Edit**.
1. Untuk **nama Header**, pilih **Tambahkan header**.
1. Buat tiga header bernama**id**,**item**, dan**location**.
1. Pilih **Simpan**.
1. Pilih tab **Integrasi respon**, dan kemudian untuk **Default - Respons**, pilih **Edit**.
1. Di bawah **pemetaan Header**, masukkan yang berikut ini.
1. Untuk **id**, masukkan **integration.response.header.x-app-id**
1. Untuk **item**, masukkan **integration.response.multivalueheader.item**
1. Untuk **lokasi**, masukkan **integration.response.body.redirect.url**
1. Pilih **Simpan**.
1. Menerapkan ulang API Anda agar perubahan diterapkan.
------
#### [ 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: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
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 memetakan respons integrasi terhadap respons metode.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# Referensi sumber pemetaan parameter untuk REST APIs di API Gateway
Saat Anda membuat pemetaan parameter, Anda menentukan permintaan metode atau parameter respons integrasi untuk dimodifikasi dan Anda menentukan cara memodifikasi parameter tersebut.
Tabel berikut menunjukkan parameter permintaan metode yang dapat Anda petakan, dan ekspresi untuk membuat pemetaan. Dalam ekspresi ini, *name* adalah nama parameter permintaan metode. Misalnya, untuk memetakan parameter header permintaan`puppies`, gunakan ekspresi`method.request.header.puppies`. Ekspresi Anda harus sesuai dengan ekspresi reguler`'^[a-zA-Z0-9._$-]+$]'`. Anda dapat menggunakan pemetaan parameter dalam permintaan integrasi untuk integrasi proxy dan non-proxy.
| **Sumber data yang dipetakan** | **Ekspresi pemetaan** |
| --- | --- |
| Jalur permintaan metode | method.request.path.name |
| String kueri permintaan metode | method.request.querystring.name |
| String kueri permintaan metode multi-nilai | method.request.multivaluequerystring.name |
| Header permintaan metode | method.request.header.name |
| Header permintaan metode multi-nilai | method.request.multivalueheader.name |
| Badan permintaan metode | method.request.body |
| Metode permintaan badan (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION*adalah JSONPath ekspresi untuk bidang JSON dari badan permintaan. Untuk informasi lebih lanjut, lihat [JSONPath ekspresi](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variabel tahap | stageVariables.name |
| Variabel konteks | `context.name` Nama harus menjadi salah satu [variabel konteks yang didukung](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Nilai statis | `'static_value'`. *static\$1value*Ini adalah string literal dan harus diapit dalam sepasang tanda kutip tunggal. Misalnya, `'https://www.example.com'`. |
Tabel berikut menunjukkan parameter respons integrasi yang dapat Anda petakan dan ekspresi untuk membuat pemetaan. Dalam ekspresi ini, *name* adalah nama parameter respons integrasi. Anda dapat memetakan header respons metode dari header respons integrasi atau badan respons integrasi, variabel \$1context, atau nilai statis. Untuk menggunakan pemetaan parameter untuk respons integrasi, Anda memerlukan integrasi non-proxy.
| Sumber data yang dipetakan | Ekspresi pemetaan |
| --- | --- |
| Header respon integrasi | integration.response.header.name |
| Header respon integrasi | integration.response.multivalueheader.name |
| Badan respons integrasi | integration.response.body |
| Integrasi respon body (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION*adalah JSONPath ekspresi untuk bidang JSON dari tubuh respons. Untuk informasi lebih lanjut, lihat [JSONPath ekspresi](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variabel tahap | stageVariables.name |
| Variabel konteks | `context.name` Nama harus menjadi salah satu [variabel konteks yang didukung](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Nilai statis | ` 'static_value'` *static\$1value*Ini adalah string literal dan harus diapit dalam sepasang tanda kutip tunggal. Misalnya, `'https://www.example.com'`. |
# 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\":{}}"}
```
# Variabel untuk transformasi data untuk API Gateway
Saat Anda membuat pemetaan parameter, Anda dapat menggunakan variabel konteks sebagai sumber data Anda. Saat Anda membuat transformasi template pemetaan, Anda dapat menggunakan variabel konteks, input, dan variabel util dalam skrip yang Anda tulis di [Velocity Template](https://velocity.apache.org/engine/devel/vtl-reference.html) Language (VTL). Misalnya template pemetaan yang menggunakan variabel referensi ini, lihat[Contoh menggunakan variabel untuk memetakan transformasi template untuk API Gateway](api-gateway-mapping-variable-examples.md).
Untuk daftar variabel referensi untuk pencatatan akses, lihat[Variabel untuk pencatatan akses untuk API Gateway](api-gateway-variables-for-access-logging.md).
## Variabel konteks untuk transformasi data
Anda dapat menggunakan `$context` variabel case-sensitive berikut untuk transformasi data.
| Parameter | Deskripsi |
| --- | --- |
| \$1context.accountId | ID AWS akun pemilik API. |
| \$1context.apiId | API Gateway identifier ditetapkan ke API Anda. |
| \$1context.authorizer.claims.property | Properti klaim yang dikembalikan dari kumpulan pengguna Amazon Cognito setelah pemanggil metode berhasil diautentikasi. Untuk informasi selengkapnya, lihat [Kontrol akses ke REST APIs menggunakan kumpulan pengguna Amazon Cognito sebagai otorisasi](apigateway-integrate-with-cognito.md). Memanggil `$context.authorizer.claims` mengembalikan null. |
| \$1context.authorizer.principalId | Identifikasi pengguna utama yang terkait dengan token yang dikirim oleh klien dan dikembalikan dari otorisasi API Gateway Lambda (sebelumnya dikenal sebagai otorisasi khusus). Untuk informasi selengkapnya, lihat [Gunakan otorisasi API Gateway Lambda](apigateway-use-lambda-authorizer.md). |
| \$1context.authorizer.property | Nilai stringifikasi dari pasangan nilai kunci yang ditentukan dari `context` peta dikembalikan dari fungsi otorisasi API Gateway Lambda. Misalnya, jika otorisasi mengembalikan `context` peta berikut: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} Memanggil `$context.authorizer.key` mengembalikan `"value"` string, memanggil `$context.authorizer.numKey` mengembalikan `"1"` string, dan memanggil `$context.authorizer.boolKey` mengembalikan `"true"` string. Sebab*property*, satu-satunya karakter khusus yang didukung adalah `(_)` karakter garis bawah. Untuk informasi selengkapnya, lihat [Gunakan otorisasi API Gateway Lambda](apigateway-use-lambda-authorizer.md). |
| \$1context.awsEndpointRequestId | ID permintaan AWS titik akhir. |
| \$1context.deploymentId | ID penerapan API. |
| \$1context.domainName | Nama domain lengkap yang digunakan untuk memanggil API. Ini harus sama dengan `Host` header yang masuk. |
| \$1context.domainPrefix | Label pertama dari`$context.domainName`. |
| \$1context.error.message | String yang berisi pesan kesalahan API Gateway. Variabel ini hanya dapat digunakan untuk substitusi variabel sederhana dalam template [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)pemetaan tubuh, yang tidak diproses oleh mesin Velocity Template Language, dan dalam logging akses. Untuk informasi selengkapnya, lihat [Pantau eksekusi WebSocket API dengan CloudWatch metrik](apigateway-websocket-api-logging.md) dan [Menyiapkan respons gateway untuk menyesuaikan respons kesalahan](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.messageString | Nilai yang dikutip dari\$1context.error.message, yaitu"\$1context.error.message". |
| \$1context.error.responseType | Sebuah [jenis [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType). Variabel ini hanya dapat digunakan untuk substitusi variabel sederhana dalam template [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)pemetaan tubuh, yang tidak diproses oleh mesin Velocity Template Language, dan dalam logging akses. Untuk informasi selengkapnya, lihat [Pantau eksekusi WebSocket API dengan CloudWatch metrik](apigateway-websocket-api-logging.md) dan [Menyiapkan respons gateway untuk menyesuaikan respons kesalahan](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.validationErrorString | Sebuah string yang berisi pesan kesalahan validasi rinci. |
| \$1context.extendedRequestId | ID tambahan yang dibuat dan ditetapkan API Gateway ke permintaan API. ID permintaan yang diperluas berisi informasi yang berguna untuk debugging dan pemecahan masalah. |
| \$1context.httpMethod | Metode HTTP yang digunakan. Nilai yang valid meliputi: `DELETE``GET`,,`HEAD`,`OPTIONS`,`PATCH`,`POST`, dan`PUT`. |
| \$1context.identity.accountId | ID AWS akun yang terkait dengan permintaan. |
| \$1context.identity.apiKey | Untuk metode API yang memerlukan kunci API, variabel ini adalah kunci API yang terkait dengan permintaan metode. Untuk metode yang tidak memerlukan kunci API, variabel ini adalah null. Untuk informasi selengkapnya, lihat [Paket penggunaan dan kunci API untuk REST APIs di API Gateway](api-gateway-api-usage-plans.md). |
| \$1context.identity.apiKeyId | ID kunci API yang terkait dengan permintaan API yang memerlukan kunci API. |
| \$1context.identity.caller | Pengidentifikasi utama penelepon yang menandatangani permintaan. Didukung untuk sumber daya yang menggunakan otorisasi IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Daftar dipisahkan koma dari semua penyedia otentikasi Amazon Cognito yang digunakan oleh penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Misalnya, untuk identitas dari kumpulan pengguna Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` *Untuk informasi tentang penyedia autentikasi Amazon Cognito yang tersedia, lihat [Menggunakan Identitas Federasi di Panduan Pengembang](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) Amazon Cognito.* |
| \$1context.identity.cognitoAuthenticationType | Jenis otentikasi Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Nilai yang mungkin termasuk `authenticated` untuk identitas yang diautentikasi dan `unauthenticated` untuk identitas yang tidak diautentikasi. |
| \$1context.identity.cognitoIdentityId | ID identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID kumpulan identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. |
| \$1context.identity.principalOrgId | [ID AWS organisasi](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). |
| \$1context.identity.sourceIp | Alamat IP sumber dari koneksi TCP langsung membuat permintaan ke titik akhir API Gateway. |
| \$1context.identity.clientCert.clientCertPem | Sertifikat klien yang dikodekan PEM yang disajikan klien selama otentikasi TLS timbal balik. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.subjectDN | Nama yang dibedakan dari subjek sertifikat yang disajikan klien. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.issuerDN | Nama terhormat dari penerbit sertifikat yang disajikan klien. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.serialNumber | Nomor seri sertifikat. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.validity.notBefore | Tanggal sebelum sertifikat tidak valid. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.validity.notAfter | Tanggal setelah sertifikat tidak valid. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.vpcId | ID VPC VPC membuat permintaan ke titik akhir API Gateway. |
| \$1context.identity.vpceId | ID titik akhir VPC dari titik akhir VPC membuat permintaan ke titik akhir API Gateway. Hadir hanya ketika Anda memiliki API pribadi. |
| \$1context.identity.user | Pengidentifikasi utama pengguna yang akan diotorisasi terhadap akses sumber daya. Didukung untuk sumber daya yang menggunakan otorisasi IAM. |
| \$1context.identity.userAgent | [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)Header pemanggil API. |
| \$1context.identity.userArn | Nama Sumber Daya Amazon (ARN) dari pengguna efektif yang diidentifikasi setelah otentikasi. Untuk informasi selengkapnya, lihat [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.isCanaryRequest | Mengembalikan `true` jika permintaan diarahkan ke kenari dan `false` jika permintaan tidak diarahkan ke kenari. Hadir hanya ketika Anda mengaktifkan kenari. |
| \$1context.path | Jalur permintaan. Misalnya, untuk URL permintaan non-proxy darihttps://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, \$1context.path nilainya adalah/\$1stage\$1/root/child. |
| \$1context.protocol | Protokol permintaan, misalnya,HTTP/1.1. API Gateway APIs dapat menerima permintaan HTTP/2, tetapi API Gateway mengirimkan permintaan ke integrasi backend menggunakan HTTP/1.1. Akibatnya, protokol permintaan dicatat sebagai HTTP/1.1 bahkan jika klien mengirim permintaan yang menggunakan HTTP/2. |
| \$1context.requestId | ID untuk permintaan. Klien dapat mengganti ID permintaan ini. Gunakan `$context.extendedRequestId` untuk ID permintaan unik yang dihasilkan API Gateway. |
| \$1context.requestOverride.header.header\$1name | Header permintaan menimpa. Jika parameter ini didefinisikan, ini berisi header yang akan digunakan alih-alih **Header HTTP** yang didefinisikan di panel **Permintaan Integrasi**. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.path.path\$1name | Jalur permintaan menimpa. Jika parameter ini ditentukan, parameter ini berisi jalur permintaan yang akan digunakan, bukan **Parameter Jalur URL** yang ditentukan di panel **Permintaan Integrasi**. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.querystring.querystring\$1name | Permintaan query string override. Jika parameter ini didefinisikan, parameter ini berisi string permintaan permintaan yang akan digunakan, bukan **Parameter String Kueri URL** yang didefinisikan di panel **Permintaan Integrasi**. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.header.header\$1name | Header respon menimpa. Jika parameter ini didefinisikan, ini berisi header yang akan dikembalikan, bukan header Response yang didefinisikan sebagai pemetaan Default di panel Integration Response. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.status | Kode status respons menimpa. Jika parameter ini didefinisikan, ini berisi kode status yang akan dikembalikan, bukan status respons Metode yang didefinisikan sebagai pemetaan Default di panel Respons Integrasi. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestTime | Waktu permintaan yang diformat [CLF](https://httpd.apache.org/docs/current/logs.html#common) (). dd/MMM/yyyy:HH:mm:ss \$1-hhmm |
| \$1context.requestTimeEpoch | Waktu permintaan yang diformat [Epoch](https://en.wikipedia.org/wiki/Unix_time), dalam milidetik. |
| \$1context.resourceId | Pengidentifikasi yang ditetapkan API Gateway ke sumber daya Anda. |
| \$1context.resourcePath | Jalan menuju sumber daya Anda. Misalnya, untuk URI permintaan non-proxy dari`https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, `$context.resourcePath` Nilainya adalah`/root/child`. Untuk informasi selengkapnya, lihat [Tutorial: Membuat REST API dengan integrasi non-proxy HTTP](api-gateway-create-api-step-by-step.md). |
| \$1context.stage | Tahap penerapan permintaan API (misalnya, `Beta` atau`Prod`). |
| \$1context.wafResponseCode | Tanggapan yang diterima dari [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` atau`WAF_BLOCK`. Tidak akan diatur jika tahap tidak terkait dengan ACL web. Untuk informasi selengkapnya, lihat [Gunakan AWS WAF untuk melindungi REST Anda APIs di API Gateway](apigateway-control-access-aws-waf.md). |
| \$1context.webaclArn | ARN lengkap dari ACL web yang digunakan untuk memutuskan apakah akan mengizinkan atau memblokir permintaan. Tidak akan diatur jika tahap tidak terkait dengan ACL web. Untuk informasi selengkapnya, lihat [Gunakan AWS WAF untuk melindungi REST Anda APIs di API Gateway](apigateway-control-access-aws-waf.md). |
## Variabel masukan
Anda dapat menggunakan `$input` variabel case-sensitive berikut untuk merujuk ke metode permintaan payload dan parameter permintaan metode. Fungsi-fungsi berikut tersedia:
| Variabel dan fungsi | Deskripsi |
| --- | --- |
| \$1input.body | Mengembalikan payload permintaan mentah sebagai string. Anda dapat menggunakan `$input.body` untuk mempertahankan seluruh nomor floating point, seperti`10.00`. |
| \$1input.json(x) | Fungsi ini mengevaluasi JSONPath ekspresi dan mengembalikan hasil sebagai string JSON. Misalnya, `$input.json('$.pets')` mengembalikan string JSON yang mewakili `pets` struktur. Untuk informasi selengkapnya tentang JSONPath, lihat [JSONPath](https://goessner.net/articles/JsonPath/)atau [JSONPath untuk Java](https://github.com/json-path/JsonPath). |
| \$1input.params() | Mengembalikan peta dari semua parameter permintaan. Kami menyarankan Anda menggunakan `$util.escapeJavaScript` untuk membersihkan hasilnya untuk menghindari potensi serangan injeksi. Untuk kontrol penuh sanitasi permintaan, gunakan integrasi proxy tanpa templat dan tangani sanitasi permintaan dalam integrasi Anda. |
| \$1input.params(x) | Mengembalikan nilai parameter permintaan metode dari path, query string, atau nilai header (dicari dalam urutan itu), diberikan string `x` nama parameter. Kami menyarankan Anda menggunakan `$util.escapeJavaScript` untuk membersihkan parameter untuk menghindari potensi serangan injeksi. Untuk kontrol penuh sanitasi parameter, gunakan integrasi proxy tanpa templat dan tangani sanitasi permintaan dalam integrasi Anda. |
| \$1input.path(x) | Mengambil JSONPath ekspresi string (`x`) dan mengembalikan representasi objek JSON dari hasil. Ini memungkinkan Anda untuk mengakses dan memanipulasi elemen payload secara native di [Apache Velocity Template](https://velocity.apache.org/engine/devel/vtl-reference.html) Language (VTL). Misalnya, jika ekspresi `$input.path('$.pets')` mengembalikan objek seperti ini: [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').size()`akan kembali`"3"`. Untuk informasi selengkapnya tentang JSONPath, lihat [JSONPath](https://goessner.net/articles/JsonPath/)atau [JSONPath untuk Java](https://github.com/json-path/JsonPath). |
## Variabel tahap
Anda dapat menggunakan variabel tahap berikut sebagai placeholder untuk ARNs dan URLs dalam integrasi metode. Untuk informasi selengkapnya, lihat [Menggunakan variabel stage untuk REST API di API Gateway](stage-variables.md).
| Sintaksis | Deskripsi |
| --- | --- |
| \$1stageVariables.variable\$1name,\$1stageVariables['variable\$1name'], atau \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*merupakan nama variabel tahap. |
## Variabel Util
Anda dapat menggunakan `$util` variabel case-sensitive berikut untuk menggunakan fungsi utilitas untuk memetakan template. Kecuali ditentukan lain, set karakter default adalah UTF-8.
| Fungsi | Deskripsi |
| --- | --- |
| \$1util.escapeJavaScript() | Melarikan diri dari karakter dalam string menggunakan aturan JavaScript string. Fungsi ini akan mengubah tanda kutip tunggal biasa (`'`) menjadi yang keluar (`\'`). Namun, tanda kutip tunggal yang lolos tidak valid di JSON. Jadi, ketika output dari fungsi ini digunakan dalam properti JSON, Anda harus mengubah tanda kutip tunggal yang diloloskan (`\'`) kembali ke tanda kutip tunggal biasa (`'`). Ini ditunjukkan dalam contoh berikut: "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")" |
| \$1util.parseJson() | Mengambil “stringified” JSON dan mengembalikan representasi objek dari hasilnya. Anda dapat menggunakan hasil dari fungsi ini untuk mengakses dan memanipulasi elemen payload secara native di Apache Velocity Template Language (VTL). Misalnya, jika Anda memiliki muatan berikut: {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} dan gunakan template pemetaan berikut #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Anda akan mendapatkan output sebagai berikut: {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | Mengkonversi string ke dalam format “aplikasi/x-www-form-urlencoded”. |
| \$1util.urlDecode() | Mendekode string “aplikasi/x-www-form-urlencoded”. |
| \$1util.base64Encode() | Mengkodekan data ke dalam string yang dikodekan base64. |
| \$1util.base64Decode() | Mendekode data dari string yang dikodekan base64. |