Serviceintegrationsmuster - AWS Step Functions

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Serviceintegrationsmuster

AWS Step FunctionsIntegration mit Services in Amazon States Language. Sie können diese AWS-Services mithilfe dreier verschiedener Serviceintegrationsmuster verwalten:

  • Rufen Sie einen Dienst auf und lassen Sie Step Functions sofort nach Erhalt einer HTTP-Antwort in den nächsten Status übergehen.

  • Rufen Sie einen Dienst auf und lassen Sie Step Functions warten, bis ein Auftrag 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 im "Resource"-Feld Ihrer Aufgabendefinition eine URI erstellen.

Weitere Informationen zur KonfigurationAWS Identity and Access Management(IAM) für integrierte Dienste sieheIAM-Richtlinien für integrierte Dienste.

Request Response (Antwort anfordern)

Wenn Sie einen Dienst in der"Resource"Zeichenfolge Ihres Aufgabenstatus und SienurStellen Sie die Ressource bereit, Step Functions wartet auf eine HTTP-Antwort und geht dann zum nächsten Status über. Step Functions wartet nicht auf den Abschluss eines Auftrags.

Das folgende Beispiel zeigt, wie Sie ein Amazon SNS-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 aufVeröffentlichenAPI von Amazon SNS. Der Workflow fährt nach dem Aufruf der Publish-API mit dem nächsten Zustand fort.

Ausführen einer Aufgabe (.sync)

Für integrierte Dienste wieAWS Batchund Amazon ECS können Step Functions auf den Abschluss einer Anforderung warten, bevor in den nächsten Status übergegangen wird. Um Step Functions warten zu lassen, geben Sie"Resource"Feld in Ihrer Aufgabenstatusdefinition mit dem.syncNach dem Ressourcen-URI angehängt.

Zum Beispiel beim Einreichen einesAWS BatchJob, benutze 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" }

Den.syncTeil, der an den Amazon-Ressourcennamen (ARN) der Ressource angehängt wird, bedeutet, dass Step Functions auf den Abschluss des Auftrags wartet. Nach dem Aufrufen von AWS Batch submitJob wird der Workflow unterbrochen. Wenn der Auftrag abgeschlossen ist, wechselt Step Functions in den nächsten Status. Weitere Informationen finden Sie im AWS Batch-Beipielprojekt: Verwalten eines Stapelauftrags (AWS Batch, Amazon SNS).

Wenn eine Aufgabe dies verwendet (.sync) Das Service-Integrationsmuster wurde abgebrochen und Step Functions kann die Aufgabe nicht abbrechen. Möglicherweise fallen zusätzliche Gebühren für den integrierten Dienst an. Eine Aufgabe kann abgebrochen werden, wenn:

  • Die Ausführung der Zustandsmaschine wurde angehalten.

  • Ein anderer Zweig eines Parallelstatus schlägt mit einem nicht abgefangenen Fehler fehl.

  • Eine Iteration eines Kartenstatus schlägt mit einem nicht abgefangenen Fehler fehl.

Step Functions versucht nach bestem Bemühen, die Aufgabe abzubrechen. Zum Beispiel, wenn ein Step Functionsstates:startExecution.syncTask wurde abgebrochen, es ruft die Step Functions aufStopExecutionAPI-Aktion. Es ist jedoch möglich, dass Step Functions die Aufgabe nicht abbrechen kann. Gründe dafür sind unter anderem:

  • Ihrer IAM-Ausführungsrolle fehlt die Berechtigung, den entsprechenden API-Aufruf durchzuführen.

  • Ein vorübergehender Serviceausfall ist aufgetreten.

Für eine Liste der integrierten Services, die das Warten auf den Abschluss eines Auftrags unterstützen (.sync) vgl. Optimierte Integrationen für Step Functions. .

Anmerkung

Serviceintegrationen, die das.sync-Muster benötigen zusätzliche IAM-Berechtigungen. Weitere Informationen finden Sie unter IAM-Richtlinien für integrierte Dienste.

Warten auf einen Callback mit dem Aufgabentoken

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 auf unbestimmte Zeit anhalten und warten, bis ein externer Prozess oder Workflow abgeschlossen ist. In diesen Situationen können Sie mit Step Functions ein Task-Token anAWSSDK-Serviceintegrationen und auch einige Optimierte Service-Integrationen. Die Aufgabe wird angehalten, bis sie dieses Aufgabentoken mit einem SendTaskSuccess- oder SendTaskFailure- Aufruf zurückerhält.

Wenn einTaskStatus, bei dem das Callback-Task-Token verwendet wird, ein neues zufälliges Token wird generiert. Sie können auf die Task-Token zugreifenContext-Objekt.

Anmerkung

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

Zu verwenden.waitForTaskTokenmit einemAWSSDK-Integration, die von Ihnen verwendete API muss über ein Parameterfeld verfügen, in dem das Task-Token platziert werden soll.

Anmerkung

Sie müssen Task-Token von Principals innerhalb derselben übergebenAWS-Konto. Die Tokens funktionieren nicht, wenn Sie sie von Auftraggebern in einem anderenAWS-Konto.

Eine Liste der integrierten Services, die das Warten auf ein Aufgabentoken unterstützen (.waitForTaskToken) finden Sie unter Optimierte Integrationen für Step Functions.

Aufgabentoken-Beispiel

In diesem Beispiel muss ein Schrittfunktions-Workflow in einen externen Microservice integriert werden, um eine Bonitätsprüfung als Teil eines Genehmigungs-Workflows durchzuführen. Step Functions veröffentlicht eine Amazon SQS SQS-Nachricht, die ein Task-Token als Teil der Nachricht enthält. Ein externes System ist in Amazon SQS integriert 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 Workflow fort.


            SQS-Aufgabe, die auf die Rückgabe eines Aufgabentokens wartet

Die"Resource"Feld der Aufgabendefinition, das auf Amazon SQS verweist, umfasst.waitForTaskTokenan das 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, anzuhalten und auf das Task-Token zu 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 Kontext-Objekt ist ein internes JSON-Objekt mit Informationen zu Ihrer Ausführung. 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 angehängt.$an den Parameternamen weist Step Functions an, 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 Amazon SQS SQS-Beispiel.waitForTaskTokenin der"Resource"weist Step Functions an, auf die Rückgabe des Task-Tokens zu warten. Die"TaskToken.$": "$$.Task.Token"übergibt dieses Token als Teil der Amazon SQS SQS-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 Verarbeitung von Eingabe und Ausgabe 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 Quoten 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 State-Machine-Definition 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 auf die Rückgabe des Aufgabentokens mit einer der folgenden API-Aktionen:

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 Beispiel für Callback-Muster (Amazon SQS, Amazon SNS, Lambda) für eine Callback-Aufgabe.