SDKリファレンス-triggers
このセクションでは、トリガーを定義するために使用できるすべてのキーを列挙します。 Workatoで使用できるトリガーには3種類あります:
- ポーリングトリガー(5分ごとに新しいイベントを確認)
- 動的Webhookトリガー(Webhookからリアルタイムでトリガーします。 AppでWebhook URLのプログラムによるサブスクリプションおよび解除が可能である必要があります)
- 静的Webhookトリガー(Webhookからリアルタイムでトリガーします。 Webhook URLはエンドユーザーによってWorkatoからAppに渡されます。)
クイック概要
triggersキーは、正常なコネクションを作成した後に、レシピとSDKのテストコードタブの両方でのみ使用できます。 トリガーはコネクタのエンドユーザーによって設定され、レシピを開始します。
構造
triggers: {
[Unique_trigger_name]: {
title: String,
subtitle: String,
description: lambda do |input, picklist_label|
String
end,
help: lambda do |input, picklist_label|
Hash
end,
display_priority: Integer,
batch: Boolean,
bulk: Boolean,
deprecated: Boolean,
config_fields: Array
input_fields: lambda do |object_definitions, connection, config_fields|
Array
end,
webhook_key: lambda do |connection, input|
String
end,
webhook_response_type: String,
webhook_response_body: String,
webhook_response_headers: String,
webhook_response_status: Integer,
webhook_payload_type: String,
webhook_subscribe: lambda do |webhook_url, connection, input, recipe_id|
Hash or Array
end,
webhook_refresh: lambda do |webhook_subscribe_output|
Array
end,
webhook_unsubscribe: lambda do |webhook_subscribe_output, connection|
Hash
end,
webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params, connection, webhook_subscribe_output|
Hash or Array
end,
poll: lambda do |connection, input, closure|
Hash
end,
dedup: lambda do |record|
String
end,
output_fields: lambda do |object_definitions, connection, config_fields|
Array
end,
sample_output: lambda do |connection, input|
Hash
end,
summarize_input: Array,
summarize_output: Array
},
[Another_unique_trigger_name]: {
...
}
},title
| 属性 | 説明 |
|---|---|
| キー | title |
| タイプ | 文字列 |
| 必須 | 任意です。 ラベル付きキーから作成されたタイトルがデフォルトです。 |
| 説明 | これにより、トリガーのタイトルを定義できます。これは割り当てられたキーの名前と異なる場合があります。Key = new_updated_object、title = "New/updated object" |
| 想定される出力 | String 例: "New/updated object" |
| UIリファレンス | ![]() |
TIP
Workatoでは、通常、トリガーには"[Adjective] [Object]"という構造を推奨しています。"Lead created"ではなく、"New lead"または"New/updated contact"を使用します。
subtitle
| 属性 | 説明 |
|---|---|
| キー | subtitle |
| タイプ | 文字列 |
| 必須 | 任意です。 コネクタ名とトリガータイトルから推測されるサブタイトルがデフォルトです。 |
| 説明 | これにより、トリガーのサブタイトルを定義できます。 |
| 想定される出力 | String 例: "Use complex queries to search objects in Percolate" |
| UIリファレンス | ![]() |
TIP
サブタイトルをわかりやすくするには、タイトルを簡潔に保ちながら、ここにより多くの情報を記載してください。 たとえば、タイトルを"New/updated object"にし、サブタイトルを"Trigger off new/updated leads, contacts etc."にできます。 ユーザーが特定のトリガーを検索すると、Workatoはサブタイトル内の一致も検索します。
description
| 属性 | 説明 |
|---|---|
| キー | description |
| タイプ | ラムダ関数 |
| 必須 | 任意です。 コネクタ名とトリガータイトルから推測される説明がデフォルトです。 |
| 説明 | これにより、レシピエディターで表示されるトリガーの説明を定義できます。 これは、必要に応じて静的な説明または動的な説明にできます。 |
| 指定可能な引数 | input-input_fieldsで定義されたユーザー指定の入力を表すHash picklist_label-ユーザーの回答がピックリストラベルと値の両方で構成されるピックリストにのみ適用されます。 このHashは、ピックリストフィールドに対するユーザー指定の入力のラベルを表します。 ユースケースについては以下を参照してください。 |
| 想定される出力 | String 例: "New or updated <span class='provider'>campaign</span> in <span class='provider'>Percolate</span>" 説明テキストに強調を追加するには、<span> HTMLタグを追加します。 |
| UIリファレンス | ![]() |
例-description:
descriptionブロックでは、説明を動的にするために2つの引数にアクセスできます。 これは、特定のユーザーによるアクションの設定方法に基づいて説明を変更したい場合に便利です。 これらの変更は、ユーザーがアクションの設定をクリックして表示しなくても、そのアクションの処理内容を把握できるようにするうえで非常に役立ちます。
new_updated_object: {
description: lambda do |input, picklist_label|
"New or updated <span class='provider'>#{picklist_label['object'] || 'object'}</span> in " \
"<span class='provider'>Percolate</span>"
end,
config_fields: [
{
name: 'object',
control_type: 'select',
pick_list: 'object_types',
optional: false
}
]
# More keys to define the action
}前述の例では、アクションは汎用オブジェクトアクションであり、ユーザーはレシピを設定する際に複数のオブジェクトタイプから選択できます。 picklist_label引数を参照することで、ユーザーが選択したオブジェクトの説明を変更できます。

help
| 属性 | 説明 |
|---|---|
| キー | help |
| タイプ | ラムダ関数 |
| 必須 | 任意です。 それ以外の場合、ヘルプは表示されません。 |
| 説明 | このトリガーの設定方法についてユーザーをガイドするためのヘルプテキストです。 ドキュメントを参照するように案内することもできます。 |
| 指定可能な引数 | input-input_fieldsで定義されたユーザー指定の入力を表すHash picklist_label-ユーザーの回答がピックリストラベルと値の両方で構成されるピックリストにのみ適用されます。 このHashは、ピックリストフィールドに対するユーザー指定の入力のラベルを表します。 ユースケースについては以下を参照してください。connection-connectionで定義されたユーザー指定の入力を表すHash。 webhook_base_url-静的Webhookトリガーを使用している場合に使用されます。 コネクタの静的Webhook URLを表すString。 |
| 想定される出力 | HashまたはString 例については以下を参照してください。 |
| UIリファレンス | ![]() |
例-help:
help lambda関数の出力は、単純なStringまたはHashのいずれかにできます。 以下では2つの例を説明します:
- 文字列
help: lambda do |input, picklist_label, connection, webhook_base_url|
'Create an object in Percolate. First, select from a list of ' \
'objects that we currently support. After selecting your object,' \
' dynamic input fields specific to your scope and object selected ' \
'will be populated.' \
' Creating an approval denotes submitting a specified piece of content' \
' or campaign for a specific approval workflow.'
end,- ハッシュ
help: lambda do |input, picklist_label, connection, webhook_base_url|
{
body: "First, filter by the object you want then fill up the input fields " \
"which appear based on the object you have selected. Amongst other things, " \
"you’ll be able to search for contacts in your company and cloud recordings from the past. ",
learn_more_url: "https://docs.workato.com/connectors/zoom/event-actions.html#search-event-details",
learn_more_text: "Learn more"
}
end,
例-静的Webhookトリガー-コネクションと入力を使用して一意のWebhook URLを作成する
1つのコネクタと静的Webhook URLで複数のコネクションにわたる複数のレシピを動作させる必要がある場合、ユーザーに各コネクション固有の属性を含むWebhook URLを登録してもらう必要がある場合があります。 現在は、help lambdaを通じてこれを実行できます。WebhookのURLパラメーター内に任意のコネクション属性を含む、ユーザーが登録するWebhook URLを提供できます。
{
title: "Sample connector",
webhook_keys: lambda do |params, headers, payload|
"#{params['org_id']}@#{payload['formId']}"
end,
triggers: {
sample_static_webhook_trigger: {
help: lambda do |input, picklist_label, connection, webhook_base_url|
next unless webhook_base_url.present?
<<~HTML
Creates a job when an form submission is received. To set this webhook up,
'you will need to register the webhook below under "settings" => "webhooks" => "new". <br>
<b>Webhook endpoint URL</b>
<b class="tips__highlight">#{webhook_base_url}?org_id=#{connection['org_id']}</b>
HTML
end,
webhook_key: lambda do |connection, input|
"#{connection['org_id']}@#{input['formId']}"
end,
input_fields: lambda do |object_definitions, connection, config_fields|
[
{
name: 'formId',
label: "Form",
control_type: "select",
pick_list: "forms",
hint: "Select the form you want to trigger this recipe off."
}
]
end,
}
}
}display_priority
| 属性 | 説明 |
|---|---|
| キー | display_priority |
| タイプ | 整数 |
| 必須 | 任意です。 デフォルトはゼロです。それ以外の場合は、アクションタイトルのアルファベット順になります。 |
| 説明 | これにより、レシピエディターでのトリガーの順序に影響を与え、上位のトリガーを強調表示できます。 整数が大きいほど、優先度が高くなります。 2つのトリガーの優先度が同じ場合、タイトル順に並べられます。 |
batch
| 属性 | 説明 |
|---|---|
| キー | batch |
| タイプ | ブール値 |
| 必須 | 任意です。 |
| 説明 | これにより、アクションの横に"Batch"タグが表示され、このアクションが複数のレコードで動作することを示します。 通常、ユーザーがレコードのリストを渡せるバッチトリガーまたはバッチ作成/更新/upsertアクションで使用されます。 |
| UIリファレンス | ![]() |
bulk
| 属性 | 説明 |
|---|---|
| キー | bulk |
| タイプ | ブール値 |
| 必須 | 任意です。 |
| 説明 | これにより、アクションの横に"Bulk"タグが表示され、このアクションがレコードの大きなフラットファイルで動作することを示します。 通常、ユーザーがレコードのCSVを渡す一括作成/更新/upsertアクションで使用されます。 |
| UIリファレンス | ![]() |
deprecated
| 属性 | 説明 |
|---|---|
| キー | deprecated |
| タイプ | ブール値 |
| 必須 | 任意です。 |
| 説明 | これにより、アクションの横に"deprecated"タグが表示され、このアクションが非推奨になったことを示します。 以前にこのアクションを使用していたレシピは引き続き動作しますが、今後のレシピではこのアクションを検索および選択できません。 |
| UIリファレンス | ![]() |
TIP
非推奨化は、変更に後方互換性がない場合にユーザーを新しいアクションへ移行させる優れた方法です。 これにより、アクションをより使いやすくしたり、今後のAPI変更に対応したりする自由度が高まります。
config_fields
| 属性 | 説明 |
|---|---|
| キー | config_fields |
| タイプ | 配列 |
| 必須 | 任意です。 |
| 説明 | このキーは、ユーザーに表示される入力フィールドとして表示されるHashの配列を受け入れます。 設定フィールドは入力フィールドがレンダリングされる前にユーザーに表示され、エンドユーザーに表示する入力フィールドのセットを変更するために使用できます。 これは、設定フィールドでユーザーにオブジェクトを選択させ、その選択に基づいて入力フィールドをレンダリングする汎用オブジェクトアクションでよく使用されます。 config_fieldsに指定された入力は、input_fields lambda関数内の引数を介してコネクタから参照できます。 これはすべてのobject_defintionsにも引数として存在します。 設定フィールドの定義の詳細については、Workato Schemaを参照してください。 |
| 想定される出力 | Hashの配列。 この配列内の各Hashは、個別の設定フィールドに対応します。 |
| UIリファレンス | ![]() |
TIP
設定フィールドは、アクションに動的な動作を導入するための強力なツールです。 これらを使用してコネクタをより使いやすくし、新しい機能を見つけやすくします。 上記のサンプルGIFでは、入力"Event"によって実際にさらに多くの入力フィールドがレンダリングされることがわかります。 これらの入力フィールドは、値"Meeting"の選択に基づいてレンダリングされます。
input_fields
| 属性 | 説明 |
|---|---|
| キー | input_fields |
| タイプ | ラムダ関数 |
| 必須 | True |
| 説明 | このlambda関数を使用すると、レシピエディターでこのトリガーを設定するユーザーに表示する入力フィールドを定義できます。 このlambda関数の出力はHashの配列である必要があり、この配列内の各Hashは個別の入力フィールドに対応します。 入力フィールドの定義の詳細については、Workato Schemaを参照してください。 |
| 指定可能な引数 | object_definitions-オブジェクト定義を参照できます。 オブジェクト定義は、入力フィールドまたは出力フィールド(データピル)の両方を表すために使用できるこれらのHash配列の格納場所です。 これらは任意のアクションまたはトリガーから参照できます。 connection-connectionで定義されたユーザー指定の入力を表すHash。 config_fields-該当する場合、config_fieldsで定義されたユーザー指定の入力を表すHash。 |
| 想定される出力 | Hashの配列。 この配列内の各ハッシュは、個別の入力フィールドに対応します。 |
| UIリファレンス | ![]() |
webhook_key
| 属性 | 説明 |
|---|---|
| キー | webhook_key |
| タイプ | ラムダ関数 |
| 必須 | トリガーが静的Webhookトリガーの場合はTrue。 それ以外の場合はfalseです。 webhook_subscribe、webhook_unsubscribeが定義されている場合は使用しないでください。 |
| 説明 | コネクタのルートレベルキーとして存在する必要があるwebhook_keysと組み合わせて使用されます。actionsおよびtriggersと同じレベルです コネクションまたはトリガーからの任意のユーザー入力を使用して、このトリガーの一意の署名を構築できます。 これは静的な文字列値にすることもできます。 このlambda関数の署名が webhook_keys lambda関数の署名と一致すると、Webhookはこのトリガーに送信されます。 詳細については、静的Webhookガイドを参照してください。 |
| 指定可能な引数 | connection-connectionで定義されたユーザー指定の入力を表すHash。 input-input_fieldsで定義されたユーザー指定の入力を表すHash |
| 想定される出力 | Hashの配列。 この配列内の各ハッシュは、個別の入力フィールドに対応します。 |
例-webhook_key:
webhook_key lambda関数は単一のトリガーに固有で、出力署名はユーザー入力から構築されます。 一方、webhook_keys lambda関数はコネクタ全体に関連付けられており、出力署名は受信Webhookの本文、ヘッダー、クエリパラメーターなどの属性から構築されます。 これら2つの署名の一致を想定すると、受信Webhookから適切なトリガーへルーティングしてジョブを作成する仕組みがわかりやすくなります。
{
title: "Sample connector",
webhook_keys: lambda do |params, headers, payload|
payload['formId']
end,
triggers: {
sample_static_webhook_trigger: {
help: lambda do |_input, _picklist_label|
{
body: “Triggers in real-time whenever an event is created. Set up this trigger by registering the Webhook URL ” \
“below in <b>Settings</b> => <b>Webhooks</b>.“,
learn_more_url: “https://docs.workato.com”,
learn_more_text: “Learn more”
}
end,
webhook_url_help: lambda do |_connection, _input, webhook_base_url|
webhook_base_url
end,
input_fields: lambda do |object_definitions, connection, config_fields|
[
{
name: 'formId',
label: "Form",
control_type: "select",
pick_list: "forms",
hint: "Select the form you want to trigger this recipe off."
}
]
end,
webhook_key: lambda do |connection, input|
input['formId']
end,
}
}
}webhook_response_type
| 属性 | 説明 |
|---|---|
| キー | webhook_response_type |
| タイプ | 文字列 |
| 必須 | 任意です。 動的Webhookトリガー(webhook_subscribeおよびwebhook_unsubscribeを持つトリガー)にのみ適用されます |
| 説明 | デフォルトでは、WorkatoはWebhookイベントに対してcontent-typeヘッダーなしで応答します。 webhook_response_typeでは'plain'と'json'を使用でき、それぞれcontent-typeヘッダーtext/plainとapplication/jsonに対応します。 |
webhook_response_body
| 属性 | 説明 |
|---|---|
| キー | webhook_response_body |
| タイプ | 文字列 |
| 必須 | 任意です。 動的Webhookトリガー(webhook_subscribeおよびwebhook_unsubscribeを持つトリガー)にのみ適用されます |
| 説明 | デフォルトでは、WorkatoはWebhookイベントに対して空の本文で応答します。 webhook_response_bodyでは、WorkatoがWebhookにどのように応答するかを定義できるmustacheテンプレートを使用できます。 |
Mustacheテンプレートでは、次の変数にアクセスできます:
| name | 説明 | 使用例 |
|---|---|---|
| headers | リクエストヘッダーを含みます。 ヘッダーは正規化されます(x-custom-header -> X-Custom-Header) | { “challenge”:“{{{headers.X-Challenge}}}” } |
| body | リクエスト本文はwebhook_response_typeに従って解析されます。 ドット表記を使用してネストされた値にアクセスできます。 | { “challenge”: “{{body.x-challenge}}” } |
| query | クエリパラメーターを含みます | { “X-Challenge”: “{{query.challenge}}” } |
例-webhook_response_body:-カスタムWebhook応答の定義
webhook_response_bodyは2つのシナリオで使用します:
- Webhook送信者に静的な文字列またはJSON応答で応答する必要がある場合。
webhook_response_type: 'json',
webhook_response_body: '{ "success": true }',これにより、Workatoはcontent-typeapplication/jsonと本文で応答します
{
"success": true
}- Webhookイベントに基づいて動的な応答で応答する必要がある場合。 たとえば、Webhook送信者がWebhook URLの準備完了を確認するためにWebhookイベントを送信する場合です。
webhook_response_type: 'json',
webhook_response_body: '{ “challenge”: “{{body.verification.Challenge}}” }',送信者が次の本文でWebhookを送信した場合
{
"verification": {
"Challenge": "abc123"
}
}その後、Workatoは次のように応答します
{
"challenge": "abc123"
}場合によっては、Webhook送信者がイベントの配列を送信することもあります。 Mustacheで通常のイテレーターを使用して配列を処理することもできます。
たとえば、Microsoft Event Gridに基づく送信者が次の本文でWebhook検証イベントを送信した場合
[
{
"id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
"topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"subject": "",
"data": {
"validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6",
"validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/myeventsub/validate?id=0000000000-0000-0000-0000-00000000000000&t=2022-10-28T04:23:35.1981776Z&apiVersion=2018-05-01-preview&token=1A1A1A1A"
},
"eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
"eventTime": "2022-10-28T04:23:35.1981776Z",
"metadataVersion": "1",
"dataVersion": "1"
}
]そして、data.validationCodeで応答することが求められます。 webhook_response_bodyを次のように定義できます。
webhook_response_type: 'json',
webhook_response_body: '{{#body}}{ "validationResponse": “{{data.validationCode}}” }{{/body}}',Webhook送信者がカスタム応答を期待するさまざまな状況があります:
- 各Webhookイベントに対する静的または動的な応答
- Webhook URLがイベントを受け入れる準備ができていることを確認するためのチャレンジへの応答
調査では、両方が該当するケースはほとんど見つかっていません。 そのため、この単一のキーwebhook_response_bodyは、両方のユースケースを実現することを目的としています。 Webhook応答をより細かく制御するために、mustacheテンプレートでinverted sectionsなどの組み込みロジックを使用することもできます。
webhook_response_headers
| 属性 | 説明 |
|---|---|
| キー | webhook_response_headers |
| タイプ | 文字列 |
| 必須 | 任意です。 動的Webhookトリガー(webhook_subscribeおよびwebhook_unsubscribeを持つトリガー)にのみ適用されます |
| 説明 | デフォルトでは、WorkatoはWebhookイベントに対して標準ヘッダー(レート制限、バイト制限)で応答します。 webhook_response_headersでは、Workatoが応答ヘッダーに含めるヘッダーを定義できるmustacheテンプレートを使用できます。 webhook_response_bodyを参照してください |
WARNING
Workatoでは、x-forwarded-host、x-forwarded-proto、x-forwarded-port、x-forwarded-for、x-request-id、x-frame-options、x-powered-byを除き、x-で始まるヘッダーのカスタマイズのみをサポートしています。
webhook_response_status
| 属性 | 説明 |
|---|---|
| キー | webhook_response_status |
| タイプ | 整数 |
| 必須 | 任意です。 動的Webhookトリガー(webhook_subscribeおよびwebhook_unsubscribeを持つトリガー)にのみ適用されます |
| 説明 | デフォルトでは、WorkatoはWebhookイベントに対して200で応答します。 webhook_response_statusを使用すると、これを任意の2XX応答コードにカスタマイズできます。 |
WARNING
Workatoでは、2XXレスポンスコードのカスタマイズのみをサポートしています。
webhook_payload_type
| 属性 | 説明 |
|---|---|
| キー | webhook_payload_type |
| タイプ | 文字列 |
| 必須 | 任意です。 デフォルトは"parsed" |
| 説明 | デフォルトでは、WorkatoはJSON.parse()を使用して受信Webhookペイロードを解析します。 webhook_payload_typeを"raw"に設定すると、JSON解析済みのペイロードではなく、生のWebhookペイロードを受信できます。 |
例-webhook_payload_type:-Webhookの検証またはXML Webhookの処理
webhook_payload_typeは2つのシナリオで使用します:
- rawペイロードに基づいてWebhookペイロード署名を計算する必要がある場合。 解析済みjsonペイロードを取得するために
workato.parse_jsonを使用する前に、Webhook通知lambdaでこれを行うことができます。
webhook_payload_type: "raw",
webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params, connection, webhook_subscribe_output|
original_payload = payload
client_secret = input['client_secret'] || account_property('hubspot_webhook_client_secret')
if client_secret.present?
source_string = client_secret + original_payload
v1_signature = source_string.encode_sha256.encode_hex
end
if (client_secret.present? && v1_signature == headers['X-Hubspot-Signature']) || !client_secret.present?
payload = workato.parse_json(payload).select do |event|
event['propertyName'] == input['contact_property'] && event['subscriptionType'] == 'contact.propertyChange'
end
if payload.length > 0
{
events: payload,
headers: headers,
webhook_validated: client_secret.present? ? true : false
}
end
end
end,- JSON形式ではないWebhookを受信している場合。
webhook_payload_type: "raw",
webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params, connection, webhook_subscribe_output|
payload.from_xml
end,webhook_subscribe
| 属性 | 説明 |
|---|---|
| キー | webhook_subscribe |
| タイプ | ラムダ関数 |
| 必須 | トリガーが動的Webhookトリガーの場合はTrue。 それ以外の場合はfalseです。 webhook_keyが定義されている場合は使用しないでください。 |
| 説明 | このlambda関数は、動的WebhookトリガーがプログラムでWebhookをサブスクライブするために使用されます。 この関数は、この定義を持つトリガーを使用してユーザーがレシピを開始したときに呼び出されます。 詳細については、動的Webhookガイドを参照してください。 |
| 指定可能な引数 | webhook_url-レシピ固有のWebhook URLを表すString。 これはWebhookサブスクリプションを作成するときにAPIに渡す必要があります。 connection-connectionで定義されたユーザー指定の入力を表すHash。 input-input_fieldsで定義されたユーザー指定の入力を表すHash recipe_id-Workato内のレシピのIDを表すInt。 |
| 想定される出力 | 出力には2つの可能性があります: - webhook_unsubscribe、webhook_notification、webhook_refresh lambda関数にwebhook_subscribe_outputとして渡されるHash。 - 最初のインデックスが webhook_subscribe_outputとして渡される同じHashで、2番目のインデックスがwebhook_refreshをトリガーするWebhook有効期限日時である配列。 |
有効期限が切れるWebhookサブスクリプションの処理
Microsoft's Graph APIなどの特定のAPIではWebhookサブスクリプションを作成できますが、一定時間後に有効期限が切れます。 つまり、イベントを引き続き受信できるように、トリガーはWebhookサブスクリプションの有効期限が近づいていることをインテリジェントに把握し、このサブスクリプションを更新できる必要があります。
Webhookが1時間後に期限切れになるサンプルコード。
webhook_subscribe: lambda do |webhook_url, connection, input, recipe_id|
[
post("https://www.acme.com/api/webhook_subscriptions", url: webhook_url),
1.hour.from_now
]
end,
webhook_refresh: lambda do |webhook_subscribe_output|
[
patch("https://www.acme.com/api/webhook_subscriptions/#{webhook_subscribe_output['id']}", refresh: true),
1.hour.from_now
]
end,
webhook_unsubscribe: lambda do |webhook_subscribe_output, connection|
delete("https://www.acme.com/api/webhook_subscriptions/#{webhook_subscribe_output['id']}")
end,上記の例では、webhook_subscribeの出力は、Webhookサブスクリプションを更新するために次にwebhook_refreshが呼び出される時刻に対応する日時値を含む配列です。 これはwebhook_refreshについても同様に行われます。 webhook_refreshの出力は元のwebhook_subscribe_outputも置き換えることに注意してください。
webhook_refresh
| 属性 | 説明 |
|---|---|
| キー | webhook_refresh |
| タイプ | ラムダ関数 |
| 必須 | False. webhook_subscribeが定義されている場合にのみ適用されます。 |
| 説明 | このlambda関数は、Webhookサブスクリプションにwebhook_subscribeの出力で定義された有効期限が設定されている場合に呼び出されます。 これにより、トリガーがイベントを引き続き受信できるようにWebhookサブスクリプションを更新できます。 |
| 指定可能な引数 | webhook_subscribe_output-webhook_subscribe lambda関数の出力を表すHash。 |
| 想定される出力 | - 最初のインデックスがwebhook_subscribe_outputとして渡される同じHashで、2番目のインデックスがwebhook_refreshをトリガーするWebhook有効期限日時である配列。 |
webhook_unsubscribe
| 属性 | 説明 |
|---|---|
| キー | webhook_unsubscribe |
| タイプ | ラムダ関数 |
| 必須 | トリガーが動的Webhookトリガーの場合はTrue。 それ以外の場合はfalseです。 webhook_keyが定義されている場合は使用しないでください。 |
| 説明 | このlambda関数は、動的WebhookトリガーがプログラムでWebhookサブスクリプションを解除するために使用されます。 この関数は、この定義を持つトリガーを使用してユーザーがレシピを停止したときに呼び出されます。 詳細については、動的Webhookガイドを参照してください。 |
| 指定可能な引数 | webhook_subscribe_output-webhook_subscribe lambda関数の出力を表すHash。 connection-connectionで定義されたユーザー指定の入力を表すHash。 |
| 想定される出力 | 出力は不要です。 |
webhook_notification
| 属性 | 説明 |
|---|---|
| キー | webhook_notification |
| タイプ | ラムダ関数 |
| 必須 | トリガーが動的Webhookトリガーまたは静的Webhookトリガーのいずれかの場合はTrue。 |
| 説明 | このlambda関数は、このトリガーに送信されたWebhookに対してこのトリガーが何を行うかを処理します。 この関数を使用して、任意のデータ操作を実行できます。 このlambda関数では、追加のHTTPリクエストを行ったり、追加の再利用可能なmethodsを呼び出したりすることはできません。 |
| 指定可能な引数 | input-input_fieldsで定義されたユーザー指定の入力を表すHash payload-受信Webhookのペイロードを表すHash。 extended_input_schema-例については以下を参照してください。 extended_output_schema-例については以下を参照してください headers-受信Webhookのヘッダーを表すHash。 params-受信Webhookのクエリパラメーターを表すHash。 connection-connectionで定義されたユーザー指定の入力を表すHash。 webhook_subscribe_output-webhook_subscribe lambda関数の出力を表すHash。 |
| 想定される出力 | 単一のジョブの出力を表すHash、または個々のジョブを表すHashの配列。 |
メモ
webhook_notification lambdaでは、ユーザーがmethodsまたはHTTPメソッドを呼び出すことはできません。 Webhookペイロードが軽量な場合は、追加のHTTPリクエストを実行するためにトリガーの出力を受け取れるアクションを追加してください。
Webhook検証
- Workatoは、webhookの
Content-Typeヘッダーで示されるJSONベースのwebhookに対して検証を実行し、ペイロードが有効なJSONであることを確認します。 そうでない場合、Workatoは400 bad requestで応答します。 - 受信webhookペイロードはUTF-8互換であることが期待されており、UTF-8非互換の文字が見つかった場合、Workatoは400 bad requestで応答します。
poll
| 属性 | 説明 |
|---|---|
| キー | poll |
| タイプ | ラムダ関数 |
| 必須 | トリガーがポーリングトリガーまたはハイブリッドトリガーの場合はTrue |
| 説明 | このlambda関数は、このトリガーがAPIから新しいレコードを取得してジョブを作成する方法を処理します。 この関数は各ポーリング間隔で呼び出されます(デフォルトは5分ですが、レシピレベルで設定可能です)。 |
| 指定可能な引数 | connection-connectionで定義されたユーザー指定の入力を表すHash。 input-input_fieldsで定義されたユーザー指定の入力を表すHash closure - 同じ関数の前回実行からpoll lambda関数に渡されたカーソル値を表すHash。 extended_input_schema-例については以下を参照してください。 extended_output_schema-例については以下を参照してください |
| 想定される出力 | 3つの属性を含むHash - ジョブに変換されるレコードの配列 - 5分後ではなく直ちに再度ポーリングするようトリガーに指示するBooleanフラグ - closureとして格納され、同じ関数の次回実行に渡される値/Hash。 例については以下を参照してください |
TIP
カーソルに複数の値を格納する必要がある場合、closure値は単純な文字列/整数またはHashのいずれかにできます。
例-poll:
pollブロックの出力は次の構造のHashである必要があります:
poll: lambda do |connection, input, closure, _eis, _eos|
# Timestamp which we need to filter records based off.
updated_since = (closure || input['since']).to_time.utc.iso8601
request_page_size = 100
records = get("/records/endpoint").
params(
# filter for records only updated after this time
updated_since: updated_since,
page_size: request_page_size
)
# Example JSON response
# {
# data: [
# {
# "id": "abcd123",
# "name": "record1"
# ...
# },
# {
# "id": "dcba321",
# "name": "record2",
# ...
# },
# ...
# ],
# total_records: 1000
# }
# Derive last updated since timestamp to filter
next_updated_since = records['data'].last['updated_at'] unless records.blank?
{
# Event accepts an array of records. Each record is a new job.
events: records['data'],
# Closure value which is passed as closure argument in next poll
next_poll: next_updated_since,
# Boolean flag to denote whether we should wait 5 mins to poll or poll immediately.
# Poll immediately if total records is still more than page size.
can_poll_more: records['total_records'] >= request_page_size
}
end,例-poll:-extended_input_schemaおよびextended_output_schema
拡張入力および出力スキーマは、アクションで使用されるobject_definitionsの任意のスキーマです。 この情報は、スキーマを動的に生成し、それを使用してデータの前処理または後処理を行いたい場合によく役立ちます。 これらの引数にはconfig_fieldsは含まれません。
たとえば、extended_input_schemaを使用して、どの入力が日時であり、ターゲットAPIで受け入れられるEpoch時間に変換する必要があるかを把握できます。 同様に、extended_output_schemaを使用して応答を取得し、Epoch変数を再びISO8601日時に変換できます。
create_object: {
description: lambda do |input, picklist_label|
"Create a <span class='provider'>#{picklist_label['object'] || 'object'}</span> in " \
"<span class='provider'>Percolate</span>"
end,
config_fields: [
{
name: 'object',
control_type: 'select',
pick_list: 'object_types',
optional: false
}
],
input_fields: lambda do |object_definitions, connection, config_fields|
object = config_fields['object']
object_definitions[object].ignored('id')
end,
execute: lambda do |connection, input, extended_input_schema, extended_output_schema|
puts extended_input_schema
# [
# {
# "type": "string",
# "name": "status",
# "control_type": "select",
# "label": "Status",
# "hint": "Status is required for creating Content",
# "pick_list": "post_statuses",
# "optional": false
# },
# ...
# ]
puts extended_output_schema
# [
# {
# "type": "string",
# "name": "id",
# "control_type": "text",
# "label": "Content ID",
# "hint": "The Content ID, Example: <b>post:45565410</b>.",
# "optional": true
# },
# {
# "type": "string",
# "name": "status",
# "control_type": "select",
# "label": "Status",
# "hint": "Status is required for creating Content",
# "pick_list": "post_statuses",
# "optional": false
# },
# ...
# ]
end,
output_fields: lambda do |object_definitions, connection, config_fields|
object = config_fields['object']
object_definitions[object]
end,
}dedup
| 属性 | 説明 |
|---|---|
| キー | dedup |
| タイプ | ラムダ関数 |
| 必須 | True。 |
| 説明 | このlambda関数を使用すると、トリガーイベントを重複排除して、同じイベントを2回トリガーしないようにできます。 これは、受信レコードの属性に基づいて一意の署名文字列を作成することで行われます。 |
| 指定可能な引数 | record-単一のレコードを表すHash。 これは、poll lambda関数のevents配列内の単一インデックス、またはwebhook_notification lambda関数のHash出力です。 です。 |
| 想定される出力 | String - "#{record['id']}@#{record['created_at']}"または"#{record['id']}@#{record['updated_at']}" |
output_fields
| 属性 | 説明 |
|---|---|
| キー | output_fields |
| タイプ | ラムダ関数 |
| 必須 | True |
| 説明 | このlambda関数を使用すると、レシピエディターでこのトリガーを設定するユーザーに表示する出力フィールド(データピル)を定義できます。 このlambda関数の出力はHashの配列である必要があり、この配列内の各Hashは個別の出力フィールド(データピル)に対応します。 出力フィールドの定義の詳細については、Workato Schemaを参照してください。 |
| 指定可能な引数 | object_definitions-オブジェクト定義を参照できます。 オブジェクト定義は、入力フィールドまたは出力フィールドのいずれかを表すことができるこれらの配列の格納場所です。 これらは任意のアクションまたはトリガーから参照できます。 connection-connectionで定義されたユーザー指定の入力を表すHash。 config_fields-該当する場合、config_fieldsで定義されたユーザー指定の入力を表すHash。 |
| 想定される出力 | Hashの配列。 この配列内の各ハッシュは、個別の入力フィールドに対応します。 |
| UIリファレンス | ![]() |
sample_output
| 属性 | 説明 |
|---|---|
| キー | sample_output |
| タイプ | ラムダ関数 |
| 必須 | False. |
| 説明 | このlambda関数を使用すると、出力フィールド(データピル)の横に表示されるサンプル出力を定義できます。 |
| 指定可能な引数 | connection-connectionで定義されたユーザー指定の入力を表すHash。 input-input_fieldsで定義されたユーザー指定の入力を表すHash |
| 想定される出力 | Hash。 このHashは、execute lambda関数のスタブ化された出力である必要があります。 |
| UIリファレンス | ![]() |
summarize_input
| 属性 | 説明 |
|---|---|
| キー | summarize_input |
| タイプ | 配列 |
| 必須 | False. |
| 説明 | 長いリストを含む入力を要約するには、これを使用します。 入力を要約することは、ジョブページを軽量に保ち、すばやく読み込めるようにするために重要です。 一般に、入力に100行を超えるリストがある場合は要約する必要があります。 |
| 想定される出力 | Array。 例: ['leads']または['report.records', 'report.description'] |
summarize_output
| 属性 | 説明 |
|---|---|
| キー | summarize_output |
| タイプ | 配列 |
| 必須 | False. |
| 説明 | 長いリストを含むアクション出力を要約するには、これを使用します。 出力を要約することは、ジョブページを軽量に保ち、すばやく読み込めるようにするために重要です。 一般に、出力に100行を超えるリストがある場合は要約する必要があります。 |
| 想定される出力 | Array。 例: ['leads']または['report.records', 'report.description'] |
| UIリファレンス | ![]() |
例-ジョブデータ内の入力と出力の要約
大きな配列やデータを扱う場合、Workatoは各アクションのジョブの入力タブと出力タブにすべてのデータを表示しようとします。 大きな数のレコードや長い文字列を扱う場合、これがわかりにくくなることがあります。 summarize_inputキーとsummarize_outputキーを使用して、ジョブの入力タブと出力タブのデータを要約し、コネクタのユーザーにとって読みやすくできます。
input_fields: lambda do
[
{
name: 'report',
type: 'object',
properties: [
{
name: 'records',
type: :array,
of: :object,
properties: [
{
name: 'item_name',
type: 'string'
}
]
},
{
name: 'description',
type: 'string'
},
{
name: 'comment',
type: 'string'
}
],
}
]
end,
summarize_input: ['report.records', 'report.description'],Last updated:











