Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Datentransformationen für REST APIs in API Gateway **Anmerkung** In diesem Abschnitt werden die Features erläutert, die Sie mit einer Nicht-Proxy-Integration verwenden. Wir empfehlen jedoch, wann immer möglich, eine Proxy-Integration für Ihre REST-API zu verwenden. Eine Proxy-Integration bietet eine vereinfachte Integrationskonfiguration und kann sich gemeinsam mit dem Backend weiterentwickeln, ohne die bestehende Einrichtung zu beeinträchtigen. Weitere Informationen finden Sie unter [Auswählen eines API Gateway-API-Integration](api-gateway-api-integration-types.md). Wenn Sie eine Nicht-Proxy-Integration verwenden, können Sie zwei Features von API Gateway nutzen, um Ihre Methodenanforderung und Ihre Integrationsantwort zu transformieren. Sie können die Methodenanforderung transformieren, wenn sie ein anderes Format der Nutzdaten als die Integrationsanforderung verwendet. Sie können die Integrationsantwort transformieren, wenn sie ein anderes Format der Nutzdaten zurückliefert als das Format, das Sie in der Methodenantwort zurückgeben müssen. Weitere Informationen zum Lebenszyklus einer Anfrage finden Sie unter [Beispielressource für eine REST-API](rest-api-develop.md#rest-api-develop-example). Im folgenden Beispiel wird eine Daten­transformation dargestellt: Für den Header `"x-version:beta"` wird der Header-Parameter `x-version` in den Header-Parameter `app-version` transformiert. Diese Transformation von `x-version` in `app-version` erfolgt in der Integrationsanforderung. Auf diese Weise empfängt das Integrationsendpunkt den transformierten Header-Parameterwert. Wenn der Integrationsendpunkt einen Statuscode zurückgibt, wird dieser von `200` in `204` transformiert, bevor er als Methodenantwort zurückgegeben wird. ![\[Diagramm der Datentransformation in API Gateway\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/develop-non-proxy.png) Um eine Datentransformation zu erstellen, können Sie die folgenden Features verwenden: **Parameterzuweisung** Bei der Zuweisung von Parametern können Sie die URL-Pfadparameter, die URL-Abfragezeichenfolgenparameter oder die HTTP-Header-Werte der Integrationsanforderung ändern, aber nicht die Nutzdaten der Integrationsanforderung. Sie können auch die Header-Werte der HTTP-Antwort ändern. Verwenden Sie die Parameterzuweisung, um statische Header-Werte für Cross-Origin Resource Sharing (CORS) zu erstellen. Sie können die Zuweisung von Parametern in Ihrer Integrationsanforderung sowohl für Proxy- als auch für Nicht-Proxy-Integrationen verwenden. Um jedoch die Zuweisung von Parametern für eine Integrationsantwort zu nutzen, benötigen Sie eine Nicht-Proxy-Integration. Die Zuweisung von Parametern erfordert kein Scripting in der [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Weitere Informationen finden Sie unter [Parameterzuordnung für REST APIs in API Gateway](rest-api-parameter-mapping.md). **Transformationen mit Zuweisungsvorlagen** Bei Transformationen mit Zuweisungsvorlagen verwenden Sie eine Vorlage, um URL-Pfadparameter, URL-Abfragezeichenfolgenparameter, HTTP-Header sowie den Body der Integrationsanforderung oder Integrationsantwort zuzuweisen. Eine *Mapping-Vorlage* ist ein Skript, das in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) mithilfe von [JSONPath Ausdrücken](https://goessner.net/articles/JsonPath/) ausgedrückt und basierend auf dem Header auf die `Content-type` Payload angewendet wird. Mit einer Zuweisungsvorlage können Sie Folgendes tun: + Wählen Sie aus, welche Daten mithilfe der Integration gesendet werden sollen AWS-Services, z. B. mit Amazon DynamoDB- oder Lambda-Funktionen oder HTTP-Endpunkten. Weitere Informationen finden Sie unter [Tutorial: Ändern Sie die Integrationsanfrage und die Antwort für Integrationen zu Diensten AWS](set-up-data-transformations-in-api-gateway.md). + Bedingt die Parameter einer Integrationsanforderung und -antwort einer API überschreiben, neue Header-Werte erstellen und Statuscodes überschreiben. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). Das Verhalten Ihrer API festlegen, wenn die Nutzdaten einer Integrationsanforderung einen `Content-type`-Header enthalten, für den keine passenden Zuweisungsvorlagen vorhanden sind. Dies wird als Integrations-Passthrough-Verhalten bezeichnet. Weitere Informationen finden Sie unter [Verhalten bei Methodenanfragen für Payloads ohne Zuordnungsvorlagen für REST APIs in API Gateway](integration-passthrough-behaviors.md). ## Auswahl zwischen Zuweisung von Parametern und Transformationen mit Zuweisungsvorlagen Wir empfehlen, die Zuweisung von Parametern zu verwenden, um Daten nach Möglichkeit zu transformieren. Wenn Ihre API jedoch erfordert, dass Sie den Body ändern oder bedingte Überschreibungen und Modifikationen basierend auf der eingehenden Integrationsanforderung oder Integrationsantwort vornehmen und Sie keine Proxy-Integration verwenden können, sollten Sie Transformationen mit Zuweisungsvorlagen einsetzen. # Parameterzuordnung für REST APIs in API Gateway **Anmerkung** Wenn Sie eine HTTP-API verwenden, finden Sie weitere Informationen unter [API-Anforderungen und -Antworten für HTTP-APIs in API Gateway transformieren](http-api-parameter-mapping.md). Bei der Zuweisung von Parametern weisen Sie Anfrage- oder Antwortparameter zu. Sie können Parameter mithilfe von Ausdrücken zur Parameterzuweisung oder statischen Werten zuweisen. Eine Liste der Zuweisungsweisungsausdrücke finden Sie unter [Quellenreferenz für die Parameterzuweisung für REST APIs in API Gateway](rest-api-parameter-mapping-sources.md). Sie können die Zuweisung von Parametern in Ihrer Integrationsanforderung sowohl für Proxy- als auch für Nicht-Proxy-Integrationen verwenden. Um jedoch die Zuweisung von Parametern für eine Integrationsantwort zu nutzen, benötigen Sie eine Nicht-Proxy-Integration. Beispielsweise können Sie den Header-Parameter `puppies` der Methodenanforderung dem Header-Parameter `DogsAge0` der Integrationsanforderung zuweisen. Wenn ein Client den Header `puppies:true` an Ihre API sendet, sendet die Integrationsanforderung den Anfrage-Header `DogsAge0:true` an den Integrationsendpunkt. Das folgende Diagramm zeigt den Anfragelebenszyklus dieses Beispiels. ![\[Diagramm eines Beispiels zur Parameterzuweisung in API Gateway für eine Anfrage\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/parameter-mapping-example1.png) Informationen zum Erstellen dieses Beispiels mit API Gateway finden Sie unter [Beispiel 1: Zuweisen eines Methodenanforderungsparameters zu einem Integrationsanforderungsparameter](request-response-data-mappings.md#request-response-data-mappings-example-1). Als weiteres Beispiel können Sie den Header-Parameter `kittens` der Integrationsantwort dem Header-Parameter `CatsAge0` der Methodenantwort zuweisen. Wenn der Integrationsendpunkt dann `kittens:false` zurückgibt, erhält der Client den Header `CatsAge0:false`. Das folgende Diagramm zeigt den Anfragelebenszyklus dieses Beispiels. ![\[Diagramm eines Beispiels zur Parameterzuweisung in API Gateway für eine Anfrage\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/parameter-mapping-example2.png) **Topics** + [Beispiele für die Parameterzuweisung für REST APIs in API Gateway](request-response-data-mappings.md) + [Quellenreferenz für die Parameterzuweisung für REST APIs in API Gateway](rest-api-parameter-mapping-sources.md) # Beispiele für die Parameterzuweisung für REST APIs in API Gateway Die folgenden Beispiele zeigen, wie Sie Ausdrücke zur Parameterzuweisung mithilfe der API-Gateway-Konsole, OpenAPI oder 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 im API Gateway](how-to-cors.md). ## 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-Managementkonsole ] **So weisen Sie den Parameter der Methodenanforderung zu** 1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway). 1. Wählen Sie eine REST-API aus. 1. Wählen Sie eine Methode aus. Ihre Methode muss eine Nicht-Proxy-Integration aufweisen. 1. Wählen Sie unter **Methodenanfrage-Einstellungen** die Option **Bearbeiten** aus. 1. Wählen Sie **HTTP-Anfrage-Header** aus. 1. Wählen Sie **Add header**. 1. Geben Sie unter **Name** **puppies** ein. 1. Wählen Sie **Speichern**. 1. Wählen Sie die Registerkarte **Integrationsanfrage** aus und klicken Sie dann unter **Einstellungen für Integrationsanforderungen** auf **Bearbeiten**. Das fügt AWS-Managementkonsole automatisch eine Parameterzuordnung von `method.request.header.puppies ` zu `puppies` für Sie hinzu, aber Sie müssen den **Namen** ändern, damit er mit dem Anforderungsheader-Parameter übereinstimmt, der von Ihrem Integrationsendpunkt erwartet wird. 1. Geben Sie unter **Name** **DogsAge0** ein. 1. Wählen Sie **Speichern**. 1. 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)** 1. Wählen Sie die Registerkarte **Test**. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen. 1. Geben Sie unter Headers **puppies:true** ein. 1. Wählen Sie **Test** aus. 1. 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. ------ #### [ CloudFormation ] In diesem Beispiel verwenden Sie die [Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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-Managementkonsole ] **So weisen Sie Methodenanforderungsparameter zu** 1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway). 1. Wählen Sie eine REST-API aus. 1. Wählen Sie eine Methode aus. Ihre Methode muss eine Nicht-Proxy-Integration aufweisen. 1. Wählen Sie unter **Methodenanfrage-Einstellungen** die Option **Bearbeiten** aus. 1. Klicken Sie auf **Parameter für URL-Abfragezeichenfolgen**. 1. Wählen Sie **Abfragezeichenfolge hinzufügen** aus. 1. Geben Sie unter **Name** **methodRequestQueryParam** ein. 1. Wählen Sie **HTTP-Anfrage-Headers** aus. 1. Wählen Sie **Add header**. 1. Geben Sie unter **Name** **methodRequestHeaderParam** ein. 1. Wählen Sie **Speichern**. 1. Wählen Sie die Registerkarte **Integrationsanfrage** aus und klicken Sie dann unter **Einstellungen für Integrationsanforderungen** auf **Bearbeiten**. 1. Klicken Sie auf **URL-Pfadparameter**. 1. Klicken Sie auf **Pfadparameter hinzufügen**. 1. Geben Sie unter **Name** **integrationPathParam** ein. 1. 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. 1. Klicken Sie auf **Parameter für URL-Abfragezeichenfolgen**. 1. Wählen Sie **Abfragezeichenfolge hinzufügen** aus. 1. Geben Sie unter **Name** **integrationQueryParam** ein. 1. 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. 1. Wählen Sie **Speichern**. 1. Sie müssen Ihre API erneut bereitstellen, damit die Änderungen wirksam werden. ------ #### [ CloudFormation ] In diesem Beispiel verwenden Sie die [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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 Feldern im JSON-Anforderungstext mithilfe eines Ausdrucks zuordnen. JSONPath ](http://goessner.net/articles/JsonPath/index.html#e2) 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-Managementkonsole ] **So weisen Sie Methodenanforderungsparameter zu** 1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway). 1. Wählen Sie eine REST-API aus. 1. Wählen Sie eine `POST`-, `PUT`-, `PATCH`- oder `ANY`-Methode aus. Ihre Methode muss eine Nicht-Proxy-Integration aufweisen. 1. Wählen Sie unter **Methodenanfrage-Einstellungen** die Option **Bearbeiten** aus. 1. Klicken Sie auf **URL-Anforderungsheader-Parameter**. 1. Klicken Sie auf **Header-Parameter der Anfrage hinzufügen**. 1. Geben Sie unter **Name** **body-header** ein. 1. Geben Sie für **Zugeordnet von** **method.request.body** ein. Damit wird der Body der Methodenanforderung einem neuen Header-Parameter der Integrationsanforderung zugewiesen. 1. Klicken Sie auf **Header-Parameter der Anfrage hinzufügen**. 1. Geben Sie unter **Name** **pet-price** ein. 1. 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. 1. Wählen Sie **Speichern**. 1. Sie müssen Ihre API erneut bereitstellen, damit die Änderungen wirksam werden. ------ #### [ CloudFormation ] In diesem Beispiel verwenden Sie die [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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-Managementkonsole ] **So weisen Sie die Integrationsantwort zu** 1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway). 1. Wählen Sie eine REST-API aus. 1. Wählen Sie eine Methode aus. Ihre Methode muss eine Nicht-Proxy-Integration aufweisen. 1. Wechseln Sie zur Registerkarte **Methodenantwort** und wählen Sie unter **Antwort 200** die Option **Bearbeiten** aus. 1. Wählen Sie unter **Header-Name** die Option **Header hinzufügen** aus. 1. Erstellen Sie drei Header mit den Namen **id**, **item** und **location**. 1. Wählen Sie **Speichern** aus. 1. Wechseln Sie zur Registerkarte **Integrationsantwort** und wählen Sie unter **Standard – Antwort** die Option **Bearbeiten** aus. 1. Geben Sie unter **Header-Zuweisungen** Folgendes ein. 1. Geben Sie unter **id** **integration.response.header.x-app-id** ein. 1. Geben Sie unter **item** **integration.response.multivalueheader.item** ein. 1. Geben Sie unter **location** **integration.response.body.redirect.url** ein. 1. Wählen Sie **Speichern** aus. 1. Sie müssen Ihre API erneut bereitstellen, damit die Änderungen wirksam werden. ------ #### [ CloudFormation ] In diesem Beispiel verwenden Sie die [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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 } } } } } ``` ------ # Quellenreferenz für die Parameterzuweisung für REST APIs in API Gateway Wenn Sie eine Parameterzuweisung erstellen, geben Sie die zu ändernden Parameter der Methodenanforderung oder Integrationsantwort an und legen fest, wie diese Parameter geändert werden sollen. Die folgende Tabelle zeigt die Parameter der Methodenanforderung, die Sie zuweisen können, sowie den Ausdruck, um die Zuweisung zu erstellen. In diesen Ausdrücken *name* ist dies der Name eines Methodenanforderungsparameters. Beispielsweise verwenden Sie zur Zuweisung des Header-Parameters in der Anforderung `puppies` den Ausdruck `method.request.header.puppies`. Ihr Ausdruck muss dem regulären Ausdruck `'^[a-zA-Z0-9._$-]+$]'` entsprechen. Sie können die Parameterzuweisung in Ihrer Integrationsanforderung sowohl für Proxy- als auch für Nicht-Proxy-Integrationen verwenden. | **Zugewiesene Datenquelle** | **Mapping-Ausdruck** | | --- | --- | | Methodenanforderungspfad | method.request.path.name | | Abfragezeichenfolge der Methodenanforderung | method.request.querystring.name | | Mehrwertmethode Abfrage Abfrage Zeichenfolge | method.request.multivaluequerystring.name | | Methodenanforderungs-Header | method.request.header.name | | Mehrfachmethodenanforderungs-Header | method.request.multivalueheader.name | | Methodenanforderungstext | method.request.body | | Hauptteil der Methodenanforderung (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION*ist ein JSONPath Ausdruck für ein JSON-Feld im Hauptteil einer Anfrage. Weitere Informationen finden Sie unter [JSONPath Ausdruck](http://goessner.net/articles/JsonPath/index.html#e2). | | Stufenvariablen | stageVariables.name | | Kontextvariablen | `context.name` Der Name muss eine der [unterstützten Kontextvariablen](api-gateway-mapping-template-reference.md#context-variable-reference) sein. | | Statischer Wert | `'static_value'`. Das *static\$1value* ist ein Zeichenfolgenliteral und muss in zwei einfache Anführungszeichen eingeschlossen werden. Beispiel, `'https://www.example.com'`. | Die folgende Tabelle zeigt die Parameter der Integrationsantwort, die Sie zuweisen können, sowie den Ausdruck zur Erstellung der Zuweisung. *name*Ist in diesen Ausdrücken der Name eines Antwortparameters für die Integration. Sie können Header der Methodenantwort aus beliebigen Headern der Integrationsantwort oder dem Body einer Integrationsantwort, aus \$1context-Variablen oder aus statischen Werten zuweisen. Um die Zuweisung von Parametern für eine Integrationsantwort zu verwenden, benötigen Sie eine Nicht-Proxy-Integration. | Zugewiesene Datenquelle | Mapping-Ausdruck | | --- | --- | | Integrationsantwort-Header | integration.response.header.name | | Integrationsantwort-Header | integration.response.multivalueheader.name | | Integrationsantworttext | integration.response.body | | Hauptteil der Integrationsantwort (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION*ist ein JSONPath Ausdruck für ein JSON-Feld im Hauptteil einer Antwort. Weitere Informationen finden Sie unter [JSONPath Ausdruck](http://goessner.net/articles/JsonPath/index.html#e2). | | Stufenvariable | stageVariables.name | | Kontextvariable | `context.name` Der name muss eine der [unterstützten Kontextvariablen](api-gateway-mapping-template-reference.md#context-variable-reference) sein. | | Statischer Wert | ` 'static_value'` Das *static\$1value* ist ein Zeichenfolgenliteral und muss in zwei einfache Anführungszeichen eingeschlossen werden. Beispiel, `'https://www.example.com'`. | # Zuordnen von Vorlagentransformationen für REST APIs in API Gateway Eine Transformation mit Zuweisungsvorlagen verwendet eine Zuweisungsvorlage, um Ihre Integrationsanforderung oder Integrationsantwort zu ändern. Eine *Mapping-Vorlage* ist ein in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) ausgedrücktes Skript, das anhand [JSONPath ](https://goessner.net/articles/JsonPath/)des Headers auf eine Payload angewendet wird. `Content-type` Sie verwenden Zuweisungsvorlagen, wenn Sie Transformationen mit Zuweisungsvorlagen einsetzen. In diesem Abschnitt werden konzeptionelle Informationen zu Zuweisungsvorlagen beschrieben. Das folgende Diagramm zeigt den Anforderungslebenszyklus für eine `POST /pets` Ressource, die über eine Integration mit einem Integrationsendpunkt PetStore verfügt. In dieser API senden Benutzer Daten zu einem Haustier, und der Integrationsendpunkt gibt die mit dem Haustier verbundene Adoptionsgebühr zurück. In diesem Anfragelebenszyklus filtern Transformationen mit Zuweisungsvorlagen den Anfragebody zum Integrationsendpunkt und den Antwortbody vom Integrationsendpunkt. ![\[Beispiel eines Anfragelebenszyklus\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/mapping-template-transforms.png) Die folgenden Abschnitte erläutern den Lebenszyklus von Anfrage und Antwort. ## Methodenanforderung und Integrationsanforderung Im vorherigen Beispiel gilt: Wenn dies der Anforderungs-Body ist, der an die Methodenanforderung gesendet wird: ``` POST /pets HTTP/1.1 Host:abcd1234.us-west-2.amazonaws.com Content-type: application/json { "id": 1, "type": "dog", "Age": 11, } ``` Dieser Body der Anfrage liegt nicht im richtigen Format vor, um vom Integrationsendpunkt verwendet zu werden. Daher führt API Gateway eine Zuweisungsvorlagen-Transformation durch. API Gateway führt diese Transformation nur aus, weil eine Zuweisungsvorlage für den Inhaltstyp `application/json` definiert ist. Wenn Sie keine Zuweisungsvorlage für den Inhaltstyp definieren, leitet API Gateway den Body standardmäßig über die Integrationsanforderung an den Integrationsendpunkt weiter. Informationen zum Ändern dieses Verhaltens finden Sie unter [Verhalten bei Methodenanfragen für Payloads ohne Zuordnungsvorlagen für REST APIs in API Gateway](integration-passthrough-behaviors.md). Die folgende Zuweisungsvorlage transformiert die Daten der Methodenanforderung in der Integrationsanforderung, bevor sie an den Integrationsendpunkt gesendet werden: ``` #set($inputRoot = $input.path('$')) { "dogId" : "dog_"$elem.id, "Age": $inputRoot.Age } ``` 1. Die Variable `$inputRoot` stellt in den ursprünglichen JSON-Daten aus dem vorherigen Abschnitt das Stammobjekt dar. Richtlinien beginnen mit dem `#`-Symbol. 1. `dog` ist eine Verkettung der `id` des Benutzers und einer Zeichenfolge. 1. `Age` stammt aus dem Body der Methodenanforderung. Anschließend wird die folgende Ausgabe an den Integrationsendpunkt weitergeleitet: ``` { "dogId" : "dog_1", "Age": 11 } ``` ## Integrationsantwort und Methodenantwort Nach einer erfolgreichen Anfrage an den Integrationsendpunkt sendet der Endpunkt eine Antwort an die Integrationsantwort von API Gateway. Im Folgenden sehen Sie die Beispieldaten, die vom Integrationsendpunkt zurückgegeben werden: ``` { "dogId" : "dog_1", "adoptionFee": 19.95, } ``` Die Methodenantwort erwartet andere Nutzdaten als die, die von der Integrationsantwort zurückgegeben werden. Daher führt API Gateway eine Transformation mit Zuweisungsvorlagen aus. API Gateway führt diese Transformation nur aus, weil eine Zuweisungsvorlage für den Inhaltstyp `application/json` definiert ist. Wenn Sie keine Zuweisungsvorlage für den Inhaltstyp definieren, leitet API Gateway den Body standardmäßig über die Integrationsantwort an die Methodenantwort weiter. Informationen zum Ändern dieses Verhaltens finden Sie unter [Verhalten bei Methodenanfragen für Payloads ohne Zuordnungsvorlagen für REST APIs in API Gateway](integration-passthrough-behaviors.md). ``` #set($inputRoot = $input.path('$')) { "adoptionFee" : $inputRoot.adoptionFee, } ``` Die folgende Ausgabe wird an die Methodenantwort gesendet: ``` {"adoptionFee": 19.95} ``` Damit ist das Beispiel zur Transformation mit Zuweisungsvorlagen abgeschlossen. Wir empfehlen, wann immer möglich, statt Transformationen mit Zuweisungsvorlagen eine Proxy-Integration zu verwenden, um Ihre Daten zu transformieren. Weitere Informationen finden Sie unter [Auswählen eines API Gateway-API-Integration](api-gateway-api-integration-types.md). # Verhalten bei Methodenanfragen für Payloads ohne Zuordnungsvorlagen für REST APIs in API Gateway Wenn Ihre Methodenanforderung Nutzdaten enthält und Sie keine Zuweisungsvorlage für den `Content-Type`-Header definiert haben, können Sie wählen, ob die vom Client bereitgestellten Anfragenutzdaten ohne Transformation über die Integrationsanforderung an das Backend weitergegeben werden. Dieser Prozess wird als "Integrations-Pass-Through" bezeichnet. Das tatsächliche Passthrough-Verhalten einer eingehenden Anfrage wird durch diese Einstellung bestimmt. Es gibt drei Optionen: **Wenn keine Vorlage mit dem angeforderten Inhaltstyp-Header übereinstimmt** Wählen Sie diese Option, falls der Methodenanforderungstext ohne Umwandlung durch die Integrationsanforderung an das Backend übergeben werden soll, sofern der Inhaltstyp der Methodenanforderung keinem mit den Zuweisungsvorlagen verknüpften Inhaltstyp entspricht. Beim Aufruf der API-Gateway-API wählen Sie diese Option aus, indem Sie `WHEN_NO_MATCH` als `passthroughBehavior`-Eigenschaftswert für die [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) festlegen. **Wenn keine Vorlagen definiert sind (empfohlen)** Wählen Sie diese Option, falls der Methodenanforderungstext ohne Umwandlung durch die Integrationsanforderung an das Backend übergeben werden soll, sofern in der Integrationsanforderung keine Zuweisungsvorlage definiert ist. Wenn eine Vorlage definiert und diese Option ausgewählt ist, wird die Methodenanforderung mit Nutzdaten und einem Inhaltstyp, der keiner definierten Zuweisungsvorlage entspricht, mit einer HTTP-415-Antwort (Nicht unterstützter Medientype) zurückgewiesen. Beim Aufruf der API-Gateway-API wählen Sie diese Option aus, indem Sie `WHEN_NO_TEMPLATES` als `passthroughBehavior`-Eigenschaftswert für die [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) festlegen. **Niemals** Wählen Sie diese Option, falls der Methodenanforderungstext nicht ohne Umwandlung durch die Integrationsanforderung an das Backend übergeben werden soll, sofern in der Integrationsanforderung keine Zuweisungsvorlage definiert ist. Wenn eine Vorlage definiert und diese Option ausgewählt ist, wird die Methodenanforderung eines nicht zugeordneten Inhaltstyps mit einer Antwort "HTTP 415 Unsupported Media Type" zurückgewiesen. Beim Aufruf der API-Gateway-API wählen Sie diese Option aus, indem Sie `NEVER` als `passthroughBehavior`-Eigenschaftswert für die [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) festlegen. Die folgenden Beispiele veranschaulichen die möglichen Pass-Through-Verhalten. Beispiel 1: Eine Mapping-Vorlage wird in der Integrationsanforderung für den Content-Type `application/json` definiert. | Inhaltstyp | Pass-Through-Option | Behavior | | --- | --- | --- | | Keine API Gateway verwendet standardmäßig `application/json` | WHEN\$1NO\$1MATCH | Die Anforderungsnutzlast wird anhand der Vorlage umgewandelt. | | Keine API Gateway verwendet standardmäßig `application/json` | WHEN\$1NO\$1TEMPLATES | Die Anforderungsnutzlast wird anhand der Vorlage umgewandelt. | | Keine API Gateway verwendet standardmäßig `application/json` | NEVER | Die Anforderungsnutzlast wird anhand der Vorlage umgewandelt. | | application/json | WHEN\$1NO\$1MATCH | Die Anforderungsnutzlast wird anhand der Vorlage umgewandelt. | | application/json | WHEN\$1NO\$1TEMPLATES | Die Anforderungsnutzlast wird anhand der Vorlage umgewandelt. | | application/json | NEVER | Die Anforderungsnutzlast wird anhand der Vorlage umgewandelt. | | application/xml | WHEN\$1NO\$1MATCH | Die Anforderungsnutzlast wird nicht umgewandelt, sondern unverändert an das Backend gesendet. | | application/xml | WHEN\$1NO\$1TEMPLATES | Die Anforderung wird mit der HTTP-Antwort 415 Unsupported Media Type abgelehnt. | | application/xml | NEVER | Die Anforderung wird mit der HTTP-Antwort 415 Unsupported Media Type abgelehnt. | Beispiel 2: Eine Mapping-Vorlage wird in der Integrationsanforderung für den Content-Type `application/xml` definiert. | Inhaltstyp | Pass-Through-Option | Behavior | | --- | --- | --- | | Keine API Gateway verwendet standardmäßig `application/json` | WHEN\$1NO\$1MATCH | Die Anforderungsnutzlast wird nicht umgewandelt, sondern unverändert an das Backend gesendet. | | Keine API Gateway verwendet standardmäßig `application/json` | WHEN\$1NO\$1TEMPLATES | Die Anforderung wird mit der HTTP-Antwort 415 Unsupported Media Type abgelehnt. | | Keine API Gateway verwendet standardmäßig `application/json` | NEVER | Die Anforderung wird mit der HTTP-Antwort 415 Unsupported Media Type abgelehnt. | | application/json | WHEN\$1NO\$1MATCH | Die Anforderungsnutzlast wird nicht umgewandelt, sondern unverändert an das Backend gesendet. | | application/json | WHEN\$1NO\$1TEMPLATES | Die Anforderung wird mit der HTTP-Antwort 415 Unsupported Media Type abgelehnt. | | application/json | NEVER | Die Anforderung wird mit der HTTP-Antwort 415 Unsupported Media Type abgelehnt. | | application/xml | WHEN\$1NO\$1MATCH | Die Anforderungsnutzlast wird anhand der Vorlage umgewandelt. | | application/xml | WHEN\$1NO\$1TEMPLATES | Die Anforderungsnutzlast wird anhand der Vorlage umgewandelt. | | application/xml | NEVER | Die Anforderungsnutzlast wird anhand der Vorlage umgewandelt. | Beispiel 3: In der Integrationsanforderung sind keine Zuweisungsvorlagen definiert. | Inhaltstyp | Pass-Through-Option | Behavior | | --- | --- | --- | | Keine API Gateway verwendet standardmäßig `application/json` | WHEN\$1NO\$1MATCH | Die Anforderungsnutzlast wird nicht umgewandelt, sondern unverändert an das Backend gesendet. | | Keine API Gateway verwendet standardmäßig `application/json` | WHEN\$1NO\$1TEMPLATES | Die Anforderungsnutzlast wird nicht umgewandelt, sondern unverändert an das Backend gesendet. | | Keine API Gateway verwendet standardmäßig `application/json` | NEVER | Die Anforderung wird mit der HTTP-Antwort 415 Unsupported Media Type abgelehnt. | | application/json | WHEN\$1NO\$1MATCH | Die Anforderungsnutzlast wird nicht umgewandelt, sondern unverändert an das Backend gesendet. | | application/json | WHEN\$1NO\$1TEMPLATES | Die Anforderungsnutzlast wird nicht umgewandelt, sondern unverändert an das Backend gesendet. | | application/json | NEVER | Die Anforderung wird mit der HTTP-Antwort 415 Unsupported Media Type abgelehnt. | | application/xml | WHEN\$1NO\$1MATCH | Die Anforderungsnutzlast wird nicht umgewandelt, sondern unverändert an das Backend gesendet. | | application/xml | WHEN\$1NO\$1TEMPLATES | Die Anforderungsnutzlast wird nicht umgewandelt, sondern unverändert an das Backend gesendet. | | application/xml | NEVER | Die Anforderung wird mit der HTTP-Antwort 415 Unsupported Media Type abgelehnt. | # Beispiel für eine zusätzliche Zuordnungsvorlage für REST APIs in API Gateway Das folgende Beispiel zeigt eine Fotoalbum-API in API Gateway, die Zuweisungsvorlagen verwendet, um Daten der Integrationsanforderung und Integrationsantwort zu transformieren. Es werden außerdem Datenmodelle verwendet, um die Nutzdaten der Methodenanforderung und der Integrationsantwort zu definieren. Weitere Informationen zu Datenmodellen finden Sie unter [Datenmodelle für REST APIs](models-mappings-models.md). ## Methodenanforderung und Integrationsanforderung Im Folgenden ist ein Modell dargestellt, das den Body der Methodenanforderung definiert. Bei diesem Eingabemodell muss der Aufrufer mindestens eine Fotoseite hochladen und für jede Seite wird ein Minimum von 10 Fotos vorgegeben. Sie können dieses Eingabemodell verwenden, um ein SDK zu generieren oder um eine Anfragevalidierung für Ihre API zu nutzen. Bei der Verwendung der Anfragevalidierung lässt API Gateway die Anfrage fehlschlagen, wenn der Body der Methodenanforderung nicht der Datenstruktur des Modells entspricht. ``` { "$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" } } } } } } } } ``` Im Folgenden sehen Sie ein Beispiel für einen Body der Methodenanforderung, der der Datenstruktur des vorherigen Datenmodells entspricht. ``` { "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 } ] } } ``` In diesem Beispiel transformiert die Zuweisungsvorlage die Nutzdaten der vorherigen Methodenanforderung, wenn sie vom Client übermittelt wurden, sodass das Format den Anforderungen des Integrationsendpunkts entspricht. ``` #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 ] } ``` Im folgenden Beispiel sehen Sie die Ausgabedaten aus der Transformation. ``` { "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 } ] } ``` Diese Daten werden an die Integrationsanforderung und anschließend an den Integrationsendpunkt gesendet. ## Integrationsantwort und Methodenantwort Im Folgenden sehen Sie ein Beispielausgabemodell für die Fotodaten vom Integrationsendpunkt. Sie können dieses Modell für ein Methodenantwortmodell verwenden; dies ist erforderlich, wenn Sie ein stark typisiertes SDK für die API generieren. Dies stellt sicher, dass die Ausgabe an eine geeignete Klasse in Java oder Objective-C übergeben wird. ``` { "$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" } } } } } } ``` Der Integrationsendpunkt liefert möglicherweise keine Antwort, die der Datenstruktur dieses Modells entspricht. Zum Beispiel könnte die Integrationsantwort wie folgt aussehen: ``` "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 } ] } ``` Die folgende Zuweisungsvorlage transformiert die Integrationsantwortdaten in das Format, das von der Methodenantwort erwartet wird: ``` #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 ] } ``` Im folgenden Beispiel sehen Sie die Ausgabedaten aus der Transformation. ``` { "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 } ] } ``` Diese Daten werden an die Methodenantwort gesendet und anschließend an den Client zurückgegeben. # Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway Sie können Transformationen mit Zuweisungsvorlagen verwenden, um beliebige Arten von Anfrageparametern, Antwort-Headern oder Antwortstatuscodes zu überschreiben. Mit einer Zuweisungsvorlage können Sie Folgendes tun: + Führen Sie many-to-one Parameterzuordnungen durch + Eine Überschreibung von Parametern, nachdem standardmäßige API-Gateway-Zuweisungen angewendet wurden + Die Zuordnung konditionaler Parameter auf Grundlage des Textinhalts oder anderer Parameterwerte + Die programmgesteuerte Erstellung neuer Parameter + Das Überschreiben von Statuscodes, die von Ihrem Integrationsendpunkt zurückgegeben wurden Überschreibungen sind endgültig. Eine Überschreibung darf nur einmal auf jeden Parameter angewendet werden. Wenn Sie versuchen, denselben Parameter mehrmals zu überschreiben, gibt API Gateway eine `5XX`-Antwort zurück. Wenn Sie denselben Parameter in einer Vorlage mehrmals überschreiben müssen, empfehlen wir die Erstellung einer Variable und Umsetzung der Überschreibung am Ende der Vorlage. Die Vorlage wird erst nach der Analyse der gesamten Vorlage angewendet. ## Beispiel 1: Überschreiben des Statuscodes basierend auf dem Body der Integration Im folgenden Beispiel wird die [Beispiel-API](api-gateway-create-api-from-example.md) verwendet, um den Statuscode basierend auf dem Body der Integrationsantwort zu überschreiben. ------ #### [ AWS-Managementkonsole ] **Überschreiben eines Statuscodes basierend auf dem Body der Integrationsantwort** 1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway). 1. Wählen Sie **Create API** (API erstellen) aus. 1. Wählen Sie unter **REST-API** die Option **Erstellen** aus. 1. Wählen Sie unter **API-Details** die Option **Beispiel-API** aus. 1. Wählen Sie **Create API** (API erstellen) aus. API Gateway erstellt eine Beispiel-API für einen PetStore. Um Informationen über ein Haustier abzurufen, verwenden Sie die API-Methodenanforderung `GET /pets/{petId}`, wobei `{petId}` ein Pfadparameter ist, der einer ID-Nummer für ein Haustier entspricht. In diesem Beispiel überschreiben Sie den Antwortcode der `GET`-Methode auf `400`, wenn eine Fehlerbedingung erkannt wird. 1. Wählen Sie in der **Ressourcen**-Struktur unter `GET` die `/{petId}`-Methode aus. 1. Testen Sie zunächst die aktuelle Implementierung der API. Wählen Sie die Registerkarte **Test**. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen. 1. Geben Sie für **petId** **-1** ein und klicken Sie dann auf **Test**. Der **Antworttext weist auf einen Fehler** hin: out-of-range ``` { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] } ``` Außerdem endet die letzte Zeile unter **Logs** mit: `Method completed with status: 200`. Die Integration wurde erfolgreich abgeschlossen, es ist jedoch ein Fehler aufgetreten. Jetzt überschreiben Sie den Statuscode auf Grundlage der Integrationsantwort. 1. Klicken Sie auf der Registerkarte **Integrationsantwort** unter **Standard - Antwort** auf **Bearbeiten**. 1. Wählen Sie **Zuordnungsvorlagen** aus. 1. Wählen Sie **Add mapping template**. 1. Geben Sie für **Content type** (Inhaltstyp) **application/json** ein. 1. Geben Sie für **Vorlagentext** Folgendes ein: ``` #set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end ``` Diese Zuweisungsvorlage verwendet die Variable `$context.responseOverride.status`, um den Statuscode auf `400` zu überschreiben, wenn die Integrationsantwort den Zeichenfolge `error` enthält. 1. Wählen Sie **Speichern**. 1. Wählen Sie die Registerkarte **Test**. 1. Geben Sie als **petid** **-1** ein. 1. In den Ergebnissen gibt der **Antworttext** einen out-of-range Fehler an: ``` { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] } ``` Die letzte Zeile unter dem **Logs** endet nun jedoch mit: `Method completed with status: 400`. ------ #### [ CloudFormation ] In diesem Beispiel verwenden Sie die [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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: 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 ] Die folgende OpenAPI-Definition erstellt die `GET pets/{petId}`-Ressource und überschreibt den Statuscode basierend auf dem Body der Integration. ``` { "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" } } } } } } ``` ------ ## Beispiel 2: Überschreiben des Anfrage-Headers und Erstellen neuer Header Das folgende Beispiel verwendet die [Beispiel-API](api-gateway-create-api-from-example.md), um den Anfrage-Header zu überschreiben und neue Header zu erstellen. ------ #### [ AWS-Managementkonsole ] **So überschreiben Sie einen Methodenanforderungs-Header indem Sie einen neuen Header erstellen** 1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway). 1. Wählen Sie die Beispiel-API aus, die Sie im vorherigen Tutorial erstellt haben. Der Name der API sollte lauten. **PetStore** 1. Wählen Sie in der **Ressourcen**-Struktur unter `GET` die `/pet`-Methode aus. 1. Klicken Sie auf der Registerkarte **Methodenanfrage** unter **Methodenanfrage-Einstellungen** auf **Bearbeiten**. 1. Wählen Sie **HTTP Request Headers** (HTTP-Anforderungs-Header) und dann **Add header** (Header hinzufügen) aus. 1. Geben Sie unter **Name** **header1** ein. 1. Klicken Sie auf **Header hinzufügen** und erstellen Sie dann einen zweiten Header namens **header2**. 1. Wählen Sie **Speichern** aus. Kombinieren Sie jetzt diese Header mithilfe einer Zuweisungsvorlage zu einem einzigen Header-Wert. 1. Klicken Sie auf der Registerkarte **Integrationsanfrage** unter **Einstellungen für Integrationsanfragen** auf **Bearbeiten**. 1. Wählen Sie für **Anforderungstext-Pass-Through** die Option **Wenn keine Vorlagen definiert sind (empfohlen)** aus. 1. Wählen Sie **Vorlagen zuordnen** aus und gehen Sie dann wie folgt vor: 1. Wählen Sie **Add mapping template**. 1. Geben Sie für **Content type** (Inhaltstyp) **application/json** ein. 1. Geben Sie für **Vorlagentext** Folgendes ein: ``` #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]) ``` Diese Zuweisungsvorlage überschreibt `header1` mit der Zeichenfolge `pets` und erstellt einen mehrwertigen Header mit dem Namen `$header3Value`, der `header1` und `header2` kombiniert. 1. Wählen Sie **Speichern**. 1. Wählen Sie die Registerkarte **Test**. 1. Kopieren Sie unter **Headers** den folgenden Code: ``` header1:header1Val header2:header2Val ``` 1. Wählen Sie **Test** aus. In den **Logs** sollten Sie einen Eintrag sehen, der diesen Text enthält: ``` Endpoint request headers: {header3=header1Valheader2Val, header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id, Accept=application/json, multivalueheader=pets,header1Valheader2Val} ``` ------ #### [ CloudFormation ] In diesem Beispiel verwenden Sie die [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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: 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 ] Die folgende OpenAPI-Definition erstellt die `GET pets`-Ressource, überschreibt den Anfrage-Header und erstellt neue Header. ``` { "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" } } } } } ``` ------ Um eine Zuweisungsvorlage zum Überschreiben zu verwenden, fügen Sie eine oder mehrere der folgenden `$context`-Variablen hinzu. Sie finden eine Liste der `$context`-Variablen unter [Kontextvariablen für Datentransformationen](api-gateway-mapping-template-reference.md#context-variable-reference). # Tutorial: Ändern Sie die Integrationsanfrage und die Antwort für Integrationen zu Diensten AWS Das folgende Tutorial zeigt, wie Sie mithilfe von Mapping-Vorlagentransformationen Mapping-Vorlagen einrichten, um Integrationsanfragen und -antworten mithilfe der Konsole und der AWS CLI zu transformieren. **Topics** + [Einrichten einer Datentransformation mithilfe der API-Gateway-Konsole](#mapping-example-console) + [Richten Sie die Datentransformation mit der AWS CLI ein](#mapping-example-cli) + [CloudFormation Vorlage für die Datentransformation abgeschlossen](#api-gateway-data-transformations-full-cfn-stack) ## Einrichten einer Datentransformation mithilfe der API-Gateway-Konsole [In diesem Tutorial erstellen Sie eine unvollständige API- und DynamoDB-Tabelle mithilfe der folgenden ZIP-Datei .zip. data-transformation-tutorial-console](samples/data-transformation-tutorial-console.zip) Diese unvollständige API hat eine `/pets`-Ressource mit den Methoden `GET` und `POST`. + Die `GET`-Methode ruft Daten vom `http://petstore-demo-endpoint.execute-api.com/petstore/pets`-HTTP-Endpunkt ab. Die Ausgabedaten werden gemäß der Zuweisungsvorlage zu [Zuordnen von Vorlagentransformationen für REST APIs in API Gateway](models-mappings.md) transformiert. + Die `POST`-Methode ermöglicht dem Benutzer die `POST`-Aktion von Haustierinformationen mithilfe einer Zuweisungsvorlage an eine Amazon-DynamoDB-Tabelle. [Laden Sie die Vorlage zur App-Erstellung für herunter und entpacken Sie sie. CloudFormation](samples/data-transformation-tutorial-console.zip) Sie verwenden diese Vorlage, um eine DynamoDB-Tabelle zum Posten von Haustierinformationen und einer unvollständigen API zu erstellen. Sie schließen die restlichen Schritte in der API-Gateway-Konsole ab. **Um einen Stack zu erstellen CloudFormation** 1. Öffnen Sie die CloudFormation Konsole unter [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Wählen Sie **Stack erstellen** und dann **Mit neuen Ressourcen (Standard)** aus. 1. Wählen Sie unter **Vorlage angeben** die Option **Vorlagendatei hochladen** aus. 1. Wählen Sie die Vorlage aus, die Sie heruntergeladen haben. 1. Wählen Sie **Weiter** aus. 1. Geben Sie für **Stack-Name** die Zeichenfolge **data-transformation-tutorial-console** ein und klicken Sie auf **Weiter**. 1. Wählen Sie in **Stack-Optionen konfigurieren** die Option **Weiter** aus. 1. Bestätigen Sie bei **Capabilities**, dass IAM-Ressourcen in Ihrem Konto erstellt werden CloudFormation können. 1. Wählen Sie **Weiter** und anschließend **Absenden** aus. CloudFormation stellt die in der Vorlage angegebenen Ressourcen bereit. Die Bereitstellung der Ressourcen kann einige Minuten dauern. Wenn der Status Ihres CloudFormation Stacks **CREATE\$1COMPLETE** lautet, können Sie mit dem nächsten Schritt fortfahren. **So testen Sie die `GET`-Integrationsantwort** 1. Wählen Sie auf der Registerkarte **Ressourcen** des CloudFormation Stacks für **data-transformation-tutorial-console** die physische ID Ihrer API aus. 1. Klicken Sie im Hauptnavigationsbereich auf **Ressourcen** und wählen Sie dann die **GET**-Methode in der Ressourcenstruktur aus. 1. Wählen Sie die Registerkarte **Test**. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen. Das Ergebnis des Tests wird Folgendes zeigen: ``` [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Sie transformieren diese Ausgabe gemäß der Zuweisungsvorlage in [Zuordnen von Vorlagentransformationen für REST APIs in API Gateway](models-mappings.md). **So transformieren Sie die `GET`-Integrationsantwort** 1. Klicken Sie auf die Registerkarte **Integrationsantwort**. Derzeit sind keine Zuweisungsvorlagen definiert, sodass die Integrationsantwort nicht transformiert wird. 1. Klicken Sie unter **Standard - Antwort** auf **Bearbeiten**. 1. Wählen Sie **Vorlagen zuordnen** aus und gehen Sie dann wie folgt vor: 1. Wählen Sie **Add mapping template**. 1. Geben Sie für **Content type** (Inhaltstyp) **application/json** ein. 1. Geben Sie für **Vorlagentext** Folgendes ein: ``` #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description" : "Item $elem.id is a $elem.type.", "askingPrice" : $elem.price }#if($foreach.hasNext),#end #end ] ``` Wählen Sie **Speichern**. **So testen Sie die `GET`-Integrationsantwort** + Wählen Sie die Registerkarte **Test** und dann **Test** aus Die Ausgabe des Tests zeigt die transformierte Antwort. ``` [ { "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 } ] ``` **So transformieren Sie Eingabedaten aus der `POST`-Methode** 1. Wählen Sie die **POST**-Methode aus. 1. Wählen Sie die Registerkarte **Integrationsanfrage** aus und klicken Sie dann unter **Einstellungen für Integrationsanforderungen** auf **Bearbeiten**. Die CloudFormation Vorlage hat einige Felder für Integrationsanfragen ausgefüllt. + Der Integrationstyp ist AWS-Service. + Das AWS-Service ist DynamoDB. + Die HTTP-Methode ist `POST`. + Die Aktion ist `PutItem`. + Die Ausführungsrolle, die es API Gateway ermöglicht, ein Element in die DynamoDB-Tabelle aufzunehmen, lautet. `data-transformation-tutorial-console-APIGatewayRole` CloudFormation hat diese Rolle erstellt, damit API Gateway über die Mindestberechtigungen für die Interaktion mit DynamoDB verfügt. Der Name der DynamoDB-Tabelle wurde nicht angegeben. In den folgenden Schritten geben Sie den Namen an. 1. Für **Text-Passthrough anfordern** wählen Sie **Nie** aus. Dies bedeutet, dass die API Daten mit Inhaltstypen ablehnt, die keine Zuweisungsvorlage haben. 1. Wählen Sie **Zuordnungsvorlagen** aus. 1. Der **Inhaltstyp** ist auf `application/json` gesetzt. Das bedeutet, dass Inhaltstypen, die dies nicht sind, von der API abgelehnt application/json werden. Weitere Informationen zu Integrations-Passthrough-Verhaltensweisen finden Sie unter [Verhalten bei Methodenanfragen für Payloads ohne Zuordnungsvorlagen für REST APIs in API Gateway](integration-passthrough-behaviors.md). 1. Geben Sie den folgenden Code in den Texteditor ein. ``` { "TableName":"data-transformation-tutorial-console-ddb", "Item": { "id": { "N": $input.json("$.id") }, "type": { "S": $input.json("$.type") }, "price": { "N": $input.json("$.price") } } } ``` Diese Vorlage spezifiziert die Tabelle als `data-transformation-tutorial-console-ddb` und legt die Elemente als `id`, `type` und `price` fest. Die Elemente kommen aus dem Hauptteil der `POST`-Methode. Sie können auch ein Datenmodell verwenden, um eine Zuweisungsvorlage zu erstellen. Weitere Informationen finden Sie unter [Validierung für REST APIs in API Gateway anfordern](api-gateway-method-request-validation.md). 1. Betätigen Sie die Schaltfläche **Speichern**, um die Zuweisungsvorlage zu speichern. **So fügen Sie eine Methode und eine Integrationsantwort aus der `POST`-Methode hinzu** Sie CloudFormation haben eine leere Methode und Integrationsantwort erstellt. Sie werden diese Antwort bearbeiten, um weitere Informationen bereitzustellen. Weitere Informationen zum Bearbeiten von Antworten finden Sie unter [Beispiele für die Parameterzuweisung für REST APIs in API Gateway](request-response-data-mappings.md). 1. Klicken Sie auf der Registerkarte **Integrationsantwort** unter **Standard - Antwort** auf **Bearbeiten**. 1. Wählen Sie **Zuordnungsvorlagen** aus und klicken Sie dann auf **Zuordnungsvorlage hinzufügen**. 1. Geben Sie für **Inhaltstyp** **application/json** ein. 1. Geben Sie im Code-Editor die folgende Ausgabe–Zuweisungsvorlage ein, um eine Ausgabenachricht zu senden: ``` { "message" : "Your response was recorded at $context.requestTime" } ``` Weitere Informationen zu Kontextvariablen finden Sie unter  [Kontextvariablen für Datentransformationen](api-gateway-mapping-template-reference.md#context-variable-reference). 1. Betätigen Sie die Schaltfläche **Speichern**, um die Zuweisungsvorlage zu speichern. **Testen der `POST`-Methode** Wählen Sie die Registerkarte **Test**. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen. 1. Geben Sie im Anforderungstext das folgende Beispiel ein. ``` { "id": "4", "type" : "dog", "price": "321" } ``` 1. Wählen Sie **Test** aus. Die Ausgabe sollte Ihre Erfolgsmeldung enthalten. Sie können die DynamoDB-Konsole unter öffnen, [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)um zu überprüfen, ob sich das Beispielelement in Ihrer Tabelle befindet. **Um einen Stapel zu löschen CloudFormation** 1. Öffnen Sie die CloudFormation Konsole unter [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Wählen Sie Ihren CloudFormation Stack aus. 1. Wählen Sie **Löschen** und bestätigen Sie dann Ihre Auswahl. ## Richten Sie die Datentransformation mit der AWS CLI ein [In diesem Tutorial erstellen Sie eine unvollständige API- und DynamoDB-Tabelle mithilfe der folgenden ZIP-Datei .zip. data-transformation-tutorial-cli](samples/data-transformation-tutorial-cli.zip) Diese unvollständige API verfügt über eine `/pets`-Ressource mit einer `GET`-Methode, die in den `http://petstore-demo-endpoint.execute-api.com/petstore/pets`-HTTP-Endpunkt integriert ist. Sie erstellen eine `POST`-Methode, um eine Verbindung zu einer DynamoDB-Tabelle herzustellen, und verwenden Zuweisungsvorlagen, um Daten in eine DynamoDB-Tabelle einzugeben. + Sie transformieren die Ausgabedaten gemäß der Zuweisungsvorlage zu [Zuordnen von Vorlagentransformationen für REST APIs in API Gateway](models-mappings.md). + Sie erstellen eine `POST`-Methode, die es dem Benutzer ermöglicht, mithilfe einer Zuweisungsvorlage die `POST`-Aktion an eine Amazon-DynamoDB-Tabelle durchzuführen. **Um einen Stapel zu erstellen CloudFormation** Laden Sie [die Vorlage zur App-Erstellung für CloudFormation](samples/data-transformation-tutorial-cli.zip) herunter und entpacken Sie sie. Um die folgenden Schritte durchzuführen, benötigen Sie die [AWS Command Line Interface (AWS CLI) Version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). Bei langen Befehlen wird ein Escape-Zeichen (`\`) verwendet, um einen Befehl auf mehrere Zeilen aufzuteilen. **Anmerkung** In Windows werden einige Bash-CLI-Befehle, die Sie häufig verwenden (z. B. `zip`), von den integrierten Terminals des Betriebssystems nicht unterstützt. Um eine in Windows integrierte Version von Ubuntu und Bash zu erhalten, [installieren Sie das Windows-Subsystem für Linux](https://learn.microsoft.com/en-us/windows/wsl/install). Die CLI-Beispielbefehle in diesem Handbuch verwenden die Linux-Formatierung. Befehle, die Inline-JSON-Dokumente enthalten, müssen neu formatiert werden, wenn Sie die Windows-CLI verwenden. 1. Verwenden Sie den folgenden Befehl, um den CloudFormation Stack zu erstellen. ``` aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM ``` 1. CloudFormation stellt die in der Vorlage angegebenen Ressourcen bereit. Die Bereitstellung der Ressourcen kann einige Minuten dauern. Verwenden Sie den folgenden Befehl, um den Status Ihres CloudFormation Stacks zu überprüfen. ``` aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli ``` 1. Wenn der Status Ihres CloudFormation Stacks lautet`StackStatus: "CREATE_COMPLETE"`, verwenden Sie den folgenden Befehl, um relevante Ausgabewerte für future Schritte abzurufen. ``` aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}" ``` Die Ausgabewerte sind die folgenden: + ApiRole, das ist der Rollenname, der es API Gateway ermöglicht, Elemente in die DynamoDB-Tabelle einzufügen. Für dieses Tutorial ist der Rollenname `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`. + DDBTableName, das ist der Name der DynamoDB-Tabelle. Für dieses Tutorial ist der Name der Tabelle `data-transformation-tutorial-cli-ddb`. + ResourceId, das ist die ID der Pets-Ressource, in der die `POST` Methoden `GET` und verfügbar gemacht werden. Für dieses Tutorial lautet die Ressourcen-ID `efg456`. + ApiId, was die ID für die API ist. Für dieses Tutorial lautet die API-ID `abc123`. **So testen Sie die `GET`-Methode vor der Datentransformation** + Geben Sie den folgenden Befehl ein, um die `GET`-Methode zu testen. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET ``` Die Ausgabe des Tests wird Folgendes zeigen. ``` [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Sie transformieren diese Ausgabe gemäß der Zuweisungsvorlage in [Zuordnen von Vorlagentransformationen für REST APIs in API Gateway](models-mappings.md). **So transformieren Sie die `GET`-Integrationsantwort** + Führen Sie den folgenden Befehl aus, um die Integrationsantwort für die `GET`-Methode zu aktualisieren. Ersetzen Sie das *rest-api-id* und *resource-id* durch Ihre Werte. Verwenden Sie den folgenden Befehl, um die Integrationsantwort zu erstellen. ``` 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]"}' ``` **So testen Sie die `GET`-Methode** + Geben Sie den folgenden Befehl ein, um die `GET`-Methode zu testen. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ ``` Die Ausgabe des Tests zeigt die transformierte Antwort. ``` [ { "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 } ] ``` **So erstellen Sie eine `POST`-Methode** 1. Führen Sie den folgenden Befehl aus, um eine neue Methode für die `/pets`-Ressource zu erstellen. ``` aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --authorization-type "NONE" \ ``` Mit dieser Methode können Sie Pet-Informationen an die DynamoDB-Tabelle senden, die Sie im Stack erstellt haben. CloudFormation 1. Verwenden Sie den folgenden Befehl, um eine AWS-Service Integration für die `POST` Methode zu erstellen. ``` 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. Verwenden Sie den folgenden Befehl, um eine Methodenantwort für einen erfolgreichen Aufruf der `POST`-Methode zu erstellen. ``` aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 ``` 1. Verwenden Sie den folgenden Befehl, um eine Integrationsantwort für den erfolgreichen Aufruf der `POST`-Methode zu erstellen. ``` 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\"}"}' ``` **So testen Sie die `POST`-Methode** + Geben Sie den folgenden Befehl ein, um die `POST`-Methode zu testen. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}' ``` In der Ausgabe wird die Erfolgsmeldung angezeigt. **Um einen CloudFormation Stapel zu löschen** + Verwenden Sie den folgenden Befehl, um Ihre CloudFormation Ressourcen zu löschen. ``` aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli ``` ## CloudFormation Vorlage für die Datentransformation abgeschlossen Das folgende Beispiel ist eine fertige CloudFormation Vorlage, die eine API und eine DynamoDB-Tabelle mit einer `/pets` Ressource mit `GET` und `POST` Methoden erstellt. + Die `GET`-Methode ruft Daten vom `http://petstore-demo-endpoint.execute-api.com/petstore/pets`-HTTP-Endpunkt ab. Die Ausgabedaten werden gemäß der Zuweisungsvorlage zu [Zuordnen von Vorlagentransformationen für REST APIs in API Gateway](models-mappings.md) transformiert. + Die `POST`-Methode ermöglicht es dem Benutzer, mithilfe einer Zuweisungsvorlage die `POST`-Aktion zu einer DynamoDB-Tabelle durchzuführen. ### Beispiel für eine Vorlage CloudFormation ``` 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 ``` # Beispiele für die Verwendung von Variablen bei Zuweisungsvorlagen-Transformationen in API Gateway Die folgenden Beispiele zeigen, wie Sie `$context`-, `input`- und `util`-Variablen in Zuweisungsvorlagen verwenden. Sie können eine Scheinintegration oder eine Lambda-Nicht-Proxy-Integration verwenden, die das Eingabeereignis an API Gateway zurückgibt. Eine Liste aller unterstützten Variablen für Datentransformationen finden Sie unter [Variablen für Datentransformationen für API Gateway](api-gateway-mapping-template-reference.md). ## Beispiel 1: Übergeben mehrerer `$context`-Variablen an den Integrationsendpunkt Das folgende Beispiel zeigt eine Mapping-Vorlage für die Zuordnung eingehender `$context` Variablen zu Backend-Variablen mit geringfügig unterschiedlichen Namen in der Nutzlast einer Integrationsanforderung: ``` { "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" } ``` Die Ausgabe dieser Zuweisungsvorlage sollte wie folgt aussehen: ``` { 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' } ``` Eine der Variablen ist ein API-Schlüssel. In diesem Beispiel wird vorausgesetzt, dass die Methode einen API-Schlüssel erfordert. ## Beispiel 2: Übergeben aller Anfrageparameter an den Integrationsendpunkt über Nutzdaten im JSON-Format Das folgende Beispiel übergibt alle Anfrageparameter, einschließlich `path`-, `querystring`- und `header`-Parameter, an den Integrationsendpunkt über Nutzdaten im JSON-Format: ``` #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 } } ``` Wenn eine Anfrage die folgenden Eingabeparameter enthält: + Einen Pfadparameter namens `myparam` + Die Abfragezeichenfolgenparameter `querystring1=value1,value2` + Headers `"header1" : "value1"` Die Ausgabe dieser Zuweisungsvorlage sollte wie folgt aussehen: ``` {"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}} ``` ## Beispiel 3: Übergeben eines Unterabschnitts einer Methodenanforderung an den Integrationsendpunkt Im folgenden Beispiel wird der Eingabeparameter `name` verwendet, um nur den Parameter `name` abzurufen, und der Eingabeparameter `input.json('$')`, um den gesamten Body der Methodenanforderung abzurufen: ``` { "name" : "$input.params('name')", "body" : $input.json('$') } ``` Für eine Anforderung, die die Parameter der Abfragezeichenfolge `name=Bella&type=dog` und den folgenden Text enthält: ``` { "Price" : "249.99", "Age": "6" } ``` Die Ausgabe dieser Zuweisungsvorlage sollte wie folgt aussehen: ``` { "name" : "Bella", "body" : {"Price":"249.99","Age":"6"} } ``` Diese Zuweisungsvorlage entfernt den Abfragezeichenfolgenparameter `type=dog`. Wenn die JSON-Eingabe Zeichen ohne Escape-Zeichen enthält, die nicht analysiert werden können JavaScript, gibt API Gateway möglicherweise eine 400-Antwort zurück. Eine Anwendung von `$util.escapeJavaScript($input.json('$'))` stellt sicher, dass die JSON-Eingabe ordnungsgemäß eingelesen werden kann. Im vorangegangenen Beispiel hätte eine Anwendung von `$util.escapeJavaScript($input.json('$'))` folgendes Ergebnis: ``` { "name" : "$input.params('name')", "body" : "$util.escapeJavaScript($input.json('$'))" } ``` In diesem Fall sollte die Ausgabe dieser Zuweisungsvorlage wie folgt aussehen: ``` { "name" : "Bella", "body": {"Price":"249.99","Age":"6"} } ``` ## Beispiel 4: Verwenden Sie JSONPath Expression, um einen Unterabschnitt einer Methodenanforderung an den Integrationsendpunkt zu übergeben Im folgenden Beispiel werden die JSONPath Ausdrücke verwendet, um nur den Eingabeparameter `name` und den `Age` aus dem Anforderungstext abzurufen: ``` { "name" : "$input.params('name')", "body" : $input.json('$.Age') } ``` Für eine Anforderung, die die Parameter der Abfragezeichenfolge `name=Bella&type=dog` und den folgenden Text enthält: ``` { "Price" : "249.99", "Age": "6" } ``` Die Ausgabe dieser Zuweisungsvorlage sollte wie folgt aussehen: ``` { "name" : "Bella", "body" : "6" } ``` Diese Zuweisungsvorlage entfernt den Abfragezeichenfolgenparameter `type=dog` sowie das Feld `Price` aus dem Body. Wenn die Payload einer Methodenanforderung Zeichen ohne Escape-Zeichen enthält, die nicht analysiert werden können JavaScript, gibt API Gateway möglicherweise eine Antwort zurück. `400` Eine Anwendung von `$util.escapeJavaScript()` stellt sicher, dass die JSON-Eingabe ordnungsgemäß eingelesen werden kann. Im vorangegangenen Beispiel hätte eine Anwendung von `$util.escapeJavaScript($input.json('$.Age'))` folgendes Ergebnis: ``` { "name" : "$input.params('name')", "body" : "$util.escapeJavaScript($input.json('$.Age'))" } ``` In diesem Fall sollte die Ausgabe dieser Zuweisungsvorlage wie folgt aussehen: ``` { "name" : "Bella", "body": "\"6\"" } ``` ## Beispiel 5: Verwenden Sie einen JSONPath Ausdruck, um Informationen über eine Methodenanforderung an den Integrationsendpunkt zu übergeben Im folgenden Beispiel werden `$input.params()`, `$input.path()` und `$input.json()` verwendet, um Informationen über eine Methodenanforderung an den Integrationsendpunkt zu senden. Diese Zuweisungsvorlage nutzt die Methode `size()`, um die Anzahl der Elemente in einer Liste bereitzustellen. ``` { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : $input.json('$.things') } ``` Für eine Anforderung, die den Pfadparameter `123` und den folgenden Text enthält: ``` { "things": { "1": {}, "2": {}, "3": {} } } ``` Die Ausgabe dieser Zuweisungsvorlage sollte wie folgt aussehen: ``` {"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}} ``` Wenn die Payload einer Methodenanforderung Zeichen ohne Escape-Zeichen enthält, die nicht analysiert werden können JavaScript, gibt API Gateway möglicherweise eine Antwort zurück. `400` Eine Anwendung von `$util.escapeJavaScript()` stellt sicher, dass die JSON-Eingabe ordnungsgemäß eingelesen werden kann. Im vorangegangenen Beispiel hätte eine Anwendung von `$util.escapeJavaScript($input.json('$.things'))` folgendes Ergebnis: ``` { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : "$util.escapeJavaScript($input.json('$.things'))" } ``` Die Ausgabe dieser Zuweisungsvorlage sollte wie folgt aussehen: ``` {"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"} ``` # Variablen für Datentransformationen für API Gateway Wenn Sie eine Parameterzuweisung erstellen, können Sie Kontextvariablen als Datenquelle verwenden. Wenn Sie Zuweisungsvorlagen-Transformationen erstellen, können Sie Kontextvariablen sowie input- und util-Variablen in Skripten verwenden, die Sie in der [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) schreiben. Beispiele für Zuweisungsvorlagen, die diese Referenzvariablen verwenden, finden Sie unter [Beispiele für die Verwendung von Variablen bei Zuweisungsvorlagen-Transformationen in API Gateway](api-gateway-mapping-variable-examples.md). Eine Liste der Referenzvariablen für Zugriffsprotokollierung finden Sie unter [Variablen für die Zugriffsprotokollierung in API Gateway](api-gateway-variables-for-access-logging.md). ## Kontextvariablen für Datentransformationen Für Datenumwandlungen können Sie die folgenden `$context`-Variablen verwenden, bei denen die Groß-/Kleinschreibung beachtet werden muss. | Parameter | Description | | --- | --- | | \$1context.accountId | Die AWS Konto-ID des API-Besitzers. | | \$1context.apiId | Die ID, die API Gateway Ihrer API zuweist. | | \$1context.authorizer.claims.property | Eine Eigenschaft der Claims, die aus dem Amazon Cognito-Benutzerpool zurückgegeben werden, nachdem der Methodenaufrufer erfolgreich authentifiziert wurde. Weitere Informationen finden Sie unter [Steuern Sie den Zugriff auf REST APIs mithilfe von Amazon Cognito Cognito-Benutzerpools als Autorisierer](apigateway-integrate-with-cognito.md). Bei einem Aufruf von `$context.authorizer.claims` wird null (0) zurückgegeben. | | \$1context.authorizer.principalId | Die ID des Prinzipalbenutzers in Verbindung mit dem Token, das vom Client gesendet und von einem API Gateway-Lambda-Genehmiger (früher als benutzerdefinierter Genehmiger bekannt) zurückgegeben wurde. Weitere Informationen finden Sie unter [API Gateway-Lambda-Genehmiger verwenden](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.property | Der in einer Zeichenfolge umgewandelte Wert des angegebenen Schlüssel-Wert-Paares der `context`-Zuordnung, der von einer API Gateway Lambda-Genehmigerfunktion zurückgegeben wird. Angenommen, der Genehmiger gibt folgende `context`-Zuweisung zurück: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
Ein Aufruf von `$context.authorizer.key` gibt die Zeichenfolge `"value"` zurück, ein Aufruf von `$context.authorizer.numKey` gibt die Zeichenfolge `"1"` zurück und ein Aufruf von `$context.authorizer.boolKey` gibt die Zeichenfolge `"true"` zurück. Denn *property* das einzige unterstützte Sonderzeichen ist der `(_)` Unterstrich. Weitere Informationen finden Sie unter [API Gateway-Lambda-Genehmiger verwenden](apigateway-use-lambda-authorizer.md). | | \$1context.awsEndpointRequestId | Die Anforderungs-ID des AWS Endpunkts. | | \$1context.deploymentId | Die ID der API-Bereitstellung | | \$1context.domainName | Der zum Aufrufen der API verwendete vollständige Domänennamen. Dieser Wert sollte mit dem für den eingehenden `Host`-Header übereinstimmen. | | \$1context.domainPrefix | Das erste Label der `$context.domainName`. | | \$1context.error.message | Eine Zeichenfolge, die eine API Gateway-Fehlermeldung enthält. Diese Variable kann nur für die einfache Variablenersetzung in einer [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)Body-Mapping-Vorlage, die nicht von der Velocity Template Language-Engine verarbeitet wird, und für die Zugriffsprotokollierung verwendet werden. Weitere Informationen erhalten Sie unter [Überwachen Sie die WebSocket API-Ausführung mit CloudWatch Metriken](apigateway-websocket-api-logging.md) und [Einrichten von Gateway-Antworten, um Fehlerantworten anzupassen](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.messageString | Die Wert von \$1context.error.message in Anführungszeichen, d. h. "\$1context.error.message". | | \$1context.error.responseType | [Ein Typ von. [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) Diese Variable kann nur für die einfache Variablenersetzung in einer [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)Body-Mapping-Vorlage, die nicht von der Velocity Template Language-Engine verarbeitet wird, und für die Zugriffsprotokollierung verwendet werden. Weitere Informationen erhalten Sie unter [Überwachen Sie die WebSocket API-Ausführung mit CloudWatch Metriken](apigateway-websocket-api-logging.md) und [Einrichten von Gateway-Antworten, um Fehlerantworten anzupassen](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.validationErrorString | Eine Zeichenfolge mit einer detaillierten Validierungs-Fehlermeldung. | | \$1context.extendedRequestId | Die erweiterte ID, die API Gateway generiert und der API-Anfrage zuweist. Die erweiterte Anforderungs-ID enthält zusätzliche nützliche Informationen für Debugging und Fehlerbehebung. | | \$1context.httpMethod | Die verwendete HTTP-Methode. Gültige Werte sind: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` und `PUT`. | | \$1context.identity.accountId | Die der AWS Anfrage zugeordnete Konto-ID. | | \$1context.identity.apiKey | Bei API-Methoden, für die ein API-Schlüssel erforderlich ist, ist diese Variable der API-Schlüssel für die Methodenanforderung. Bei Methoden, für die kein API-Schlüssel erforderlich ist, ist diese Variable nichtig. Weitere Informationen finden Sie unter [Nutzungspläne und API-Schlüssel für REST APIs in API Gateway](api-gateway-api-usage-plans.md). | | \$1context.identity.apiKeyId | Die API-Schlüssel-ID für die API-Anforderung, falls ein API-Schlüssel erforderlich ist. | | \$1context.identity.caller | Die Hauptkennung des Aufrufers, der die Anforderung signiert hat. Wird für Ressourcen unterstützt, die die IAM-Autorisierung verwenden. | | \$1context.identity.cognitoAuthenticationProvider | Eine durch Komma getrennte Liste aller Amazon-Cognito-Authentifizierungsanbieter, die vom anfordernden Aufrufer verwendet werden. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Zum Beispiel für eine Identität aus einem Amazon Cognito-Benutzerpool, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Weitere Informationen zu verfügbaren Amazon-Cognito-Authentifizierungsanbietern finden Sie unter [Verbundidentitäten verwenden](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) im *Amazon-Cognito-Entwicklerhandbuch*. | | \$1context.identity.cognitoAuthenticationType | Der Amazon Cognito-Authentifizierungstyp des Aufrufers, der den Anfrage erstellt hat. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Mögliche Werte sind `authenticated` für authentifizierte Identitäten und `unauthenticated` für nicht authentifizierte Identitäten. | | \$1context.identity.cognitoIdentityId | Die Amazon Cognito Identitäts-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. | | \$1context.identity.cognitoIdentityPoolId | Die Amazon Cognito Identitätspool-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. | | \$1context.identity.principalOrgId | Die [AWS -Organisations-ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). | | \$1context.identity.sourceIp | Die Quell-IP-Adresse der TCP-Verbindung, von der die Anforderung an den API-Gateway-Endpunkt gesendet wird. | | \$1context.identity.clientCert.clientCertPem | Das PEM-codierte Clientzertifikat, das der Client während der gegenseitigen TLS-Authentifizierung präsentiert hat. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. | | \$1context.identity.clientCert.subjectDN | Der Distinguished Name des Zertifikatantragsstellers, den ein Client präsentiert. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domain-Namens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. | | \$1context.identity.clientCert.issuerDN | Der Distinguished Name des Ausstellers des Zertifikats, das ein Client präsentiert. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. | | \$1context.identity.clientCert.serialNumber | Die Seriennummer des Zertifikats. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. | | \$1context.identity.clientCert.validity.notBefore | Das Datum, vor dem das Zertifikat ungültig ist. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. | | \$1context.identity.clientCert.validity.notAfter | Das Datum, nach dem das Zertifikat ungültig ist. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. | | \$1context.identity.vpcId | Die VPC-ID der VPC, deren Anforderung an den API-Gateway-Endpunkt gesendet wird. | | \$1context.identity.vpceId | Die VPC-Endpunkt-ID des VPC-Endpunkts, dessen Anforderung an den API-Gateway-Endpunkt gesendet wird. Diese ist nur vorhanden, wenn Ihre API privat ist. | | \$1context.identity.user | Die Hauptkennung des Benutzers, der für den Ressourcenzugriff autorisiert wird. Wird für Ressourcen unterstützt, die die IAM-Autorisierung verwenden. | | \$1context.identity.userAgent | Die [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)-Kopfzeile des API-Aufrufers. | | \$1context.identity.userArn | Der ARN (Amazon Resource Name) des tatsächlichen Benutzers nach der Authentifizierung. Weitere Informationen finden Sie unter [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). | | \$1context.isCanaryRequest | Gibt `true` zurück, wenn die Anforderung an den Canary gerichtet war oder `false`, wenn die Anforderung nicht an den Canary ging. Dies ist nur vorhanden, wenn Sie einen Canary aktiviert haben. | | \$1context.path | Der Anforderungspfad. Bei einer Nicht-Proxy-Anforderungs-URL von https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child lautet der \$1context.path-Wert beispielsweise /\$1stage\$1/root/child. | | \$1context.protocol | Das Anforderungsprotokoll ist z. B, HTTP/1.1. API Gateway APIs kann HTTP/2-Anfragen akzeptieren, aber API Gateway sendet Anfragen über HTTP/1.1 an Backend-Integrationen. Infolgedessen wird das Anforderungsprotokoll als HTTP/1.1 protokolliert, auch wenn ein Client eine Anfrage sendet, die HTTP/2 verwendet. | | \$1context.requestId | Eine ID für die Anforderung. Clients können diese Anforderungs-ID überschreiben. Verwenden von `$context.extendedRequestId` für eine eindeutige Anforderungs-ID, die API Gateway generiert. | | \$1context.requestOverride.header.header\$1name | Der Anforderungs-Header-Override. Wenn dieser Parameter definiert ist, enthält er die Header, die statt der **HTTP Header**, die im Bereich **Integrationsanforderung** definiert sind, verwendet werden sollen. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.path.path\$1name | Der Anforderungspfad-Override. Wenn dieser Parameter definiert ist, enthält er den Anforderungspfad, der statt der **URL-Pfadparameter**, die im Bereich **Integrationsanforderung** definiert sind, verwendet werden soll. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.querystring.querystring\$1name | Der Abfragestring-Override. Wenn dieser Parameter definiert ist, enthält er die Abfragestrings, die statt der **URL-Abfragestring-Parameter**, die im Bereich **Integrationsanforderung** definiert sind, verwendet werden sollen. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.header.header\$1name | Der Antwort-Header-Override. Wenn dieser Parameter definiert ist, enthält er den Header, der anstelle des Antwort-Headers, der als Standard-Mapping im Bereich Integrationsantwort definiert ist, ausgegeben werden soll. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.status | Der Antwortstatuscode-Override. Wenn dieser Parameter definiert ist, enthält er den Statuscode, der anstelle des Methoden-Antwortstatus, der als Standard-Mapping im Bereich Integrationsantwort definiert ist, ausgegeben werden soll. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestTime | Die Anforderungszeit im [CLF](https://httpd.apache.org/docs/current/logs.html#common)-Format (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | Die Anforderungszeit im [Epoch](https://en.wikipedia.org/wiki/Unix_time)-Format in Millisekunden. | | \$1context.resourceId | Der Bezeichner, den API Gateway Ihrer Ressource zuweist. | | \$1context.resourcePath | Der Pfad zu Ihrer Ressource. Beim Nicht-Proxy-Anforderungs-URI von `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` lautet der `$context.resourcePath`-Wert beispielsweise `/root/child`. Weitere Informationen finden Sie unter [Tutorial: REST-API mit HTTP-API ohne Proxy-Integration erstellen](api-gateway-create-api-step-by-step.md). | | \$1context.stage | Die Bereitstellungsstufe der API-Anforderung (z. B. `Beta` oder `Prod`). | | \$1context.wafResponseCode | Die von [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) empfangene Antwort: `WAF_ALLOW` oder `WAF_BLOCK`. Wird nicht festgelegt, wenn die Stufe mit keiner Web-ACL verknüpft ist. Weitere Informationen finden Sie unter [Verwenden Sie AWS WAF , um Ihren REST APIs in API Gateway zu schützen](apigateway-control-access-aws-waf.md). | | \$1context.webaclArn | Vollständiger ARN der Web-Zugriffskontrollliste (Web-ACL), anhand deren entschieden wird, ob die Anforderung zugelassen oder blockiert wird. Wird nicht festgelegt, wenn die Stufe mit keiner Web-ACL verknüpft ist. Weitere Informationen finden Sie unter [Verwenden Sie AWS WAF , um Ihren REST APIs in API Gateway zu schützen](apigateway-control-access-aws-waf.md). | ## Eingabevariablen Sie können die folgenden `$input`-Variablen, bei denen die Groß- und Kleinschreibung beachtet werden muss, verwenden, um auf die Nutzdaten der Methodenanforderung und die Parameter der Methodenanforderung zu verweisen. Die folgenden Funktionen sind verfügbar: | Variable und Funktion | Beschreibung | | --- | --- | | \$1input.body | Gibt die Nutzlast der Raw-Anforderung als Zeichenfolge zurück. Sie können `$input.body` verwenden, um ganze Fließkommazahlen beizubehalten, z. B. `10.00`. | | \$1input.json(x) | Diese Funktion wertet einen JSONPath Ausdruck aus und gibt die Ergebnisse als JSON-Zeichenfolge zurück. Beispielsweise gibt `$input.json('$.pets')` eine JSON-Zeichenfolge zurück, die die `pets`-Struktur abbildet. Weitere Informationen zu JSONPath, finden Sie unter [JSONPath](https://goessner.net/articles/JsonPath/)oder [JSONPath für Java](https://github.com/json-path/JsonPath). | | \$1input.params() | Gibt die Zuweisung aller Anforderungsparameter zurück. Wir empfehlen, das Ergebnis `$util.escapeJavaScript` zu bereinigen, um einen möglichen Injektionsangriff zu vermeiden. Um die vollständige Kontrolle über die Bereinigung von Anfragen zu erhalten, verwenden Sie eine Proxy-Integration ohne Vorlage und übernehmen Sie die Anforderungsbereinigung in Ihrer Integration. | | \$1input.params(x) | Gibt aus der Zeichenfolge eines Parameternamens `x` aus dem Pfad, der Abfragezeichenfolge oder dem Header-Wert (in dieser Reihenfolge) den Wert eines Methodenanforderungs-Parameters zurück. Wir empfehlen, den Parameter `$util.escapeJavaScript` zu bereinigen, um einen möglichen Injektionsangriff zu vermeiden. Um die vollständige Kontrolle über die Parameterbereinigung zu erhalten, verwenden Sie eine Proxy-Integration ohne Vorlage und übernehmen Sie die Anforderungsbereinigung in Ihrer Integration. | | \$1input.path(x) | Nimmt einen JSONPath Ausdruck string (`x`) und gibt eine JSON-Objektdarstellung des Ergebnisses zurück. Dies ermöglicht einen nativen Zugriff auf Elemente der Nutzlast in [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) und deren Bearbeitung. Beispiel: Der Ausdruck `$input.path('$.pets')` könnte das folgende Objekt zurückgeben: 
[
  { 
    "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()` gibt `"3"` zurück. Weitere Informationen zu JSONPath Java finden Sie unter [JSONPath](https://goessner.net/articles/JsonPath/)oder [JSONPath für Java](https://github.com/json-path/JsonPath). | ## Stufenvariablen Sie können die folgenden Stufenvariablen als Platzhalter für ARNs und URLs in Methodenintegrationen verwenden. Weitere Informationen finden Sie unter [Stufenvariablen für eine REST-API in API Gateway verwenden](stage-variables.md). | Syntax | Description | | --- | --- | | \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'] oder \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*steht für einen Stufenvariablennamen. | ## Util-Variablen Sie können die folgenden `$util`-Variablen verwenden, bei denen Groß- und Kleinschreibung beachtet werden muss, um Dienstprogrammfunktionen für Zuweisungsvorlagen zu verwenden. Sofern nicht anders angegeben, wird UTF-8 als Standardzeichensatz genutzt. | Funktion | Description | | --- | --- | | \$1util.escapeJavaScript() | Escapiert die Zeichen in einer Zeichenfolge mithilfe von JavaScript Zeichenfolgenregeln. Mit dieser Funktion werden alle einfachen Anführungszeichen (`'`) durch Escape-Zeichen (`\'`) geschützt. Allerdings sind diese durch Escape-Zeichen geschützten einfachen Anführungszeichen in JSON nicht zulässig. Sofern die Ausgabe dieser Funktion in einer JSON-Eigenschaft verwendet werden soll, müssen alle einfachen Anführungszeichen, die durch Escape-Zeichen geschützt sind (`\'`), wieder in reguläre einfache Anführungszeichen (`'`) geändert werden. Das wird im folgenden Beispiel veranschaulicht: 
 "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"
| | \$1util.parseJson() | Erhält das "stringify"-JSON-Objekt und gibt eine Objektdarstellung des Ergebnisses zurück. Mit dem Ergebnis dieser Funktion können Sie Elemente der Nutzlast, die in Apache Velocity Template Language (VTL) sind, aufrufen und bearbeiten. Angenommen, Sie haben folgende Nutzlast: 
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}
Und verwenden die folgende Mapping-Vorlage: 
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Dann erhalten Sie die folgende Ausgabe: 
{
   "errorMessageObjKey2ArrVal" : 1
}
| | \$1util.urlEncode() | Konvertiert eine Zeichenfolge in das Format „application/x-www-form-urlencoded“. | | \$1util.urlDecode() | Dekodiert eine Zeichenfolge „application/x-www-form-urlencoded“. | | \$1util.base64Encode() | Codiert die Daten in eine base64-verschlüsselte Zeichenfolge. | | \$1util.base64Decode() | Decodiert die Daten einer base64-verschlüsselten Zeichenfolge. |