Beispiel 1: Zuweisen eines Methodenanforderungsparameters zu einem Integrationsanforderungsparameter Beispiel 2: Zuweisen mehrerer Parameter der Methodenanforderung zu verschiedenen Parametern der Integrationsanforderung Beispiel 3: Zuweisen von Feldern aus dem JSON-Body der Anfrage zu Parametern der Integrationsanforderung Beispiel 4: Zuweisen der Integrationsantwort zur Methodenantwort

Beispiele für Parameterzuweisungen für REST-APIs in API Gateway

Die folgenden Beispiele zeigen, wie Sie Ausdrücke zur Parameterzuweisung mithilfe der API-Gateway-Konsole, OpenAPI oder AWS CloudFormation-Vorlagen erstellen. Ein Beispiel, wie Sie die Parameterzuweisung verwenden, um die erforderlichen CORS-Header zu erstellen, finden Sie unter CORS für REST-APIs in API Gateway.

Beispiel 1: Zuweisen eines Methodenanforderungsparameters zu einem Integrationsanforderungsparameter

Im folgenden Beispiel wird der Header-Parameter puppies der Methodenanforderung dem Header-Parameter DogsAge0 der Integrationsanforderung zugewiesen.

AWS Management Console

So weisen Sie den Parameter der Methodenanforderung zu

Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.
Wählen Sie eine REST-API aus.
Wählen Sie eine Methode aus.

Ihre Methode muss eine Nicht-Proxy-Integration aufweisen.
Wählen Sie unter Methodenanfrage-Einstellungen die Option Bearbeiten aus.
Wählen Sie HTTP-Anfrage-Header aus.
Wählen Sie Add header.
Geben Sie als Name die Zeichenfolge „puppies“ ein.
Wählen Sie Speichern aus.
Wählen Sie die Registerkarte Integrationsanfrage aus und klicken Sie dann unter Einstellungen für Integrationsanforderungen auf Bearbeiten.

Die AWS Management Console fügt automatisch eine Parameterzuweisung von method.request.header.puppies zu puppies hinzu, aber Sie müssen den Namen ändern, damit er dem Header-Parameter entspricht, den Ihr Integrationsendpunkt erwartet.
Geben Sie als Name die Zeichenfolge „DogsAge0“ ein.
Wählen Sie Speichern aus.
Sie müssen Ihre API erneut bereitstellen, damit die Änderungen wirksam werden.

Nachfolgend wird beschrieben, wie Sie überprüfen können, ob Ihre Parameterzuordnung erfolgreich war.

Überprüfen der erfolgreichen Parameterzuweisung (optional)

Wählen Sie die Registerkarte Test. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen.
Geben Sie unter Headers puppies:true ein.
Wählen Sie Test aus.

Unter Protokoll sollte das Ergebnis wie folgt aussehen:


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}

Der Header-Parameter der Anfrage wurde von puppies auf DogsAge0 geändert.

AWS CloudFormation

In diesem Beispiel verwenden Sie die Body-Eigenschaft, um eine OpenAPI-Definitionsdatei in API Gateway zu importieren.


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

Beispiel 2: Zuweisen mehrerer Parameter der Methodenanforderung zu verschiedenen Parametern der Integrationsanforderung

Im folgenden Beispiel wird der Mehrwert-Abfragezeichenfolgenparameter der Methodenanforderung methodRequestQueryParam dem Abfragezeichenfolgenparameter der Integrationsanforderung integrationQueryParam zugewiesen, und der Header-Parameter der Methodenanforderung methodRequestHeaderParam wird dem Pfadparameter der Integrationsanforderung integrationPathParam zugewiesen.

AWS Management Console

So weisen Sie Methodenanforderungsparameter zu

Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.
Wählen Sie eine REST-API aus.
Wählen Sie eine Methode aus.

Ihre Methode muss eine Nicht-Proxy-Integration aufweisen.
Wählen Sie unter Methodenanfrage-Einstellungen die Option Bearbeiten aus.
Klicken Sie auf Parameter für URL-Abfragezeichenfolgen.
Wählen Sie Abfragezeichenfolge hinzufügen aus.
Geben Sie als Name die Zeichenfolge „methodRequestQueryParam“ ein.
Wählen Sie HTTP-Anfrage-Headers aus.
Wählen Sie Add header.
Geben Sie als Name die Zeichenfolge „methodRequestHeaderParam“ ein.
Wählen Sie Speichern aus.
Wählen Sie die Registerkarte Integrationsanfrage aus und klicken Sie dann unter Einstellungen für Integrationsanforderungen auf Bearbeiten.
Klicken Sie auf URL-Pfadparameter.
Klicken Sie auf Pfadparameter hinzufügen.
Geben Sie als Name die Zeichenfolge „integrationPathParam“ ein.
Geben Sie für Zugeordnet von method.request.header.methodRequestHeaderParam ein.

Damit wird der von Ihnen in der Methodenanforderung angegebene Header-Parameter einem neuen Pfadparameter der Integrationsanforderung zugewiesen.
Klicken Sie auf Parameter für URL-Abfragezeichenfolgen.
Wählen Sie Abfragezeichenfolge hinzufügen aus.
Geben Sie als Name die Zeichenfolge „integrationQueryParam“ ein.
Geben Sie für Zugeordnet von method.request.multivaluequerystring.methodRequestQueryParam ein.

Damit wird der Parameter der Mehrwert-Anfragezeichenfolge einem neuen einfachwertigen Parameter der Mehrwert-Anfragezeichenfolge der Integrationsanforderung zugewiesen.
Wählen Sie Speichern aus.
Sie müssen Ihre API erneut bereitstellen, damit die Änderungen wirksam werden.

