# SDK リファレンス - actions
このセクションでは、アクションを定義するときに使用できるすべてのキーを列挙します。
簡単な概要
actions キーは、コネクションの作成が正常に済んだ後に、レシピとデバッガーコンソールの両方でのみ使用できます。アクションは、レシピ内の以前のステップからのデータをデータピルを介して取得したり、エンドポイントにリクエストを送信したり、レスポンスをデータピルとして提供したりします。
# 構造
actions: {
[Unique_action_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,
execute: lambda do |connection, input, extended_input_schema, extended_output_schema, continue|
Hash
end,
output_fields: lambda do |object_definitions, connection, config_fields|
Array
end,
sample_output: lambda do |connection, input|
Hash
end,
retry_on_response: Array,
retry_on_request: Array,
max_retries: Int,
summarize_input: Array,
summarize_output: Array
},
[Another_unique_action_name]: {
...
}
},
# title
| 属性 | 説明 |
|---|---|
| キー | title |
| 型 | String |
| 必須 | 省略可能。デフォルトではラベル付きキーをもとに作成されたタイトルになります。 |
| 説明 | このキーにより、アクションのタイトルを定義できます。タイトルは、アクションに割り当てられているキーの名前と異なっていても構いません - キーは search_object_query、タイトルは "Search object via query" のようにできます。 |
| 期待される出力 | String たとえば "Search object via query" |
| UI 参考 |  |
TIP
Workato では基本的に、「Lead created」ではなく、「Create lead」や「Search object」のような「[動詞] [目的語]」の構成が推奨されています。
# subtitle
| 属性 | 説明 |
|---|---|
| キー | subtitle |
| 型 | String |
| 必須 | 省略可能。デフォルトではコネクター名とアクションのタイトルから推測されるサブタイトルになります。 |
| 説明 | このキーにより、アクションのサブタイトルを定義できます。 |
| 期待される出力 | Stringたとえば "Use complex queries to search objects in Percolate" |
| UI 参考 |  |
TIP
サブタイトルを有意義なものにするため、タイトルは簡潔にしておき、サブタイトルでより多くの情報を提供するようにしてください。たとえば、タイトルを「Create object (オブジェクトの作成)」とし、サブタイトルを「Create objects like leads, customers, and accounts in Salesforce (Salesforce のリード、顧客、取引先といったオブジェクトを作成)」のようにするとよいでしょう。ユーザーが特定のアクションを検索する場合、Workato はサブタイトルが一致するものも探します。
# description
| 属性 | 説明 |
|---|---|
| キー | description |
| 型 | lambda 関数 |
| 必須 | 省略可能。デフォルトではコネクター名とアクションのタイトルから推測される説明になります。 |
| 説明 | このキーにより、レシピエディターで表示される際のアクションの説明を定義できます。必要に応じて、静的な説明にも動的な説明にもできます。 |
| 使用可能な引数 | input - input_fields で定義されたユーザー入力を表すハッシュ picklist_label - ユーザーの回答がピックリストのラベルと値の両方から構成されるピックリストにのみ適用されます。このハッシュは、ピックリスト項目でのユーザー入力のラベルを表します。使用例については以下を参照してください。 |
| 期待される出力 | Stringたとえば "Create a <span class='provider'>campaign</span> in <span class='provider'>Percolate</span>" HTML タグ <span> を追加すると、説明テキストを強調表示できます。 |
| UI リファレンス |  |
例 - description:
lambda 関数 description では、2つの引数を使用して、説明を動的なものにすることができます。この機能は、個々のユーザーがアクションをどのように設定したかに基づいて説明を変更したい場合に便利です。このような変更は、ユーザーにとって非常に役立ちます。アクションの設定をクリックして表示しなくても、そのアクションの現在の動作がわかるようになるためです。
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
}
]
# More keys to define the action
}
上記の例にあるのは、汎用的なオブジェクトのアクションです。つまり、このアクションはさまざまな型のオブジェクトを作成できるようになっていて、ユーザーは後でレシピを設定するときに、作成するオブジェクトの型を選ぶことができます。これは、作成したい object (オブジェクト) をユーザーが選択することで達成されます。ユーザーがどのオブジェクトを選択したかに応じて説明を変更するには、引数 picklist_label を参照して、選択済みのオブジェクトに説明を対応させます。
# help
| 属性 | 説明 |
|---|---|
| キー | help |
| 型 | lambda 関数 |
| 必須 | 省略可能。定義されていない場合、ヘルプは表示されません。 |
| 説明 | このアクションの設定方法についてユーザーをガイドするためのヘルプテキスト。参照するべきドキュメントをユーザーに示すこともできます。 |
| 使用可能な引数 | input - input_fields で定義されたユーザー入力を表すハッシュ picklist_label - ユーザーの回答がピックリストのラベルと値の両方から構成されるピックリストにのみ適用されます。このハッシュは、ピックリスト項目でのユーザー入力のラベルを表します。使用例については以下を参照してください。 |
| 期待される出力 | Hash または String。例については以下を参照してください。 |
| UI 参考 |  |
例 - help:
lambda 関数 help の出力は、単純な文字列またはハッシュのいずれかです。以下に2つの例を示します。
- 文字列
help: lambda do |input, picklist_label|
'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|
{
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,
# display_priority
| 属性 | 説明 |
|---|---|
| キー | display_priority |
| 型 | Integer |
| 必須 | 省略可能。デフォルトでは0になり、さらにはアクションのタイトルのアルファベット順が使用されます。 |
| 説明 | このキーにより、レシピエディタ内でのアクションの並び順に影響を与え、上位のアクションを目立たせることができます。この整数値が大きくなるほど、優先度が高くなります。2つのアクションの優先度が同じ場合、それらはタイトルに基づいて並べられます。 |
# batch
| 属性 | 説明 |
|---|---|
| キー | batch |
| 型 | Boolean |
| 必須 | 省略可能。 |
| 説明 | アクションの横に「Batch」というタグを表示し、このアクションが複数のレコードを扱えることを示します。通常はバッチトリガーで使用するか、ユーザーがレコードのリストを渡せるバッチでの作成/更新/アップサートアクションで使用します。 |
| UI 参考 |  |
# bulk
| 属性 | 説明 |
|---|---|
| キー | bulk |
| 型 | Boolean |
| 必須 | 省略可能。 |
| 説明 | アクションの横に「Bulk」というタグを表示し、このアクションが多くのレコードからなる大規模なフラットファイルを扱えることを示します。通常は、ユーザーが多くのレコードからなる CSV ファイルを渡す、バルクでの作成/更新/アップサートアクションで使用します。 |
| UI 参考 |  |
# deprecated
| 属性 | 説明 |
|---|---|
| キー | deprecated |
| 型 | Boolean |
| 必須 | 省略可能。 |
| 説明 | アクションの横に「Deprecated」というタグを表示し、このアクションが廃止されることを示します。このアクションを使用してきたレシピはこれからも動作し続けますが、今後のレシピではこのアクションの検索や選択を行えなくなります。 |
| UI 参考 |  |
TIP
「廃止」は、後方互換性のない変更を行った際に、ユーザーを新しいアクションに移行させるための優れた方法です。この方法により、アクションをより便利なものにしたり、今後の API の変更に対応させたりしやすくなります。
# config_fields
| 属性 | 説明 |
|---|---|
| キー | config_fields |
| 型 | Array |
| 必須 | 省略可能。 |
| 説明 | このキーは、入力項目としてユーザーに表示されるハッシュからなる配列を受け付けます。コンフィギュレーション項目は、入力項目よりも前にユーザーに表示されます。エンドユーザーに表示する入力項目のセットを変更するのに利用できます。これは多くの場合、汎用的なオブジェクトのアクションで使用されます。そのようなアクションにおいて、コンフィギュレーション項目はオブジェクトを選択するようユーザーに求め、入力項目はその選択に基づいて表示されます。Workato での、コンフィギュレーション項目の定義方法の詳細については、こちらをクリックしてください。 |
| 期待される出力 | ハッシュの配列。この配列の各ハッシュは、それぞれ個別のコンフィギュレーション項目に対応します。 |
| UI 参考 |  |
TIP
コンフィギュレーション項目は、アクションに動的な動作をもたらす強力なツールです。これを使用すると、コネクターで新しい機能を利用したり見つけたりするのが簡単になります。上の gif 動画の例では、[Event] への入力を行うと、追加の入力項目が表示されることがわかります。これらの入力項目は、「Meeting」という値の選択に基づいて表示されています。
# input_fields
| 属性 | 説明 |
|---|---|
| キー | input_fields |
| 型 | lambda 関数 |
| 必須 | はい |
| 説明 | この lambda 関数では、レシピエディターでこのアクションを設定しているユーザーに対し、どのような入力項目を表示するか定義できます。この lambda 関数の出力はハッシュの配列です。この配列に含まれるハッシュはそれぞれ、個別の入力項目に対応します。Workato 内の入力項目を定義する方法について、詳しくはこちらを参照してください。 |
| 使用可能な引数 | object_definitions - これを利用してオブジェクト定義を参照できます。オブジェクト定義は、入力項目と出力項目 (データピル) の両方を表現するために使用できる、ハッシュの配列の保管場所です。それらの定義は、どのアクションやトリガーからも参照できます。connection - connection で定義されたユーザー入力を表すハッシュ。config_fields - config_fields で定義されたユーザー入力を表すハッシュ (該当する場合)。 |
| 期待される出力 | ハッシュの配列。この配列に含まれる各ハッシュは、それぞれ個別の入力項目に対応します。 |
| UI 参考 |  |
# execute
| 属性 | 説明 |
|---|---|
| キー | execute |
| 型 | lambda 関数 |
| 必須 | 必須です。 |
| 説明 | この lambda 関数では、エンドユーザーから渡された入力に対して、このアクションがどのような処理を行うか定義できます。それらの入力は、静的な値である場合も、上流のアクションやトリガーからのデータピルである場合もあります。そのような入力は、データを取得するための HTTP リクエストの送信に使用され、取得されたデータは、データピルとして提供することができます。 この lambda 関数 execute は必要に応じて、入力データをリクエストとして送信する前に前処理を行ったり、レスポンスデータをデータピルとして渡す前に後処理を行ったりするために利用することもできます。 |
| 使用可能な引数 | connection - Connection で定義されたユーザー入力を表すハッシュ。 input - input_fields で定義されたユーザー入力を表すハッシュ extended_input_schema - 例については以下を参照してください。extended_output_schema - 例については以下を参照してください。continue - 以前の execute の呼び出しからのカーソルを表現するハッシュ。これは省略可能であり、非同期型のアクションのために使用されます。例については以下を参照してください。 |
| 期待される出力 | このアクションの出力データピルにマッピングされるデータを表すハッシュ。 |
例 - execute: - extended_input_schema および extended_output_schema
拡張入出力スキーマとは、アクションで使用される object_definitions に由来するスキーマのことを言います。この情報は、スキーマを動的に生成し、それを使ってデータの前処理や後処理を行いたい場合にしばしば役立ちます。これらの引数には config_fields は含まれません。
たとえば、extended_input_schema を使用すれば、どの入力が日時であり、ターゲット API が受け付けるエポック時間に変換する必要があるのかを知ることができます。また同様にして、extended_output_schema を使ってレスポンスを取得し、エポック変数を 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,
}
例 - execute: - continue
非同期 API を利用して、ターゲットアプリケーション内で長時間実行されるジョブやプロセスを起動する場合、リクエストを送信した上で、そのジョブやプロセスに対応する ID が返されるのを待つことがよくあります。アクションは次に、結果を取得したり、レシピ内の次のステップに進んだりする前に、API を絶えずチェックして、ジョブが完了したかどうかを確認します。
たとえば、Google BigQuery に対してクエリー開始のリクエストを送信すると、Google BigQuery はそのジョブの ID を返してくるでしょう。この場合、アクションのタスクは結果の行を取得する前に、クエリーが完了したかどうかを Google BigQuery に定期的に問い合わせることになります。
こうしたロジックをユーザーがレシピ内で設定する代わりに、カスタムコネクターの「マルチステップ」アクションを使用して、このロジック全体を単一のアクションに組み込めるようになりました。「マルチステップ」アクションを使用するには、引数 continue と、reinvoke_after という専用メソッドを組み合わせて使用します。以下に、引数 continue の使い方に関する例をいくつか示します。
「マルチステップ」アクションの詳しい作成方法については、Workato のこちらのガイドを参照してください。
multistep_action_sample: {
input_fields: lambda do |object_definitions, connection, config_fields|
end,
execute: lambda do |connection, input, e_i_s, e_o_s, continue|
if !continue.present? #continue is nil on the first invocation of the execute
puts continue
# nil
reinvoke_after(seconds: 100, continue: { current_step: 1 })
elsif continue['current_step'] == 1 #first reinvocation
puts continue
# {
# "current_step": 1
# }
reinvoke_after(seconds: 100, continue: { current_step: continue['current_step'] + 1 })
else
puts continue
# {
# "current_step": 2
# }
end
end,
output_fields: lambda do |object_definitions, connection, config_fields|
end,
}
# output_fields
| 属性 | 説明 |
|---|---|
| キー | output_fields |
| 型 | lambda 関数 |
| 必須 | 必須です。 |
| 説明 | この lambda 関数では、レシピエディターでアクションを設定しているユーザーに表示する出力項目 (データピル) を定義できます。この lambda 関数の出力はハッシュの配列です。この配列に含まれるハッシュはそれぞれ、個別の出力項目 (データピル) に対応します。Workato の入力項目の詳しい定義方法については、こちらを参照してください。 |
| 使用可能な引数 | object_definitions - これを利用すると、オブジェクト定義を参照できます。オブジェクト定義は、入力項目または出力項目を表現できる配列の保存場所です。それらの定義は、どのアクションやトリガーからも参照できます。connection - connection で定義されたユーザー入力を表すハッシュ。config_fields - config_fields で定義されたユーザー入力を表すハッシュ (該当する場合)。 |
| 期待される出力 | ハッシュの配列。この配列に含まれる各ハッシュは、それぞれ個別の入力項目に対応します。 |
| UI 参考 |  |
例 - output_fields:
出力項目は、レシピエディターでユーザーに表示されるデータピルと直接関係しています。そうした出力項目の定義は、lambda 関数 execute の出力であるハッシュに対応付けられます。
create_object: {
execute: lambda do |connection, input, extended_input_schema, extended_output_schema|
post("/object/create", input)
# JSON response passed out of the execute: lambda function.
# {
# "id": 142414,
# "title": "Newly created object",
# "description": "This was created via an API"
# }
end,
output_fields: lambda do |object_definitions, connection, config_fields|
[
{
name: "id",
type: "integer"
},
{
name: "title",
type: "string"
},
{
name: "description",
type: "string"
}
]
end,
}
# sample_output
| 属性 | 説明 |
|---|---|
| キー | sample_output |
| 型 | lambda 関数 |
| 必須 | 必須ではありません。 |
| 説明 | この lambda 関数では、出力項目 (データピル) の横に表示されるサンプル出力を定義できます。 |
| 使用可能な引数 | connection - connection で定義されたユーザー入力を表すハッシュ。input - input_fields で定義されたユーザー入力を表すハッシュ。 |
| 期待される出力 | ハッシュ。このハッシュは、lambda 関数 execute のスタブ出力である必要があります。 |
| UI 参考 |  |
# retry_on_response
| 属性 | 説明 |
|---|---|
| キー | retry_on_response |
| 型 | Array |
| 必須 | 必須ではありません。 |
| 説明 | retry_on_request: および max_retries: と組み合わせて使用します。 この宣言を使用すると、特定の HTTP メソッドやレスポンスに対する再試行メカニズムを実装できます。これにより、サーバー障害で「500 Internal Server Error」コードのようなエラーを返すことのある API への対策を取ることができます。 この配列が指定されていると、Workato は再試行の対象とするエラーコード、文字列全体、または正規表現を了承します。 エラーコードが1つも定義されていない場合、Workato は、与えられた正規表現またはプレーン文字列のみをメッセージ本文から検索します。ただし、これはエラーコードが次のデフォルトのコードリストに該当する場合に限ります: (429、500、502、503、504、507)。正規表現ではなく文字列全体を指定した場合は、レスポンス全体が完全にマッチするときにのみ再試行が実行されます。 文字列全体または正規表現がマッチし、かつエラーコードが定義されている場合、再試行がトリガーされるためには、エラーコードと文字列の両方がマッチする必要があります。 |
| 期待される出力 | Array。例: [500]、[500,/error/] または [‘“error”’, 500] |
# retry_on_request
| 属性 | 説明 |
|---|---|
| キー | retry_on_request |
| 型 | Array |
| 必須 | 必須ではありません。 |
| 説明 | retry_on_request: および max_retries: と組み合わせて使用します。 この宣言を使用すると、特定の HTTP メソッドやレスポンスに対する再試行メカニズムを実装できます。これにより、サーバー障害で「500 Internal Server Error」コードのようなエラーを返すことのある API への対策を取ることができます。 これは省略可能です。定義されていない場合、デフォルトでは HTTP リクエスト「GET」および「HEAD」のみとなります。 |
| 期待される出力 | Array。例: [“GET”] または [“GET”, “HEAD”] |
# max_retries
| 属性 | 説明 |
|---|---|
| キー | max_retries |
| 型 | Int |
| 必須 | 必須ではありません。 |
| 説明 | retry_on_request: および max_retries: と組み合わせて使用します。 この宣言を使用すると、特定の HTTP メソッドやレスポンスに対する再試行メカニズムを実装できます。これにより、サーバー障害で「500 Internal Server Error」コードのようなエラーを返すことのある API への対策を取ることができます。 これは再試行の回数です。許容される最大値は3です。3を超えている場合、アクションは再試行を3回実行します。 Workato は最初の再試行のために5秒間待機し、その後の再試行ごとに間隔を5秒ずつ増やします。 |
| 期待される出力 | Int。例: 1 または 2 |
TIP
- 可能であれば、アクションごとに1つの HTTP メソッドだけを使用することをお勧めします。
- 1つのアクションで複数の GET リクエストを実行することも可能です。
- 再試行はアクションレベルで行うため、アクションで定義する POST リクエストは、最大でも1つのみにすることが推奨されます。そうすることで、最初の POST リクエストが成功して次の POST リクエストが失敗してしまうケースを防げます。
例 - 再試行メカニズムの実装
アクション (およびレシピ) をターゲットアプリの不安定性に対応させる上で、API リクエストの再試行は非常に有用です。再試行を実装するには、retry_on_response:、retry_on_request:、max_retries: キーを組み合わせて使用する必要があります。
actions: {
custom_http: {
input_fields: lambda do |object_definitions|
[{ name: 'url', optional: false }]
end,
execute: lambda do |_connection, input|
{
results: get(input['url'])
}
end,
output_fields: lambda do |object_definitions|
[]
end,
retry_on_response: [500, /error/] # contains error codes and error message match rules
retry_on_request: ["GET", "HEAD"],
max_retries: 3
}
}
# summarize_input
| 属性 | 説明 |
|---|---|
| キー | summarize_input |
| 型 | Array |
| 必須 | 必須ではありません。 |
| 説明 | これを使用すると、長いリストを含んでいる入力を要約できます。入力を要約することは、ジョブページを軽量に保ち、すばやく読み込めるようにするために重要です。一般に、入力に100行を超えるリストがある場合、それらを要約する必要があります。 |
| 期待される出力 | Array。例: ['leads'] または ['report.records', 'report.description'] |
# summarize_output
| 属性 | 説明 |
|---|---|
| キー | summarize_output |
| 型 | Array |
| 必須 | 必須ではありません。 |
| 説明 | これを使用すると、長いリストを含んでいるアクションの出力を要約できます。出力を要約することは、ジョブページを軽量に保ち、すばやく読み込めるようにするために重要です。一般に、出力に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: 2023/8/31 1:07:14