Contoh pemetaan parameter untuk REST APIs di API Gateway

Contoh berikut menunjukkan cara membuat ekspresi pemetaan parameter menggunakan konsol API Gateway, OpenAPI, AWS CloudFormation dan template. Untuk contoh cara menggunakan pemetaan parameter untuk membuat header CORS yang diperlukan, lihat. CORS untuk REST APIs di API Gateway

Contoh 1: Petakan parameter permintaan metode ke parameter permintaan integrasi

Contoh berikut memetakan parameter header permintaan metode puppies ke parameter header permintaan integrasiDogsAge0.

AWS Management Console

Untuk memetakan parameter permintaan metode

1. Masuk ke konsol API Gateway di https://console.aws.amazon.com/apigateway.

2. Pilih REST API.

3. Pilih metode.

   Metode Anda harus memiliki integrasi non-proxy.

4. Untuk pengaturan permintaan Metode, pilih Edit.

5. Pilih header permintaan HTTP.

6. Pilih Tambahkan header.

7. Untuk Nama, masukkan puppies.

8. Pilih Simpan.

9. Pilih tab Permintaan integrasi, dan kemudian untuk pengaturan permintaan Integrasi, pilih Edit.

   AWS Management Console 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.

10. Untuk Nama, masukkan DogsAge0.

11. Pilih Simpan.

12. 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.

2. Untuk header, masukkanpuppies:true.

3. Pilih Uji.

4. 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 menjadiDogsAge0.

AWS CloudFormation

Dalam contoh ini, Anda menggunakan properti 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.

AWS Management Console

Untuk memetakan parameter permintaan metode

1. Masuk ke konsol API Gateway di https://console.aws.amazon.com/apigateway.

2. Pilih REST API.

3. Pilih metode.

   Metode Anda harus memiliki integrasi non-proxy.

4. Untuk pengaturan permintaan Metode, pilih Edit.

5. Pilih parameter string kueri URL.

6. Pilih Tambahkan string kueri.

7. Untuk Nama, masukkan methodRequestQueryParam.

8. Pilih header permintaan HTTP.

9. Pilih Tambahkan header.

10. Untuk Nama, masukkan methodRequestHeaderParam.

11. Pilih Simpan.

12. Pilih tab Permintaan integrasi, dan kemudian untuk pengaturan permintaan Integrasi, pilih Edit.

13. Pilih parameter jalur URL.

14. Pilih Tambahkan parameter jalur.

15. Untuk Nama, masukkan integrationPathParam.

16. Untuk Dipetakan dari, masukkanmethod.request.header.methodRequestHeaderParam.

    Ini memetakan header permintaan metode yang Anda tentukan dalam permintaan metode ke parameter jalur permintaan integrasi baru.

17. Pilih parameter string kueri URL.

18. Pilih Tambahkan string kueri.

19. Untuk Nama, masukkan integrationQueryParam.

20. Untuk Dipetakan dari, masukkanmethod.request.multivaluequerystring.methodRequestQueryParam.

    Ini memetakan parameter string kueri multivalue ke parameter string kueri permintaan integrasi bernilai tunggal baru.

21. Pilih Simpan.

22. Menerapkan ulang API Anda agar perubahan diterapkan.

AWS CloudFormation

Dalam contoh ini, Anda menggunakan properti body untuk mengimpor file definisi OpenAPI ke API Gateway.

Definisi OpenAPI berikut membuat pemetaan parameter berikut untuk integrasi HTTP:

• Header permintaan metode, bernamamethodRequestHeaderParam, ke dalam parameter jalur permintaan integrasi, bernama integrationPathParam

• Metode multi-nilai meminta string kueri, bernamamethodRequestQueryParam, 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, bernamamethodRequestHeaderParam, ke dalam parameter jalur permintaan integrasi, bernama integrationPathParam

• Metode multi-nilai meminta string kueri, bernamamethodRequestQueryParam, 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. 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 bernamapet-price.

Untuk menguji contoh ini, berikan masukan yang berisi kategori harga, seperti berikut ini:

[ 
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }
]

AWS Management Console

Untuk memetakan parameter permintaan metode

1. Masuk ke konsol API Gateway di https://console.aws.amazon.com/apigateway.

2. Pilih REST API.

3. PilihPOST,, PUTPATCH, atau ANY metode.

   Metode Anda harus memiliki integrasi non-proxy.

4. Untuk pengaturan permintaan Integrasi, pilih Edit.

5. Pilih parameter header permintaan URL.

6. Pilih Tambahkan parameter header permintaan.

7. Untuk Nama, masukkan body-header.

8. Untuk Dipetakan dari, masukkanmethod.request.body.

   Ini memetakan badan permintaan metode ke parameter header permintaan integrasi baru.

9. Pilih Tambahkan parameter header permintaan.

10. Untuk Nama, masukkan pet-price.

11. Untuk Dipetakan dari, masukkan method.request.body[0].price.

    Ini memetakan bagian dari badan permintaan metode ke parameter header permintaan integrasi baru.

12. Pilih Simpan.

13. Menerapkan ulang API Anda agar perubahan diterapkan.

AWS CloudFormation

Dalam contoh ini, Anda menggunakan properti 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 bernamalocation, memetakan header respons integrasi x-app-id ke header respons metodeid, dan memetakan header respons integrasi multi-nilai item ke header items respons metode.

AWS Management Console

Untuk memetakan respon integrasi

1. Masuk ke konsol API Gateway di https://console.aws.amazon.com/apigateway.

2. Pilih REST API.

3. Pilih metode.

   Metode Anda harus memiliki integrasi non-proxy.

4. Pilih tab respons Metode, dan kemudian untuk Respons 200, pilih Edit.

5. Untuk nama Header, pilih Tambahkan header.

6. Buat tiga header bernamaid,item, danlocation.

7. Pilih Simpan.

8. Pilih tab Integrasi respon, dan kemudian untuk Default - Respons, pilih Edit.

9. Di bawah pemetaan Header, masukkan yang berikut ini.

   1. Untuk id, masukkan integration.response.header.x-app-id

   2. Untuk item, masukkan integration.response.multivalueheader.item

   3. Untuk lokasi, masukkan integration.response.body.redirect.url

10. Pilih Simpan.

11. Menerapkan ulang API Anda agar perubahan diterapkan.

AWS CloudFormation

Dalam contoh ini, Anda menggunakan properti 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
        }
      }
    }
  }
}