How to ガイド - CLI におけるアクションの実行

ここでは、Workato Gem を使用してアクションを実行する方法について説明します。

前提条件

• Workato SDK Gem をインストールして、実行可能であること。詳細については、「入門ガイド」を参照してください。
• 少なくとも1つのアクションを備えた、動作するコネクターがあること。以下のサンプルコネクターを使用します。
• 有効な資格情報セットを所有していること。サンプルコネクターのコードを使用する場合、コネクター用に適切な資格情報を所有していることを確認してください。

サンプルコネクター - Chargebee

connector.rb のコードを以下に示します。

{
  title: 'Chargebee-demo',

  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'
      },
      {
        name: 'domain',
        control_type: 'subdomain',
        url: 'chargebee.com'
      }
    ],

    authorization: {
      type: 'basic_auth',  

      apply: lambda do |connection|
        user(connection['api_key'])
      end
    },

    base_uri: lambda do |connection|
      "https://#{connection['domain']}.chargebee.com"
    end
  },

  test: lambda do |_connection|
    get('/api/v2/plans', limit: 1)
  end,

  actions: {

    search_customers: {
      title: 'Search customers',
      subtitle: 'Search for customers using name',
      description: 'Search customer in Chargebee',

      input_fields: lambda do |_object_definitions|
        [
          {
            name: 'name',
            label: 'Name to query by',
            hint: 'Provide the name of the customer to query'
          },
          {
            name: 'id',
            label: 'Name to query by',
            hint: 'Provide the name of the customer to query'
          }
        ]
      end,

      execute: lambda do |_connection, input, _input_schema, _output_schema|
        get('/api/v2/customers', input)
      end,

      output_fields: lambda do |_object_definitions|
        [
          {
            name: 'first_name'
          },
          {
            name: 'last_name'
          },
          {
            name: 'id'
          }
        ]
      end
    }

  },
  
}

settings.yaml.enc に格納された資格情報です。

api_key: valid_api_key
domain: valid_domain

TIP

暗号化された settings.yaml ファイルを使う場合は、workato edit <PATH> を使用して、このファイルを編集または作成する必要があります。詳細については、こちらを参照してください　:::

SDK Gem を使用すると、アクションの lambda 関数を個別に呼び出し、アクション各部の動作をより詳細に制御できるようになります。たとえば、input_fields lambda とは独立して execute lambda 関数を実行することができます。

input_fields lambda と output_fields lambda の実行

このガイドでは、input_fields lambda を取り扱いますが、output_fields lambda も同じように実行することができます。

TIP

サンプルのペイロードのリクエストやレスポンスが入手できる場合もあります。CLI コマンド workato generate schema を使用して、このペイロードを簡単に Workato スキーマに変換することもできます。Workato CLI のスキーマ生成の詳細については、こちらを参照してください。

input_fields lambda は、ユーザーに表示すべき入力項目に対応する Workato のスキーマを返すことが予期されます。上記の場合は単に、格納されている Workato スキーマを返します。

$ workato exec actions.search_customers.input_fields 

[  
  {
    "name": "name",
    "label": "Name to query by",
    "hint": "Provide the name of the customer to query"
  },
  {
    "name": 'limit',
    "hint": 'Total number of records to return'
  }
]

ただし、必要な場合に追加の引数を指定することもできます。たとえば、input_fields が config_fields に依存している場合、これを機能させるには config_fields を渡す必要があります。これは、以下のようなものを使用して行うことができます。ここで、customer_config.json は、lambda の config_fields 引数を表します。

$ workato exec actons.search_customers.input_fields --config-fields='fixtures/actions/search_customers/customer_config.json'

TIP

ここでは他のオプションも使うことができます。たとえば、--verbose を指定すると input_fields の構築時に送信された HTTP リクエストの詳細なログが表示され、--output を指定すると関数の出力が JSON ファイルに保存されます。

object_definitions 引数には何も渡す必要はありません。これは、Gem がコネクターを検査する際にその情報を参照できるからです。

execute lambda の実行

execute lambda は、アクションの出力を表すハッシュを返すことが予期されています。上記の場合、これは Chargebee により送られてくるレスポンスを返します。fixtures フォルダーに格納される JSON ファイルを指すコマンドで input を参照していることがわかります。このファイルには、input_fields から execute lambda に渡される実際の値が格納されているはずです。

この場合、ファイル fixtures/actions/search_customers/input.json の内容は以下のとおりです。

{
  "name": "bennett",
  "limit": 1
}

CLI コマンドを実行して execute lambda を実行する場合 :

$ workato exec actions.search_customers.execute --input='fixtures/actions/search_customers/input.json' --verbose

SETTINGS
{
  "api_key": "valid_api_key",
  "domain": "valid_domain"
}
INPUT
{
  "name": "bennett",
  "limit": 1
}

RestClient.get "https://test.chargebee.com/api/v2/customers?limit=1&name=bennett", "Accept"=>"application/json", "Accept-Encoding"=>"gzip, deflate", "User-Agent"=>"rest-client/2.0.2 (darwin19.6.0 x86_64) ruby/2.4.10p364"
# => 200 OK | application/json 753 bytes                                                                                
Progress: |--=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=-|

OUTPUT
{
  "list": [
    {
      "customer": {
        "id": "abc",
        "first_name": "John",
        "last_name": "doe",
        "email": "[email protected]",
        "phone": "+100",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1630848839,
        "taxability": "taxable",
        "updated_at": 1630848840,
        "locale": "en-US",
        "pii_cleared": "active",
        "resource_version": 1630848840782,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "unbilled_charges": 0,
        "preferred_currency_code": "SGD",
      }
    }
  ],
  "next_offset": "[\"1630848839000\",\"42903379\"]"
}

--verbose を使用して、SDK Gem が、API リクエストやレスポンスなど、より多くの情報を出力するようにしている点に注意してください。

connection の入力は settings.yaml.enc ファイルと見なされ、別の settings.yaml ファイルを使用しない限りは宣言する必要はありません。

TIP

--output などのオプションを使用して、関数の出力を JSON ファイルに保存することもできます。

アクション全体の実行

execute lambda の実行により input 引数をスタブにすることもできますが、入力項目に渡された入力が、アクションを通してどのように実行されるのかを確認したい場合もよくあります。たとえば、データ型の変換を行う convert_input や convert_output などのスキーマ属性を使用する場合です。

たとえば、limit が文字列として指定される上記の例の入力がユーザーから提供される場合、この値を整数に変換する必要があります。

#fixtures/actions/search_customers/input.json
{
  "name": "bennett",
  "limit": "1"
}

これは、この値を取得して変換を実行する convert_input などのスキーマ属性を使用して行うことができます。

[  
  {
    "name": "name",
    "label": "Name to query by",
    "hint": "Provide the name of the customer to query"
  },
  {
    "name": 'limit',
    "convert_input": "integer_conversion",
    "hint": "Total number of records to return"
  }
]

変換の後、execute lambda への input 引数は次のようになります。

{
  "name": "bennett",
  "limit": 1
}

TIP

ユーザーが入力項目に静的な値やテキスト値を指定する場合、これらは文字列として execute に渡されると見なす必要があります。convert_input や convert_output などの属性を使用すると、これが execute lambda への input 引数として表される前に、データを変換することができます。

入力の変換と出力の変換の詳細については、こちらを参照してください。

スキーマから生じたこの変換をテストするには、以下のように CLI コマンドを実行してアクション全体を実行する必要があります。

$ workato exec actions.search_customers --input='fixtures/actions/search_customers/input.json' --verbose

SETTINGS
{
  "api_key": "valid_api_key",
  "domain": "valid_domain"
}
INPUT
{
  "name": "bennett",
  "limit": "1"
}

RestClient.get "https://test.chargebee.com/api/v2/customers?limit=1&name=bennett", "Accept"=>"application/json", "Accept-Encoding"=>"gzip, deflate", "User-Agent"=>"rest-client/2.0.2 (darwin19.6.0 x86_64) ruby/2.4.10p364"
# => 200 OK | application/json 753 bytes                                                                                
Progress: |--=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=---=-|

OUTPUT
{
  "list": [
    {
      "customer": {
        "id": "1",
        "first_name": "bennett",
        "last_name": "doe",
        "email": "[email protected]",
        "phone": "+100",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1630848839,
        "taxability": "taxable",
        "updated_at": 1630848840,
        "locale": "en-US",
        "pii_cleared": "active",
        "resource_version": 1630848840782,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "unbilled_charges": 0,
        "preferred_currency_code": "SGD",
      }
    }
  ],
  "next_offset": "[\"1630848839000\",\"42903379\"]"
}