Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Contoh pemetaan parameter untuk REST APIs di API Gateway
<a name="request-response-data-mappings"></a>

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
<a name="request-response-data-mappings-example-1"></a>

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
<a name="request-response-data-mappings-example-2"></a>

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
<a name="request-response-data-mappings-example-3"></a>

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
<a name="request-response-data-mappings-example-4"></a>

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
        }
      }
    }
  }
}
```

------