Beispiel 1: Überschreiben des Statuscodes basierend auf dem Body der Integration Beispiel 2: Überschreiben des Anfrage-Headers und Erstellen neuer Header

Ü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 verwendet, um den Statuscode basierend auf dem Body der Integrationsantwort zu überschreiben.

AWS Management Console

Überschreiben eines Statuscodes basierend auf dem Body der Integrationsantwort

Melden Sie sich bei der API Gateway Gateway-Konsole unter https://console.aws.amazon.com/apigatewayan.
Wählen Sie Create API (API erstellen) aus.
Wählen Sie unter REST-API die Option Erstellen aus.
Wählen Sie unter API-Details die Option Beispiel-API aus.
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.
Wählen Sie in der Ressourcen-Struktur unter GET die /{petId}-Methode aus.
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.
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.
Klicken Sie auf der Registerkarte Integrationsantwort unter Standard - Antwort auf Bearbeiten.
Wählen Sie Zuordnungsvorlagen aus.
Wählen Sie Add mapping template.
Geben Sie für Content type (Inhaltstyp) application/json ein.
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.
Wählen Sie Speichern.
Wählen Sie die Registerkarte Test.
Geben Sie als petid -1 ein.
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.

AWS CloudFormation

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


AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Body: 
        openapi: 3.0.1
        info:
          title: 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, um den Anfrage-Header zu überschreiben und neue Header zu erstellen.

AWS Management Console

So überschreiben Sie einen Methodenanforderungs-Header indem Sie einen neuen Header erstellen

Melden Sie sich bei der API Gateway Gateway-Konsole unter https://console.aws.amazon.com/apigatewayan.
Wählen Sie die Beispiel-API aus, die Sie im vorherigen Tutorial erstellt haben. Der Name der API sollte lauten. PetStore
Wählen Sie in der Ressourcen-Struktur unter GET die /pet-Methode aus.
Klicken Sie auf der Registerkarte Methodenanfrage unter Methodenanfrage-Einstellungen auf Bearbeiten.
Wählen Sie HTTP Request Headers (HTTP-Anforderungs-Header) und dann Add header (Header hinzufügen) aus.
Geben Sie unter Name header1 ein.
Klicken Sie auf Header hinzufügen und erstellen Sie dann einen zweiten Header namens header2.
Wählen Sie Speichern aus.

Kombinieren Sie jetzt diese Header mithilfe einer Zuweisungsvorlage zu einem einzigen Header-Wert.
Klicken Sie auf der Registerkarte Integrationsanfrage unter Einstellungen für Integrationsanfragen auf Bearbeiten.
Wählen Sie für Anforderungstext-Pass-Through die Option Wenn keine Vorlagen definiert sind (empfohlen) aus.
Wählen Sie Vorlagen zuordnen aus und gehen Sie dann wie folgt vor:
1. Wählen Sie Add mapping template.
2. Geben Sie für Content type (Inhaltstyp) application/json ein.
3. 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.
Wählen Sie Speichern.
Wählen Sie die Registerkarte Test.
Kopieren Sie unter Headers den folgenden Code:
```
header1:header1Val
header2:header2Val
```

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}

AWS CloudFormation

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


AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Body: 
        openapi: 3.0.1
        info:
          title: 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.

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

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

Dokumentkonventionen

Zusätzliches Beispiel für Zuweisungsvorlagen

Tutorial: Ändern Sie die Integrationsanfrage und die Antwort für Integrationen zu Diensten AWS