Rufen Sie API Gateway mit Step Functions - AWS Step Functions

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.

Rufen Sie API Gateway mit Step Functions

Step Functions können bestimmte steuernAWS-Services direkt aus der Amazon States Language. Weitere Informationen zur Arbeit mitAWS Step Functionsund seine Integrationen finden Sie im Folgenden:

Wie sich die optimierte API-Gateway-Integration von dem API Gateway unterscheidetAWSSDK-Integration
  • apigateway:invoke:hat kein Äquivalent imAWSSDK-Serviceintegration. Stattdessen ruft der Optimized API-Gateway-Dienst Ihren API-Gateway-Endpunkt direkt auf.

Sie verwenden Amazon API Gateway zum Erstellen, Veröffentlichen, Warten und Überwachen von HTTP- und REST-APIs. Um es in API Gateway zu integrieren, definieren Sie einTaskstatus in Step Functions, der direkt einen API Gateway HTTP- oder API-Gateway-REST-Endpunkt aufruft, ohne Code zu schreiben oder sich auf eine andere Infrastruktur zu verlassen. EINTaskDie Statusdefinition enthält alle notwendigen Informationen für den API-Aufruf. Sie können auch verschiedene Autorisierungsmethoden auswählen.

Anmerkung

Step Functions unterstützt die Möglichkeit, HTTP-Endpoints über API Gateway aufzurufen, unterstützt jedoch derzeit nicht die Möglichkeit, generische HTTP-Endpunkte aufzurufen.

Unterstützung von API-Gateway-Funktion

Die Step Functions API Gateway Gateway-Integration unterstützt einige, aber nicht alle API-Gateway-Funktionen. Eine detailliertere Liste der unterstützten Funktionen finden Sie im Folgenden.

  • Unterstützt sowohl von der Step Functions API Gateway REST API als auch von API Gateway HTTP-API-Integrationen:

    • Authorizers: IAM (verwendenSignaturversion 4), No Auth, Lambda Authorizers (Request-Parameterbasiert und tokenbasiert mit benutzerdefiniertem Header)

    • API-Typen: Regional

    • API-Management: API-Gateway-API-Domänennamen, API-Phase, Pfad, Abfrageparameter, Anforderungstext

  • Unterstützt durch die Step Functions API Gateway HTTP-API-Integration, aber nicht die Step Functions API Gateway REST API-Integration:

    • Edge-optimierte APIs

  • Nicht unterstützt von der Step Functions API Gateway Gateway-Integration:

    • Authorizers: Amazon Cognito, Native Open ID Connect/OAuth 2.0, Autorisierungsheader für tokenbasierte Lambda-Autorisierer

    • API-Typen: Privat

    • API-Management: Benutzerdefinierte Domänennamen

Weitere Informationen über API Gateway und seine HTTP- und REST-APIs finden Sie im Folgenden.

Anforderungsformat

Wenn Sie Ihre erstellenTaskStatusdefinition, Step Functions validiert die Parameter, erstellt die erforderliche URL zum Ausführen des Aufrufs und ruft dann die API auf. Die Antwort enthält den HTTP-Statuscode, die Header und den Antworttext. Das Anforderungsformat hat sowohl erforderliche als auch optionale Parameter.

Erforderliche Anfrageparameter

  • ApiEndpoint

    • Typ: String

    • Der Hostname einer API-Gateway-URL. Das Format ist <API ID>.execute-api.<region>.amazonaws.com.

      Die API-ID darf nur eine Kombination der folgenden alphanumerischen Zeichen enthalten:0123456789abcdefghijklmnopqrstuvwxyz

  • Method

    • Typ: Enum

    • Die HTTP-Methode, die eine der folgenden sein muss:

      • GET

      • POST

      • PUT

      • DELETE

      • PATCH

      • HEAD

      • OPTIONS

Optionale Anfrageparameter

  • Headers

    • Typ: JSON

    • HTTP-Header erlauben eine Liste von Werten, die mit demselben Schlüssel verknüpft sind.

  • Stage

    • Typ: String

    • Der Name des Schrittes, auf dem die API im API Gateway bereitgestellt wird. Es ist optional für jede HTTP-API, die die$default-Stufe.

  • Path

    • Typ: String

    • Pfadparameter, die nach dem API-Endpunkt angehängt werden.

  • QueryParameters

    • Typ: JSON

    • Abfragezeichenfolgen erlauben eine Liste von Werten, die mit demselben Schlüssel verknüpft sind.

  • RequestBody

    • Typ: JSON oder String.

    • Der Text der HTTP-Anforderung. Sein Typ kann eines derJSONObjekt oderStringaus.RequestBodywird nur unterstützt fürPATCH,POST, undPUTHTTP-Methoden.

  • AllowNullValues

    • Typ: BOOLEAN

    • Festlegen vonAllowNullValueszutrueermöglicht es Ihnen, Nullwerte wie die folgenden zu übergeben:

      { "NewPet": { "type": "turtle", "price": 123, "name": null } }
  • AuthType

    • Typ: JSON

    • Die Authentifizierungsmethode. Die Standardmethode istNO_AUTHaus. Die zulässigen Werte lauten:

      • NO_AUTH

      • IAM_ROLE

      • RESOURCE_POLICY

      Siehe .Authentifizierung und AutorisierungFür weitere Informationen finden Sie unter.

Anmerkung

Aus Sicherheitsüberlegungen sind die folgenden HTTP-Header-Schlüssel derzeit nicht zulässig:

  • Alles mit dem PräfixX-Forwarded,X-AmzoderX-Amznaus.

  • Authorization

  • Connection

  • Content-md5

  • Expect

  • Host

  • Max-Forwards

  • Proxy-Authenticate

  • Server

  • TE

  • Transfer-Encoding

  • Trailer

  • Upgrade

  • Via

  • Www-Authenticate

Das folgende Codebeispiel veranschaulicht, wie API Gateway mithilfe von Step Functions aufgerufen wird.

{ "Type": "Task", "Resource":"arn:aws:states:::apigateway:invoke", "Parameters": { "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com", "Method": "GET", "Headers": { "key": ["value1", "value2"] }, "Stage": "prod", "Path": "bills", "QueryParameters": { "billId": ["123456"] }, "RequestBody": {}, "AuthType": "NO_AUTH" } }

Authentifizierung und Autorisierung

Sie können die folgenden Authentifizierungsmethoden verwenden:

  • Keine Autorisierung: Rufen Sie die API direkt ohne Autorisierungsmethode auf.

  • IAM-Rolle: Mit dieser Methode übernimmt Step Functions die Rolle der Zustandsmaschine, signiert die Anfrage mitSignaturversion 4(Sigv4), ruft dann die API auf.

    Anmerkung

    Die kontoübergreifende Unterstützung ist für diese Authentifizierungsmethode nicht verfügbar.

  • -Ressourcenrichtlinie: Step Functions authentifiziert die Anfrage und ruft dann die API auf. Sie müssen eine Ressourcenrichtlinie an die API anhängen, die Folgendes angibt:

    1. Der Zustandsmaschine, der API Gateway aufruft.

      Wichtig

      Sie müssen Ihren Statuscomputer angeben, um den Zugriff darauf einzuschränken. Wenn nicht, dann jeder Statuscomputer, der seine API-Gateway-Anforderung authentifiziert, mit-RessourcenrichtlinieDie Authentifizierung an Ihrer API wird Zugriff gewährt.

    2. That Step Functions ist der Dienst, der API Gateway aufruft:"Service": "states.amazonaws.com"aus.

    3. Die Ressource, auf die Sie zugreifen möchten, einschließlich:

      • DieRegionaus.

      • Dieaccount-idIn der angegebenen Region.

      • Dieapi-IDaus.

      • DieStufennameaus.

      • DieHTTP-VERB(Methode).

      • Dieressourcen-Pfad-Spezifiziereraus.

    Eine Beispiel-Ressourcenrichtlinie finden Sie unterIAM-Richtlinien für Step Functions und API Gatewayaus.

    Weitere Informationen zum Ressourcenformat finden Sie unterRessourcenformat für Berechtigungen zur Ausführung der API in API GatewayIm API Gateway Gateway-Entwicklerhandbuch.

    Anmerkung

    Ressourcenrichtlinien werden nur für die REST-API unterstützt.

Service-Integrationsmuster

Die API Gateway Gateway-Integration unterstützt zwei Service-Integrationsmuster:

  • Request Response (Antwort anfordern), welches das Standard-Integrationsmuster ist. Dadurch können Step Functions unmittelbar nach Erhalt einer HTTP-Antwort zum nächsten Schritt weiterlaufen.

  • Warten auf einen Callback mit dem Aufgabentoken(.waitForTaskToken), der wartet, bis ein Aufgabentoken mit einer Nutzlast zurückgegeben wird. So verwenden Sie den.waitForTaskTokenpattern, append .waitForTaskToken am Ende desRessource-Feld Ihrer Aufgabendefinition wie im folgenden Beispiel dargestellt:

    { "Type": "Task", "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", "Parameters": { "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com", "Method": "POST", "Headers": { "TaskToken.$": "States.Array($$.Task.Token)" }, "Stage": "prod", "Path": "bills/add", "QueryParameters": {}, "RequestBody": { "billId": "my-new-bill" }, "AuthType": "IAM_ROLE" } }

Ausgabeformat

Die folgenden Ausgabeparameter werden bereitgestellt:

Name Typ Beschreibung
ResponseBody JSON oder String Der Antworttext des API-Aufrufs.
Headers JSON Die Antwort-Header.
StatusCode Integer Den HTTP-Statuscode der Antwort.
StatusText String Der Statustext der Antwort.

Eine Beispielantwort:

{ "ResponseBody": { "myBills": [] }, "Headers": { "key": ["value1", "value2"] }, "StatusCode": 200, "StatusText": "OK" }

Fehlerbehandlung

Wenn ein Fehler auftritt, wird eineerrorundcausewird wie folgt zurückgegeben:

  • Wenn der HTTP-Statuscode verfügbar ist, wird der Fehler im Format zurückgegebenApiGateway.<HTTP Status Code>aus.

  • Wenn der HTTP-Statuscode nicht verfügbar ist, wird der Fehler im Format zurückgegebenApiGateway.<Exception>aus.

In beiden Fällen wirdcausewird als -Zeichenfolge zurückgegeben.

Das folgende Beispiel zeigt eine Antwort, bei der ein Fehler aufgetreten ist:

{ "error": "ApiGateway.403", "cause": "{\"message\":\"Missing Authentication Token\"}" }
Anmerkung

Ein Statuscode von2XXzeigt den Erfolg an, und es wird kein Fehler zurückgegeben. Alle anderen Statuscodes oder ausgelösten Ausnahmen führen zu einem Fehler.

Weitere Informationen finden Sie unter:

Amazon API Gateway-KonzepteIm API Gateway Gateway-Entwicklerhandbuch.