はじめに
Workato では、標準ではサポートされていないアプリケーションに対して、自分でコネクターを作成するコネクター SDK があります。
コネクター作成時に、アクションの入出力の項目の名称や型（スキーマ）を設定しますが、コネクターの作成時にはスキーマを確定できない場合があります。
例えば、DBMS などでは、テーブルの型によって、更新時の入力や検索結果の出力の項目は変わってきます。
そのため、レシピ作成時に入出力のスキーマを変更する必要があります。
ここでは、2024 年 3 月現在で利用できる、レシピ作成時に出力用のスキーマを変更するための方法を説明します。
入力用のスキーマについてはこちらの記事を参照してください。
レシピ作成時に出力用のスキーマを変更するには
Workato ではレシピ作成時にスキーマを変更するために、スキーマデザイナーという機能が提供されています。
コネクター作成時にこのスキーマデザイナーを利用することで、レシピ作成時にスキーマを変更することが可能となります。
出力項目設定時のスキーマデザイナーの利用方法
この記事では、 Qiita の REST API の呼び出しを例として説明します。
カスタムコネクターの作成
-
Workato の [Tools] > [Connector SDK] で コネクター SDK を起動します。
-
[New connector] でコネクターを新規作成します。
-
[Get guided from a Workato template] を選択して、[Next] をクリックします。
-
アプリケーション名に「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: {},
}
入力項目の設定
-
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 }, }, -
出力スキーマカスタマイズ用の項目をスキーマデザイナーとして追加します。
出力スキーマの設定もユーザーによる入力にあたるため、入力項目として設定します。
スキーマデザイナーは、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", }, ] -
アクションの出力用のスキーマを 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 公式サイト
- Qiita 公式サイト