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 HTTPS APIs in Step Functions Functions-Workflows auf
Ein HTTP-Task ist ein [Workflow-Status der Aufgabe](state-task.md) Zustandstyp, den Sie verwenden können, um HTTPS APIs in Ihren Workflows aufzurufen. Die API kann öffentlich sein, z. B. SaaS-Anwendungen von Drittanbietern wie Stripe oder Salesforce. Sie können auch private APIs aufrufen, z. B. HTTPS-basierte Anwendungen in einer Amazon Virtual Private Cloud.
Für die Autorisierung und Netzwerkkonnektivität benötigt eine HTTP-Task eine EventBridge Verbindung.
Um eine HTTPS-API aufzurufen, verwenden Sie den [Task-Status](state-task.md) mit der `arn:aws:states:::http:invoke` Ressource. Geben Sie dann die Konfigurationsdetails des API-Endpunkts an, z. B. die API-URL, die Methode, die Sie verwenden möchten, und [Verbindungsdetails](#http-task-authentication).
Wenn Sie [Workflow Studio](workflow-studio.md) verwenden, um Ihren Zustandsmaschine zu erstellen, der eine HTTP-Task enthält, generiert Workflow Studio automatisch eine Ausführungsrolle mit IAM Richtlinien für die HTTP-Task. Weitere Informationen finden Sie unter [Rolle zum Testen von HTTP-Aufgaben in Workflow Studio](manage-state-machine-permissions.md#test-state-role-http).
**Anmerkung**
HTTP Task unterstützt derzeit nur öffentliche Domainnamen mit öffentlich vertrauenswürdigen Zertifikaten für HTTPS-Endpunkte, wenn private APIs verwendet werden. HTTP Task unterstützt kein gegenseitiges TLS (mTLS).
**Topics**
+ [
## Konnektivität für eine HTTP-Task
](#http-task-authentication)
+ [
## Definition der HTTP-Aufgabe
](#connect-http-task-definition)
+ [
## Felder für HTTP-Aufgaben
](#connect-http-task-fields)
+ [
## EventBridgeVerbindungs- und HTTP-Aufgabendefinitionsdaten zusammenführen
](#http-task-data-merge)
+ [
## Anwenden der URL-Codierung auf den Anforderungstext
](#url-encode-request-body)
+ [
## IAM-Berechtigungen zum Ausführen einer HTTP-Aufgabe
](#connect-http-task-permissions)
+ [
## Beispiel für eine HTTP-Aufgabe
](#connect-http-task-example)
+ [
## Testen einer HTTP-Aufgabe
](#http-task-test)
+ [
## Antworten auf HTTP-Aufgaben werden nicht unterstützt
](#unsupported-http-task-responses)
+ [Verbindungsfehler](#connect-http-task-errors)
## Konnektivität für eine HTTP-Task
Ein HTTP-Task erfordert eine [EventBridgeVerbindung](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html), die die Authentifizierungsdaten eines API-Anbieters sicher verwaltet. Eine *Verbindung* definiert die Autorisierungsmethode und die Anmeldeinformationen, die für die Verbindung zu einer bestimmten API verwendet werden sollen. Wenn Sie eine Verbindung zu einer privaten API herstellen, z. B. einer privaten API in einer Amazon Virtual Private Cloud (Amazon VPC), können Sie die Verbindung auch verwenden, um eine sichere point-to-point Netzwerkkonnektivität zu definieren. Durch die Verwendung einer Verbindung können Sie vermeiden, Secrets wie API-Schlüssel durch Hartkodierung in die Definition Ihres Zustandsautomaten einzubetten. Eine EventBridge Verbindung unterstützt die Autorisierungsschemata Basic OAuth, und API Key.
Wenn Sie eine EventBridge Verbindung herstellen, geben Sie Ihre Autorisierungs- und Netzwerkverbindungsdetails an. Sie können auch die Header-, Text- und Abfrageparameter angeben, die für die Autorisierung mit einer API erforderlich sind. Sie müssen den Verbindungs-ARN in jede HTTP-Aufgabe aufnehmen, die eine HTTPS-API aufruft.
Wenn Sie eine Verbindung herstellen, EventBridge erstellt ein [https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) in AWS Secrets Manager. EventBridge Speichert in diesem Secret die Verbindungs- und Autorisierungsparameter in verschlüsselter Form. Um erfolgreich eine Verbindung herzustellen oder zu aktualisieren, müssen Sie eine Verbindung verwenden, AWS-Konto die über die Berechtigung zur Verwendung von Secrets Manager verfügt. Weitere Informationen zu den IAM Berechtigungen, die Ihr State-Machine für den Zugriff auf eine EventBridge Verbindung benötigt, finden Sie unter[IAM-Berechtigungen zum Ausführen einer HTTP-Aufgabe](#connect-http-task-permissions).
Die folgende Abbildung zeigt, wie die Autorisierung für HTTPS-API-Aufrufe über eine EventBridge Verbindung Step Functions gehandhabt wird. Die EventBridge Verbindung verwaltet die Anmeldeinformationen eines HTTPS-API-Anbieters. EventBridgeerstellt ein [https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)Secrets Manager, um die Verbindungs- und Autorisierungsparameter in verschlüsselter Form zu speichern. Speichert im Fall von Private APIs EventBridge auch Netzwerkkonnektivitätskonfigurationen.
**Timeouts für Verbindungen**
Bei HTTP-Aufgabenanfragen kommt es nach 60 Sekunden zu einem Timeout.
![\[Step Functions verwendet Autorisierung und Netzwerkkonfiguration in EventBridge Verbindungen für Aufrufe an HTTPS-Endpunkte.\]](http://docs.aws.amazon.com/de_de/step-functions/latest/dg/images/connections-overview_step-functions_conceptual.png)
## Definition der HTTP-Aufgabe
Die [ASL-Definition](concepts-amazon-states-language.md) stellt eine HTTP-Aufgabe mit `http:invoke` Ressource dar. Die folgende HTTP-Aufgabendefinition ruft eine öffentliche Stripe-API auf, die eine Liste aller Kunden zurückgibt.
```
"Call HTTPS API": {
"Type": "Task",
"Resource": "arn:aws:states:::http:invoke",
"Parameters": {
"ApiEndpoint": "https://api.stripe.com/v1/customers",
"Authentication": {
"ConnectionArn": "arn:aws:events:region:account-id:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
},
"Method": "GET"
},
"End": true
}
```
## Felder für HTTP-Aufgaben
Eine HTTP-Task umfasst die folgenden Felder in ihrer Definition.
**`Resource` (Erforderlich)**
Um einen [Aufgabentyp](state-task.md#task-types) anzugeben, geben Sie dessen ARN in das `Resource` Feld ein. Für eine HTTP-Aufgabe geben Sie das `Resource` Feld wie folgt an.
```
"Resource": "arn:aws:states:::http:invoke"
```
**`Parameters` (Erforderlich)**
Enthält die `ConnectionArn` Felder `ApiEndpoint``Method`, und, die Informationen über die HTTPS-API enthalten, die Sie aufrufen möchten. `Parameters`enthält auch optionale Felder wie `Headers` und`QueryParameters`.
Sie können eine Kombination aus statischem JSON und [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)Syntax wie `Parameters` im `Parameters` Feld angeben. Weitere Informationen finden Sie unter [Übergeben von Parametern an eine Service-API in Step Functions](connect-parameters.md).
Um die EventBridge Verbindung anzugeben, verwenden Sie entweder das `InvocationConfig` Feld `Authentication` *oder*.
`ApiEndpoint`**(Erforderlich)**
Gibt die URL der HTTPS-API an, die Sie aufrufen möchten. Verwenden Sie das `QueryParameters` Feld, um Abfrageparameter an die URL anzuhängen. Das folgende Beispiel zeigt, wie Sie eine Stripe-API aufrufen können, um die Liste aller Kunden abzurufen.
```
"ApiEndpoint":"https://api.stripe.com/v1/customers"
```
Sie können mithilfe der [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)Syntax auch einen [Referenzpfad](amazon-states-language-paths.md#amazon-states-language-reference-paths) angeben, um den JSON-Knoten auszuwählen, der die HTTPS-API-URL enthält. Nehmen wir zum Beispiel an, Sie möchten einen von Stripe APIs mit einer bestimmten Kunden-ID anrufen. Stellen Sie sich vor, Sie haben den folgenden Status eingegeben.
```
{
"customer_id": "1234567890",
"name": "John Doe"
}
```
Um die Details dieser Kunden-ID mithilfe einer Stripe-API abzurufen, geben Sie die `ApiEndpoint` wie im folgenden Beispiel gezeigt an. In diesem Beispiel werden eine [systeminterne Funktion und](intrinsic-functions.md) ein Referenzpfad verwendet.
```
"ApiEndpoint.$":"States.Format('https://api.stripe.com/v1/customers/{}', $.customer_id)"
```
Zur Laufzeit löst Step Functions den Wert von `ApiEndpoint` wie folgt auf.
```
https://api.stripe.com/v1/customers/1234567890
```
`Method`**(Erforderlich)**
Gibt die HTTP-Methode an, die Sie für den Aufruf einer HTTPS-API verwenden möchten. Sie können in Ihrer HTTP-Aufgabe eine der folgenden Methoden angeben: GET, POST, PUT, DELETE, PATCH, OPTIONS oder HEAD.
Um beispielsweise die GET-Methode zu verwenden, geben Sie das `Method` Feld wie folgt an.
```
"Method": "GET"
```
Sie können auch einen [Referenzpfad](amazon-states-language-paths.md#amazon-states-language-reference-paths) verwenden, um die Methode zur Laufzeit anzugeben. Beispiel, **"Method.\$1": "\$1.myHTTPMethod"**.
`Authentication`**(Befriedigend)**
*Wir empfehlen, `InvocationConfig` over sowohl `Authentication` für öffentliche als auch für private HTTPS-API-Aufrufe zu verwenden.*
Bestehende `Authentication` Referenzen werden aus Gründen der Abwärtskompatibilität beibehalten. Innerhalb des Felds müssen Sie ein Feld angeben, das eine `ConnectionArn` Verbindungsressource von angibt, mit der Amazon EventBridge eine Verbindung hergestellt werden soll. `ApiEndpoint`
`InvocationConfig`**(Bedingt)**
**Enthält die Autorisierungs- und Netzwerkkonnektivitätskonfiguration für öffentliche und private HTTPS-API-Aufrufe.**
Step Functionsverarbeitet die Verbindung für eine angegebene Verbindung `ApiEndpoint` mithilfe der Verbindungsressource vonAmazon EventBridge. Weitere Informationen finden Sie unter [Herstellen einer privaten Verbindung APIs](https://docs.aws.amazon.com/eventbridge/latest/userguide/connection-private.html) im * EventBridgeAmazon-Benutzerhandbuch*.
`ConnectionArn`**(Erforderlich)**
Gibt den EventBridge Verbindungs-ARN an.
Ein HTTP-Task erfordert eine [EventBridge Verbindung](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html), die die Autorisierungsdaten eines API-Anbieters sicher verwaltet. Eine *Verbindung* gibt den Autorisierungstyp und die Anmeldeinformationen an, die für die Autorisierung einer HTTPS-API verwendet werden sollen. Im privaten Bereich APIs definiert die Verbindung auch eine sichere point-to-point Netzwerkkonnektivität. Durch die Verwendung einer Verbindung können Sie vermeiden, Secrets wie API-Schlüssel durch Hartkodierung in die Definition Ihres Zustandsautomaten einzubetten. In einer Verbindung können Sie auch `RequestBody` Parameter `Headers``QueryParameters`, und angeben.
Weitere Informationen finden Sie unter [Konnektivität für eine HTTP-Task](#http-task-authentication).
Das folgende Beispiel zeigt das Format von `InvocationConfig` in einer HTTP-Aufgabe:
```
"InvocationConfig": {
"ConnectionArn": "arn:aws:events:region:account-id:connection/connection-id"
}
```
`Headers` (Optional)
Stellt zusätzlichen Kontext und Metadaten für den API-Endpunkt bereit. Sie können Header als Zeichenfolge oder JSON-Array angeben.
Sie können Header in der EventBridge Verbindung und das `Headers` Feld in einer HTTP-Task angeben. Wir empfehlen, dass Sie in dem `Headers` Feld keine Authentifizierungsdetails für Ihre API-Anbieter angeben. Wir empfehlen Ihnen, diese Details in Ihre EventBridge Verbindung aufzunehmen.
Step Functionsfügt die Header, die Sie in der EventBridge Verbindung angeben, zu den Headern hinzu, die Sie in der HTTP-Aufgabendefinition angeben. Wenn dieselben Header-Schlüssel in der Definition und Verbindung vorhanden sind, Step Functions verwendet die entsprechenden Werte, die in der EventBridge Verbindung für diese Header angegeben wurden. Weitere Hinweise zur Durchführung der Step Functions Datenzusammenführung finden Sie unter. [EventBridgeVerbindungs- und HTTP-Aufgabendefinitionsdaten zusammenführen](#http-task-data-merge)
Das folgende Beispiel spezifiziert einen Header, der in einen HTTPS-API-Aufruf aufgenommen wird:`content-type`.
```
"Headers": {
"content-type": "application/json"
}
```
Sie können auch einen [Referenzpfad](amazon-states-language-paths.md#amazon-states-language-reference-paths) verwenden, um die Header zur Laufzeit anzugeben. Beispiel, **"Headers.\$1": "\$1.myHTTPHeaders"**.
Step Functionslegt die `User-Agent` `Host` Header`Range`, und fest. Step Functionslegt den Wert des `Host` Headers basierend auf der API fest, die Sie aufrufen. Im Folgenden finden Sie ein Beispiel für diese Header.
```
User-Agent: Amazon|StepFunctions|HttpInvoke|region,
Range: bytes=0-262144,
Host: api.stripe.com
```
Sie können die folgenden Header nicht in Ihrer HTTP-Aufgabendefinition verwenden. Wenn Sie diese Header verwenden, schlägt die HTTP-Aufgabe mit dem `States.Runtime` Fehler fehl.
+ A-IM
+ Accept-Charset
+ Accept-Datetime
+ Accept-Encoding
+ Autorisierung
+ Cache-Control
+ Connection (Verbindung)
+ Content-Encoding
+ Inhalt- MD5
+ Date
+ Expect
+ Forwarded
+ Aus
+ Host
+ HTTP2-Einstellungen
+ If-Match
+ If-Modified-Since
+ If-None-Match
+ If-Range
+ If-Unmodified-Since
+ Max-Forwards
+ Ursprung
+ Pragma
+ Proxy-Authorization
+ Referer
+ Server
+ TE
+ Trailer
+ Transfer-Encoding
+ Upgrade
+ Via
+ Warnung
+ x-weiterleitet-\$1
+ x-amz-\$1
+ x-amzn-\$1
`QueryParameters` (Optional)
Fügt Schlüssel-Wert-Paare am Ende einer API-URL ein. Sie können Abfrageparameter als Zeichenfolge, JSON-Array oder JSON-Objekt angeben. Step FunctionsBeim Aufrufen einer HTTPS-API werden Abfrageparameter automatisch URL-kodiert.
Nehmen wir beispielsweise an, Sie möchten die Stripe-API aufrufen, um nach Kunden zu suchen, die ihre Transaktionen in US-Dollar (USD) tätigen. Stellen Sie sich vor, Sie haben Folgendes `QueryParameters` als Statuseingabe angegeben.
```
"QueryParameters": {
"currency": "usd"
}
```
Zur Laufzeit hängt Step Functions die wie folgt `QueryParameters` an die API-URL an.
```
https://api.stripe.com/v1/customers/search?currency=usd
```
Sie können auch einen [Referenzpfad](amazon-states-language-paths.md#amazon-states-language-reference-paths) verwenden, um die Abfrageparameter zur Laufzeit anzugeben. Beispiel, **"QueryParameters.\$1": "\$1.myQueryParameters"**.
Wenn Sie in Ihrer EventBridge Verbindung Abfrageparameter angegeben haben, Step Functions fügt diese Abfrageparameter den Abfrageparametern hinzu, die Sie in der HTTP-Aufgabendefinition angeben. Wenn dieselben Abfrageparameterschlüssel in der Definition und Verbindung vorhanden sind, Step Functions verwendet die entsprechenden Werte, die in der EventBridge Verbindung für diese Header angegeben wurden. Weitere Hinweise zur Durchführung der Step Functions Datenzusammenführung finden Sie unter. [EventBridgeVerbindungs- und HTTP-Aufgabendefinitionsdaten zusammenführen](#http-task-data-merge)
`Transform` (Optional)
Enthält die `RequestEncodingOptions` Felder `RequestBodyEncoding` und. Step FunctionsSendet den Anforderungstext standardmäßig als JSON-Daten an einen API-Endpunkt.
Wenn Ihr API-Anbieter `form-urlencoded` Anfragetexte akzeptiert, verwenden Sie das `Transform` Feld, um die URL-Kodierung für die Anfragetexte anzugeben. Sie müssen den `content-type` Header auch als angeben. `application/x-www-form-urlencoded` Step Functionsdann wird Ihr Anfragetext automatisch URL-kodiert.
`RequestBodyEncoding`
Gibt die URL-Kodierung Ihres Anfragetexts an. Sie können einen dieser Werte angeben: `NONE` oder. `URL_ENCODED`
+ `NONE`— Der Hauptteil der HTTP-Anfrage wird das serialisierte JSON des `RequestBody` Felds sein. Dies ist der Standardwert.
+ `URL_ENCODED`— Der Hauptteil der HTTP-Anfrage besteht aus den URL-codierten Formulardaten des Felds. `RequestBody`
`RequestEncodingOptions`
Bestimmt die Kodierungsoption, die für Arrays in Ihrem Anfragetext verwendet werden soll, wenn Sie diese Option festlegen. `RequestBodyEncoding` `URL_ENCODED`
Step Functionsunterstützt die folgenden Array-Kodierungsoptionen. Weitere Informationen zu diesen Optionen und ihren Beispielen finden Sie unter[Anwenden der URL-Codierung auf den Anforderungstext](#url-encode-request-body).
+ `INDICES`— Kodiert Arrays mithilfe des Indexwerts von Array-Elementen. Step FunctionsVerwendet standardmäßig diese Kodierungsoption.
+ `REPEAT`— Wiederholt einen Schlüssel für jedes Element in einem Array.
+ `COMMAS`— Kodiert alle Werte in einem Schlüssel als kommagetrennte Werteliste.
+ `BRACKETS`— Wiederholt einen Schlüssel für jedes Element in einem Array und hängt eine Klammer [] an den Schlüssel an, um anzuzeigen, dass es sich um ein Array handelt.
Im folgenden Beispiel wird die URL-Kodierung für die Hauptdaten der Anfrage festgelegt. Außerdem wird angegeben, dass die `COMMAS` Kodierungsoption für Arrays im Anforderungstext verwendet werden soll.
```
"Transform": {
"RequestBodyEncoding": "URL_ENCODED",
"RequestEncodingOptions": {
"ArrayFormat": "COMMAS"
}
}
```
`RequestBody` (Optional)
Akzeptiert JSON-Daten, die Sie in der Statuseingabe angeben. `RequestBody`In können Sie eine Kombination aus statischem JSON und [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)Syntax angeben. Angenommen, Sie geben die folgende Statuseingabe an:
```
{
"CardNumber": "1234567890",
"ExpiryDate": "09/25"
}
```
Um diese Werte von `CardNumber` und zur Laufzeit `ExpiryDate` in Ihrem Anfragetext zu verwenden, können Sie die folgenden JSON-Daten in Ihrem Anfragetext angeben.
```
"RequestBody": {
"Card": {
"Number.$": "$.CardNumber",
"Expiry.$": "$.ExpiryDate",
"Name": "John Doe",
"Address": "123 Any Street, Any Town, USA"
}
}
```
Wenn die HTTPS-API, die Sie aufrufen möchten, `form-urlencoded` Anfragetexte benötigt, müssen Sie die URL-Kodierung für Ihre Anfragetextdaten angeben. Weitere Informationen finden Sie unter [Anwenden der URL-Codierung auf den Anforderungstext](#url-encode-request-body).
## EventBridgeVerbindungs- und HTTP-Aufgabendefinitionsdaten zusammenführen
Wenn Sie eine HTTP-Task aufrufen, können Sie Daten in Ihrer EventBridge Verbindung und Ihrer HTTP-Aufgabendefinition angeben. Zu diesen Daten gehören `Headers``QueryParameters`, und `RequestBody` Parameter. Vor dem Aufrufen einer HTTPS-API führt Step Functions den Hauptteil der Anfrage in allen Fällen mit den Parametern des Verbindungstexts zusammen, es sei denn, Ihr Anfragetext ist eine Zeichenfolge und die Parameter für den Verbindungstext sind nicht leer. In diesem Fall schlägt die HTTP-Task mit dem `States.Runtime` Fehler fehl.
Wenn in der HTTP-Task-Definition und der EventBridge Verbindung doppelte Schlüssel angegeben sind, werden die Werte in der HTTP-Task mit den Werten in der Verbindung Step Functions überschrieben.
In der folgenden Liste wird beschrieben, wie Daten Step Functions zusammengeführt werden, bevor eine HTTPS-API aufgerufen wird:
+ **Header** — Step Functions Fügt alle Header, die Sie in der Verbindung angegeben haben, zu den Headern im `Headers` Feld der HTTP-Aufgabe hinzu. Wenn ein Konflikt zwischen den Header-Schlüsseln besteht, Step Functions verwendet die in der Verbindung angegebenen Werte für diese Header. Wenn Sie beispielsweise den `content-type` Header sowohl in der HTTP-Aufgabendefinition als auch in der EventBridge Verbindung angegeben haben, Step Functions verwendet es den in der Verbindung angegebenen `content-type` Header-Wert.
+ **Abfrageparameter** — Step Functions Fügt alle Abfrageparameter, die Sie in der Verbindung angegeben haben, den Abfrageparametern im `QueryParameters` Feld des HTTP-Tasks hinzu. Wenn ein Konflikt zwischen den Abfrageparameterschlüsseln besteht, Step Functions verwendet die in der Verbindung angegebenen Werte für diese Abfrageparameter. Wenn Sie beispielsweise den `maxItems` Abfrageparameter sowohl in der HTTP-Aufgabendefinition als auch in der EventBridge Verbindung angegeben haben, Step Functions wird der in der Verbindung angegebene `maxItems` Abfrageparameterwert verwendet.
+ **Body-Parameter**
+ Step Functionsfügt alle in der Verbindung angegebenen Werte des Anforderungstexts zum Anforderungstext im `RequestBody` Feld der HTTP-Task hinzu. Wenn ein Konflikt zwischen den Schlüsseln des Anforderungstexts besteht, Step Functions verwendet die in der Verbindung angegebenen Werte für den Anforderungstext. Angenommen, Sie haben ein `Mode` Feld sowohl in `RequestBody` der HTTP-Aufgabendefinition als auch in der EventBridge Verbindung angegeben. Step Functionsverwendet den `Mode` Feldwert, den Sie in der Verbindung angegeben haben.
+ Wenn Sie den Anforderungstext als Zeichenfolge statt als JSON-Objekt angeben und die EventBridge Verbindung auch den Anforderungstext enthält, Step Functions kann der an diesen beiden Stellen angegebene Anforderungstext nicht zusammengeführt werden. Die HTTP-Aufgabe schlägt mit dem `States.Runtime` Fehler fehl.
Step Functionswendet alle Transformationen an und serialisiert den Anforderungstext, nachdem die Zusammenführung des Anforderungstexts abgeschlossen ist.
Im folgenden Beispiel werden die `RequestBody` Felder `Headers``QueryParameters`, und sowohl in der HTTP-Aufgabe als auch in der HTTP-Verbindung festgelegt. EventBridge
**Definition der HTTP-Aufgabe**
```
{
"Comment": "Data merging example for HTTP Task and EventBridge connection",
"StartAt": "ListCustomers",
"States": {
"ListCustomers": {
"Type": "Task",
"Resource": "arn:aws:states:::http:invoke",
"Parameters": {
"Authentication": {
"ConnectionArn": "arn:aws:events:region:account-id:connection/Example/81210c42-8af1-456b-9c4a-6ff02fc664ac"
},
"ApiEndpoint": "https:/example.com/path",
"Method": "GET",
"Headers": {
"Request-Id": "my_request_id",
"Header-Param": "state_machine_header_param"
},
"RequestBody": {
"Job": "Software Engineer",
"Company": "AnyCompany",
"BodyParam": "state_machine_body_param"
},
"QueryParameters": {
"QueryParam": "state_machine_query_param"
}
}
}
}
}
```
**EventBridgeVerbindung**
```
{
"AuthorizationType": "API_KEY",
"AuthParameters": {
"ApiKeyAuthParameters": {
"ApiKeyName": "ApiKey",
"ApiKeyValue": "key_value"
},
"InvocationHttpParameters": {
"BodyParameters": [
{
"Key": "BodyParam",
"Value": "connection_body_param"
}
],
"HeaderParameters": [
{
"Key": "Header-Param",
"Value": "connection_header_param"
}
],
"QueryStringParameters": [
{
"Key": "QueryParam",
"Value": "connection_query_param"
}
]
}
}
}
```
In diesem Beispiel werden doppelte Schlüssel in der HTTP-Task und der EventBridge Verbindung angegeben. Step FunctionsÜberschreibt daher die Werte in der HTTP-Task mit den Werten in der Verbindung. Der folgende Codeausschnitt zeigt die HTTP-Anfrage, die an die Step Functions HTTPS-API gesendet wird.
```
POST /path?QueryParam=connection_query_param HTTP/1.1
Apikey: key_value
Content-Length: 79
Content-Type: application/json; charset=UTF-8
Header-Param: connection_header_param
Host: example.com
Range: bytes=0-262144
Request-Id: my_request_id
User-Agent: Amazon|StepFunctions|HttpInvoke|region
{"Job":"Software Engineer","Company":"AnyCompany","BodyParam":"connection_body_param"}
```
## Anwenden der URL-Codierung auf den Anforderungstext
Step FunctionsSendet den Anfragetext standardmäßig als JSON-Daten an einen API-Endpunkt. Wenn Ihr HTTPS-API-Anbieter `form-urlencoded` Anfragetexte benötigt, müssen Sie die URL-Kodierung für die Anfragetexte angeben. Step Functionsdann wird der Anfragetext automatisch auf der Grundlage der von Ihnen ausgewählten URL-Kodierungsoption URL-codiert.
Sie geben die URL-Kodierung mithilfe des Felds an. `Transform` Dieses Feld enthält das `RequestBodyEncoding` Feld, das angibt, ob Sie die URL-Kodierung für Ihre Anfragetexte anwenden möchten oder nicht. Wenn Sie das `RequestBodyEncoding` Feld angeben, wird Ihr JSON-Anforderungstext in den Anforderungstext Step Functions `form-urlencoded` konvertiert, bevor die HTTPS-API aufgerufen wird. Sie müssen auch den `content-type` Header angeben APIs , `application/x-www-form-urlencoded` denn wer URL-kodierte Daten akzeptiert, erwartet den Header. `content-type`
Step FunctionsStellt die folgenden Array-Kodierungsoptionen bereit, um Arrays in Ihrem Anfragetext zu kodieren.
+ `INDICES`— Wiederholt einen Schlüssel für jedes Element in einem Array und hängt eine Klammer [] an den Schlüssel an, um anzuzeigen, dass es sich um ein Array handelt. Diese eckigen Klammern enthalten den Index des Array-Elements. Wenn Sie den Index hinzufügen, können Sie die Reihenfolge der Array-Elemente angeben. Step FunctionsVerwendet standardmäßig diese Kodierungsoption.
Zum Beispiel, wenn Ihr Anfragetext das folgende Array enthält.
```
{"array": ["a","b","c","d"]}
```
Step Functionskodiert dieses Array in die folgende Zeichenfolge.
```
array[0]=a&array[1]=b&array[2]=c&array[3]=d
```
+ `REPEAT`— Wiederholt einen Schlüssel für jedes Element in einem Array.
Zum Beispiel, wenn Ihr Anfragetext das folgende Array enthält.
```
{"array": ["a","b","c","d"]}
```
Step Functionskodiert dieses Array in die folgende Zeichenfolge.
```
array=a&array=b&array=c&array=d
```
+ `COMMAS`— Kodiert alle Werte in einem Schlüssel als kommagetrennte Werteliste.
Zum Beispiel, wenn Ihr Anfragetext das folgende Array enthält.
```
{"array": ["a","b","c","d"]}
```
Step Functionskodiert dieses Array in die folgende Zeichenfolge.
```
array=a,b,c,d
```
+ `BRACKETS`— Wiederholt einen Schlüssel für jedes Element in einem Array und hängt eine Klammer [] an den Schlüssel an, um anzuzeigen, dass es sich um ein Array handelt.
Zum Beispiel, wenn Ihr Anfragetext das folgende Array enthält.
```
{"array": ["a","b","c","d"]}
```
Step Functionskodiert dieses Array in die folgende Zeichenfolge.
```
array[]=a&array[]=b&array[]=c&array[]=d
```
## IAM-Berechtigungen zum Ausführen einer HTTP-Aufgabe
Ihre State-Machine-Ausführungsrolle muss über die folgenden Berechtigungen verfügen, damit ein HTTP-Task eine HTTPS-API aufrufen kann:
+ `states:InvokeHTTPEndpoint`
+ `events:RetrieveConnectionCredentials`
+ `secretsmanager:GetSecretValue`
+ `secretsmanager:DescribeSecret`
Das folgende Beispiel für eine IAM-Richtlinie gewährt Ihrer State-Machine-Rolle die geringsten Rechte, die für den Aufruf von Stripe APIs erforderlich sind. Diese IAM-Richtlinie gewährt der State-Machine-Rolle auch die Erlaubnis, auf eine bestimmte EventBridge Verbindung zuzugreifen, einschließlich des Geheimnisses für diese Verbindung, das in Secrets Manager gespeichert ist.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Action": "states:InvokeHTTPEndpoint",
"Resource": "arn:aws:states:us-east-2:123456789012:stateMachine:myStateMachine",
"Condition": {
"StringEquals": {
"states:HTTPMethod": "GET"
},
"StringLike": {
"states:HTTPEndpoint": "https://api.stripe.com/*"
}
}
},
{
"Sid": "Statement2",
"Effect": "Allow",
"Action": [
"events:RetrieveConnectionCredentials"
],
"Resource": "arn:aws:events:us-east-2:123456789012:connection/oauth_connection/aeabd89e-d39c-4181-9486-9fe03e6f286a"
},
{
"Sid": "Statement3",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
}
]
}
```
## Beispiel für eine HTTP-Aufgabe
Die folgende State-Machine-Definition zeigt einen HTTP-Task`Headers`, der die `RequestBody` Parameter `QueryParameters``Transform`,, und enthält. Die HTTP-Aufgabe ruft eine Stripe-API ( https://api.stripe.com/v1/Rechnungen) auf, um eine Rechnung zu generieren. Die HTTP-Aufgabe spezifiziert auch die URL-Kodierung für den Anfragetext mithilfe der `INDICES` Kodierungsoption.
Stellen Sie sicher, dass Sie eine EventBridge Verbindung hergestellt haben. Das folgende Beispiel zeigt eine Verbindung, die mit dem Basic-Authentifizierungstyp erstellt wurde.
```
{
"Type": "BASIC",
"AuthParameters": {
"BasicAuthParameters": {
"Password": "myPassword",
"Username": "myUsername"
},
}
}
```
Denken Sie daran, den *italicized* Text durch Ihre ressourcenspezifischen Informationen zu ersetzen.
```
{
"Comment": "A state machine that uses HTTP Task",
"StartAt": "CreateInvoiceAPI",
"States": {
"CreateInvoiceAPI": {
"Type": "Task",
"Resource": "arn:aws:states:::http:invoke",
"Parameters": {
"ApiEndpoint": "https://api.stripe.com/v1/invoices",
"Method": "POST",
"Authentication": {
"ConnectionArn": ""arn:aws:events:region:account-id:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
},
"Headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
"RequestBody": {
"customer.$": "$.customer_id",
"description": "Monthly subscription",
"metadata": {
"order_details": "monthly report data"
}
},
"Transform": {
"RequestBodyEncoding": "URL_ENCODED",
"RequestEncodingOptions": {
"ArrayFormat": "INDICES"
}
}
},
"Retry": [
{
"ErrorEquals": [
"States.Http.StatusCode.429",
"States.Http.StatusCode.503",
"States.Http.StatusCode.504",
"States.Http.StatusCode.502"
],
"BackoffRate": 2,
"IntervalSeconds": 1,
"MaxAttempts": 3,
"JitterStrategy": "FULL"
}
],
"Catch": [
{
"ErrorEquals": [
"States.Http.StatusCode.404",
"States.Http.StatusCode.400",
"States.Http.StatusCode.401",
"States.Http.StatusCode.409",
"States.Http.StatusCode.500"
],
"Comment": "Handle all non 200 ",
"Next": "HandleInvoiceFailure"
}
],
"End": true
}
}
}
```
Um diesen Zustandsmaschine auszuführen, geben Sie die Kunden-ID als Eingabe ein, wie im folgenden Beispiel gezeigt:
```
{
"customer_id": "1234567890"
}
```
Das folgende Beispiel zeigt die HTTP-Anfrage, die Step Functions an die Stripe-API gesendet wird.
```
POST /v1/invoices HTTP/1.1
Authorization: Basic
Content-Type: application/x-www-form-urlencoded
Host: api.stripe.com
Range: bytes=0-262144
Transfer-Encoding: chunked
User-Agent: Amazon|StepFunctions|HttpInvoke|region
description=Monthly%20subscription&metadata%5Border_details%5D=monthly%20report%20data&customer=1234567890
```
## Testen einer HTTP-Aufgabe
Sie können die [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API über die Konsole, das SDK oder das verwenden, AWS CLI um eine HTTP-Task zu [testen](test-state-isolation.md). Das folgende Verfahren beschreibt, wie die TestState API in der Step Functions Konsole verwendet wird. Sie können die API-Anfrage, die Antwort und die Authentifizierungsdetails iterativ testen, bis Ihre HTTP-Aufgabe wie erwartet funktioniert.
**Testen Sie den Status einer HTTP-Task in der Konsole Step Functions**
1. Öffnen Sie die [Step Functions Functions-Konsole](https://console.aws.amazon.com/states/home?region=us-east-1#/).
1. Wählen Sie **Create State Machine**, um mit der Erstellung einer State-Machine zu beginnen, oder wählen Sie eine bestehende State-Machine aus, die eine HTTP-Task enthält.
Lesen Sie Schritt 4, wenn Sie die Aufgabe in einer vorhandenen Zustandsmaschine testen.
1. Konfigurieren Sie in Workflow Studio eine HTTP-Aufgabe visuell. [Entwurfsmodus](workflow-studio.md#wfs-interface-design-mode) Oder wählen Sie den Codemodus, um die State-Machine-Definition aus Ihrer lokalen Entwicklungsumgebung zu kopieren und einzufügen.
1. Wählen Sie im Entwurfsmodus im [Inspektor-Panel](workflow-studio.md#workflow-studio-components-formdefinition) Bedienfeld von Workflow Studio die Option **Teststatus** aus.
1. Gehen Sie im Dialogfeld **Teststatus** wie folgt vor:
1. Wählen Sie **unter Ausführungsrolle** eine Ausführungsrolle aus, um den Status zu testen. Wenn Sie nicht über eine Rolle mit [ausreichenden Berechtigungen](#connect-http-task-permissions) für eine HTTP-Aufgabe verfügen, finden Sie weitere Informationen unter [Rolle zum Testen von HTTP-Aufgaben in Workflow Studio](manage-state-machine-permissions.md#test-state-role-http) So erstellen Sie eine Rolle.
1. (Optional) Geben Sie alle JSON-Eingaben an, die Ihr ausgewählter Bundesstaat für den Test benötigt.
1. Behalten Sie für **Inspection Level** die Standardauswahl **INFO** bei. Diese Stufe zeigt Ihnen den Status des API-Aufrufs und die Statusausgabe. Dies ist nützlich, um die API-Antwort schnell zu überprüfen.
1. Wählen Sie **Test starten**.
1. Wenn der Test erfolgreich ist, wird die Statusausgabe auf der rechten Seite des Dialogfelds **Teststatus** angezeigt. Schlägt der Test fehl, wird ein Fehler angezeigt.
Auf der Registerkarte **Statusdetails** des Dialogfelds können Sie die Statusdefinition und einen Link zu Ihrer [EventBridgeVerbindung](#http-task-authentication) sehen.
1. Ändern Sie die **Inspektionsebene auf** **TRACE**. Diese Stufe zeigt Ihnen die unverarbeitete HTTP-Anfrage und -Antwort und ist nützlich, um Header, Abfrageparameter und andere API-spezifische Details zu überprüfen.
1. **Aktivieren Sie das Kontrollkästchen Geheimnisse enthüllen.** In Kombination mit **TRACE** können Sie mit dieser Einstellung die vertraulichen Daten sehen, die die EventBridge Verbindung einfügt, z. B. API-Schlüssel. Die IAM Benutzeridentität, die Sie für den Zugriff auf die Konsole verwenden, muss berechtigt sein, die `states:RevealSecrets` Aktion auszuführen. Ohne diese Berechtigung wird beim Starten des Tests die Fehlermeldung „Zugriff verweigert“ ausgegeben. Step Functions Ein Beispiel für eine IAM Richtlinie, die die `states:RevealSecrets` Berechtigung festlegt, finden Sie unter[IAMBerechtigungen für die Verwendung der TestState API](test-state-isolation.md#test-state-permissions).
Die folgende Abbildung zeigt einen erfolgreichen Test für eine HTTP-Aufgabe. Die **Inspektionsebene** für diesen Status ist auf **TRACE** festgelegt. Die Registerkarte „**HTTP-Anfrage und Antwort**“ in der folgenden Abbildung zeigt das Ergebnis des HTTPS-API-Aufrufs.
![\[Ausgabe eines ausgewählten Status, der den Test für die TRACE-Stufe erfolgreich abgeschlossen hat.\]](http://docs.aws.amazon.com/de_de/step-functions/latest/dg/images/test-state-trace-success.png)
1. Wählen Sie **Test starten**.
1. Wenn der Test erfolgreich ist, können Sie Ihre HTTP-Details auf der Registerkarte **HTTP-Anfrage und -Antwort** sehen.
## Antworten auf HTTP-Aufgaben werden nicht unterstützt
Eine HTTP-Aufgabe schlägt mit dem `States.Runtime` Fehler fehl, wenn eine der folgenden Bedingungen für die zurückgegebene Antwort zutrifft:
+ Die Antwort enthält einen Inhaltstyp-Header von`application/octet-stream`, `image/*``video/*`, oder. `audio/*`
+ Die Antwort kann nicht als gültige Zeichenfolge gelesen werden. Zum Beispiel Binär- oder Bilddaten.
## Verbindungsfehler
Wenn bei EventBridge der Verbindung mit der angegebenen API während der Workflow-Ausführung ein Problem auftritt, löst Step Functions den Fehler in Ihrem Workflow aus. Verbindungsfehlern wird ein Präfix vorangestellt`Events.ConnectionResource.`.
Zu diesen Fehlern gehören:
+ `Events.ConnectionResource.InvalidConnectionState`
+ `Events.ConnectionResource.InvalidPrivateConnectionState`
+ `Events.ConnectionResource.AccessDenied`
+ `Events.ConnectionResource.ResourceNotFound`
+ `Events.ConnectionResource.AuthInProgress`
+ `Events.ConnectionResource.ConcurrentModification`
+ `Events.ConnectionResource.InternalError`