SDKリファレンス-actions

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

このセクションでは、アクションを定義するために使用できるすべてのキーを列挙します。

クイック概要

actionsキーは、正常なコネクションを作成した後、レシピとSDKのテストコードタブの両方でのみ使用できます。 アクションは、レシピ内の以前のステップからデータピル経由でデータを受け取り、エンドポイントにリクエストを送信し、レスポンスをデータピルとして提示します。

構造

ruby
    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
タイプ文字列
必須任意です。 ラベル付きキーから作成されたタイトルがデフォルトです。
説明これにより、アクションのタイトルを定義できます。このタイトルは、割り当てられたキーの名前と異なる場合があります。キー=search_object_query、タイトル="Search object via query"
想定される出力String
例:"Search object via query"
UIリファレンス

TIP

Workatoでは通常、"Lead created"ではなく、"[Verb] [Object]"-"Create lead"または"Search object"という構造を推奨しています。


subtitle

属性説明
キーsubtitle
タイプ文字列
必須任意です。 デフォルトでは、コネクター名とアクションタイトルから推測されるサブタイトルになります。
説明これにより、アクションのサブタイトルを定義できます。
想定される出力String
例: "Use complex queries to search objects in Percolate"
UIリファレンス

TIP

サブタイトルをわかりやすくするには、タイトルを簡潔に保ちながら、ここにより多くの情報を記載してください。 たとえば、タイトルを"Create object"、サブタイトルを"Create objects like leads, customers, and accounts in Salesforce."にできます。 ユーザーが特定のアクションを検索すると、Workatoはサブタイトル内の一致も検索します。


description

属性説明
キーdescription
タイプラムダ関数
必須任意です。 デフォルトでは、コネクター名とアクションタイトルから推測される説明になります。
説明これにより、レシピエディターで表示されるアクションの説明を定義できます。 これは、必要に応じて静的な説明または動的な説明にできます。
指定可能な引数input-input_fieldsで定義されたユーザー指定の入力を表すHash
picklist_label-ユーザーの回答がピックリストラベルと値の両方で構成されるピックリストにのみ適用されます。 このHashは、ピックリストフィールドに対するユーザー指定の入力のラベルを表します。 ユースケースについては以下を参照してください。
想定される出力String
例:"Create a <span class='provider'>campaign</span> in <span class='provider'>Percolate</span>" 説明テキストに重みを付けるには、<span>HTMLタグを追加します。
UIリファレンス
例-description:

descriptionラムダ関数では、説明を動的にするために2つの引数にアクセスできます。 これは、特定のユーザーによるアクションの設定方法に基づいて説明を変更したい場合に便利です。 これらの変更は、ユーザーがアクションの設定をクリックして表示しなくても、そのアクションの処理内容を把握できるようにするうえで非常に役立ちます。

ruby
    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
    }

前述の例では、アクションは汎用オブジェクトアクションであり、ユーザーはレシピを設定する際に複数のオブジェクトタイプから選択できます。 picklist_label引数を参照することで、ユーザーが選択したオブジェクトの説明を変更できます。


help

属性説明
キーhelp
タイプラムダ関数
必須任意です。 それ以外の場合、ヘルプは表示されません。
説明このアクションの設定方法についてユーザーを案内するためのヘルプテキスト。 ドキュメントを参照するように案内することもできます。
指定可能な引数input-input_fieldsで定義されたユーザー指定の入力を表すHash
picklist_label-ユーザーの回答がピックリストラベルと値の両方で構成されるピックリストにのみ適用されます。 このHashは、ピックリストフィールドに対するユーザー指定の入力のラベルを表します。 ユースケースについては以下を参照してください。
想定される出力HashまたはString 例については以下を参照してください。
UIリファレンス
例-help:

help lambda関数の出力は、単純なStringまたはHashのいずれかにできます。 以下では2つの例を説明します:

  • 文字列
ruby
    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,
  • ハッシュ
ruby
    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
タイプ整数
必須任意です。 デフォルトはゼロです。それ以外の場合は、アクションタイトルのアルファベット順になります。
説明これにより、レシピエディター内のアクションの並び順に影響を与え、上位のアクションを強調できます。 整数が大きいほど、優先度が高くなります。 2つのアクションの優先度が同じ場合、タイトル順に並べられます。

batch

属性説明
キーbatch
タイプブール値
必須任意です。
説明これにより、アクションの横に"Batch"タグが表示され、このアクションが複数のレコードで動作することを示します。 通常、ユーザーがレコードのリストを渡せるバッチトリガーまたはバッチ作成/更新/upsertアクションで使用されます。
UIリファレンス

bulk

属性説明
キーbulk
タイプブール値
必須任意です。
説明これにより、アクションの横に"Bulk"タグが表示され、このアクションがレコードの大きなフラットファイルで動作することを示します。 通常、ユーザーがレコードのCSVを渡す一括作成/更新/upsertアクションで使用されます。
UIリファレンス

deprecated

属性説明
キーdeprecated
タイプブール値
必須任意です。
説明これにより、アクションの横に"deprecated"タグが表示され、このアクションが非推奨になったことを示します。 以前にこのアクションを使用していたレシピは引き続き動作しますが、今後のレシピではこのアクションを検索および選択できません。
UIリファレンス

TIP

非推奨化は、変更に後方互換性がない場合にユーザーを新しいアクションへ移行させる優れた方法です。 これにより、アクションをより使いやすくしたり、今後のAPI変更に対応したりする自由度が高まります。


config_fields

属性説明
キーconfig_fields
タイプ配列
必須任意です。
説明このキーは、ユーザーに表示される入力フィールドとして表示されるHashの配列を受け入れます。 設定フィールドは入力フィールドがレンダリングされる前にユーザーに表示され、エンドユーザーに表示する入力フィールドのセットを変更するために使用できます。 これは、設定フィールドでユーザーにオブジェクトを選択させ、その選択に基づいて入力フィールドをレンダリングする汎用オブジェクトアクションでよく使用されます。 設定フィールドの定義の詳細については、Workato Schemaを参照してください。
想定される出力Hashの配列。 この配列内の各Hashは、個別の設定フィールドに対応します。
UIリファレンス

TIP

設定フィールドは、アクションに動的な動作を導入するための強力なツールです。 これらを使用してコネクタをより使いやすくし、新しい機能を見つけやすくします。 上記のサンプルGIFでは、入力"Event"によって実際にさらに多くの入力フィールドがレンダリングされることがわかります。 これらの入力フィールドは、値"Meeting"の選択に基づいてレンダリングされます。


input_fields

属性説明
キーinput_fields
タイプラムダ関数
必須True
説明このラムダ関数を使用すると、レシピエディターでこのアクションを設定するユーザーに表示する入力フィールドを定義できます。 このlambda関数の出力はHashの配列である必要があり、この配列内の各Hashは個別の入力フィールドに対応します。 入力フィールドの定義の詳細については、Workato Schemaを参照してください。
指定可能な引数object_definitions-オブジェクト定義を参照できます。 オブジェクト定義は、入力フィールドまたは出力フィールド(データピル)の両方を表すために使用できるこれらのHash配列の格納場所です。 これらは任意のアクションまたはトリガーから参照できます。
connection-connectionで定義されたユーザー指定の入力を表すHash。
config_fields-該当する場合、config_fieldsで定義されたユーザー指定の入力を表すHash。
想定される出力Hashの配列。 この配列内の各ハッシュは、個別の入力フィールドに対応します。
UIリファレンス

execute

属性説明
キーexecute
タイプラムダ関数
必須True
説明このラムダ関数を使用すると、エンドユーザーから渡された入力に対して、このアクションが何を行うかを定義できます。 これらの入力は、静的な値、またはアップストリームのアクションやトリガーからのデータピルである場合があります。 その後、これらを使用してHTTPリクエストを送信し、データピルとして提示できるデータを取得します。

必要に応じて、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で受け入れられるEpoch時間に変換する必要があるかを把握できます。 同様に、extended_output_schemaを使用して応答を取得し、Epoch変数を再びISO8601日時に変換できます。

ruby
    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に定期的に確認してクエリが完了したかどうかを確認することです。

ユーザーにこのロジックをレシピで設定させるのではなく、カスタムコネクターで"multi-step"アクションを使用して、このロジック全体を単一のアクションに埋め込むことができます。 "multi-step"アクションを使用するには、continue引数をreinvoke_afterという専用メソッドと組み合わせて使用します。 以下では、continue引数がどのようなものになり得るかについて、いくつかの例を説明します。

詳細については、マルチステップアクションガイドを参照してください。

ruby
    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,
    }

before_suspend

属性説明
キーbefore_suspend
タイプラムダ関数
必須False
説明このラムダ関数は、Wait for resume actions専用です。 これは、executeラムダでsuspendメソッドが呼び出された後に呼び出されます。 これにより、applyに基づいて外部システムへの認証済みAPIリクエストを定義し、ジョブを再開するためのコールバックを登録できます。
指定可能な引数
  • resume_token: このトークンは特定のジョブに固有で、Workatoフレームワークによって生成されます。 外部システムがジョブを再開しようとする場合、Resume job APIへの再開リクエストにこのトークンを含める必要があります。
  • expires_at: ジョブが期限切れとなり、タイムアウトで再開される時刻を表すPSTのタイムスタンプ。
  • continue: suspendメソッドから渡されたcontinueハッシュ。 これには、外部システム内のプロセスのIDなどの重要な情報を含めることができます。
想定される出力該当なし

before_resume

属性説明
キーbefore_resume
タイプラムダ関数
必須False
説明このラムダ関数は、Wait for resume actions専用です。 これは、外部システムがジョブを再開するためのAPIリクエストを送信した後に呼び出されます。 これにより、ジョブが再開されるときにexecuteラムダへ送り返されるcontinueハッシュの状態を制御できます。 さらに、APIリクエスト内のデータ値へのアクセスを付与します。
指定可能な引数
  • data: これは、ジョブを再開するAPIリクエスト内のdata値を表します。
  • input: レシピがアクションに直接送信する入力。
  • continue: suspendメソッドから渡されたcontinueハッシュ。 これには、外部システム内のプロセスのIDなどの重要な情報を含めることができます。
想定される出力N/A
ただし、このラムダを使用すると、continueハッシュの値を編集できます。
例-continueハッシュの値を編集する

この例では、continueハッシュの値を編集する方法を示します。

suspendメソッドから渡されたcontinueメソッドが次の場合:

ruby
{
  "state": "suspended",
  "job_id": "abc_123"
}

そして、before_resumeラムダが次の場合:

ruby
before_resume: lambda do |data, input, continue|
  if continue["state"] == "suspended"
    continue["state"] = "resumed"
    continue["payload"] = "important data"
  else
    { "result" => "Unexpected state" }
  end
end,

すると、executeラムダに渡されるcontinue引数は次のようになります:

ruby
{
  "state": "resumed",
  "job_id": "abc_123",
  "payload": "important data"
}

before_timeout_resume

属性説明
キーbefore_timeout_resume
タイプラムダ関数
必須False
説明このラムダ関数は、Wait for resume actions専用です。 これは、expires_at時刻が過ぎ、Workatoがジョブを再開するためのAPIリクエストを受信していない場合に呼び出されます。 これにより、ジョブが再開されるときにexecuteラムダへ渡し戻されるcontinueハッシュの状態を管理できます。
指定可能な引数
  • input: レシピがアクションに直接送信する入力。
  • continue: suspendメソッドから渡されたcontinueハッシュ。 これには、外部システム内のプロセスのIDなどの重要な情報を含めることができます。
想定される出力N/A
ただし、このラムダを使用すると、continue hashの値を編集できます。 詳細については、before_resumeの例を参照してください。

output_fields

属性説明
キーoutput_fields
タイプラムダ関数
必須True
説明このラムダ関数を使用すると、レシピエディターでこのアクションを設定するユーザーに表示する出力フィールド(データピル)を定義できます。 このlambda関数の出力はHashの配列である必要があり、この配列内の各Hashは個別の出力フィールド(データピル)に対応します。 出力フィールドの定義の詳細については、Workato Schemaを参照してください。
指定可能な引数object_definitions-オブジェクト定義を参照できます。 オブジェクト定義は、入力フィールドまたは出力フィールドのいずれかを表すことができるこれらの配列の格納場所です。 これらは任意のアクションまたはトリガーから参照できます。
connection-connectionで定義されたユーザー指定の入力を表すHash。
config_fields-該当する場合、config_fieldsで定義されたユーザー指定の入力を表すHash。
想定される出力Hashの配列。 この配列内の各ハッシュは、個別の入力フィールドに対応します。
UIリファレンス
例-output_fields:

出力フィールドは、ユーザーがレシピエディターで確認するデータピルに直接関連しています。 これらの出力フィールドの定義は、ハッシュであるexecuteラムダ関数の出力にマッピングされます。

ruby
    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
タイプラムダ関数
必須False.
説明このlambda関数を使用すると、出力フィールド(データピル)の横に表示されるサンプル出力を定義できます。
指定可能な引数connection-connectionで定義されたユーザー指定の入力を表すHash。
input-input_fieldsで定義されたユーザー指定の入力を表すHash
想定される出力Hash。 このHashは、execute lambda関数のスタブ化された出力である必要があります。
UIリファレンス

retry_on_response

属性説明
キーretry_on_response
タイプ配列
必須False.
説明retry_on_request:およびmax_retries:と組み合わせて使用:

特定のHTTPメソッドおよびレスポンスに対する再試行メカニズムを実装するには、この宣言を使用します。 これにより、500 Internal Server Errorコードなど、サーバー障害が原因でエラーを返すことがあるAPIに備えることができます。

この配列を指定すると、再試行の対象となるエラーコードに加えて、完全な文字列または正規表現を受け付けます。

エラーコードが定義されていない場合、Workatoは、エラーコードがデフォルトのコードリスト(429、500、502、503、504、507)に該当する場合にのみ、指定された正規表現またはプレーン文字列をメッセージ本文で検索します。 正規表現の代わりに完全な文字列を指定した場合、レスポンス全体が完全に一致する場合にのみ再試行されます。

完全な文字列または正規表現が一致し、エラーコードが定義されている場合、再試行がトリガーされるには、エラーコードと文字列の両方が一致している必要があります
想定される出力Array。 例:[500]または[500,/error/]または[‘“error”’, 500]

retry_on_request

属性説明
キーretry_on_request
タイプ配列
必須False.
説明retry_on_request:およびmax_retries:と組み合わせて使用:

特定のHTTPメソッドおよびレスポンスに対する再試行メカニズムを実装するには、この宣言を使用します。 これにより、500 Internal Server Errorコードなど、サーバー障害が原因でエラーを返すことがあるAPIに備えることができます。

任意。 定義されていない場合、デフォルトでは“GET”および“HEAD”HTTPリクエストのみになります。
想定される出力Array。 例:[“GET”]または[“GET”, “HEAD”]

max_retries

属性説明
キーmax_retries
タイプInt
必須False.
説明retry_on_request:およびmax_retries:と組み合わせて使用:

特定のHTTPメソッドおよびレスポンスに対する再試行メカニズムを実装するには、この宣言を使用します。 これにより、500 Internal Server Errorコードなど、サーバー障害が原因でエラーを返すことがあるAPIに備えることができます。

再試行の回数。 最大3回まで許可されます。 3回を超える場合、アクションは3回再試行します。

Workatoは最初の再試行まで5秒待機し、その後の再試行ごとに間隔を5秒ずつ増やします。
想定される出力Int。 例:1または2

TIP

  • 可能であれば、アクションごとにHTTPメソッドを1つだけ使用することをお勧めします
  • 1つのアクション内で複数のGETリクエストを使用することもできます
  • アクションレベルで再試行するため、アクションは最大でもPOSTリクエストを1つだけ含むように定義する必要があります。 これにより、最初のpostリクエストが成功し、2番目のpostリクエストが失敗するケースに備えることができます。
例-再試行メカニズムの実装

APIリクエストの再試行は、アクション(およびレシピ)がターゲットアプリの不整合に耐えられるようにするうえで非常に役立ちます。 これを実装するには、retry_on_response:、retry_on_request:、max_retries:キーを組み合わせて使用する必要があります。

ruby
    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
タイプ配列
必須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キーを使用して、ジョブの入力タブと出力タブのデータを要約し、コネクタのユーザーにとって読みやすくできます。

ruby
    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: