Product UpdatesStatus PageAutomation Institute
日本語
コネクターの SDK
SDK リファレンス
コネクターで使用する キー

# SDK リファレンス - connection

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

簡単な概要

端的に言えば、connection ハッシュには、コネクターが正常に接続を確立するのに必要となる指示すべてが格納されています。

  • fields キーは、認証用の情報を収集するためにどの入力項目を表示すべきかをコネクターに指示します。
  • extended_fields を使用すると、前の入力に基づいてコネクション項目を動的に表示できます。この項目を定義するかどうかは任意です。
  • authorization キーは、コネクターが収集した情報をどのように扱うかを指示します。このキーを使用して、収集した情報と access_token を交換してください。
  • base_uri キーは、接続成功後の HTTP リクエストすべての先頭に付加する URI をコネクターに指示します。これにより、アクションやトリガーの定義時にコネクターのコード内で相対パスを使用できます。

# 構造

  connection: {
    fields: Array,

    extended_fields: lambda do |connection|
      Array
    end,

    authorization: Hash,

    base_uri: lambda do |connection|
      String
    end
  }

# fields

'fields' キーは以下のような属性を持っています。

キー
fields
型
Array
必須
必須ではありません。
説明
ハッシュからなる配列を受け入れます。この配列の各ハッシュは、それぞれ個別の入力項目に対応しています。
Workato の入力項目の定義方法について、詳しくは SDK リファレンス - スキーマを参照してください。

# コネクション項目におけるピックリスト

control_type が select または multiselect として定義されている項目については、pick_list 属性ではなく options 属性を使用して静的なピックリストを定義してください。

ピックリストはコネクションハッシュに適用されない

connection ハッシュ内では、コネクター内で定義されているピックリストへの参照は利用できません。なぜなら、この時点では資格情報が渡されていないためです。

# 例: 「高度な設定」内でピックリストが入れ子になっているコネクション項目

    fields: [
      {
        name: 'api_key',
        control_type: 'password',
        hint: 'You can find your API key final change3' \
          "under 'Settings'=>'Configure Chargebee'=>'API Keys and Webhooks'" \
          " in Chargebee's web console.",
        label: 'Your API Key',
        default: "helloaaaabbb",
        optional: false
      },
      {
        name: 'domain',
        control_type: 'subdomain',
        url: 'chargebee.com'
      },
      {
        name: "advanced_settings",
        type: "object",
        optional: "true",
        properties: [
          {
            name: "environment",
            optional: true,
            control_type: "select",
            options: [
              ["Development", "dev"],
              ["Production", "prod"]
            ]
          }
        ]
      }
    ],

# extended_fields

'extended_fields' キーは以下のような属性を持っています。

キー
extended_fields
型
lambda 関数
必須
必須ではありません。
説明
これを利用すると、コネクションに対応したさらなる入力項目を必要に応じて表示できます。出力は、有効な Workato スキーマであることが期待されています。スキーマについて詳しくは、SDK リファレンス - スキーマを参照してください。

# extended_fields の使用方法

extended_fields を使用すると、前の項目に基づいて追加的な項目を動的に表示できます。コネクションの設定が複雑で、多くの入力項目から構成されている場合は、ユーザーが見ることのできる入力項目の数を絞るとよいでしょう。すべての項目を一度に表示するのではなく、extended_fields を使用して、ユーザーに最初に表示する項目の数と、追加の項目を表示するタイミングを制御しましょう。

このような場合において、extended_fields にはコネクション設定時にユーザーに表示する項目を制御し、設定作業の際にガイドの役割を果たせるという、さらなるメリットがあります。また、ケースによっては、関連性の低い項目の表示を制限するために利用することもできます。

# 例: extended_fields を利用したコネクション項目

    fields: [
      {
        name: "api_key",
        control_type: "password",
        hint: "You can find your API key " \
          "under 'Settings'=>'Configure Chargebee'=>'API Keys and Webhooks'" \
          " in Chargebee's web console.",
        label: "Your API Key"
      },
      {
        name: "custom_domain",
        label: "Are you using a custom domain?",
        extends_schema: true,
        control_type: "checkbox"
      }
    ],
    
    extended_fields: lambda do |connection|
      if connection['custom_domain'] == "true"
        [
          {
            name: "domain",
            control_type: "subdomain",
            extends_schema: true,
            url: ".acme.com"
          }
        ]
      end
    end,

Workato は connection ハッシュ を、この他の lambda 関数すべて (authorization や execute を含む) に渡します。connection ハッシュには、fields と extended_fields の両方からの値が格納されます。

# 例: extended_fields と extends_schema を利用したコネクション項目

以下の例では、extended_fields 内で extends_schema を使用し、複数のステップからなるコネクション設定を作成する方法を示しています。

  connection: {
    fields: [
      {
        name: "api_key",
        control_type: "password",
        hint: "You can find your API key " \
          "under 'Settings'=>'Configure Chargebee'=>'API Keys and Webhooks'" \
          " in Chargebee's web console.",
        label: "Your API Key"
      },
      {
        name: "custom_domain",
        label: "Are you using a custom domain?",
        extends_schema: true,
        control_type: "checkbox"
      }
    ],
    
    extended_fields: lambda do |connection|
        [
          (
            if connection['custom_domain'] == "true"
              {
                name: "domain",
                control_type: "subdomain",
                optional: false,
                url: ".acme.com"
              }
            end 
          ),
          (
            if connection['custom_domain'] == "true"
              {
                name: "instance_type",
                control_type: "select",
                extends_schema: true,
                optional: false,
                options: [ ["Production", "production"], ["Sandbox", "sandbox"]]
              }
            end 
          ),
          (
            if connection['instance_type'] == "sandbox"
              {
                name: "protocol",
                control_type: "select",
                optional: false,
                options: [ ["HTTPS", "https://"], ["HTTP", "http://"]]
              }
            end
          )
        ].compact
    end,

    authorization: {
      type: 'basic',

      apply: lambda { |connection, access_token|
        headers("x-api-key": "#{connection['api_key']}")
      }
    },

    base_uri: lambda do |connection|
        if connection['custom_domain'] == "true"
          "#{connection['protocol']}#{connection['domain']}.acme.com/"
        else
          "https://api.acme.com/"
        end
    end
  },

# authorization

'authorization' キーは以下のような属性を持っています。

キー
authorization
型
Hash
必須
必須です。
説明
さまざまな種類の認証に対応する子キーを持つオブジェクトを受け入れます。

authorization のハッシュの詳細については、SDK リファレンス - authorization を参照してください。

# base_uri

'base_uri' キーは以下のような属性を持っています。

キー
base_uri
型
lambda 関数
必須
必須ではありません。ただし、使用が推奨されます。
説明
将来の HTTP リクエストすべてのベース URI を定義します。
使用可能な引数
connection
Connection で定義されているユーザーからの入力を表すハッシュ。
期待される出力
以下のいずれかのような String (文字列)。
  • "https://#{connection['host']}.com/"
  • "https://api.acme.com"

# base_uri の設定

base_uri キーを定義する際には、最終的に適用される URI に注意してください。base_uri を下流の HTTP リクエストとともに使用する場合、次の2通りの使われ方があります。

  1. HTTP 動詞のメソッドにおいて、get('/hello/there') のように、引数の先頭に "/" (スラッシュ) が付いている場合、base_uri 内のパスパラメータはすべて無視されます。

    たとえば、base_uri として定義されている https://api.hubapi.com/test/ は、実質的に https://api.hubapi.com となります。リクエストは https://api.hubapi.com/hello/there に送信されます。

  2. HTTP 動詞のメソッドにおいて、get('hello/there') のように、引数の先頭に "/" (スラッシュ) が付いていない場合、base_uri 内のパスパラメータはすべて採用されます。

    たとえば、base_uri として定義されている https://api.hubapi.com/test/ は、https://api.hubapi.com/test/ のままとなります。リクエストは https://api.hubapi.com/test/hello/there に送信されます。

← SDK リファレンス
認証 →


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

On this page