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.
# 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\":{}}"}
```