APIUnterstützung von Gateway-Funktionen Anforderungsformat Authentifizierung und Autorisierung Muster der Serviceintegration Ausgabeformat Fehlerbehandlung IAMRichtlinien

APIGateway REST APIs mit Step-Funktionen erstellen

Erfahren Sie, wie Sie Amazon API Gateway zum Erstellen, Veröffentlichen, Verwalten HTTP und Überwachen sowie REST APIs mit Step Functions verwenden. Für die Integration mit API Gateway definieren Sie in Step Functions einen Task Status, der direkt einen API API Gateway HTTP - oder REST Gateway-Endpunkt aufruft, ohne Code zu schreiben oder sich auf eine andere Infrastruktur zu verlassen. Eine Task Statusdefinition umfasst alle für den API Anruf erforderlichen Informationen. Sie können auch verschiedene Autorisierungsmethoden auswählen.

Um mehr über die Integration mit zu erfahren AWS Dienste in Step Functions, siehe Integrieren von -Services undÜbergeben von Parametern an einen Dienst API in Step Functions.

Hauptmerkmale der optimierten API Gateway-Integration

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

APIUnterstützung von 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.

Wird sowohl von den Step Functions API Gateway REST API - als auch von den API HTTP API Gateway-Integrationen unterstützt:
- Autorisierer: IAM (mit Signature Version 4), No Auth, Lambda Authorizers (auf Anforderungsparametern und Token-basiert mit benutzerdefiniertem Header)
- APITypen: Regional
- APIVerwaltung: API API Gateway-Domänennamen, API Stufe, Pfad, Abfrageparameter, Anforderungstext
Unterstützt durch die Step Functions API HTTP API Gateway-Integration. Die Step Functions API REST API Gateway-Integration, die die Option für Edge-Optimized bietet, wird nicht APIs unterstützt.
Wird von der Step Functions API Gateway-Integration nicht unterstützt:
- Autorisierer: Amazon Cognito, Native Open ID Connect/OAuth2.0, Autorisierungsheader für tokenbasierte Lambda-Autorisierer
- APITypen: Privat
- APIVerwaltung: Benutzerdefinierte Domainnamen

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

Die Amazon API Gateway-Konzeptseite.
Auswahl zwischen HTTP APIs und REST APIs im API Gateway-Entwicklerhandbuch.

Anforderungsformat

Wenn Sie Ihre Task Statusdefinition erstellen, validiert Step Functions die Parameter, erstellt die für den Aufruf erforderlichen URL Daten und ruft dann den aufAPI. Die Antwort umfasst den HTTP Statuscode, die Header und den Antworttext. Das Anforderungsformat hat sowohl erforderliche als auch optionale Parameter.

Erforderliche Anforderungsparameter

ApiEndpoint
- Typ: String
- Der Hostname eines API GatewaysURL. 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 Anforderungsparameter

Headers
- Typ: JSON
- HTTPHeader ermöglichen eine Liste von Werten, die demselben Schlüssel zugeordnet sind.
Stage
- Typ: String
- Der Name der Phase, in der das in API Gateway bereitgestellt API wird. Für alle, die die $default Phase verwenden HTTPAPI, ist er optional.
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 Hauptteil der HTTP Anfrage. Sein Typ kann entweder ein JSON Objekt oder seinString. RequestBodywird nur für PUT HTTP Methoden PATCHPOST, und unterstützt.
AllowNullValues
- Typ: BOOLEAN — Standardwert: false
- Mit der Standardeinstellung werden Nullwerte im Status der Anforderungseingabe nicht an Ihren gesendetAPI. Im folgenden Beispiel wird das category Feld nicht in die Anforderung aufgenommen, es sei denn, es AllowNullValues ist true in Ihrer State-Machine-Definition auf festgelegt.
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "category": null
    }
}
```
  Anmerkung
  Standardmäßig werden Felder mit Nullwerten im Anforderungseingabestatus nicht an Ihren gesendetAPI. Sie können das Senden von Nullwerten an Sie erzwingen, API indem Sie true in Ihrer Zustandsmaschinen-Definition AllowNullValues auf festlegen.
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, dem einX-Forwarded, X-Amz oder X-Amzn vorangestellt ist.
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 das API direkt ohne Autorisierungsmethode auf.
IAMRolle: Bei dieser Methode übernimmt Step Functions die Rolle der Zustandsmaschine, signiert die Anfrage mit Signature Version 4 (Sigv4) und ruft dann die API auf.
Ressourcenrichtlinie: Step Functions authentifiziert die Anfrage und ruft dann die aufAPI. Sie müssen der eine Ressourcenrichtlinie beifügenAPI, die Folgendes festlegt:
1. Die Zustandsmaschine, die API Gateway aufruft.
  
  Wichtig
  Sie müssen Ihren Zustandsmaschine angeben, um den Zugriff darauf zu beschränken. Wenn Sie dies nicht tun, wird jeder Zustandsmaschine, die ihre API Gateway-Anfrage mit der Ressourcenrichtlinien-Authentifizierung für API Sie 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:
  - Das Tool region.
  - Das Tool account-id in der angegebenen Region.
  - Das Tool api-id.
  - Das Tool stage-name.
  - Das Tool HTTP-VERB (Methode).
  - Das Tool resource-path-specifier.
Ein Beispiel für eine Ressourcenrichtlinie finden Sie unter IAMRichtlinien für Step Functions und API Gateway.

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

Anmerkung
Ressourcenrichtlinien werden nur für die unterstützt RESTAPI.

Muster der Serviceintegration

Die API Gateway-Integration unterstützt zwei Serviceintegrationsmuster:

Request Response (Antwort anfordern), was das Standard-Integrationsmuster ist. Dadurch kann Step Functions unmittelbar nach Erhalt einer HTTP Antwort mit dem nächsten Schritt fortfahren.

Warten Sie auf einen Rückruf mit Task Token(.waitForTaskToken), wodurch gewartet wird, bis ein Task-Token mit einer Nutzlast zurückgegeben wird. Um das .waitForTaskToken Muster zu verwenden, fügen Sie es an. waitForTaskFügen Sie das Ende des Felds Ressource Ihrer Aufgabendefinition ein, 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 sind verfügbar:

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

Ein Beispiel für eine Antwort:


{
    "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 folgenden 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 das 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

Der Statuscode 2XX bedeutet Erfolg, und es wird kein Fehler zurückgegeben. Alle anderen Statuscodes oder ausgelösten Ausnahmen führen zu einem Fehler.

IAMRichtlinien für Anrufe an Amazon API Gateway

Die folgenden Beispielvorlagen zeigen, wie AWS Step Functions generiert IAM Richtlinien auf der Grundlage der Ressourcen in Ihrer State-Machine-Definition. Weitere Informationen erhalten Sie unter So generiert Step Functions IAM Richtlinien für integrierte Dienste und Entdecken Sie Serviceintegrationsmuster in Step Functions.

Ressourcen:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
                "arn:[[region]]:[[accountId]]:*"
            ]
        }
    ]
}

Das folgende Codebeispiel zeigt eine Ressourcenrichtlinie für den Aufruf von API Gateway.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "states.amazonaws.com"
            },
            "Action": "execute-api:Invoke",
            "Resource": "arn:aws:execute-api:<region>:<account-id>:<api-id>/<stage-name>/<HTTP-VERB>/<resource-path-specifier>",
            "Condition": {
                "StringEquals": {
                    "aws:SourceArn": [
                        "<SourceStateMachineArn>"
                    ]
                }
            }
        }
    ]
}

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

Integration optimierter Dienste

Amazon Athena

APIGateway REST APIs mit Step-Funktionen erstellen

Hauptmerkmale der optimierten API Gateway-Integration

APIUnterstützung von Gateway-Funktionen

Anforderungsformat

Erforderliche Anforderungsparameter

Optionale Anforderungsparameter

Anmerkung

Anmerkung

Authentifizierung und Autorisierung

Wichtig

Anmerkung

Muster der Serviceintegration

Ausgabeformat

Fehlerbehandlung

Anmerkung

IAMRichtlinien für Anrufe an Amazon API Gateway