Wie verwende ich API Gateway als Proxy für einen anderen AWS-Service?

Lesedauer: 10 Minute

Ich möchte Amazon API Gateway als Proxy für einen anderen AWS-Service verwenden und andere Services in API Gateway integrieren.

Kurzbeschreibung

AWS-Service-APIs sind im Wesentlichen REST-APIs, an die Sie eine HTTPS-Anfrage stellen können. Sie können zahlreiche AWS-Services in API Gateway integrieren, die Einrichtung und Zuordnung variieren jedoch je nach Service-API.

Um einen anderen Dienst in API Gateway zu integrieren, erstellen Sie eine HTTPS-Anfrage von API Gateway an die Service-API. Auf diese Weise werden alle Anforderungsparameter korrekt zugeordnet.

In diesem Artikel wird ein Beispiel für die Integration der Publish-API von Amazon Simple Notification Service (Amazon SNS) mit API Gateway beschrieben. Verwenden Sie dieses Beispiel als grobe Anleitung für die Integration anderer Dienste.

Lösung

Hinweis: Wenn Sie beim Ausführen von Befehlen der AWS Command Line Interface (AWS CLI) Fehler erhalten, stellen Sie sicher, dass Sie die neueste AWS-CLI-Version verwenden.

Einrichten der erforderlichen Tools und Ressourcen

Konfigurieren Sie Ihre Umgebung und erstellen Sie alle AWS-Ressourcen, die für Ihren Anwendungsfall erforderlich sind. Gehen Sie für das Amazon-SNS-Beispiel-Setup wie folgt vor:

Installieren Sie die AWS-CLI.
Erstellen Sie ein Amazon-SNS-Thema. Notieren Sie sich den Amazon-Ressourcennamen (ARN) des Themas. Verwenden Sie diese Informationen im nächsten Schritt und später in diesem Setup.
Erstellen Sie ein Abonnement für das Thema.
Öffnen Sie die AWS Identity and Access Management (IAM)-Konsole und erstellen Sie dann eine AWS-Service-Proxy-Ausführungsrolle. Notieren Sie sich den ARN der Rolle für die spätere Verwendung im Setup. Diese IAM-Rolle erteilt API Gateway als vertrauenswürdige Entität die Berechtigung, den Dienst zu übernehmen und die API-Aktion auszuführen, die Sie integrieren. Lassen Sie für das Amazon-SNS-Beispiel-Setup die Aktion sns:Publish zu. Weitere Informationen finden Sie unter API-Gateway-Berechtigungsmodell für den Aufruf einer API.
Erstellen Sie eine API-Gateway-REST-API mit einer Test-Ressource. Weitere Informationen und Beispiele finden Sie in den Amazon-API-Gateway-Tutorials und -Workshops.
**Hinweis:**Importieren Sie optional die REST-API mithilfe der folgenden OpenAPI-2.0-Beispieldefinition (Swagger). Mit dieser Option werden die Einstellungen für das Amazon-SNS-Beispiel-Setup vorkonfiguriert. Achten Sie darauf, arn:aws:iam::account-id:role/apigateway-sns-role durch den ARN Ihrer IAM-Rolle zu ersetzen. Ersetzen Sie die Region durch die AWS-Region, in der Sie Ihre REST-API erstellen möchten.

{
  "swagger": "2.0",
  "info": {
    "version": "2019-10-09T14:10:24Z",
    "title": "aws-service-integration"
  },
  "basePath": "/dev",
  "schemes": [
    "https"
  ],
  "paths": {
    "/test": {
      "post": {
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "Message",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "TopicArn",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "credentials": "arn:aws:iam::account-id:role/apigateway-sns-role",
          "uri": "arn:aws:apigateway:region:sns:action/Publish",
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestParameters": {
            "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn",
            "integration.request.querystring.Message": "method.request.querystring.Message"
          },
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws"
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object",
      "title": "Empty Schema"
    }
  }
}

