Mit Callbacks warten

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, um Sie zu benachrichtigen, wenn ein Produkt wieder auf Lager ist oder wenn ein Artikel versendet wurde. Oder Sie erstellen einen Workflow, der eine Pause macht, um menschliche Interaktion zu ermöglichen, z. B. die Überprüfung eines Auftrags oder die Validierung einer Übersetzung.

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:

Endpunkt erstellen, der eine Callback-Anfrage empfängt

Erstellen Sie einen Callback-Endpunkt, der HTTP-Anfragen erhalten kann, die am Endpunkt ankommen.

  1. Führen Sie die Schritte zum Erstellen eines neuen Workflows aus oder wählen Sie einen vorhandenen Workflow zum Aktualisieren aus, stellen Sie ihn jedoch noch nicht bereit.
  2. 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, entweder GET, HEAD, POST, PUT, DELETE, OPTIONS oder PATCH. Der Standardwert ist POST.

    Das Ergebnis ist eine Zuordnung callback_details mit einem Feld url, 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 Run-Funktion.

  3. 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 ein TimeoutError ausgelöst.

    Beachten Sie, dass es eine maximale Ausführungsdauer gibt. Weitere Informationen finden Sie unter Anfragenlimit.

    Die callback_details-Karte aus dem vorherigen create_callback-Schritt wird als Argument übergeben.

  4. 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 eine query-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 Run Functions sowie Dienste von Drittanbietern mit den entsprechenden IAM-Berechtigungen dazu autorisiert werden, und zwar durch 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 Direkte Anfrageberechtigungen.

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"
  }
Der accessToken-Code kann dann in einem curl-Aufruf an die Callback-Endpunkt-URL verwendet werden, wie in den folgenden Beispielen: 
  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 Run-Funktion generieren

Wenn Sie einen Callback von einer Cloud Run-Funktion aufrufen, die dasselbe Dienstkonto wie der Workflow im selben Projekt verwendet, können Sie ein OAuth-Zugriffstoken in der Funktion selbst generieren. Beispiel: