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.
# Ü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).