Workflows mit Step Functions aufrufen HTTPS APIs

Eine HTTP Aufgabe ist eine Art von Workflow-Status der Aufgabe Status, mit dem Sie HTTPS API in Ihren Workflows eine Aufgabe aufrufen können. APISie können öffentlich sein, z. B. SaaS-Anwendungen von Drittanbietern wie Stripe oder Salesforce. Sie können auch private Anwendungen aufrufenAPI, z. B. HTTPS basierte Anwendungen in einer Amazon Virtual Private Cloud.

Für die Autorisierung und Netzwerkkonnektivität benötigt eine HTTP Aufgabe eine EventBridge Verbindung.

Um eine aufzurufen HTTPSAPI, verwenden Sie den Task-Status mit der arn:aws:states:::http:invoke Ressource. Geben Sie dann die Details zur API Endpunktkonfiguration an, z. B. die Methode APIURL, die Sie verwenden möchten, und Verbindungsdetails.

Wenn Sie Workflow Studio verwenden, um Ihren Zustandsmaschine zu erstellen, der eine HTTP Aufgabe enthält, generiert Workflow Studio automatisch eine Ausführungsrolle mit IAM Richtlinien für die HTTP Aufgabe. Weitere Informationen finden Sie unter Rolle zum Testen von HTTP Aufgaben in Workflow Studio.

Konnektivität für eine HTTP Aufgabe

Eine HTTP Aufgabe erfordert eine EventBridgeVerbindung, die die Authentifizierungsdaten eines API Anbieters sicher verwaltet. Eine Verbindung definiert die Autorisierungsmethode und die Anmeldeinformationen, die verwendet werden sollen, um eine Verbindung zu einer bestimmten Verbindung herzustellenAPI. Wenn Sie eine Verbindung zu einer privaten Verbindung herstellenAPI, z. B. zu einer privaten Verbindung API in einer Amazon Virtual Private Cloud (AmazonVPC), 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 verhindern, dass Geheimnisse wie API Schlüssel fest in Ihre Zustandsmaschinen-Definition eingebunden werden. Eine EventBridge Verbindung unterstützt die Autorisierungsschemata BasicOAuth, 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 einem erforderlich sindAPI. Sie müssen die Verbindung ARN in jede HTTP Aufgabe aufnehmen, die eine aufruft HTTPSAPI.

Wenn Sie eine Verbindung herstellen, EventBridge erstellt ein Geheimnis 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. Für weitere Informationen über IAM Berechtigungen, die Ihr Zustandsmaschine für den Zugriff auf eine EventBridge Verbindung benötigt, finden Sie unterIAMBerechtigungen zum Ausführen einer Aufgabe HTTP.

Die folgende Abbildung zeigt, wie Step Functions verarbeitet die Autorisierung von HTTPS API Anrufen mit einem EventBridge Verbindung. Das Tool EventBridge Die Verbindung verwaltet die Anmeldeinformationen eines HTTPS API Anbieters. EventBridge erstellt ein Geheimnis in Secrets Manager um die Verbindungs- und Autorisierungsparameter in verschlüsselter Form zu speichern. Speichert im privaten APIs Fall EventBridge auch Netzwerkkonnektivitätskonfigurationen.

HTTPDefinition der Aufgabe

Die ASLDefinition stellt eine HTTP Aufgabe mit http:invoke Ressource dar. Die folgende HTTP Aufgabendefinition ruft einen öffentlichen Stripe aufAPI, der 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:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
    },
    "Method": "GET"
  },
  "End": true
}

HTTPFelder für Aufgaben

Eine HTTP Aufgabe umfasst die folgenden Felder in ihrer Definition.

Zusammenführen EventBridge Verbindungs- und HTTP Aufgabendefinitionsdaten

Wenn Sie eine HTTP Aufgabe aufrufen, können Sie Daten in Ihrem angeben EventBridge Verbindung und Ihre HTTP Aufgabendefinition. Diese Daten beinhalten HeadersQueryParameters, und RequestBody Parameter. Vor dem HTTPS API Aufrufen von führt Step Functions in allen Fällen den Hauptteil der Anfrage mit den Parametern des Verbindungstexts zusammen, es sei denn, Ihr Anforderungstext ist eine Zeichenfolge und die Parameter für den Verbindungstext sind nicht leer. In diesem Fall schlägt die HTTP Aufgabe mit dem States.Runtime Fehler fehl.

Wenn in der HTTP Aufgabendefinition doppelte Schlüssel angegeben sind und EventBridge Verbindung, Step Functions überschreibt die Werte in der HTTP Aufgabe mit den Werten in der Verbindung.

In der folgenden Liste wird beschrieben, wie Step Functions führt Daten zusammen, bevor ein HTTPS API aufgerufen wird:

Im folgenden Beispiel werden die FelderHeaders, und sowohl in Task als QueryParameters auch in den RequestBody Feldern Task und festgelegt HTTP EventBridge Verbindung.

HTTPAufgabendefinition

{
  "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:us-east-1:123456789012: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"
        }
      }
    }
  }
}

EventBridge Verbindung

{
  "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 Aufgabe angegeben und EventBridge Verbindung. Daher Step Functions überschreibt die Werte in der HTTP Aufgabe mit den Werten in der Verbindung. Der folgende Codeausschnitt zeigt die Anfrage HTTP Step Functions sendet an die. HTTPS API

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|us-east-1

{"Job":"Software Engineer","Company":"AnyCompany","BodyParam":"connection_body_param"}

Wendet URL -Encoding auf den Hauptteil der Anfrage an

Standardmäßig Step Functions sendet den Anforderungstext als JSON Daten an einen API Endpunkt. Wenn Ihr HTTPS API Anbieter form-urlencoded Anforderungstexte benötigt, müssen Sie URL -encoding für die Anfragetexte angeben. Step Functions URLkodiert dann automatisch den Anfragetext auf der Grundlage der von Ihnen ausgewählten Option URL -encoding.

Sie geben URL -encoding 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, Step Functions konvertiert den Hauptteil Ihrer JSON Anfrage in den form-urlencoded Hauptteil der Anfrage, bevor Sie den aufrufen HTTPSAPI. Sie müssen auch den content-type Header angebenAPIs, application/x-www-form-urlencoded da die URL Accept-kodierten Daten den content-type Header erwarten.

Um Arrays in Ihrem Anfragetext zu kodieren, Step Functions bietet die folgenden Optionen zur Array-Kodierung.

IAMBerechtigungen zum Ausführen einer Aufgabe HTTP

Ihre State-Machine-Ausführungsrolle muss über die folgenden Berechtigungen verfügen, damit ein HTTP Task eine aufrufen kann HTTPSAPI:

Das folgende IAM Richtlinienbeispiel gewährt Ihrer State-Machine-Rolle die geringsten Rechte, die für den Aufruf von Stripe erforderlich sindAPIs. 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/*"
        }
    ]
}

HTTPBeispiel für eine Aufgabe

Die folgende State-Machine-Definition zeigt eine HTTP AufgabeHeaders, die die RequestBody ParameterQueryParameters,Transform, und enthält. Die HTTP Aufgabe ruft einen Stripe API ( https://api.stripe.com/v1/Rechnungen) auf, um eine Rechnung zu generieren. Die HTTP Aufgabe spezifiziert außerdem URL -encoding für den Anforderungstext mithilfe der INDICES Kodierungsoption.

Stellen Sie sicher, dass Sie eine erstellt haben EventBridge Verbindung. 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:us-east-2:123456789012: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 Step Functions sendet an den StripeAPI.

POST /v1/invoices HTTP/1.1
Authorization: Basic <base64 of username and password>
Content-Type: application/x-www-form-urlencoded
Host: api.stripe.com
Range: bytes=0-262144
Transfer-Encoding: chunked
User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1

description=Monthly%20subscription&metadata%5Border_details%5D=monthly%20report%20data&customer=1234567890

Eine HTTP Aufgabe testen

Sie können das TestStateAPIüber die Konsole oder das verwendenSDK, AWS CLI um eine HTTP Aufgabe zu testen. Das folgende Verfahren beschreibt, wie Sie den TestState API in der Step Functions console. Sie können die API Anfrage-, Antwort- und Authentifizierungsdetails iterativ testen, bis Ihre HTTP Aufgabe erwartungsgemäß funktioniert.

Antworten auf Aufgaben werden nicht unterstützt HTTP

Eine HTTP Aufgabe schlägt mit dem States.Runtime Fehler fehl, wenn eine der folgenden Bedingungen für die zurückgegebene Antwort zutrifft:

Verbindungsfehler

Wenn bei EventBridge der Verbindung mit dem 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 vorangestelltEvents.ConnectionResource..

Zu diesen Fehlern gehören: