Workato カスタムコネクター開発：アクションの出力項目をレシピ作成時にカスタマイズする方法

はじめに

Workato では、標準ではサポートされていないアプリケーションに対して、自分でコネクターを作成するコネクター SDK があります。

コネクター作成時に、アクションの入出力の項目の名称や型（スキーマ）を設定しますが、コネクターの作成時にはスキーマを確定できない場合があります。
例えば、DBMS などでは、テーブルの型によって、更新時の入力や検索結果の出力の項目は変わってきます。
そのため、レシピ作成時に入出力のスキーマを変更する必要があります。

ここでは、2024 年 3 月現在で利用できる、レシピ作成時に出力用のスキーマを変更するための方法を説明します。

入力用のスキーマについてはこちらの記事を参照してください。

レシピ作成時に出力用のスキーマを変更するには

Workato ではレシピ作成時にスキーマを変更するために、スキーマデザイナーという機能が提供されています。
コネクター作成時にこのスキーマデザイナーを利用することで、レシピ作成時にスキーマを変更することが可能となります。

出力項目設定時のスキーマデザイナーの利用方法

この記事では、 Qiita の REST API の呼び出しを例として説明します。

カスタムコネクターの作成

1. Workato の [Tools] > [Connector SDK] で コネクター SDK を起動します。
   

2. [New connector] でコネクターを新規作成します。

3. [Get guided from a Workato template] を選択して、[Next] をクリックします。

4. アプリケーション名に「Qiita」を入力して、[Go to editor] をクリックします。

ここでは認証認可にアクセストークンを使用する方法で Qiita へのコネクタを作成し、Get 用のアクションを定義します。
ここに関しての詳細は本記事では省略します。

{
  title: "Qiita Connector",

  connection: {
    fields: [
      {
        name: "token",
        control_type: "string",
        label: "Bearer token",
        optional: false,
      },
    ],

    authorization: {
      type: "custom_auth",

      apply: lambda do |connection|
        headers("Authorization": "Bearer #{connection["token"]}")
      end,
    },

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

  test: lambda do |connection|
    get("authenticated_user")
  end,

  methods: {},

  object_definitions: {},

  actions: {
    get_action: {
      title: "Get Action",
      description: "Get Action",

      input_fields: lambda do |object_definitions, connection, config_fields|
        []
      end,

      execute: lambda do |connection, input|

      end,

      output_fields: lambda do |object_definitions|
        []
      end,
    },
  },

  triggers: {},

  pick_lists: {},
}

入力項目の設定

1. Get アクションの入力用のスキーマを object_definitions ブロックで設定します。
   ここでは、呼び出し先の URL を定義します。

     input_fields: lambda do |object_definitions, connection, config_fields|
       object_definitions["get_action_input"]
     end,
   

   object_definitions: {
     get_action_input: {
       fields: lambda do |_connection, config_fields|
         [
           {
             name: "url",
             label: "URL",
             optional: false,
           },
         ]
       end
     },
   },
   

2. 出力スキーマカスタマイズ用の項目をスキーマデザイナーとして追加します。
   出力スキーマの設定もユーザーによる入力にあたるため、入力項目として設定します。
   スキーマデザイナーは、control_type に schema-designer を指定することで利用可能です。
   入出力の項目定義に影響を与えるため、extends_schema に true を設定して、object_definitions 内で config_fields として参照できるようにします。

       [
         {
           name: "url",
           label: "URL",
           optional: false,
         },
         {
           name: "output",
           label: "Output",
           optional: true,
           sticky: true,
           extends_schema: true,
           control_type: "schema-designer",
           sample_data_type: "json_input",
         },
       ]
   

3. アクションの出力用のスキーマを object_definitions ブロックで設定します。

     output_fields: lambda do |object_definitions|
       object_definitions["action_output"]
     end,
   

   出力スキーマの設定があるときのみ評価するように if ブロックを追加します。
   出力項目として body を定義し、種別を object、入力された出力スキーマを properties として設定します。
   スキーマ情報は文字列なので、parse_json で解析します。

   action_output: {
     fields: lambda do |_connection, config_fields, object_definitions|
       if config_fields["output"].present?
         output_schema = parse_json(config_fields["output"])
         response_body = { name: "body" }
         response_body[:type] = "object"
         response_body[:properties] = output_schema
   
         [response_body]
       else
         []
       end
     end,
   },
   

アクションの出力

入力された URL に対して、get メソッドを呼びだします。
レスポンスを action_output での記載に合わせて body の値として設定します。

execute: lambda do |connection, input|
    url = input['url']

    {
        "body": get(url)
    }
end,

動作確認１

ここでは、アクセストークンに紐付いたユーザーを取得します。

[URL] にユーザー情報取得のエンドポイントの authenticated_user を指定します。

出力スキーマ情報はスキーマデザイナーで [Use JSON] を指定して、リファレンスのサンプル出力の JSON を貼り付けて設定します。

実行結果を見ると、出力項目名が実際の値ではなく、ラベルになっているため、マッピングがされていることがわかります。

動作確認2

次に、タグの一覧を取得します。

[URL] にタグ一覧のエンドポイントの tags を指定します。

出力スキーマ情報はスキーマデザイナーで [Use JSON] を指定して、リファレンスのサンプル出力の JSON を貼り付けて設定します。

実行結果を見ると、出力項目名がラベルになっておらず、実際の値のため、マッピングに失敗していることがわかります。

あらためて出力項目の設定を見ると、array という項目名で配列が定義されていることがわかります。

get のレスポンスには、array という項目がないため、マッピングに失敗しているようです。

出力項目の調整

タグ一覧のようにレスポンスとして直接配列が返ってくるケースのために、出力項目の処理を変更します。
出力スキーマの項目が一つだけで、配列の場合、レスポンスの配列を body として参照できるように設定します。

    action_output: {
      fields: lambda do |_connection, config_fields, object_definitions|
        if config_fields["output"].present?
          output_schema = parse_json(config_fields["output"])
          response_body = { name: "body" }
            if output_schema.length == 1 and output_schema.dig(0, "type") == "array"
              response_body[:type] = "array"
              response_body[:properties] = output_schema.dig(0, "properties")
            else
              response_body[:type] = "object"
              response_body[:properties] = output_schema
            end

            [response_body]
        else
          []
        end
      end,
    },

動作確認3

先程のテストを再度実行します。
実行結果を見ると、出力項目名が実際の値ではなく、ラベルになっているため、マッピングがされていることがわかります。

なお、今回の対応では、 {"tags": [{"name": "Ruby", "versions": ["0.0.1"]}]} のように、項目名がついて配列になっているパターンには対応できませんが、項目数を見ているため、出力スキーマの設定時にダミーの項目を追加することで回避可能です。
["a", "b"] のように、レスポンスの配列の中身がオブジェクトでないパターンにも対応していませんが、今回のやり方を応用することで対応できると思います。

まとめ

まとめると、以下のようになります。

• Workato のカスタムコネクターでレシピ作成時にスキーマを指定したい場合は、スキーマデザイナーが利用できる
• レスポンスとして直接配列が返ってくるパターンに対応するためには出力項目の処理に工夫が必要

おわりに

カスタムコネクターで出力項目をレシピ作成時に行いたいケースでは、スキーマデザイナーが利用できます。
出力項目にスキーマデザイナーを使う場合は、直接配列が返ってくるケースに工夫が必要になります。

Workatoの導入・導入後の活用などでお困りの場合、Workatoリセラーにご相談する方法もございます。お困りごとがございましたら、認定リセラーの日立ソリューションズへ是非ご相談ください。

参考リンク

• 株式会社 日立ソリューションズ
  • Workato ご紹介サイト
• Workato 公式サイト
  • Workato スキーマ
• Qiita 公式サイト
  • Qiita API v2ドキュメント