Callbacks ermöglichen es Workflow-Ausführungen, zu warten, bis ein anderer Dienst eine Anfrage an den Callback-Endpunkt sendet. Diese Anfrage setzt die Ausführung des Workflows fort.
Mit Callbacks können Sie Ihrem Workflow signalisieren, dass ein bestimmtes Ereignis aufgetreten ist, und auf dieses Ereignis ohne Abfrage warten. Sie können beispielsweise einen Workflow erstellen, der Sie benachrichtigt, wenn ein Produkt wieder auf Lager ist, wenn ein Artikel versendet wird oder wenn eine menschliche Interaktion wie das Überprüfen einer Bestellung oder die Validierung einer Übersetzung möglich ist.
Auf dieser Seite erfahren Sie, wie Sie einen Workflow erstellen, der einen Callback-Endpunkt unterstützt und wartet, bis HTTP-Anfragen von externen Prozessen an diesem Endpunkt ankommen. Sie können auch mit Callbacks und Eventarc-Triggern auf Ereignisse warten.
Callbacks erfordern die Verwendung von zwei integrierten Funktionen für Standardbibliotheken:
events.create_callback_endpoint
: Erstellt einen Callback-Endpunkt, der die angegebene HTTP-Methode erwartetevents.await_callback
: Wartet, bis ein Callback am angegebenen Endpunkt empfangen wird
Endpunkt erstellen, der eine Callback-Anfrage empfängt
Erstellen Sie einen Callback-Endpunkt, der HTTP-Anfragen erhalten kann, die am Endpunkt ankommen.
- Führen Sie die Schritte zum Erstellen eines neuen Workflows aus oder wählen Sie einen vorhandenen Workflow aus, um ihn zu aktualisieren, aber noch nicht bereitzustellen.
- Fügen Sie der Definition des Workflows einen Schritt hinzu, um einen Callback-Endpunkt zu erstellen:
YAML
- create_callback: call: events.create_callback_endpoint args: http_callback_method: "METHOD" result: callback_details
JSON
[ { "create_callback": { "call": "events.create_callback_endpoint", "args": { "http_callback_method": "METHOD" }, "result": "callback_details" } } ]
Ersetzen Sie
METHOD
durch die erwartete HTTP-Methode, entwederGET
,HEAD
,POST
,PUT
,DELETE
,OPTIONS
oderPATCH
. Der Standardwert istPOST
.Das Ergebnis ist eine Zuordnung
callback_details
mit einem Feldurl
, das die URL des erstellten Endpunkts speichert.Der Callback-Endpunkt kann jetzt eingehende Anfragen mit der angegebenen HTTP-Methode empfangen. Die URL des erstellten Endpunkts kann verwendet werden, um den Callback von einem Prozess außerhalb des Workflows auszulösen. Dazu übergeben Sie beispielsweise die URL an eine Cloud Functions-Funktion.
- Fügen Sie in der Definition des Workflows einen Schritt hinzu, um auf eine Callback-Anfrage zu warten:
YAML
- await_callback: call: events.await_callback args: callback: ${callback_details} timeout: TIMEOUT result: callback_request
JSON
[ { "await_callback": { "call": "events.await_callback", "args": { "callback": "${callback_details}", "timeout": TIMEOUT }, "result": "callback_request" } } ]
Ersetzen Sie
TIMEOUT
durch die maximale Anzahl von Sekunden, die der Workflow auf eine Anfrage warten soll. Der Standardwert ist 43.200 (12 Stunden). Wenn diese Zeit vor dem Empfang einer Anfrage verstrichen ist, wird einTimeoutError
ausgelöst.Beachten Sie, dass es eine maximale Ausführungsdauer gibt. Weitere Informationen finden Sie unter Anfragelimit.
Die
callback_details
-Zuordnung aus dem vorherigen Schrittcreate_callback
wird als Argument übergeben. - Stellen Sie Ihren Workflow bereit, um ihn zu erstellen oder zu aktualisieren.
Wenn eine Anfrage empfangen wird, werden alle Details der Anfrage in der Zuordnung
callback_request
gespeichert. Anschließend haben Sie Zugriff auf die gesamte HTTP-Anfrage, einschließlich Header, Text und einequery
-Zuordnung für alle Abfrageparameter. Beispiel:YAML
http_request: body: headers: {...} method: GET query: {} url: "/v1/projects/350446661175/locations/us-central1/workflows/workflow-1/executions/46804f42-dc83-46d6-87e4-93962866ed81/callbacks/49c80102-74d2-49cd-a70e-805a9fded94f_2de9b413-6332-412d-99c3-d7e9b6eeeda2" received_time: 2021-06-24 12:49:16.988072651 -0700 PDT m=+742581.005780667 type: HTTP
JSON
{ "http_request":{ "body":null, "headers":{ ... }, "method":"GET", "query":{ }, "url":"/v1/projects/350446661175/locations/us-central1/workflows/workflow-1/executions/46804f42-dc83-46d6-87e4-93962866ed81/callbacks/49c80102-74d2-49cd-a70e-805a9fded94f_2de9b413-6332-412d-99c3-d7e9b6eeeda2" }, "received_time":"2021-06-24 12:49:16.988072651 -0700 PDT m=+742581.005780667", "type":"HTTP" }
Wenn der HTTP-Text ein Text oder JSON ist, versucht Workflows, den Text zu decodieren. Andernfalls werden Rohbyte zurückgegeben.
Anfragen an den Callback-Endpunkt autorisieren
Zum Senden einer Anfrage an einen Callback-Endpunkt müssen Google Cloud-Dienste wie Cloud Run und Cloud Functions sowie Dienste von Drittanbietern dazu autorisiert werden. Dazu müssen sie die entsprechenden IAM-Berechtigungen (Identity and Access Management) haben, insbesondere workflows.callbacks.send
(in der Rolle „Workflows Invoker“ enthalten).
Direkte Anfrage stellen
Am einfachsten erstellen Sie kurzlebige Anmeldedaten für ein Dienstkonto, indem Sie eine direkte Anfrage stellen. An diesem Ablauf sind zwei Identitäten beteiligt: der Aufrufer und das Dienstkonto, für das die Anmeldedaten erstellt werden. Der Aufruf des grundlegenden Workflows auf dieser Seite ist ein Beispiel für eine direkte Anfrage. Weitere Informationen finden Sie unter Zugriff mit IAM steuern und Berechtigungen für direkte Anfragen.
OAuth 2.0-Zugriffstoken generieren
Zum Autorisieren einer Anwendung zum Aufrufen des Callback-Endpunkts können Sie ein OAuth 2.0-Zugriffstoken für das mit dem Workflow verknüpfte Dienstkonto generieren.
Wenn Sie die erforderlichen Berechtigungen (für die Rollen Workflows Editor
oder Workflows Admin
und Service Account Token Creator
) haben, können Sie selbst ein Token generieren. Führen Sie dazu die generateAccessToken
-Methode aus.
Wenn die Anfrage generateAccessToken
erfolgreich ist, enthält der zurückgegebene Antworttext ein OAuth 2.0-Zugriffstoken und eine Ablaufzeit. Standardmäßig sind OAuth 2.0-Zugriffstokens maximal eine Stunde lang gültig. Beispiel:
{ "accessToken": "eyJ0eXAi...NiJ9", "expireTime": "2020-04-07T15:01:23.045123456Z" }
accessToken
-Code kann dann wie in den folgenden Beispielen in einem curl-Aufruf an die Callback-Endpunkt-URL verwendet werden:
curl -X GET -H "Authorization: Bearer ACCESS_TOKEN_STRING" CALLBACK_URL
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ACCESS_TOKEN_STRING" -d '{"foo" : "bar"}' CALLBACK_URL
OAuth-Token für eine Cloud Functions-Funktion generieren
Wenn Sie einen Callback von einer Cloud Functions-Funktion aufrufen, die dasselbe Dienstkonto wie der Workflow im selben Projekt verwendet, können Sie ein OAuth-Zugriffstoken in der Funktion selbst generieren. Beispiel:
Weitere Informationen finden Sie in der Anleitung Human-in-the-Loop-Workflow mit Callbacks erstellen.
Offlinezugriff anfordern
Zugriffstokens laufen regelmäßig ab und werden zu ungültigen Anmeldedaten für eine zugehörige API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne den Nutzer um eine Berechtigung zu bitten, wenn Sie den Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben. Das Anfordern des Offlinezugriffs ist eine Voraussetzung für jede Anwendung, die auf eine Google API zugreifen muss, wenn der Nutzer nicht vorhanden ist. Weitere Informationen finden Sie unter Zugriffstoken aktualisieren (Offlinezugriff).
Einfachen Callback-Workflow testen
Sie können einen einfachen Workflow erstellen und dann den Aufruf an den Callback-Endpunkt dieses Workflows mit curl testen. Sie benötigen die erforderlichen Workflows Editor
- oder Workflows Admin
-Berechtigungen für das Projekt, in dem sich der Workflow befindet.
-
Erstellen und stellen Sie den folgenden Workflow bereit und execute.
YAML
- create_callback: call: events.create_callback_endpoint args: http_callback_method: "GET" result: callback_details - print_callback_details: call: sys.log args: severity: "INFO" text: ${"Listening for callbacks on " + callback_details.url} - await_callback: call: events.await_callback args: callback: ${callback_details} timeout: 3600 result: callback_request - print_callback_request: call: sys.log args: severity: "INFO" text: ${"Received " + json.encode_to_string(callback_request.http_request)} - return_callback_result: return: ${callback_request.http_request}
JSON
[ { "create_callback": { "call": "events.create_callback_endpoint", "args": { "http_callback_method": "GET" }, "result": "callback_details" } }, { "print_callback_details": { "call": "sys.log", "args": { "severity": "INFO", "text": "${\"Listening for callbacks on \" + callback_details.url}" } } }, { "await_callback": { "call": "events.await_callback", "args": { "callback": "${callback_details}", "timeout": 3600 }, "result": "callback_request" } }, { "print_callback_request": { "call": "sys.log", "args": { "severity": "INFO", "text": "${\\"Received \\" + json.encode_to_string(callback_request.http_request)}" } } }, { "return_callback_result": { "return": "${callback_request.http_request}" } } ]
Nach dem Ausführen des Workflows hat die Workflowausführung den Status
ACTIVE
, bis die Callback-Anfrage empfangen wird oder das Zeitlimit erreicht wurde. - Bestätigen Sie den Ausführungsstatus und rufen Sie die Callback-URL ab:
Console
-
Rufen Sie in der Google Cloud Console die Seite Workflows auf:
Zur Seite „Workflows“ -
Klicken Sie auf den Namen des gerade ausgeführten Workflows.
Der Status der Workflow-Ausführung wird angezeigt.
- Klicken Sie auf den Tab Logs.
Suchen Sie nach einem Logeintrag wie dem Folgenden:
Listening for callbacks on https://workflowexecutions.googleapis.com/v1/projects/...
- Kopieren Sie die Callback-URL, die im nächsten Befehl verwendet werden soll.
gcloud
- Rufen Sie zuerst die Ausführungs-ID ab:
gcloud logging read "Listening for callbacks" --freshness=DURATION
Ersetzen SieDURATION
durch eine geeignete Zeit, um die zurückgegebenen Logeinträge zu begrenzen, wenn Sie den Workflow mehrmals ausgeführt haben.Beispielsweise gibt
--freshness=t10m
Logeinträge zurück, die nicht älter als 10 Minuten sind. Weitere Informationen findest du untergcloud topic datetimes
.Die Ausführungs-ID wird zurückgegeben. Die Callback-URL wird ebenfalls im Feld
textPayload
zurückgegeben. Kopieren Sie beide Werte, um sie in den folgenden Schritten zu verwenden. - Führen Sie dazu diesen Befehl aus:
-
- Sie können jetzt mit einem curl-Befehl den Callback-Endpunkt aufrufen:
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" CALLBACK_URL
Beachten Sie, dass Sie für einen
POST
-Endpunkt einenContent-Type
-Darstellungsheader verwenden müssen. Beispiel:curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -d '{"foo" : "bar"}' CALLBACK_URL
Ersetzen Sie
CALLBACK_URL
durch die URL, die Sie im vorherigen Schritt kopiert haben. - Bestätigen Sie über die Google Cloud Console oder die Google Cloud CLI, dass der Status der Workflowausführung jetzt
SUCCEEDED
lautet. - Suchen Sie nach dem Logeintrag mit dem zurückgegebenen
textPayload
, der in etwa so aussieht:Received {"body":null,"headers":...
Beispiele
Diese Beispiele veranschaulichen die Syntax.
Zeitüberschreitungsfehler abfangen
Dieses Beispiel erweitert das vorherige Beispiel, indem Zeitüberschreitungsfehler abgefangen und die Fehler in das Systemlog geschrieben werden.
YAML
main: steps: - create_callback: call: events.create_callback_endpoint args: http_callback_method: "GET" result: callback_details - print_callback_details: call: sys.log args: severity: "INFO" text: ${"Listening for callbacks on " + callback_details.url} - await_callback: try: call: events.await_callback args: callback: ${callback_details} timeout: 3600 result: callback_request except: as: e steps: - log_error: call: sys.log args: severity: "ERROR" text: ${"Received error " + e.message} next: end - print_callback_result: call: sys.log args: severity: "INFO" text: ${"Received " + json.encode_to_string(callback_request.http_request)}
JSON
{ "main": { "steps": [ { "create_callback": { "call": "events.create_callback_endpoint", "args": { "http_callback_method": "GET" }, "result": "callback_details" } }, { "print_callback_details": { "call": "sys.log", "args": { "severity": "INFO", "text": "${\"Listening for callbacks on \" + callback_details.url}" } } }, { "await_callback": { "try": { "call": "events.await_callback", "args": { "callback": "${callback_details}", "timeout": 3600 }, "result": "callback_request" }, "except": { "as": "e", "steps": [ { "log_error": { "call": "sys.log", "args": { "severity": "ERROR", "text": "${\"Received error \" + e.message}" }, "next": "end" } } ] } } }, { "print_callback_result": { "call": "sys.log", "args": { "severity": "INFO", "text": "${\"Received \" + json.encode_to_string(callback_request.http_request)}" } } } ] } }
Auf einen Callback in einer Wiederholungsschleife warten
In diesem Beispiel wird das vorherige Beispiel durch Implementieren eines Wiederholungsschritts geändert. Mit einem benutzerdefinierten Wiederholungsprädikat protokolliert der Workflow eine Warnung, wenn ein Zeitlimit auftritt, und wiederholt die Wartezeit auf dem Callback-Endpunkt bis zu fünfmal. Wenn das Wiederholungskontingent aufgebraucht ist, bevor der Callback empfangen wird, führt der letzte Zeitüberschreitungsfehler dazu, dass der Workflow fehlschlägt.
YAML
main: steps: - create_callback: call: events.create_callback_endpoint args: http_callback_method: "GET" result: callback_details - print_callback_details: call: sys.log args: severity: "INFO" text: ${"Listening for callbacks on " + callback_details.url} - await_callback: try: call: events.await_callback args: callback: ${callback_details} timeout: 60.0 result: callback_request retry: predicate: ${log_timeout} max_retries: 5 backoff: initial_delay: 1 max_delay: 10 multiplier: 2 - print_callback_result: call: sys.log args: severity: "INFO" text: ${"Received " + json.encode_to_string(callback_request.http_request)} log_timeout: params: [e] steps: - when_to_repeat: switch: - condition: ${"TimeoutError" in e.tags} steps: - log_error_and_retry: call: sys.log args: severity: "WARNING" text: "Timed out waiting for callback, retrying" - exit_predicate: return: true - otherwise: return: false
JSON
{ "main": { "steps": [ { "create_callback": { "call": "events.create_callback_endpoint", "args": { "http_callback_method": "GET" }, "result": "callback_details" } }, { "print_callback_details": { "call": "sys.log", "args": { "severity": "INFO", "text": "${\"Listening for callbacks on \" + callback_details.url}" } } }, { "await_callback": { "try": { "call": "events.await_callback", "args": { "callback": "${callback_details}", "timeout": 60 }, "result": "callback_request" }, "retry": { "predicate": "${log_timeout}", "max_retries": 5, "backoff": { "initial_delay": 1, "max_delay": 10, "multiplier": 2 } } } }, { "print_callback_result": { "call": "sys.log", "args": { "severity": "INFO", "text": "${\"Received \" + json.encode_to_string(callback_request.http_request)}" } } } ] }, "log_timeout": { "params": [ "e" ], "steps": [ { "when_to_repeat": { "switch": [ { "condition": "${\"TimeoutError\" in e.tags}", "steps": [ { "log_error_and_retry": { "call": "sys.log", "args": { "severity": "WARNING", "text": "Timed out waiting for callback, retrying" } } }, { "exit_predicate": { "return": true } } ] } ] } }, { "otherwise": { "return": false } } ] } }