Entdecken Sie Serviceintegrationsmuster in Step Functions

AWS Step Functions lässt sich direkt in Dienste in der Sprache der Amazon-Staaten integrieren. Sie können diese kontrollieren AWS Dienste, die drei Dienstintegrationsmuster verwenden:

• Rufen Sie einen Dienst auf und lassen Sie Step Functions sofort zum nächsten Status übergehen, nachdem es eine HTTP Antwort erhalten hat.

• Rufen Sie einen Service auf und lassen Sie Step Functions warten, bis ein Job abgeschlossen ist.

• Rufen Sie einen Dienst mit einem Task-Token auf und lassen Sie Step Functions warten, bis dieses Token mit einer Nutzlast zurückgegeben wird.

Jedes dieser Serviceintegrationsmuster wird dadurch gesteuert, wie Sie es URI im "Resource" Feld Ihrer Aufgabendefinition erstellen.

Für Informationen zur Konfiguration AWS Identity and Access Management (IAM) Informationen zu integrierten Diensten finden Sie unterSo generiert Step Functions IAM Richtlinien für integrierte Dienste.

Unterstützung von Integrationsmustern

Standard-Workflows und Express-Workflows unterstützen dieselben Integrationen, aber nicht dieselben Integrationsmuster.

• Standard-Workflows unterstützen Request Response-Integrationen. Bestimmte Dienste unterstützen Run a Job (.sync) oder Wait for Callback (. waitForTaskToken) und in einigen Fällen beides. Einzelheiten finden Sie in der folgenden Tabelle mit optimierten Integrationen.

• Express Workflows unterstützen nur Request Response-Integrationen.

Informationen zur Entscheidung zwischen den beiden Typen finden Sie unterWorkflowtyp in Step Functions auswählen.

AWS SDKIntegrationen in Step Functions

Integrierter Service	Request Response (Antwort anfordern)	Einen Job ausführen - .sync	Warte auf Rückruf -. waitForTaskWertmarke
Über zweihundert Dienste	Standard und Express	Wird nicht unterstützt	Standard

Optimierte Integrationen in Step Functions

Integrierter Service	Request Response (Antwort anfordern)	Einen Job ausführen - .sync	Warte auf Rückruf -. waitForTaskWertmarke
Amazon API Gateway	Standard und Express	Wird nicht unterstützt	Standard
Amazon Athena	Standard und Express	Standard	Wird nicht unterstützt
AWS Batch	Standard und Express	Standard	Wird nicht unterstützt
Amazon Bedrock	Standard und Express	Standard	Standard
AWS CodeBuild	Standard und Express	Standard	Wird nicht unterstützt
Amazon DynamoDB	Standard und Express	Wird nicht unterstützt	Wird nicht unterstützt
Amazon ECS/Fargate	Standard und Express	Standard	Standard
Amazon EKS	Standard und Express	Standard	Standard
Amazon EMR	Standard und Express	Standard	Wird nicht unterstützt
Amazon EMR on EKS	Standard und Express	Standard	Wird nicht unterstützt
Amazon EMR Serverless	Standard und Express	Standard	Wird nicht unterstützt
Amazon EventBridge	Standard und Express	Wird nicht unterstützt	Standard
AWS Glue	Standard und Express	Standard	Wird nicht unterstützt
AWS Glue DataBrew	Standard und Express	Standard	Wird nicht unterstützt
AWS Lambda	Standard und Express	Wird nicht unterstützt	Standard
AWS Elemental MediaConvert	Standard und Express	Standard	Wird nicht unterstützt
Amazon SageMaker	Standard und Express	Standard	Wird nicht unterstützt
Amazon SNS	Standard und Express	Wird nicht unterstützt	Standard
Amazon SQS	Standard und Express	Wird nicht unterstützt	Standard
AWS Step Functions	Standard und Express	Standard	Standard

Request Response (Antwort anfordern)

Wenn Sie in der "Resource" Zeichenfolge Ihres Aufgabenstatus einen Dienst angeben und nur die Ressource angeben, wartet Step Functions HTTP auf eine Antwort und geht dann zum nächsten Status über. Step Functions wartet nicht darauf, dass ein Job abgeschlossen ist.

Das folgende Beispiel zeigt, wie Sie ein SNS Amazon-Thema veröffentlichen können.

"Send message to SNS":{
            "Type":"Task",
            "Resource":"arn:aws:states:::sns:publish",
            "Parameters":{
            "TopicArn":"arn:aws:sns:us-east-1:123456789012:myTopic",
            "Message":"Hello from Step Functions!"
            },
            "Next":"NEXT_STATE"
            }

Dieses Beispiel verweist auf Publish API of AmazonSNS. Der Workflow geht nach dem Aufrufen von zum nächsten Status über PublishAPI.

Tipp

Um einen Beispiel-Workflow bereitzustellen, der das Request Response Service-Integrationsmuster verwendet, auf Ihrem AWS-Konto, siehe Modul 2 — Antwort auf Anfragen von AWS Step Functions Werkstatt.

Ausführen einer Aufgabe (.sync)

Für integrierte Dienste wie AWS Batch und AmazonECS, Step Functions kann warten, bis eine Anfrage abgeschlossen ist, bevor sie zum nächsten Status übergeht. Damit Step Functions warten kann, geben Sie das "Resource" Feld in Ihrer Aufgabenstatusdefinition mit dem .sync Suffix an, das nach der Ressource angehängt wird. URI

Zum Beispiel beim Einreichen eines AWS Batch Job, verwenden Sie das "Resource" Feld in der State-Machine-Definition, wie in diesem Beispiel gezeigt.

"Manage Batch task": {
            "Type": "Task",
            "Resource": "arn:aws:states:::batch:submitJob.sync",
            "Parameters": {
            "JobDefinition": "arn:aws:batch:us-east-2:123456789012:job-definition/testJobDefinition",
            "JobName": "testJob",
            "JobQueue": "arn:aws:batch:us-east-2:123456789012:job-queue/testQueue"
            },
            "Next": "NEXT_STATE"
            }

Wenn der .sync Teil an die Ressource Amazon Resource Name (ARN) angehängt ist, bedeutet dies, dass Step Functions auf den Abschluss des Jobs wartet. Nach dem Anruf AWS Batch submitJob, der Workflow wird angehalten. Wenn der Job abgeschlossen ist, wechselt Step Functions zum nächsten Status. Weitere Informationen finden Sie im AWS Batch Beispielprojekt:Verwalten Sie einen Batch-Job mit AWS Batch and Amazon SNS.

Wenn eine Aufgabe, die dieses Dienstintegrationsmuster (.sync) verwendet, abgebrochen wird und Step Functions die Aufgabe nicht stornieren kann, fallen möglicherweise zusätzliche Gebühren für den integrierten Service an. Eine Aufgabe kann abgebrochen werden, wenn:

• Die Ausführung der Zustandsmaschine ist gestoppt.

• Ein anderer Zweig eines Parallel-Zustands schlägt mit einem nicht abgefangenen Fehler fehl.

• Eine Iteration eines Map-Status schlägt mit einem nicht erfassten Fehler fehl.

Step Functions versucht nach besten Kräften, die Aufgabe abzubrechen. Wenn beispielsweise eine Step states:startExecution.sync Functions-Aufgabe abgebrochen wird, wird die StopExecution API Aktion Step Functions aufgerufen. Es ist jedoch möglich, dass Step Functions die Aufgabe nicht abbrechen kann. Zu den Gründen hierfür gehören, sind aber nicht beschränkt auf:

• Ihrer IAM Ausführungsrolle fehlt die Berechtigung, den entsprechenden API Aufruf zu tätigen.

• Ein vorübergehender Dienstausfall ist aufgetreten.

Wenn Sie das .sync Dienstintegrationsmuster verwenden, verwendet Step Functions Polling, das Ihre zugewiesenen Kontingente und Ereignisse nutzt, um den Status eines Jobs zu überwachen. Für .sync Aufrufe innerhalb desselben Kontos verwendet Step Functions die EventBridge Ereignisse und AbfragenAPIs, die Sie im Status angeben. Task Für kontoübergreifende .sync Aufrufe verwendet Step Functions nur Polling. Beispielsweise führt Step Functions Abfragen für states:StartExecution.sync das durch DescribeExecutionAPIund verwendet Ihr zugewiesenes Kontingent.

Tipp

Um einen Beispiel-Workflow bereitzustellen, der das Dienstintegrationsmuster Run a Job (.sync) verwendet, auf Ihrem AWS-Konto, siehe Modul 3 - Einen Job ausführen (.sync) von The AWS Step Functions Werkstatt.

Für eine Liste der integrierten Services, die das Warten auf den Abschluss eines Auftrags unterstützen (.sync) vgl. Integration von Diensten mit Step Functions. .

Anmerkung

Für Serviceintegrationen, die die .waitForTaskToken Muster .sync oder verwenden, sind zusätzliche IAM Berechtigungen erforderlich. Weitere Informationen finden Sie unter So generiert Step Functions IAM Richtlinien für integrierte Dienste.

In einigen Fällen möchten Sie vielleicht, dass Step Functions Ihren Arbeitsablauf fortsetzt, bevor der Job vollständig abgeschlossen ist. Sie können dies auf die gleiche Weise erreichen wie bei der Verwendung des Warten Sie auf einen Rückruf mit Task Token Service Integration Patterns. Übergeben Sie dazu ein Aufgabentoken an Ihren Job und geben Sie es dann mit einem SendTaskSuccessSendTaskFailureAPIOR-Aufruf zurück. Step Functions verwendet die Daten, die Sie in diesem Aufruf angegeben haben, um die Aufgabe abzuschließen, die Überwachung des Jobs zu beenden und den Workflow fortzusetzen.

Warten Sie auf einen Rückruf mit Task Token

Callback-Aufgaben bieten eine Möglichkeit, einen Workflow anhalten, bis ein Aufgabentoken zurückgegeben wird. Eine Aufgabe auf eine menschliche Genehmigung warten, mit einer Drittpartei integriert werden oder ältere Systeme aufrufen müssen. Für Aufgaben wie diese können Sie Step Functions anhalten, bis die Workflow-Ausführung das Servicekontingent von einem Jahr erreicht hat (siehe,Kontingente im Zusammenhang mit staatlicher Drosselung), und warten, bis ein externer Prozess oder Workflow abgeschlossen ist. In diesen Situationen können Sie mit Step Functions ein Task-Token an die übergeben AWS SDKServiceintegrationen und auch zu einigen optimierten Serviceintegrationen. Die Aufgabe wird angehalten, bis sie dieses Aufgabentoken mit einem SendTaskSuccess- oder SendTaskFailure- Aufruf zurückerhält.

Wenn bei einem Task Status, der das Callback-Task-Token verwendet, eine Zeitüberschreitung eintritt, wird ein neues zufälliges Token generiert. Sie können vom Kontextobjekt aus auf die Task-Token zugreifen.

Anmerkung

Ein Task-Token muss mindestens ein Zeichen enthalten und darf 1024 Zeichen nicht überschreiten.

Zur Verwendung .waitForTaskToken mit einem AWS SDKFür die von API Ihnen verwendete Integration muss ein Parameterfeld vorhanden sein, in dem das Task-Token platziert werden kann.

Anmerkung

Sie müssen Aufgabentokens von Prinzipalen innerhalb derselben übergeben AWS Konto. Die Token funktionieren nicht, wenn Sie sie von Schulleitern in einem anderen Land senden AWS Konto.

Tipp

Um einen Beispiel-Workflow bereitzustellen, der ein Muster für die Integration eines Tokendiensts für Callback-Aufgaben verwendet, auf Ihrem AWS-Konto, siehe Modul 4 — Warten auf einen Callback mit dem Task-Token von AWS Step Functions Werkstatt.

Eine Liste der integrierten Services, die das Warten auf ein Aufgabentoken unterstützen (.waitForTaskToken) finden Sie unter Integration von Diensten mit Step Functions.

Themen

• Aufgabentoken-Beispiel
• Abrufen eines Tokens von einem Kontextobjekt
• Konfigurieren einer Heartbeat-Zeitüberschreitung für eine wartende Aufgabe

Aufgabentoken-Beispiel

In diesem Beispiel muss ein Step Functions Functions-Workflow in einen externen Microservice integriert werden, um eine Bonitätsprüfung als Teil eines Genehmigungsworkflows durchzuführen. Step Functions veröffentlicht eine SQS Amazon-Nachricht, die ein Task-Token als Teil der Nachricht enthält. Ein externes System integriert sich in Amazon SQS und zieht die Nachricht aus der Warteschlange. Wenn das abgeschlossen ist, werden das Ergebnis und das ursprüngliche Task-Token zurückgegeben. Step Functions setzt dann seinen Arbeitsablauf fort.

Das "Resource" Feld der Aufgabendefinition, das auf Amazon SQS Include verweist, ist .waitForTaskToken am Ende angehängt.

"Send message to SQS": {
                "Type": "Task",
                "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
                "Parameters": {
                "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
                "MessageBody": {
                "Message": "Hello from Step Functions!",
                "TaskToken.$": "$$.Task.Token"
                }
                },
                "Next": "NEXT_STATE"
                }

Dadurch wird Step Functions angewiesen, eine Pause einzulegen und auf das Task-Token zu warten. Wenn Sie eine Ressource mit .waitForTaskToken, abgeben, können Sie im "Parameters"-Feld Ihrer Zustandsdefinition mit einer speziellen Pfadbezeichnung ($$.Task.Token) auf das Aufgabentoken zugreifen. Der anfängliche $$. legt fest, dass der Pfad auf das Kontextobjekt zugreift und das Aufgabentoken für die aktuelle Aufgabe in einer laufenden Ausführung empfängt.

Wenn der Vorgang abgeschlossen ist, ruft der externe Service SendTaskSuccess oder SendTaskFailure mit taskToken auf. Erst danach wird der Workflow mit dem nächsten Zustand fortgesetzt.

Anmerkung

Wie zu vermeiden ist, dass unbegrenzt lange gewartet wird, wenn ein Prozess das Aufgabentoken nicht zusammen mit SendTaskSuccess oder SendTaskFailure sendet, finden Sie unter Konfigurieren einer Heartbeat-Zeitüberschreitung für eine wartende Aufgabe.

Abrufen eines Tokens von einem Kontextobjekt

Das Kontextobjekt ist ein internes JSON Objekt, das Informationen über Ihre Ausführung enthält. Wie die Zustandsausgabe ist es über einen Pfad aus dem Feld "Parameters" während einer Ausführung zugänglich. Wenn aus einer Aufgabendefinition darauf zugegriffen wird, enthält es Informationen über die spezifische Ausführung, einschließlich des Aufgabentokens.

{
                "Execution": {
                "Id": "arn:aws:states:us-east-1:123456789012:execution:stateMachineName:executionName",
                "Input": {
                "key": "value"
                },
                "Name": "executionName",
                "RoleArn": "arn:aws:iam::123456789012:role...",
                "StartTime": "2019-03-26T20:14:13.192Z"
                },
                "State": {
                "EnteredTime": "2019-03-26T20:14:13.192Z",
                "Name": "Test",
                "RetryCount": 3
                },
                "StateMachine": {
                "Id": "arn:aws:states:us-east-1:123456789012:stateMachine:stateMachineName",
                "Name": "name"
                },
                "Task": {
                "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
                }
                }

Sie können auf das Aufgabentoken mit einem speziellen Pfad innerhalb des "Parameters"-Felds Ihrer Aufgabendefinition zugreifen. Um auf die Eingabe oder das Kontextobjekt zuzugreifen, geben Sie zuerst an, dass der Parameter ein Pfad ist, indem Sie dem Parameternamen ein .$ anhängen. Das folgende Beispiel gibt Knoten sowohl über das Eingabe- und das Kontext-Objekt in einer "Parameters"-Spezifikation an.

"Parameters": {
                "Input.$": "$",
                "TaskToken.$": "$$.Task.Token"
                },

In beiden Fällen wird Step Functions durch Anhängen .$ an den Parameternamen angewiesen, einen Pfad zu erwarten. Im ersten Fall ist "$" ein Pfad, der die gesamte Eingabe enthält. Im zweiten Fall gibt $$. an, dass der Pfad auf das Kontext-Objekt zugreift, und $$.Task.Token setzt den Parameter auf den Wert des Aufgabentokens in dem Aufgabentoken einer laufenden Ausführung.

Im SQS Amazon-Beispiel weist das "Resource" Feld Step Functions an, .waitForTaskToken auf die Rückgabe des Aufgabentokens zu warten. Der "TaskToken.$": "$$.Task.Token" Parameter übergibt dieses Token als Teil der SQS Amazon-Nachricht.

"Send message to SQS": {
                "Type": "Task",
                "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
                "Parameters": {
                "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
                "MessageBody": {
                "Message": "Hello from Step Functions!",
                "TaskToken.$": "$$.Task.Token"
                }
                },
                "Next": "NEXT_STATE"
                }

Weitere Informationen über das Kontext-Objekt finden Sie unter Context-Objekt im Abschnitt Eingabe und Ausgabe verarbeiten in diesem Handbuch.

Konfigurieren einer Heartbeat-Zeitüberschreitung für eine wartende Aufgabe

Eine Aufgabe, die auf einen Aufgabentoken wartet, wartet, bis die Ausführung das einjährige Servicekontingent erreicht (siehe Kontingente im Zusammenhang mit staatlicher Drosselung). Um zu verhindern, dass Ausführungen hängen bleiben, können Sie eine Heartbeat-Zeitüberschreitung in Ihrer Zustandsautomatendefinition konfigurieren. Verwenden Sie das HeartbeatSeconds-Feld, um das Timeout-Intervall anzugeben.

{
                "StartAt": "Push to SQS",
                "States": {
                "Push to SQS": {
                "Type": "Task",
                "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
                "HeartbeatSeconds": 600,
                "Parameters": {
                "MessageBody": { "myTaskToken.$": "$$.Task.Token" },
                "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/push-based-queue"
                },
                "ResultPath": "$.SQS",
                "End": true
                }
                }
                }

In dieser Zustandsmaschinendefinition sendet eine Aufgabe eine Nachricht an Amazon SQS und wartet darauf, dass ein externer Prozess mit dem bereitgestellten Task-Token zurückruft. Das "HeartbeatSeconds": 600-Feld legt das Intervall der Heartbeat-Zeitüberschreitung Intervall auf 10 Minuten fest. Die Aufgabe wartet mit einer der folgenden API Aktionen darauf, dass das Aufgaben-Token zurückgegeben wird:

• SendTaskSuccess

• SendTaskFailure

• SendTaskHeartbeat

Wenn die wartende Aufgabe innerhalb dieser 10 Minuten kein gültiges Aufgabentoken erhält, schlägt die Aufgabe mit dem Fehlernamen States.Timeout fehl.

Weitere Informationen finden Sie im Beispielprojekt Erstellen Sie ein Beispiel für ein Callback-Muster mit Amazon SQSSNS, Amazon und Lambda für eine Callback-Aufgabe.