Abrufen einer beispielhaften HTTPS-Anfrage

Eine beispielhafte HTTPS-Anfrage von der Service-API, die Sie integrieren, kann Ihnen helfen, die Anforderungsparameter in API Gateway korrekt zuzuordnen. Gehen Sie wie folgt vor, um eine beispielhafte HTTPS-Anfrage zu erhalten:

Beispiele finden Sie in der API-Dokumentation. Für die Publish-API von Amazon SNS finden Sie in der API-Referenz des Dienstes eine Beispielanfrage:

https://sns.us-west-2.amazonaws.com/?Action=Publish
&TargetArn=arn%3Aaws%3Asns%3Aus-west-2%3A803981987763%3Aendpoint%2FAPNS_SANDBOX%2Fpushapp%2F98e9ced9-f136-3893-9d60-776547eafebb
&Message=%7B%22default%22%3A%22This+is+the+default+Message%22%2C%22APNS_SANDBOX%22%3A%22%7B+%5C%22aps%5C%22+%3A+%7B+%5C%22alert%5C%22+%3A+%5C%22You+have+got+email.%5C%22%2C+%5C%22badge%5C%22+%3A+9%2C%5C%22sound%5C%22+%3A%5C%22default%5C%22%7D%7D%22%7D
&Version=2010-03-31
&AUTHPARAMS

- oder -

Generieren Sie sie aus einem API-Aufruf. Verwenden Sie die AWS-CLI, um die Service-API aufzurufen, und analysieren Sie dann die Ausgabe. Ermitteln Sie den entsprechenden AWS-CLI-Befehl für die Service-API, die Sie integrieren, und führen Sie dann eine Testanfrage mit der Option**--debug** aus.

Tipp: In der AWS-CLI-Befehlsreferenz finden Sie den entsprechenden AWS-CLI-Befehl.

Führen Sie für das Amazon-SNS-Beispiel-Setup diesen Befehl aus:

Hinweis: Ersetzen Sie arn:aws:sns:us-east-1:123456789012:test durch den ARN Ihres Amazon-SNS-Themas.

$ aws sns publish --topic-arn arn:aws:sns:us-east-1:123456789012:test --message "hi" --debug

Die Befehlsausgabe enthält die HTTPS-Anfrage und die übergebenen Header. Hier ist ein Beispiel dafür, worauf Sie achten sollten:

2018-11-22 11:56:39,647 - MainThread - botocore.client - DEBUG - Registering retry handlers for service: sns
2018-11-22 11:56:39,648 - MainThread - botocore.hooks - DEBUG - Event before-parameter-build.sns.Publish: calling handler <function generate_idempotent_uuid at 0x11093d320>
2018-11-22 11:56:39,649 - MainThread - botocore.endpoint - DEBUG - Making request for OperationModel(name=Publish) (verify_ssl=True) with params: {'body': {'Action': u'Publish', u'Message': u'hello', 'Version': u'2010-03-31', u'TopicArn': u'arn:aws:sns:us-east-1:123456789012:test'}, 'url': u'https://sns.us-east-1.amazonaws.com/', 'headers': {'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8', 'User-Agent': 'aws-cli/1.15.74 Python/2.7.14 Darwin/16.7.0 botocore/1.9.23'}, 'context': {'auth_type': None, 'client_region': 'us-east-1', 'has_streaming_input': False, 'client_config': <botocore.config.Config object at 0x1118437d0>}, 'query_string': '', 'url_path': '/', 'method': u'POST'}
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event request-created.sns.Publish: calling handler <bound method RequestSigner.handler of <botocore.signers.RequestSigner object at 0x111843750>>
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event choose-signer.sns.Publish: calling handler <function set_operation_specific_signer at 0x11093d230>
2018-11-22 11:56:39,650 - MainThread - botocore.auth - DEBUG - Calculating signature using v4 auth.
2018-11-22 11:56:39,651 - MainThread - botocore.auth - DEBUG - CanonicalRequest:
POST
/

content-type:application/x-www-form-urlencoded; charset=utf-8
host:sns.us-east-1.amazonaws.com
x-amz-date:20181122T062639Z

content-type;host;x-amz-date

In diesem Beispiel wird die Anfrage als POST-HTTP-Methode gesendet.

Erstellen einer Methode für Ihre API-Gateway-API

Wählen Sie in der API-Gateway-Konsole im Bereich APIs den Namen Ihrer API aus.
Wählen Sie im Bereich Ressourcen eine Ressource aus. Wählen Sie für das Amazon-SNS-Beispiel-Setup die Testressource aus, die Sie erstellt haben.
Wählen Sie Aktionen und dann Methode erstellen aus.
Wählen Sie in der Dropdown-Liste die Methode aus, die von Ihrer Service-API in der Beispiel-HTTPS-Anfrage verwendet wird. (Wählen Sie für das Amazon-SNS-Beispiel-Setup POST aus.) Wählen Sie dann das Häkchensymbol aus.
Gehen Sie im Setup-Bereich wie folgt vor:
Wählen Sie für Integrationstyp AWS Service aus.
Wählen Sie für die AWS-Region die AWS-Region der Ressource aus, die mit der Service-API verknüpft ist, die Sie integrieren. Wählen Sie für das Amazon-SNS-Beispiel-Setup die Region Ihres SNS-Themas aus.
Wählen Sie für AWS Service den Service aus, den Sie in API Gateway integrieren. Zum Beispiel Simple Notification Service (SNS).
(Optional) Geben Sie für AWS-Subdomain die vom AWS-Service verwendete Subdomain ein. Überprüfen Sie die Verfügbarkeit einer Subdomain in der Dokumentation des Dienstes. Lassen Sie das Feld für das Amazon-SNS-Beispiel-Setup leer.
Wählen Sie für die HTTP-Methode die Methode aus, die der AWS-Service-API entspricht, die Sie integrieren. Wählen Sie für das Amazon-SNS-Beispiel-Setup POST aus.
Wenn es sich bei der Service-API, die Sie integrieren, um eine unterstützte Aktion handelt, wählen Sie unter Aktionstyp die Option Aktionsnamen verwenden aus. In der API-Referenz des Dienstes finden Sie eine Liste der unterstützten Aktionen. Für Amazon SNS, siehe Aktionen.
Geben Sie für Aktion den Namen der Service-API ein. Geben Sie für das Amazon-SNS-Beispiel-Setup Veröffentlichen ein.
-oder-
Wenn die AWS-Service-API einen Ressourcenpfad in Ihrer Anforderung erwartet, wählen Sie für Aktionstyp die Option Pfadüberschreibung verwenden aus. Geben Sie beispielsweise für die ListLexicons-API von Amazon Polly /v1/lexicons für Pfadüberschreibung (optional) ein.
Geben Sie für die Ausführungsrolle den ARN der IAM-Rolle ein, die Sie erstellt haben.
(Optional) Nehmen Sie für die Inhaltsverwaltung und die Verwendung des Standard-Timeouts die Änderungen vor, die für Ihren Anwendungsfall erforderlich sind. Ändern Sie diese Einstellungen für das Amazon-SNS-Beispiel-Setup nicht.
Wählen Sie Speichern aus.

Erstellen von Parametern für die Methodenanfrage

Ermitteln Sie die erforderlichen und optionalen Anforderungsparameter für die Service-API, die Sie integrieren. Informationen zur Identifizierung dieser Parameter finden Sie in der Beispiel-HTTPS-Anfrage, die Sie zuvor erhalten haben, oder in der API-Referenz für die Service-API. Siehe beispielsweise Veröffentlichen.

Wählen Sie in der API-Gateway-Konsole, im Bereich Methodenausführung für die Methode Ihrer API-Gateway-API die Option Methodenanforderung aus.
(Optional) Wählen Sie im Bereich Methodenanforderung für Anforderungsprüfer einen Anforderungsprüfer, einen Text und Header aus, wenn Sie die Parameter der Abfragezeichenfolge überprüfen möchten.
Erweitern Sie die URL-Abfragezeichenfolgen-Parameter.
Wählen Sie Abfragezeichenfolge hinzufügen aus.
Geben Sie unter Name den Namen eines Anforderungsparameters für die Service-API ein, die Sie integrieren.
Wählen Sie das Häkchensymbol aus (Neue Abfragezeichenfolge erstellen).
Wenn der Parameter erforderlich ist, aktivieren Sie das Kontrollkästchen unter Erforderlich.
Wiederholen Sie die Schritte 4 bis 7 für alle Anforderungsparameter, die Sie einbeziehen möchten. Erstellen Sie für das Amazon-SNS-Beispiel-Setup einen Parameter mit dem Namen T****opicArn und einen weiteren mit dem Namen Message.

Weitere Informationen finden Sie unter Einrichten einer Methode mithilfe der API-Gateway-Konsole.

Hinweis: Für einige Service-APIs müssen Sie zusätzlich zu den erforderlichen Parametern die erforderlichen Header und einen Text in der Integrationsanfrage senden. Sie können die Header und den Text im Bereich Integrationsanforderung unter HTTP-Anforderungs-Header und Anforderungstext erstellen.

Wenn Sie beispielsweise die ListCollections-API von Amazon Rekognition integrieren, erstellen Sie den Header X-Amz-Target: RekognitionService.ListCollections. Die Anfrage sieht folgendermaßen aus:

POST https://rekognition.us-west-2.amazonaws.com/ HTTP/1.1
    Host: rekognition.us-west-2.amazonaws.com
    Accept-Encoding: identity
    Content-Length: 2
    X-Amz-Target: RekognitionService.ListCollections
    X-Amz-Date: 20170105T155800Z
    User-Agent: aws-cli/1.11.25 Python/2.7.9 Windows/8 botocore/1.4.82
    Content-Type: application/x-amz-json-1.1
    Authorization: AWS4-HMAC-SHA256 Credential=XXXXXXXX/20170105/us-west-2/rekognition/aws4_request,
      SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=XXXXXXXX

    {}

Wenn Sie die SendMessage-API von Amazon Simple Queue Service (Amazon SQS) integrieren, ordnen Sie den Anforderungstext mithilfe des Mapping-Ausdrucks method.request.body.JSONPath_EXPRESSION zu. (Ersetzen Sie JSONPath_EXPRESSION durch einen JSONPath-Ausdruck für ein JSON-Feld im Hauptteil der Anfrage.) In diesem Beispiel sieht eine Anfrage etwa wie folgt aus:

{'url_path': '/', 'query_string': '', 'method': 'POST',
'headers': {'Content-Type': 'application/x-www-form-urlencoded;
charset=utf-8', 'User-Agent': 'aws-cli/1.16.81 Python/3.6.5 Darwin/18.7.0 botocore/1.12.183'},
'body': {'Action': 'SendMessage', 'Version': '2012-11-05', 'QueueUrl': 'https://sqs.ap-southeast-2.amazonaws.com/123456789012/test01', 'MessageBody': 'Hello'},
'url': 'https://ap-southeast-2.queue.amazonaws.com/', 'context': {'client_region': 'ap-southeast-2', 'client_config': <botocore.config.Config object at 0x106862da0>, 'has_streaming_input': False, 'auth_type': None}}

Erstellen von Parametern für die Integrationsanfrage

Ordnen Sie die Parameter, die Sie für die Methodenanfrage erstellt haben, den Parametern für die Integrationsanforderung zu.

Kehren Sie in der API-Gateway-Konsole zum Bereich Methodenausführung für die Methode Ihrer API-Gateway-API zurück und wählen Sie dann Integrationsanfrage aus.
Erweitern Sie im Bereich Integrationsanfrage die Option URL-Abfragezeichenfolgen-Parameter.
Wählen Sie Abfragezeichenfolge hinzufügen aus.
Geben Sie unter Name den Namen eines Anforderungsparameters für die Service-API ein, die Sie integrieren.
Hinweis: Beim Namen wird zwischen Groß- und Kleinschreibung unterschieden und er muss genau so eingegeben werden, wie es von der Service-API erwartet wird.
Geben Sie für Zugeordnet von method.request.querystring.param_name ein. Ersetzen Sie param_name durch den Namen des entsprechenden Parameters, den Sie für die Methodenanfrage erstellt haben. Zum Beispiel method.request.querystring.TopicArn.
Wählen Sie dann das Häkchensymbol aus (Erstellen).
Wiederholen Sie die Schritte 3-6, um Parameter für die Integrationsanforderung zu erstellen, die den einzelnen Parametern entsprechen, die Sie für die Methodenanfrage erstellt haben.

Hinweis: Wenn Sie die erforderlichen Header und einen Text für die Methodenanfrage erstellt haben, ordnen Sie diese ebenfalls der Integrationsanfrage zu. Erstellen Sie sie im Bereich Integrationsanfrage unter HTTP-Header und Mapping-Vorlagen.

Weitere Informationen finden Sie unter Einrichten eine API-Integrationsanfrage mithilfe der API-Gateway-Konsole.

(Optional) Überprüfen Ihrer Integrationskonfiguration

Um zu überprüfen, ob Ihr Integrations-Setup wie erwartet aussieht, können Sie den AWS-CLI-Befehl get-integration ausführen, um die Konfiguration zu überprüfen, die der folgenden ähnelt:

$ aws apigateway get-integration --rest-api-id 1234123412 --resource-id y9h6rt --http-method POST

Für das Amazon-SNS-Beispiel-Setup sieht die Ausgabe in etwa wie folgt aus:

{
    "integrationResponses": {
        "200": {
            "responseTemplates": {
                "application/json": null
            },
            "statusCode": "200"
        }
    },
    "passthroughBehavior": "WHEN_NO_MATCH",
    "timeoutInMillis": 29000,
    "uri": "arn:aws:apigateway:us-east-2:sns:action/Publish",
    "httpMethod": "POST",
    "cacheNamespace": "y9h6rt",
    "credentials": "arn:aws:iam::1234567890:role/apigateway-sns-role",
    "type": "AWS",
    "requestParameters": {
        "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn",
        "integration.request.querystring.Message": "method.request.querystring.Message"
    },
    "cacheKeyParameters": []
}

Kehren Sie in der API-Gateway-Konsole zum Bereich Methodenausführung für die Methode Ihrer API-Gateway-API zurück und wählen Sie dann TEST aus.

Gehen Sie im Bereich Methodentest wie folgt vor:
Geben Sie für Abfragezeichenfolgen eine Abfragezeichenfolge ein, die Anforderungsparameter und deren Werte enthält. Geben Sie für das Amazon-SNS-Beispiel-Setup TopicArn= arn:aws:sns:us-east-1:123456789012:test&Message="Hello" ein. Ersetzen Sie arn:aws:sns:us-east-1:123456789012:test durch den ARN Ihres Amazon-SNS-Themas.
Geben Sie für Header und Anforderungstext, sofern Sie diese für Ihr Setup erstellt haben, die Header-Namen und die Anforderungstext-JSON ein.
Wählen Sie Testen aus. Im Bereich Methodentest wird eine Antwort angezeigt. Wenn die Antwort erfolgreich ist, wird Status: 200 angezeigt. Für die Amazon-SNS-Beispielkonfiguration enthält eine erfolgreiche Antwort eine MessageId im Antworttext.
Weitere Informationen finden Sie unter Testen einer REST-API-Methode mithilfe der API-Gateway-Konsole.
Stellen Sie Ihre REST-API bereit.
Testen Sie Ihre API mit einem beliebigen Tool.