AWS CloudFormation

In diesem Beispiel verwenden Sie die body-Eigenschaft, um eine OpenAPI-Definitionsdatei in API Gateway zu importieren.

Die folgende OpenAPI-Definition erstellt die folgenden Parameterzuordnungen für eine HTTP-Integration:

den Header der Methodenanforderung, mit dem Namen methodRequestHeaderParam, in den Pfadparameter der Integrationsanforderung, mit dem Namen integrationPathParam
die Mehrwert-Anfragezeichenfolge der Methodenanforderung, mit dem Namen methodRequestQueryParam, in die Anfragezeichenfolge der Integrationsanforderung, mit dem Namen 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

Die folgende OpenAPI-Definition erstellt die folgenden Parameterzuordnungen für eine HTTP-Integration:

den Header der Methodenanforderung, mit dem Namen methodRequestHeaderParam, in den Pfadparameter der Integrationsanforderung, mit dem Namen integrationPathParam
die Mehrwert-Anfragezeichenfolge der Methodenanforderung, mit dem Namen methodRequestQueryParam, in die Anfragezeichenfolge der Integrationsanforderung, mit dem Namen 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"
        }
      }
    }
  }
}

Beispiel 3: Zuweisen von Feldern aus dem JSON-Body der Anfrage zu Parametern der Integrationsanforderung

Sie können Integrationsanforderungsparameter auch aus Feldern im JSON-Body der Anfrage mithilfe eines JSONPath-Ausdrucks zuweisen. Im folgenden Beispiel wird der Body der Methodenanforderung einem Header in einer Integrationsanforderung mit dem Namen body-header zugewiesen und ein Teil des Anfragebodys, ausgedrückt durch einen JSON-Ausdruck, wird einem Header in einer Integrationsanforderung mit dem Namen pet-price zugewiesen.

Um dieses Beispiel zu testen, geben Sie bitte eine Eingabe ein, die eine Preiskategorie enthält, wie beispielsweise die folgende:


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

AWS Management Console

So weisen Sie Methodenanforderungsparameter zu

Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.
Wählen Sie eine REST-API aus.
Wählen Sie eine POST-, PUT-, PATCH- oder ANY-Methode aus.

Ihre Methode muss eine Nicht-Proxy-Integration aufweisen.
Wählen Sie unter Methodenanfrage-Einstellungen die Option Bearbeiten aus.
Klicken Sie auf URL-Anforderungsheader-Parameter.
Klicken Sie auf Header-Parameter der Anfrage hinzufügen.
Geben Sie als Name die Zeichenfolge „body-header“ ein.
Geben Sie für Zugeordnet von method.request.body ein.

Damit wird der Body der Methodenanforderung einem neuen Header-Parameter der Integrationsanforderung zugewiesen.
Klicken Sie auf Header-Parameter der Anfrage hinzufügen.
Geben Sie als Name die Zeichenfolge „pet-price“ ein.
Geben Sie für Zugeordnet von method.request.body[0].price ein.

Damit wird ein Teil des Bodys der Methodenanforderung einem neuen Header-Parameter der Integrationsanforderung zugewiesen.
Wählen Sie Speichern aus.
Sie müssen Ihre API erneut bereitstellen, damit die Änderungen wirksam werden.

AWS CloudFormation

In diesem Beispiel verwenden Sie die body-Eigenschaft, um eine OpenAPI-Definitionsdatei in API Gateway zu importieren.


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

Die folgende OpenAPI-Definition weist Integrationsanforderungsparameter aus Feldern im JSON-Body der Anfrage zu.


{
  "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"
        }
      }
    }
  }
}

Beispiel 4: Zuweisen der Integrationsantwort zur Methodenantwort

Sie können auch die Integrationsantwort der Methodenantwort zuweisen. Im folgenden Beispiel wird der Body der Integrationsantwort einem Header der Methodenantwort mit dem Namen location zugewiesen, der Header der Integrationsantwort x-app-id dem Header der Methodenantwort id zugewiesen und der Header der Mehrwert-Integrationsantwort item dem Header der Methodenantwort items zugewiesen.

AWS Management Console

So weisen Sie die Integrationsantwort zu

Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.
Wählen Sie eine REST-API aus.
Wählen Sie eine Methode aus.

Ihre Methode muss eine Nicht-Proxy-Integration aufweisen.
Wechseln Sie zur Registerkarte Methodenantwort und wählen Sie unter Antwort 200 die Option Bearbeiten aus.
Wählen Sie unter Header-Name die Option Header hinzufügen aus.
Erstellen Sie drei Header mit den Namen id, item und location.
Wählen Sie Speichern aus.
Wechseln Sie zur Registerkarte Integrationsantwort und wählen Sie unter Standard – Antwort die Option Bearbeiten aus.
Geben Sie unter Header-Zuweisungen Folgendes ein.
1. Geben Sie unter id integration.response.header.x-app-id ein.
2. Geben Sie unter item integration.response.multivalueheader.item ein.
3. Geben Sie unter location integration.response.body.redirect.url ein.
Wählen Sie Speichern aus.
Sie müssen Ihre API erneut bereitstellen, damit die Änderungen wirksam werden.

AWS CloudFormation

In diesem Beispiel verwenden Sie die body-Eigenschaft, um eine OpenAPI-Definitionsdatei in API Gateway zu importieren.


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

Die folgende OpenAPI-Definition weist die Integrationsantwort der Methodenantwort zu.


{
  "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
        }
      }
    }
  }
}

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Parameterzuweisung

Quellenreferenz für Parameterzuweisungen