Einrichten von Datentransformationen in API Gateway - Amazon API Gateway

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.

Einrichten von Datentransformationen in API Gateway

In diesem Abschnitt wird gezeigt, wie Sie Mapping-Vorlagen einrichten, um Integrationsanfragen und -antworten mithilfe der Konsole und der AWS CLI zu transformieren.

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 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 PetStore Vorlage für eine Zuordnung 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. AWS CloudFormation 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 AWS CloudFormation
  1. Öffnen Sie die AWS CloudFormation Konsole unter https://console.aws.amazon.com/cloudformation.

  2. Wählen Sie Stack erstellen und dann Mit neuen Ressourcen (Standard) aus.

  3. Wählen Sie unter Vorlage angeben die Option Vorlagendatei hochladen aus.

  4. Wählen Sie die Vorlage aus, die Sie heruntergeladen haben.

  5. Wählen Sie Weiter aus.

  6. Geben Sie für Stack-Name die Zeichenfolge data-transformation-tutorial-console ein und klicken Sie auf Weiter.

  7. Wählen Sie in Stack-Optionen konfigurieren die Option Weiter aus.

  8. Bestätigen Sie bei Capabilities, dass IAM-Ressourcen in Ihrem Konto erstellt werden AWS CloudFormation können.

  9. Wählen Sie Absenden aus.

AWS CloudFormation stellt die in der Vorlage angegebenen Ressourcen bereit. Die Bereitstellung der Ressourcen kann einige Minuten dauern. Wenn der Status Ihres AWS CloudFormation Stacks CREATE_COMPLETE 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 AWS CloudFormation Stacks für data-transformation-tutorial-console die physische ID Ihrer API aus.

  2. Klicken Sie im Hauptnavigationsbereich auf Ressourcen und wählen Sie dann die GET-Methode in der Ressourcenstruktur aus.

  3. 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 PetStore Vorlage für eine Zuordnung.

So transformieren Sie die GET-Integrationsantwort
  1. Klicken Sie auf die Registerkarte Integrationsantwort.

    Derzeit sind keine Zuweisungsvorlagen definiert, sodass die Integrationsantwort nicht transformiert wird.

  2. Klicken Sie unter Standard - Antwort auf Bearbeiten.

  3. 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($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.

  2. Wählen Sie die Registerkarte Integrationsanfrage aus und klicken Sie dann unter Einstellungen für Integrationsanforderungen auf Bearbeiten.

    Die AWS 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 AWS 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.

  3. Für Text-Passthrough anfordern wählen Sie Nie aus.

    Dies bedeutet, dass die API Daten mit Inhaltstypen ablehnt, die keine Zuweisungsvorlage haben.

  4. Wählen Sie Zuordnungsvorlagen aus.

  5. Der Inhaltstyp ist auf application/json gesetzt. Das bedeutet, dass alle Inhaltstypen, die nicht „application/json“ sind, von der API abgelehnt werden. Weitere Informationen zu Integrations-Passthrough-Verhaltensweisen finden Sie unter Integrations-Pass-Through-Verhalten.

  6. 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 idtype 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.

  7. 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 AWS CloudFormation hat eine leere Methode und eine leere Integrationsantwort erstellt. Sie werden diese Antwort bearbeiten, um weitere Informationen bereitzustellen. Weitere Informationen zum Bearbeiten von Antworten finden Sie unter Daten-Mapping-Referenz für Amazon API Gateway-API-Anfragen und Antworten.

  1. Klicken Sie auf der Registerkarte Integrationsantwort unter Standard - Antwort auf Bearbeiten.

  2. Wählen Sie Zuordnungsvorlagen aus und klicken Sie dann auf Zuordnungsvorlage hinzufügen.

  3. Geben Sie für Inhaltstyp application/json ein.

  4. 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  $contextVariablen für Datenmodelle, Autorisierer, Zuordnungsvorlagen und Zugriffsprotokollierung CloudWatch .

  5. 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" }
  2. Wählen Sie Test aus.

    Die Ausgabe sollte Ihre Erfolgsmeldung enthalten.

    Sie können die DynamoDB-Konsole unter https://console.aws.amazon.com/dynamodb/ öffnen, um zu überprüfen, ob sich das Beispielelement in Ihrer Tabelle befindet.

Um einen AWS CloudFormation Stapel zu löschen
  1. Öffnen Sie die AWS CloudFormation Konsole unter https://console.aws.amazon.com/cloudformation.

  2. Wählen Sie Ihren AWS CloudFormation Stack aus.

  3. 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 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 PetStore Vorlage für eine Zuordnung.

  • 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 AWS CloudFormation

Laden Sie die Vorlage zur App-Erstellung für AWS CloudFormation herunter und entpacken Sie sie.

Um die folgenden Schritte durchzuführen, benötigen Sie die AWS Command Line Interface (AWS CLI) Version 2.

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. 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 AWS 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
  2. AWS 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 AWS CloudFormation Stacks zu überprüfen.

    aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
  3. Wenn der Status Ihres AWS CloudFormation Stacks lautetStackStatus: "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 sind. 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 PetStore Vorlage für eine Zuordnung.

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 die rest-api-idund 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. AWS CloudFormation

  2. 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\")} }}"}'
  3. 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
  4. 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 AWS CloudFormation Stapel zu löschen
  • Verwenden Sie den folgenden Befehl, um Ihre AWS CloudFormation Ressourcen zu löschen.

    aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli

AWS CloudFormation Vorlage für die Datentransformation abgeschlossen

Das folgende Beispiel ist eine fertige AWS 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 PetStore Vorlage für eine Zuordnung transformiert.

  • Die POST-Methode ermöglicht es dem Benutzer, mithilfe einer Zuweisungsvorlage die POST-Aktion zu einer DynamoDB-Tabelle durchzuführen.

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

Nächste Schritte

Informationen zu komplexeren Mapping-Vorlagen finden Sie in den folgenden Beispielen: