Rufen Sie HTTPS APIs in Step Functions Functions-Workflows auf

Ein HTTP-Task ist ein Workflow-Status der Aufgabe Statustyp, mit dem Sie in Ihren Workflows eine HTTPS-API aufrufen können. 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 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.

Wenn Sie Workflow Studio 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.

Konnektivität für eine HTTP-Task

Ein HTTP-Task erfordert eine EventBridgeVerbindung, 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 verhindern, dass Geheimnisse wie API-Schlüssel fest in Ihre Zustandsmaschinen-Definition integriert werden. Eine EventBridge Verbindung unterstützt die Autorisierungsschemata Basic und API Key. OAuth

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 Secret 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 unterIAM-Berechtigungen zum Ausführen einer HTTP-Aufgabe.

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 GeheimnisSecrets Manager, um die Verbindungs- und Autorisierungsparameter in verschlüsselter Form zu speichern. Speichert im Fall von Private APIs EventBridge auch Netzwerkkonnektivitätskonfigurationen.

Definition der HTTP-Aufgabe

Die ASL-Definition 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.

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 HeadersQueryParameters, 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:

Im folgenden Beispiel werden die RequestBody Felder HeadersQueryParameters, 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"}

URL-Kodierung auf den Anfragetext anwenden

Step FunctionsSendet den Anforderungstext 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.

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:

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:account-id: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:account-id: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-TaskHeaders, der die RequestBody Parameter QueryParametersTransform,, 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 <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|region

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

Testen einer HTTP-Aufgabe

Sie können die TestStateAPI über die Konsole, das SDK oder das verwenden, AWS CLI um eine HTTP-Task zu testen. Das folgende Verfahren beschreibt, wie die TestState API in der Step Functions Konsole verwendet wird. Sie können die API-Anfrage, Antwort und Authentifizierungsdetails iterativ testen, bis Ihre HTTP-Aufgabe wie erwartet funktioniert.

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:

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 vorangestelltEvents.ConnectionResource..

Zu diesen Fehlern gehören: