Unterstützung von API-Gateway-Funktionen Anforderungsformat Authentifizierung und Autorisierung Muster der Serviceintegration Ausgabeformat Fehlerbehandlung

Rufen Sie das API-Gateway mit Step-Funktionen auf

Step Functions kann bestimmte AWS Dienste direkt von der Amazon States Language aus steuern. Weitere Informationen zur Arbeit mit AWS Step Functions und den zugehörigen Integrationen finden Sie im Folgenden:

Wie sich die Optimized API Gateway-Integration von der API Gateway AWS SDK-Integration unterscheidet

apigateway:invoke:hat kein Äquivalent in der AWS SDK-Serviceintegration. Stattdessen ruft der Optimized API Gateway-Dienst Ihren API Gateway-Endpunkt direkt auf.

Sie verwenden Amazon API Gateway, um HTTP- und REST-APIs zu erstellen, zu veröffentlichen, zu verwalten und zu überwachen. Für die Integration mit API Gateway definieren Sie in Step Functions einen Task Status, der direkt einen API-Gateway-HTTP- oder API-Gateway-REST-Endpunkt aufruft, ohne Code zu schreiben oder sich auf eine andere Infrastruktur zu verlassen. Eine Task Zustandsdefinition 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-Endpunkte über API Gateway aufzurufen, unterstützt jedoch derzeit nicht die Möglichkeit, generische HTTP-Endpunkte aufzurufen.

Unterstützung von API-Gateway-Funktionen

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

Unterstützt von den Step Functions API Gateway REST-API- und API Gateway-HTTP-API-Integrationen:
- Autorisierer: IAM (mit Signature Version 4), No Auth, Lambda-Autorisatoren (basierend auf Anforderungsparametern und Tokens mit benutzerdefiniertem Header)
- API-Typen: Regional
- API-Verwaltung: API-Gateway-API-Domainnamen, API-Stufe, Pfad, Abfrageparameter, Anforderungstext
Wird von der Step Functions API Gateway HTTP API-Integration unterstützt, jedoch nicht von der Step Functions API Gateway REST-API-Integration:
- Edge-optimierte APIs
Wird von der Step Functions API Gateway-Integration nicht unterstützt:
- Autorisierer: Amazon Cognito, Native Open ID Connect/OAuth 2.0, Autorisierungsheader für tokenbasierte Lambda-Autorisierer
- API-Typen: Privat
- API-Verwaltung: Benutzerdefinierte Domainnamen

Weitere Informationen zu API Gateway und seinen HTTP- und REST-APIs finden Sie im Folgenden.

Die Seite mit den Amazon API Gateway-Konzepten.
Wählen Sie im API Gateway-Entwicklerleitfaden zwischen HTTP-APIs und REST-APIs.

Anforderungsformat

Wenn Sie Ihre Task Zustandsdefinition erstellen, validiert Step Functions die Parameter, erstellt die für die Ausführung des Aufrufs erforderliche URL 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 Anforderungsparameter

ApiEndpoint
- Typ: String
- Der Hostname einer API-Gateway-URL. Das Format ist <API ID>.execute-api.<region>.amazonaws.com.
  
  Die API-ID kann 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 Anforderungsparameter

Headers
- Typ: JSON
- HTTP-Header ermöglichen eine Liste von Werten, die demselben Schlüssel zugeordnet sind.
Stage
- Typ: String
- Der Name der Phase, in der die API in API Gateway bereitgestellt wird. Es ist optional für jede HTTP-API, die die $default Stufe verwendet.
Path
- Typ: String
- Pfadparameter, die nach dem API-Endpunkt angehängt werden.
QueryParameters
- Typ: JSON
- Abfragezeichenfolgen erlauben nur eine Liste von Werten, die demselben Schlüssel zugeordnet sind.
RequestBody
- Typ: JSON oder String.
- Der Text der HTTP-Anfrage. Sein Typ kann entweder ein JSON Objekt oder seinString. RequestBodywird nur fürPATCH,POST, und PUT HTTP-Methoden unterstützt.
AllowNullValues
- Typ: BOOLEAN
- Wenn true Sie AllowNullValues auf setzen, können Sie Nullwerte wie die folgenden übergeben:
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "name": null
    }
}
```
AuthType
- Typ: JSON
- Die Authentifizierungsmethode. Die Standardmethode istNO_AUTH. Die zulässigen Werte lauten:
  - NO_AUTH
  - IAM_ROLE
  - RESOURCE_POLICY
  Weitere Informationen finden Sie unter Authentifizierung und Autorisierung.

Anmerkung

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

Alles mit dem X-Forwarded Präfix X-Amz oderX-Amzn.
Authorization
Connection
Content-md5
Expect
Host
Max-Forwards
Proxy-Authenticate
Server
TE
Transfer-Encoding
Trailer
Upgrade
Via
Www-Authenticate

Das folgende Codebeispiel zeigt, 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: Bei dieser Methode übernimmt Step Functions die Rolle der State Machine, signiert die Anfrage mit Signature Version 4 (SIGv4) und ruft dann die API auf.
Ressourcenrichtlinie: Step Functions authentifiziert die Anfrage und ruft dann die API auf. Sie müssen der API eine Ressourcenrichtlinie anhängen, die Folgendes festlegt:
1. Die State-Maschine, die API Gateway aufruft.
  
  Wichtig
  Sie müssen Ihre State-Maschine angeben, um den Zugriff darauf einzuschränken. Wenn Sie dies nicht tun, wird jeder State-Maschine, die ihre API-Gateway-Anfrage mit der Resource Policy-Authentifizierung für Ihre API authentifiziert, Zugriff gewährt.
2. That Step Functions ist der Dienst, der API Gateway: aufruft"Service": "states.amazonaws.com".
3. Die Ressource, auf die Sie zugreifen möchten, einschließlich:
  - Die Region.
  - Die Konto-ID in der angegebenen Region.
  - Die API-ID.
  - Der Künstlername.
  - Das HTTP-VERB (Methode).
  - Der resource-path-specifier.
Ein Beispiel für eine Ressourcenrichtlinie finden Sie unter IAM-Richtlinien für Step Functions und API Gateway.

Weitere Informationen zum Ressourcenformat finden Sie im API Gateway Developer Guide unter Ressourcenformat für Berechtigungen für die Ausführung von API in API Gateway.

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

Muster der Serviceintegration

Die API Gateway-Integration unterstützt zwei Dienstintegrationsmuster:

Request Response (Antwort anfordern), was das Standard-Integrationsmuster ist. Dadurch kann Step Functions sofort nach Erhalt einer HTTP-Antwort zum nächsten Schritt übergehen.

Warten auf einen Callback mit dem Aufgabentoken(.waitForTaskToken), das wartet, bis ein Task-Token mit einer Payload zurückgegeben wird. Um das .waitForTaskToken Muster zu verwenden, fügen Sie es an. waitForTaskToken am Ende des Felds Ressource Ihrer Aufgabendefinition, wie im folgenden Beispiel gezeigt:


{
    "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 Antwortheader.
`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, cause wird ein error und wie folgt zurückgegeben:

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

In beiden Fällen cause wird der 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 von 2XX zeigt 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-Konzepte im API Gateway-Entwicklerhandbuch.
IAM-Richtlinien für Step Functions und Amazon API Gateway
Ein Beispielprojekt, das zeigt, wie Rufen Sie das API Gateway auf

Amazon API Gateway-Konzepte im API Gateway-Entwicklerhandbuch.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Amazon EKS

AWS Glue DataBrew

Rufen Sie das API-Gateway mit Step-Funktionen auf

Wie sich die Optimized API Gateway-Integration von der API Gateway AWS SDK-Integration unterscheidet

Anmerkung

Unterstützung von API-Gateway-Funktionen

Anforderungsformat

Erforderliche Anforderungsparameter

Optionale Anforderungsparameter

Anmerkung

Authentifizierung und Autorisierung

Wichtig

Anmerkung

Muster der Serviceintegration

Ausgabeformat

Fehlerbehandlung

Anmerkung