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.
# API-Gateway-REST APIs mit Step Functions erstellen
Erfahren Sie, wie Sie Amazon API Gateway verwenden, um HTTP und REST APIs mit Step Functions 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` Statusdefinition enthält alle erforderlichen Informationen für den API-Aufruf. Sie können auch verschiedene Autorisierungsmethoden auswählen.
Informationen zur Integration mit AWS Diensten in Step Functions finden Sie unter [Integrieren von -Services](integrate-services.md) und[Übergeben von Parametern an eine Service-API in Step Functions](connect-parameters.md).
**Hauptmerkmale der optimierten API-Gateway-Integration**
`apigateway:invoke:`hat kein Äquivalent in der AWS SDK-Dienstintegration. Stattdessen ruft der Optimized API Gateway Gateway-Dienst Ihren API Gateway Gateway-Endpunkt direkt auf.
## Unterstützung von API-Gateway-Funktionen
Die Step Functions API Gateway Gateway-Integration unterstützt einige, aber nicht alle API Gateway Gateway-Funktionen. Eine detailliertere Liste der unterstützten Funktionen finden Sie im Folgenden.
+ Wird sowohl von den Step Functions API Gateway Gateway-REST-API- als auch von den API Gateway Gateway-HTTP-API-Integrationen unterstützt:
+ **Autorisierer**: IAM (mit [Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html)), No Auth, Lambda Authorizers (auf Anforderungsparametern und Token-basiert mit benutzerdefiniertem Header)
+ API-Typen**:** Regional
+ **API-Verwaltung**: API-Gateway-API-Domänennamen, API-Phase, Pfad, Abfrageparameter, Anfragetext
+ Unterstützt von der Step Functions API Gateway HTTP-API-Integration. Die STEP Functions API Gateway REST-API-Integration, die die Option für Edge-Optimized bietet, wird nicht APIs unterstützt.
+ Wird von der Step Functions API Gateway 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 über API Gateway und dessen HTTP und REST APIs finden Sie im Folgenden.
+ Die [Amazon API Gateway Gateway-Konzeptseite](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html).
+ [Auswahl zwischen HTTP APIs und REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) im API Gateway Gateway-Entwicklerhandbuch.
## Anforderungsformat
Wenn Sie Ihre `Task` Statusdefinition erstellen, validiert Step Functions die Parameter, erstellt die für den Aufruf erforderliche URL und ruft dann die API auf. 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 einer API-Gateway-URL. Das Format ist `.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`
+ 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 den `$default` Stage 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 Hauptteil der HTTP-Anfrage. Sein Typ kann entweder ein `JSON` Objekt oder sein`String`. `RequestBody`wird nur für `PATCH``POST`, und `PUT` HTTP-Methoden unterstützt.
+ `AllowNullValues`
+ Typ: `BOOLEAN` — Standardwert: `false`
+ Mit der Standardeinstellung werden **Nullwerte** im Status der Anforderungseingabe **nicht** an Ihre API gesendet. Im folgenden Beispiel wird das `category` Feld **nicht** in die Anfrage 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 Ihre API gesendet. Sie können das Senden von Nullwerten an Ihre API erzwingen, indem Sie `true` in Ihrer State-Machine-Definition die Einstellung `AllowNullValues` auf setzen.
+ `AuthType`
+ Typ: `JSON`
+ Die Authentifizierungsmethode. Die Standardmethode ist`NO_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 ein`X-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",
"Arguments": {
"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 Zustandsmaschine, signiert die Anfrage mit [Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) (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 spezifiziert:
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** Ihre API authentifiziert, Zugriff gewährt.
1. That Step Functions ist der Dienst, der API Gateway aufruft:`"Service": "states.amazonaws.com"`.
1. Die Ressource, auf die Sie zugreifen möchten, einschließlich:
+ Das Tool *region*.
+ Die *account-id* in der angegebenen Region.
+ Das Tool *api-id*.
+ Das Tool *stage-name*.
+ Die *HTTP-VERB* (Methode).
+ Das Tool *resource-path-specifier*.
Ein Beispiel für eine Ressourcenrichtlinie finden Sie unter [IAM-Richtlinien für Step Functions und API Gateway](#api-gateway-iam).
Weitere Informationen zum Ressourcenformat finden Sie unter [Ressourcenformat der Berechtigungen für die Ausführung von APIs in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-iam-policy-resource-format-for-executing-api) im API Gateway Developer Guide.
**Anmerkung**
Ressourcenrichtlinien werden nur für die REST-API unterstützt.
## Muster der Serviceintegration
Die API Gateway Gateway-Integration unterstützt zwei Dienstintegrationsmuster:
+ [Request Response (Antwort anfordern)](connect-to-resource.md#connect-default), 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](connect-to-resource.md#connect-wait-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",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "POST",
"Headers": {
"TaskToken": "{% $states.context.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 | Description |
| --- | --- | --- |
| 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. |
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ückgegeben`ApiGateway.`.
+ Wenn der HTTP-Statuscode nicht verfügbar ist, wird der Fehler im Format zurückgegeben`ApiGateway.`.
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.
## IAM-Richtlinien für Aufrufe an Amazon API Gateway
Die folgenden Beispielvorlagen zeigen, wie IAM-Richtlinien auf der Grundlage der Ressourcen in Ihrer State-Machine-Definition AWS Step Functions generiert werden. Weitere Informationen erhalten Sie unter [So generiert Step Functions IAM-Richtlinien für integrierte Dienste](service-integration-iam-templates.md) und [Entdecken Sie Serviceintegrationsmuster in Step Functions](connect-to-resource.md).
*Ressourcen:*
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/GET/pets",
"arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/POST/pets"
],
"Effect": "Allow"
}
]
}
```
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:us-east-1:123456789012:myApi-id/stage-name/HTTP-VERB/resource-path-specifier",
"Condition": {
"StringEquals": {
"aws:SourceArn": [
""
]
}
}
}
]
}
```