再開待機アクション

このページは機械翻訳により提供されています。翻訳内容と英語版に相違がある場合は、英語版が優先されます。

この記事では、再開待機アクションの設定方法について説明します。 この機能を使用すると、次のタスクを実行できるアクションを構築できます:

  • 外部システムにAPIリクエストを送信して、長時間実行されるプロセスを開始します。 たとえば、バッチ処理ジョブを開始したり、承認用のドキュメントを送信したりできます。
  • リクエストの送信後、Workatoでジョブを一時停止します。
  • 外部システムがペイロードを含む認証済みリクエストをWorkatoに返送するまで待機します。
  • ペイロードを使用してジョブを再開し、下流のレシピステップを続行します。

アクションのタイムアウト

SDKアクションには180秒のタイムアウト制限があります。

ユースケース例

再開待機アクションを使用すると、次のユースケースを実現できます:

  • 単一のレシピ内でチャットフローをシミュレートします。 これはWorkbotの"ユーザー入力/アクションを待機"機能に似ています。
  • 外部システムでのドキュメント承認を待機します。 承認されると、レシピは直ちに続行されます。
  • 外部システム内のレコード用にプロセスフローを構築します。 たとえば、Marketoからリードを収集し、データ収集が完了した場合にのみ続行するワークフローを構築できます。

前提条件

このアクションを使用して外部システムにリクエストを送信する予定がある場合、選択する外部システムは、認証済みリクエストをWorkatoのDeveloper APIに返送できる必要があります。

さらに、外部システムは再開トークンを保存できる必要があります。このトークンは、WorkatoのDeveloper APIへの認証済みリクエストと一緒に送信されます。 このトークンは、Workatoがどのジョブを再開すべきかを示します。

再開待機アクションの実装方法

再開待機アクションの機能は、次の2つの重要なコンポーネントによって実現されます:

  • SDKコード: アクション内でSDKコードを使用して、レシピワークフローを一時停止および再開します。
  • APIリクエスト: サードパーティアプリケーションからWorkatoのDeveloper APIにAPIリクエストを送信して、ジョブを再開します。

SDKコード

SDKレベルでは、呼び出しの一時停止と再開を可能にする新しいコールバックがアクションに追加されています。 動作については、このサンプルカスタムコネクターで確認してください。

サンプルカスタムコネクターコード
ruby
{
  actions: {
    wait_for_webhook: {
      config_fields: [
        {
          name: 'url',
          label: 'API endpoint',
          hint: 'We will send a POST request to this endpoint with the resume token',
          optional: false
        },
        {
          name: 'payload_schema',
          optional: true,
          sticky: true,
          schema_neutral: true,
          control_type: 'schema-designer',
          sample_data_type: 'json_input',
        }
      ],
      execute: lambda do |_connection, input, _input_schema, _output_schema, continue|
        if continue.blank?
          # Calling suspend will put the job to sleep, after the request in the proc is executed.
          # in this case we send a POST request to the URL provided by the recipe builder
          # expires_at is configurable and once the time is reached, the job is resumed
          suspend(continue: { "state" => "suspended", "url" => input['url']}, expires_at: 10.minutes.from_now)
        elsif continue["state"] == "resumed"
          { "result" => "resumed", "payload" =>  continue["payload"]}
        elsif continue["state"] == "suspend_timeout"
          { "result" => "suspend_timeout" }
        else
          { "result" => "Unexpected state" }
        end
      end,
      # When suspend is called, this lambda is executed to suspend the job
      # The lambda receives 3 arguments
      # The resume token is an opaque token that must be stored in the external system. This will be used to identify the job to resume
      # expires_at is the time when the job resumes with a timeout
      # continue is the argument passed
      before_suspend: lambda do |resume_token, expires_at, continue|
        response = post(continue['url'], { expires_at: expires_at, resume_token: resume_token } )
      end,
      # Allows you to manipulate or add data before the resume.
      # We change the state of the "continue" argument
      # We also add the payload data into the "continue" argument
      # After this lambda is called, the "execute" lambda is called with the "continue" argument
      before_resume: lambda do |data, input, continue|
        if continue["state"] == "suspended"
          continue["state"] = "resumed"
          continue["payload"] = data
        else
          { "result" => "Unexpected state" }
        end
      end,
      # Allows you to manipulate or add data before the resume due to a timeout
      # We change the state of the "continue" argument
      # After this lambda is called, the "execute" lambda is called with the "continue" argument
      before_timeout_resume: lambda do |input, continue|
        if continue["state"] == "suspended"
          continue["state"] = "suspend_timeout"
        else
          { "result" => "Unexpected state" }
        end
      end,
      output_fields: lambda do |object_definition|
        object_definition['output']
      end
    }
  }
}

このガイドでは、アクションの標準属性の詳細については説明しません。 アクションの基本構造については、SDKアクションリファレンスドキュメントを参照してください。

アクションハッシュには、再開待機アクションの基盤となる4つのラムダがあります:

execute

このラムダは、標準のマルチステップアクションと同様に動作します。 主な目的は、ユーザー入力からのデータを前処理し、アクションが再開されたときの最終出力を決定することです。 これはcontinue引数によって実現されます。この引数は、アクションが初めて呼び出されたときはnilです。 continue引数には、再開時にbefore_resumeまたはbefore_timeout_resumeラムダのいずれかの出力も含まれます。

再開待機アクションが正しく機能するには、executeラムダがsuspendメソッドを呼び出して、ジョブの一時停止を開始する必要があります。

詳細については、suspendメソッドリファレンスドキュメントを参照してください。

before_suspend

このラムダは再開待機アクションに固有であり、suspendメソッドが呼び出されると起動されます。 主に、再開トークンを外部アプリケーションに登録し、この特定のジョブを再開する方法を外部アプリケーションに示します。

詳細については、キーリファレンスドキュメントを参照してください。

before_resume

このラムダは再開待機アクションに固有であり、Workatoがジョブを再開するためのAPIリクエストを受信すると起動されます。 主な目的は、必要に応じてデータを操作し、実行をexecuteラムダに移す前にcontinue引数の状態を管理するためのフックを提供することです。

詳細については、キーリファレンスドキュメントを参照してください。

before_timeout_resume

このラムダは再開待機アクションに固有であり、Workatoがジョブを再開するためのAPIリクエストを受信する前にexpires_at時刻が経過すると起動されます。 主な目的は、必要に応じてデータを操作し、実行をexecuteラムダに移す前にcontinue引数の状態を管理するためのフックを提供することです。

詳細については、キーリファレンスドキュメントを参照してください。

APIリクエスト

外部システムからジョブを再開するには、外部システムが認証済みAPIリクエストをWorkatoのDeveloper APIにディスパッチできる必要があります。

ジョブの再開

Resume jobエンドポイントは、指定したresume_tokenに基づいて一時停止中のジョブを再開します。 エンドポイントは、コンテンツなしの204レスポンスを返します。

このエンドポイントの使用方法については、ジョブの再開APIドキュメントを参照してください。

制限事項

  • executeラムダ内のAPIリクエストは.presenceを使用して呼び出す必要があります。 APIリクエストはexecuteラムダで遅延ロードされるため、suspendメソッドの前に定義されたリクエストは、そのリクエストの後に.presenceをチェーンして強制的に実行する必要があります。

  • 一時停止の最大時間: ジョブを一時停止できる最大時間は60日です。

  • レート制限: Developer APIには、このアクションに対して1分あたり100リクエストのレート制限があります。

  • 再開ペイロードの最大サイズ: 最大ペイロードサイズは50MBです。

Last updated: