Rufen Sie Drittanbieter APIs in Step Functions Functions-Workflows auf

Eine HTTP Aufgabe ist eine Art von Workflow-Status der Aufgabe Status, mit dem Sie in Ihren Workflows beliebige öffentliche Drittanbieter API wie Salesforce und Stripe aufrufen können. Um einen Drittanbieter anzurufenAPI, verwenden Sie den Aufgabenstatus 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 Authentifizierungsdetails.

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.

HTTPDefinition der Aufgabe

Die ASLDefinition stellt eine HTTP Aufgabe mit http:invoke Ressource dar. Die folgende HTTP Aufgabendefinition ruft einen Stripe aufAPI, der eine Liste aller Kunden zurückgibt.

"Call third-party 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
}

HTTPAufgabenfelder

Eine HTTP Aufgabe umfasst die folgenden Felder in ihrer Definition.

Authentifizierung für eine Aufgabe HTTP

Für eine HTTP Aufgabe ist eine EventBridge Verbindung erforderlich, die die Authentifizierungsdaten eines API Anbieters sicher verwaltet. Eine Verbindung gibt den Autorisierungstyp und die Anmeldeinformationen an, die für die Autorisierung eines Drittanbieters API verwendet werden sollen. 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 Authentifizierungsdetails 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 einen Drittanbieter aufruftAPI.

Wenn Sie eine Verbindung herstellen und Autorisierungsparameter hinzufügen, EventBridge erstellt ein Secret in AWS Secrets Manager. In diesem Secret EventBridge werden die Verbindungs- und Autorisierungsparameter in verschlüsselter Form gespeichert. 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 unterIAMBerechtigungen zum Ausführen einer Aufgabe HTTP.

Die folgende Abbildung zeigt, wie die Authentifizierung für API Anrufe von Drittanbietern über eine EventBridge Verbindung Step Functions gehandhabt wird. Die EventBridge Verbindung, die die Anmeldeinformationen eines API Drittanbieters verwaltet. EventBridgeerstellt ein GeheimnisSecrets Manager, um die Verbindungs- und Autorisierungsparameter in verschlüsselter Form zu speichern.

EventBridgeVerbindungs- und HTTP Aufgabendefinitionsdaten zusammenführen

Wenn Sie eine HTTP Aufgabe 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 eines Drittanbieters API führt Step Functions in allen Fällen den Anforderungstext 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 und der EventBridge Verbindung doppelte Schlüssel angegeben sind, werden die Werte in der HTTP Aufgabe mit den Werten in der Verbindung Step Functions überschrieben.

In der folgenden Liste wird beschrieben, wie Daten Step Functions zusammengeführt werden, bevor ein Drittanbieter aufgerufen wird: API

Im folgenden Beispiel werden die RequestBody Felder HeadersQueryParameters, und sowohl in der Aufgabe als auch in der HTTP Verbindung festgelegt. EventBridge

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

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 Aufgabe und der EventBridge Verbindung angegeben. Step FunctionsÜberschreibt daher die Werte in der HTTP Aufgabe mit den Werten in der Verbindung. Der folgende Codeausschnitt zeigt die HTTP Anfrage, die Step Functions an den Drittanbieter gesendet wird. 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"}

Anwenden von URL -encoding auf den Hauptteil der Anfrage

Standardmäßig Step Functions sendet der Anfragetext als JSON Daten an einen API Endpunkt. Wenn Ihr API Drittanbieter form-urlencoded Anforderungstexte benötigt, müssen Sie URL -encoding für die Anfragetexte angeben. Step FunctionsURLkodiert 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, wird Ihr JSON Anfragetext in den form-urlencoded Anfragetext Step Functions konvertiert, bevor der Drittanbieter API aufgerufen wird. Sie müssen auch den content-type Header angebenAPIs, application/x-www-form-urlencoded da die URL Accept-codierten Daten den content-type Header erwarten.

Step FunctionsStellt die folgenden Array-Kodierungsoptionen bereit, um Arrays in Ihrem Anfragetext zu kodieren.

IAMBerechtigungen zum Ausführen einer Aufgabe HTTP

Ihre State-Machine-Ausführungsrolle muss über die secretsmanager:DescribeSecret Berechtigungen states:InvokeHTTPEndpointevents:RetrieveConnectionCredentials,secretsmanager:GetSecretValue, und verfügen, damit eine HTTP Aufgabe einen Drittanbieter aufrufen kannAPI. 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.

Vergewissern Sie sich, 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, 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: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, die Step Functions an den Stripe gesendet wirdAPI.

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 Konsole verwenden. 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: