ハウツーガイド - ポーリングトリガー
ポーリングトリガーは、新しいイベントを取得するために、固定の時間間隔でpollキーを継続的に実行します。 この時間間隔のデフォルトは5分ごとですが、ユーザーがレシピ内でトリガーを設定する際に変更できます。 ポーリングトリガーは、各間隔でHTTPリクエストを実行し、前回ポーリングした時点以降の新しいレコードまたはイベントについてAPIにクエリすることで機能します。 これは、トリガーロジックに埋め込まれたカーソルによって可能になります。
サンプルコネクター - Freshdesk
{
title: 'My Freshdesk connector',
# More connector code here
triggers: {
updated_ticket: {
title: 'New/updated ticket',
subtitle: "Triggers when a ticket is created or " \
"updated in Freshdesk",
description: lambda do |input, picklist_label|
"New/updated <span class='provider'>ticket</span> " \
"in <span class='provider'>Freshdesk</span>"
end,
help: "Creates a job when tickets are created or " \
"updated in Freshdesk. Each ticket creates a separate job.",
input_fields: lambda do |object_definitions|
[
{
name: 'since',
label: 'When first started, this recipe should pick up events from',
type: 'timestamp',
optional: true,
sticky: true,
hint: 'When you start recipe for the first time, it picks up ' \
'trigger events from this specified date and time. Defaults to ' \
'the current time.'
}
]
end,
poll: lambda do |connection, input, closure, _eis, _eos|
closure = {} unless closure.present?
page_size = 100
updated_since = (closure['cursor'] || input['since'] || Time.now ).to_time.utc.iso8601
tickets = get("https://#{connection['helpdesk']}.freshdesk.com/api/v2/tickets.json").
params(order_by: 'updated_at',
order_type: 'asc',
per_page: page_size,
updated_since: updated_since)
closure['cursor'] = tickets.last['updated_at'] unless tickets.blank?
{
events: tickets,
next_poll: closure,
can_poll_more: tickets.length >= page_size
}
end,
dedup: lambda do |record|
"#{record['id']}@#{record['updated_at']}"
end,
output_fields: lambda do |object_definitions|
[
{
name: 'id',
type: 'integer'
},
{
name: 'email'
},
{
name: 'subject'
},
{
name: 'description'
},
{
name: 'created_at'
},
{
name: 'updated_at'
}
]
end,
sample_output: lambda do |connection, input|
{
"id": 1234,
"email": "[email protected]",
"subject": "Account provisioning",
"description": "I need access to my account"
}
end
}
}
# More connector code here
}ステップ1 - トリガーのタイトル、サブタイトル、説明、およびヘルプ
優れたトリガーを作成するための最初のステップは、トリガーの動作を適切に伝え、ユーザーに追加のヘルプを提供することです。 そのため、Workatoではアクションのタイトルと説明を定義し、ヒントを提供できます。 簡単に言えば、タイトルはアクションのタイトルであり、サブタイトルはアクションの詳細を示します。 アクションの説明には、そのアクションが何を実現するかについての仕様と説明、および接続先アプリケーションのコンテキストが含まれます。 最後に、ヘルプセグメントでは、アクションを機能させるために必要な追加情報をユーザーに提供します。
このステップの詳細については、SDKリファレンスを参照してください
ステップ2 - 入力フィールドの定義
このコンポーネントは、このトリガーを設定するユーザーに表示するフィールドをWorkatoに伝えます。 この場合、ユーザーがタイムスタンプ値を選択できるシンプルな入力フィールドが必要です。 これは後でトリガーコード内で使用され、レシピが開始される前に作成または更新されたチケットを取得します。 これは、データの遡及同期のためにコネクターのユーザーに提供できる優れたツールです。
input_fields: lambda do |object_definitions|
[
{
name: 'since',
label: 'When first started, this recipe should pick up events from',
type: 'timestamp',
optional: true,
sticky: true,
hint: 'When you start recipe for the first time, it picks up ' \
'trigger events from this specified date and time. Defaults to ' \
'the current time.'
}
]
end
新規または更新済みチケットの入力フィールド
上記で定義したもの以外にも、入力/出力フィールドにはさまざまなキーと値のペアが存在します。 詳細については、入力フィールドを参照してください。
オブジェクト定義
object_definitionsが引数として渡されることに注意してください。 Workatoでは、コネクタービルダーがオブジェクトの定義を"object_definitions"キーで個別に指定できます。 このキーは、オブジェクトの定義が大きい場合や動的に取得できる場合に使用します。
この詳細については、SDKリファレンスを参照してください
ステップ3 - pollキーの定義
pollキーは、各時間間隔で何を実行するかをWorkatoに伝えます。 各時間間隔で、このpollラムダ関数が呼び出され、該当する新規または更新済みチケットの受信を想定します。
poll: lambda do |connection, input, closure, _eis, _eos|
closure = {} unless closure.present? # initialize the closure hash when recipe is first started.
page_size = 100
updated_since = (closure['cursor'] || input['since'] || Time.now ).to_time.utc.iso8601
tickets = get("/tickets.json").
params(order_by: 'updated_at',
order_type: 'asc',
per_page: page_size,
updated_since: updated_since)
closure['cursor'] = tickets.last['updated_at'] unless tickets.blank?
{
events: tickets,
next_poll: closure,
can_poll_more: tickets.length >= page_size
}
end,上記の例では、3つの引数を受け取ります:
connection- Freshworksへのコネクションを作成する際にユーザーが指定した値に対応しますinput- このトリガーの入力に対応します。 この場合、単一の入力です:sinceclosure- 前回のポーリングから渡されたハッシュに対応します。 レシピが初めて開始されたときはnil
pollラムダ関数内では、新しい変数updated_sinceを初期化する前に、closure引数をオブジェクトとして初期化します。 このupdated_since変数には、存在する場合はclosure['cursor']が割り当てられます（前回のポーリングから渡されたカーソルを示します）。存在しない場合は、レシピが初めて開始されたときの最初のポーリングであることを示すinput['since']が割り当てられます。
次の行では、クエリパラメーターを含むGETリクエストを/tickets.jsonエンドポイントに送信して、関連するチケットを取得します。 チケットが存在する場合、closure['cursor']は最後のチケットのupdated_at属性のタイムスタンプに更新されます。
pollラムダ関数の想定される出力は、3つのキーを持つオブジェクトです:
events- イベントまたはデータの配列は、eventsキーに渡す必要があります。 配列内の各インデックスは、個別のジョブとして処理されます。next_poll- これは、トリガーの次回ポーリングでclosure引数になります。can_poll_more- これは、すぐに再度ポーリングするか、次の間隔でポーリングするかをトリガーに伝えます。 これは、Freshdeskから100件のチケットが返された場合に使用され、前回のポーリング以降に作成または更新されたチケットがさらに存在する可能性があることを示します。
pollキーの詳細については、SDKリファレンスを参照してください
ステップ4 - 出力フィールドとdedupの定義
このセクションでは、トリガーの出力として表示するデータピルと、重複レコードによって重複ジョブが作成されるのを防ぐ方法について説明します。 ジョブの重複を防ぐには（API側のバグが原因で発生する可能性があります）、各レコードに一意のシグネチャを作成する方法をコネクターに伝えるdedupキーを使用します。 このシグネチャは各レシピに保存され、同じシグネチャを持つレコードが見つかった場合、ジョブは作成されません。
データピルには、output_fieldsキーを使用します。 各データピルのname属性は、単一のチケットレコードのキーと一致する必要があります。
dedup: |record|
"#{record['id']}@#{record['updated_at']}"
end,
output_fields: lambda do |object_definitions|
[
{
name: 'id',
type: 'integer'
},
{
name: 'email'
},
{
name: 'subject'
},
{
name: 'description'
}
]
end
新規または更新済みチケットの出力フィールド
# Entire tickets array assigned to the events key
[
{
"id": 1234,
"email": "[email protected]",
"subject": "Account provisioning",
"description": "I need access to my account"
},
{
"id": 4321,
"email": "[email protected]",
"subject": "Account deprovisioning",
"description": "I want to cancel my account"
},
...
]output fieldsキーの詳細については、SDKリファレンスを参照してください
オブジェクト定義
object_definitionsが引数として渡されることに注意してください。 Workatoでは、コネクタービルダーがオブジェクトの定義を"object_definitions"キーで個別に指定できます。 このキーは、オブジェクトの定義が大きい場合や動的に取得できる場合に使用します。
この詳細については、SDKリファレンスを参照してください
ステップ5 - sample outputの定義
サンプル出力キーはコネクターの任意の補足コンポーネントですが、データピルの値がどのようなものかについてのコンテキストをユーザーに提供することで、ユーザーエクスペリエンスを大幅に向上させます。 これにより、ユーザーはレシピをより迅速に作成できます。
sample_output: lambda do |connection, input|
{
"id": 1234,
"email": "[email protected]",
"subject": "Account provisioning",
"description": "I need access to my account"
}
endsample outputキーの詳細については、SDKリファレンスを参照してください
Last updated: