Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# 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).