How to ガイド - カスタムアクションの有効化

ここでは、カスタムアクションを効果的に有効化する方法について説明します。カスタムアクションは、コネクターのユーザーのために何にでも使えるアクションを実装できる優れた手段です。カスタムアクションから送信されるすべてのリクエストは、トークンのような認証用の詳細情報と、トークン更新のための認証ロジックを継承します。

コネクターのサンプルコード

{
  title: 'Acme',
  connection: {
    fields: [
      {
        name: 'client_id',
        control_type: 'text',
        label: 'OAuth App Client ID',
        optional: 'false'
      },
      {
        name: 'client_secret',
        control_type: 'password',
        label: 'OAuth App Client secret',
        optional: 'false'
      },
      {
        name: 'advanced_settings',
        type: 'object',
        properties: [
          {
            name: 'oauth_scopes',
            control_type: 'multiselect',
            delimiter: ' ',
            hint: 'By default, only scopes for Reading and writing contacts are requested',
            options: [
              [ 'Read contacts', 'contacts.read' ],
              [ 'Write contacts', 'contacts.write' ],
              [ 'Read Invoices', 'invoices.read' ],
              [ 'Write Invoices', 'invoices.read' ],
            ]
          }
        ]
      }
    ],

    authorization: {
      type: 'oauth2',
      
      client_id: lambda do |connection|
        connection['client_id']
      end,

      client_secret: lambda do |connection|
        connection['client_secret']
      end,

      authorization_url: lambda do |connection|
        scopes = connection.dig('advanced_settings', 'oauth_scopes') || ['contacts.read', 'contacts.write'].join(" ")
        "https://api.acme.com/oauth/authorize?scopes=#{scopes}"
      end,

      token_url: lambda do |connection|
        "https://api.acme.com/oauth/token"
      end,

      apply: lambda { |connection, access_token|
        headers(Authorization: "Bearer #{access_token}")
      }
    },

    base_uri: lambda do |connection|
        "https://api.acme.com/"
    end
  },

  custom_action: true,

  custom_action_help: {
    learn_more_url: 'https://www.acme.com/api/reference',

    learn_more_text: 'Acme API documentation',

    body: 'Build your own Acme action with a HTTP request. The request will be authorized with your current connection.'
  }
}

ステップ1 - コネクションの設定

コネクションのスコープと権限は認可資格情報によって決定されるため、カスタムアクションの用途について検討しておくことが重要です。エンドポイントによっては、必要なスコープや権限が異なることがあります。これには、デフォルトのアクションに必要のないスコープや権限が含まれる場合があります。

上記のサンプルは OAuth2 向けの簡単な例であり、後から必要に応じて、OAuth のスコープを追加することができます。

ステップ2 - カスタムアクションの定義

  custom_action: true,

  custom_action_help: {
    learn_more_url: 'https://www.acme.com/api/reference',

    learn_more_text: 'Acme API documentation',

    body: 'Build your own Acme action with a HTTP request. The request will be authorized with your current connection.'
  }

このコンポーネントは、コネクターでカスタムアクションを有効にしたいことを Workato に伝えます。また、ユーザー向けの補足的なガイダンスを追加できます。特に、ユーザーがカスタムアクションを設定する際にリファレンスを見つけやすくするため、API ドキュメントへの適切なヘルプリンクを追加することが推奨されます。