Rufen Sie HTTPS-APIs in Step Functions-Workflows auf

Eine HTTP-Task ist eine Art von Workflow-Status der Aufgabe Geben Sie an, mit dem Sie HTTPS-APIs in Ihren Workflows aufrufen können. Die API kann öffentlich sein, z. B. SaaS-Anwendungen von Drittanbietern wie Stripe oder Salesforce. Sie können auch eine private API aufrufen, z. B. HTTPS-based 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 die Aufgabe Staat mit dem 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 Verbindung Einzelheiten.

Wenn du verwendest Workflow Studio 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

Eine HTTP-Task erfordert eine EventBridge Verbindung, das die Authentifizierungsdaten eines API-Anbieters sicher verwaltet. EIN 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. zu einer privaten API in einer Amazon Virtual Private Cloud (Amazon VPC), können Sie die Verbindung auch verwenden, um eine sichere Punkt-zu-Punkt-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. Und EventBridge Die Verbindung unterstützt die Autorisierungsschemata Basic, OAuth und API Key.

Wenn Sie eine erstellen EventBridge Bei der Verbindung 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-Task einbeziehen, die eine HTTPS-API aufruft.

Wenn Sie eine Verbindung erstellen, EventBridge erstellt eine Geheimnis in AWS Secrets Manager. In diesem Geheimnis EventBridge speichert die Verbindungs- und Autorisierungsparameter in verschlüsselter Form. Um eine Verbindung erfolgreich zu erstellen oder zu aktualisieren, müssen Sie eine verwenden AWS-Konto das die Erlaubnis hat, Secrets Manager zu verwenden. Für weitere Informationen über den IAM Berechtigungen, die Ihre Zustandsmaschine benötigt, um auf eine zuzugreifen EventBridge Verbindung, siehe IAM-Berechtigungen zum Ausführen einer HTTP-Task.

Das folgende Bild zeigt, wie Step Functions verarbeitet die Autorisierung für HTTPS-API-Aufrufe mithilfe einer EventBridge Verbindung. Die EventBridge Die Verbindung verwaltet die Anmeldeinformationen eines HTTPS-API-Anbieters. EventBridge erstellt eine Geheimnis in Secrets Manager um die Verbindungs- und Autorisierungsparameter in verschlüsselter Form zu speichern. Im Fall von privaten APIs EventBridge speichert auch die Konfigurationen der Netzwerkkonnektivität.

HTTP-Aufgabendefinition

Die ASL-Definition steht für eine HTTP-Task mit http:invoke Ressource. 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
}

HTTP-Aufgabenfelder

Eine HTTP-Task enthält die folgenden Felder in ihrer Definition.

Zusammenführen EventBridge Verbindungs- und HTTP-Aufgabendefinitionsdaten

Wenn Sie eine HTTP-Task aufrufen, können Sie Daten in Ihrem angeben EventBridge Verbindung und Ihre HTTP-Task-Definition. Diese Daten beinhalten Headers, QueryParameters, und RequestBody Parameter. Vor dem Aufrufen einer HTTPS-API führt Step Functions in allen Fällen den Anforderungstext mit den Verbindungstextparametern zusammen, außer wenn Ihr Anforderungstext eine Zeichenfolge ist und die Verbindungstextparameter nicht leer sind. In diesem Fall schlägt die HTTP-Task mit dem fehl States.Runtime Fehler.

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

Die folgende Liste beschreibt, wie Step Functions führt Daten zusammen, bevor eine HTTPS-API aufgerufen wird:

Das folgende Beispiel legt fest Headers, QueryParameters, und RequestBody Felder sowohl in der HTTP-Task als auch EventBridge Verbindung.

HTTP-Aufgabendefinition

{
  "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"
        }
      }
    }
  }
}

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-Task angegeben und EventBridge Verbindung. Deshalb Step Functions überschreibt die Werte in der HTTP-Task mit den Werten in der Verbindung. Der folgende Codeausschnitt zeigt die HTTP-Anfrage, die 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|region

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

Bewerben URL-encoding auf Anfrage (Text)

Standardmäßig Step Functions sendet den Anforderungstext als JSON-Daten an einen API-Endpunkt. Wenn Ihr HTTPS-API-Anbieter dies erfordert form-urlencoded Anforderungstexte müssen Sie angeben URL-encoding für die Anforderungstexte. Step Functions dann automatisch URL-encodes der Anfragetext basiert auf dem URL-encoding Option, die Sie auswählen.

Sie spezifizieren URL-encoding mit dem Transform Feld. Dieses Feld enthält RequestBodyEncoding Feld, das angibt, ob Sie sich bewerben möchten oder nicht URL-encoding für Ihre Anfragetexte. Wenn Sie das angeben RequestBodyEncoding Feld, Step Functions konvertiert Ihren JSON-Anforderungstext in form-urlencoded Anforderungstext, bevor die HTTPS-API aufgerufen wird. Sie müssen auch das angeben content-type Kopfzeile als application/x-www-form-urlencoded weil APIs, die akzeptieren URL-encoded Daten erwarten die content-type Kopfzeile.

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

IAM-Berechtigungen zum Ausführen einer HTTP-Task

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

Das folgende Beispiel für eine IAM-Richtlinie gewährt Ihrer State-Machine-Rolle die geringsten Berechtigungen, 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, einschließlich des Geheimnisses für diese Verbindung, das in Secrets Manager gespeichert ist.

Beispiel für eine HTTP-Aufgabe

Die folgende State-Machine-Definition zeigt eine HTTP-Task, die Folgendes beinhaltet Headers, QueryParameters, Transform, und RequestBody Parameter. Die HTTP-Task ruft eine Stripe-API auf, https://api.stripe.com/v1/invoices, um eine Rechnung zu generieren. Die HTTP-Task spezifiziert außerdem URL-encoding für den Anfragetext unter Verwendung der INDICES Kodierungsoption.

Stellen Sie sicher, dass Sie eine erstellt haben EventBridge Verbindung. Das folgende Beispiel zeigt eine Verbindung, die mit dem Authentifizierungstyp BASIC erstellt wurde.

{
    "Type": "BASIC",
    "AuthParameters": { 
        "BasicAuthParameters": { 
            "Password": "myPassword",
            "Username": "myUsername"
         },
    }
}

Denken Sie daran, das zu ersetzen italicized Text mit Ihren ressourcenspezifischen Informationen.

{
  "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 State Machine 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 sendet an die Stripe-API.

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

Eine HTTP-Aufgabe testen

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

Antworten auf HTTP-Tasks werden nicht unterstützt

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

Verbindungsfehler

Wenn EventBridge bei 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: