Product UpdatesStatus PageAutomation Institute
日本語
コネクターの SDK
How-to ガイド
トリガーの作成

# How to ガイド - 動的 Webhook トリガー

動的 Webhook トリガーは、プログラムで設定および破棄できるトリガーです。コネクターを作成しているアプリケーションの API に明示的に記載する必要があります。以下の例では、トリガーオブジェクトのさまざまなブロックで Webhook を設定および破棄するプロセスを定義できます。

WARNING

コネクターの静的 Webhook トリガーを定義する場合、動的 Webhook トリガーは定義できないことに注意してください。1つのコネクターで許容される Webhook トリガーは1種類のみです。コネクターには、ポーリングトリガーと1種類の Webhook トリガーの両方が含まれていることがあります。

# サンプルコネクター - Cisco Webex

{
  title: 'My Cisco Webex connector',

  # More connector code here
  triggers: {
    new_message: {
      title: 'New message',

      subtitle: "Triggers when a message event is " \
      "received from Cisco Webex",

      description: lambda do |input, picklist_label|
        "New <span class='provider'>message event</span> in " \
        "<span class='provider'>Cisco Webex</span>"
      end,

      help: "Triggers when webhook is sent from Cisco.",

      input_fields: lambda do |object_definitions|
        [
          {
            name: "id",
            label: "Room ID"
          }
        ]
      end,

      webhook_subscribe: lambda do |webhook_url, connection, input, recipe_id|
        post("https://api.ciscospark.com/v1/webhooks",
             name: "Workato recipe #{recipe_id}",
             targetUrl: webhook_url,
             resource: "messages",
             event: "created",
             filter: "roomId=#{input['id']}")
      end,

      webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params|
        payload["data"]
      end,

      webhook_unsubscribe: lambda do |webhook_subscribe_output, connection|
        delete("https://api.ciscospark.com/v1/webhooks/#{webhook_subscribe_output['id']}")
      end,

      dedup: lambda do |message|
        message["id"]
      end,

      output_fields: lambda do |object_definitions|
        [
          {
            name: "id"
          },
          {
            name: "roomId"
          },
          {
            name: "personId"
          },
          {
            name: "personEmail"
          },
          {
            name: "created"
          }
        ]
      end
    }
  },
  # More connector code here
}

# ステップ1 - トリガーのタイトル、サブタイトル、説明、ヘルプ

優れたトリガーの作成に向けた最初のステップは、そのトリガーが何を実行するかを適切に伝え、さらにユーザーに追加のヘルプを提供することです。そのために Workato では、アクションのタイトルと説明を定義したり、ヒントを提供したりできるようにしています。簡単に言えば、タイトルはアクションの名称であり、サブタイトルはそのアクションのより詳しい内容を表します。続いて、アクションの説明は、接続先となるアプリケーションにおいてそのアクションがどのようなことを達成するかについて、仕様や解説を提供します。最後に、ヘルプのセグメントは、アクションをうまく機能させるために必要な追加情報をユーザーに提供します。

このステップの詳細については、Workato の SDK リファレンスを参照してください。

# ステップ2 - 入力項目の定義

この部分では、このトリガーを設定するユーザーに向けて表示すべき項目を Workato に指示します。この場合、Candidate イベントのタイプを選択できる単純な入力項目が必要です。これは、後でトリガーコードで使用され、トリガーの個人用 Webhook キーを作成します。

    input_fields: lambda do |object_definitions|
      [
        {
          name: "id",
          label: "Room ID"
        }
      ]
    end,

入力/出力項目に関しては、上記で定義したもの以外にも、さまざまなキーと値のペアが存在します。詳細については、こちらを参照してください。

オブジェクトの定義

引数として object_definitions が渡されていることに注意してください。Workato では、コネクターの作成者が "object_definitions" キー内でオブジェクトの定義を独立して記述できるようになっています。このキーは、オブジェクトの定義が長大である場合や、定義が動的に取得される場合に使用されます。

この詳細については、Workato の SDK リファレンスを参照してください。

# ステップ3 - トリガーの Webhook サブスクリプションロジック、Webhook 処理および破棄ロジックの定義

レシピが開始されたら、Webhook サブスクリプションを作成する必要があります。この Webhook サブスクリプションには、ジョブとして受け取って処理するレシピに固有の「Webhook URL」を指定する必要があります。これを担当するのが webhook_subscribe lambda 関数であり、レシピが開始されるたびに実行されます。これを行うため、lambda 関数は次の引数を受け取ります。

  1. webhook_url - 各レシピに固有の動的に生成された Webhook URL。
  2. connection - Freshworks へのコネクション作成時にユーザーが指定した値に対応します。
  3. input - このトリガーの入力に対応します。この場合は、単一の入力である id になります。
  4. closure - 前回のポーリングから渡されたハッシュに対応します。レシピが最初に開始された場合は nil です。

以下に、webhook_url のサブスクリプションを処理する new_message トリガー内の lambda 関数を示します。このブロック内で POST リクエストを Cisco Spark API エンドポイントに送信します。関連する詳細については、こちら (opens new window)を参照してください。

    webhook_subscribe: lambda do |webhook_url, connection, input, recipe_id|
      post("https://api.ciscospark.com/v1/webhooks",
           name: "Workato recipe #{recipe_id}",
           targetUrl: webhook_url,
           resource: "messages",
           event: "created",
           filter: "roomId=#{input['id']}")
    end,

TIP

webhook_subscribe 内の HTTP リクエストがエラーになった場合は、エンドユーザーに通知され、レシピは開始されません。

次のステップでは、webhook_notifications lambda 関数で Webhook 処理を定義します。トリガーへのユーザー入力と Webhook 自体の両方を表すさまざまな引数を使用できます。Webhook のペイロードをジョブとして送信するには、単純に payload 引数を渡します。必要に応じて headers から属性を追加することもできます。Cisco の場合は、ここ (opens new window)にあるペイロードから関係のない詳細をいくつか取り除いています。

    webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params|
      payload["data"]
    end,

最後の部分では、レシピが停止したときに、この Webhook サブスクリプションを破棄します。これは、ターゲットアプリケーションで Webhook を適切にサニタイズするために重要であり、レシピが停止したときに呼び出される webhook_unsubscribe lambda 関数によって処理されます。webhook_subscribe lambda 関数の出力を表す単一の引数を使用できます。この場合は、Cisco /v1/webhooks エンドポイントへの最初のリクエストからのレスポンスになります。

この引数を使用して、作成したサブスクリプションの id を識別し、一致する DELETE リクエストを v1/webhooks エンドポイントに送信して、この Webhook を削除できます。

    webhook_unsubscribe: lambda do |webhook_subscribe_output, connection|
      delete("https://api.ciscospark.com/v1/webhooks/#{webhook_subscribe_outputhook['id']}")
    end,

上記のキーの詳細については、Workato の SDK リファレンスを参照してください。

# ステップ4 - 出力項目と dedup の定義

このセクションでは、トリガーの出力として表示するデータピルと、重複レコードを回避してジョブが繰り返されないようにする方法を指示します。ジョブが繰り返されないようにする (これは Webhook が2回送信された場合に発生する可能性があります) には、レコードごとに一意の署名を作成する方法をコネクターに指示する dedup ブロックを使用します。この署名はレシピごとに保存され、同じ署名のレコードが見つかった場合、ジョブは作成されません。

データピルの場合は、output_fields lambda 関数を使用します。各データピルの name 属性は、webhook_notifications lambda 関数の出力であるハッシュのキーと一致する必要があります。

    dedup: lambda do |message|
      message["id"]
    end,

    output_fields: lambda do |object_definitions|
      [
        {
          name: "id"
        },
        {
          name: "roomId"
        },
        {
          name: "personId"
        },
        {
          name: "personEmail"
        },
        {
          name: "created"
        }
      ]
    end

  # Sample output of the webhook_notification: lambda function
  {
    "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvOTJkYjNiZTAtNDNiZC0xMWU2LThhZTktZGQ1YjNkZmM1NjVk",
    "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
    "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "personEmail": "matt@example.com",
    "created": "2015-10-18T14:26:16.000Z"
  }

出力項目ブロックの詳細については、Workato の SDK リファレンスを参照してください。

オブジェクトの定義

引数として object_definitions が渡されていることに注意してください。Workato では、コネクターの作成者が "object_definitions" キー内でオブジェクトの定義を独立して記述できるようになっています。このキーは、オブジェクトの定義が長大である場合や、定義が動的に取得される場合に使用されます。

この詳細については、Workato の SDK リファレンスを参照してください。

# ステップ5 - Webhook イベントの保護

Webhook を受け取るようになったら、チェックを追加して、受け取る Webhook イベントの信頼性を検証することを検討してください。

# レート制限

このトリガーには、Webhook ゲートウェイの制限が適用されます。

← 静的 Webhook トリガー
ハイブリット Webhookトリガー →


Last updated: 2023/8/31 1:07:14

On this page