はじめに
以下は、APIレスポンスの形でよくある、ネストされた情報のリストです。
[
{
"project_name": "Aプロジェクト",
"status": "進行中",
"details": {
"completion_percentage": 75,
"priority_level": "高"
}
},
{
"project_name": "BAプロジェクト",
"status": "レビュー待ち",
"details": {
"completion_percentage": 90,
"priority_level": "中"
}
},
{
"project_name": "Cプロジェクト",
"status": "一時中断",
"details": {
"completion_percentage": 15,
"priority_level": "低"
}
}
]
このような形のリストをフィルタリングして、その結果を後続ステップで使いたいことってありますよね。
でも、これをWorkatoで実装しようと思うと、ちょっとした壁に直面します。
formulaがあるのに、使えない？
Workatoには、配列やリストを操作するためのFormulaが多数用意されています。
特に「where」というformulaは、任意の条件でリストを絞り込むことに適しています。
そして、Workatoにはリスト操作を行うアクションも用意されています。
複数行を一括でリストに追加する際には、「Variables by Workato」コネクターの「Create list」や「Add items to list(バッチ)」アクションを通常なら使います。
ところが、これらのアクションは、別のデータソース(リスト型のデータピル)の入力を前提としており、formulaモードには対応していません。
絞り込み専用のformulaがあるのに、その結果を格納しようとするアクション側ではformulaを使えない という歯がゆい事態が発生します。
他の手段として、Pythonコネクター等を使えば実現できますが、それだけのためにコードを書くのはちょっとな… という時に使えるお手軽なフィルター方法を紹介します。
それは「JSON tools by Workato」 コネクターを使う方法です。
「JSON tools by Workato」コネクターをおさらい
「JSON tools by Workato」コネクターには、「Parse JSON Document（JSONの解析）」アクションが用意されています。
「Parse JSON Documen」の使いどころは、ストレージに置かれたTextファイルに保存された構造化データを処理したい時や、コネクターでレスポンスの一部がデータピル化されていないような項目にアクセスしたい時です。
標準的な利用の流れとして、先行アクションのOutputであるJSON文字列を「Document」にセットします。
実装例：格納されたtxtファイル（製品群）を解析して、製品単位でSlack通知するレシピ
| Input field | 説明 |
|---|---|
| Sample document | データの構造を定義するサンプルJSONです。これに基づいて、後続アクションで利用できるデータピルが生成されます。 |
| Document | 実際に解析したいJSON形式の文字列を入力します。 |
ここで注目すべきは、「Document」フィールドが、formulaモードに対応している点です。
「where」formulaで絞り込んだ結果のリストが「Document」へ渡されることで、構造を保ちながら新しいリストとして出力されます。
その結果、絞り込み後のリストを後続ステップにデータピルとして引き継げます。
「JSON tools by Workato」を使ってデータを絞り込む方法
freee会計の取引先マスタから、「インボイス制度適格請求書発行事業者である」データのみ抽出したい！
というニーズがあるとします。
freee会計コネクターには「取引先一覧の取得」というアクションが用意されています。
このアクション単体でも、更新日、取引先名、ショートカットキーなどに基づいた取引先マスタの検索が可能です。
逆に言えば、それ以外の項目での検索には対応していません。
任意の項目に対して任意の条件で絞り込みたい場合は、全件を取得してから、自前でデータ加工する必要があります。（そもそも検索系APIがないSaaSの場合は、必ずそういう流れになります）
1. 「取引先一覧の取得」アクションを実装
まずは、条件は設定せず、まるっとfreee会計から取引先を全件取得します。
（必須の事業所IDのみ、設定します）
2. ジョブからサンプル用のJSONを取得
後続で使うJSONのサンプルには、取引先一覧の取得のレスポンスを使用します。
そのため、ここまで実装したら、一度ジョブを実行しておきます。
そして、ジョブでは「取引先一覧の取得」アクションのログを見ます。
必ず「Copy raw JSON」ボタンをクリックして、JSONを取得しましょう。
なぜ、Outputの表示内容をドラッグ＆ドロップしてコピーしてはいけないのか？
Outputに表示される内容は、以下の理由により厳密なJSON形式ではありません。
1. 論理名（日本語）の使用
表示されている項目名（例：取引先 ID）は、Workatoが理解しやすいように変換した論理名であり、APIが返す物理名（例：id）と一致しません。
2. JSON形式の違反
表示内容では、キー（項目名）がダブルクォーテーション(")で囲まれておらず、JSONの文法ルールを満たしていません。
このため、表示内容をそのままコピーしたテキストをParse JSON DocumentのSample documentにセットすると、JSONパーサーが文法エラーと判断し、以下のようにスキーマの定義に失敗します。
3. 「Parse JSON Document」アクションを実装
肝心の処理です。
ステップを追加し、App（コネクター）で「JSON tools by Workato」を選択すると、
アクションは１つしか無いため、自動的に「Parse JSON Document」アクションが選択されます。
Setup
設定が完了した状態は以下の通りです。
入力内容について、詳細を補足します。
Sample document
先ほどコピーしておいたJSONを貼り付けると、以下のようになります。
モデルを単純化すると、こうですね。
{"partners":[{取引先1},{取引先2},{取引先3}]}
ここで注意すべきなのは、Documentの欄で実装する予定の取引先リスト.where(...)は、Workatoが既にリストの本体にアクセスしていることを意味します。
したがって、Formulaが返すデータは、既に中身のリスト[]がむき出しの状態です。JSONの第1階層でリストをラップしている要素"partners"は不要なので、取り除きます。
＜編集後＞
エディターの「▼」を使いこなすと、見た目がスッキリして作業しやすくなります。
Document
Textモードから、Formulaモードに切り替えます。
やりたいことは
freee会計の取引先マスタから、「インボイス制度適格請求書発行事業者である」データのみ抽出したい！
です。
freee会計APIリファレンスによれば、取引先一覧の取得APIのレスポンスに含まれる「qualified_invoice_issuer」という項目が「インボイス制度適格請求書発行事業者かどうか(はい：true／いいえ：false)」を表します。
このため、絞り込み方は取引先リスト.where(qualified_invoice_issuer: true)となり、そのデータをJSON形式で返すべく「.to_json」で締めます。
取引先リスト.where(qualified_invoice_issuer: true).to_json
必ず最後に「.to_json」を忘れずに！
to_jsonを付け忘れると、下記のようにエラーが発生します。
なぜエラーになるのか
「where」formulaの出力は、キーと値が=>で区切られたRubyのハッシュ型のオブジェクトです。
これは、JSONの厳密な規格である {"key": value} の形式を満たしていません。具体的には、キーと値の区切りがコロン:ではないため、無効なJSONとみなされます。
Parse JSON Documentアクションは、Documentフィールドに厳密なJSON文字列を要求します。
したがって、ハッシュ型をJSON文字列に変換する「to_json」formulaを使い、有効なJSON文字列に変換する必要があります。
完成レシピ
レシピ実行結果
ステップ2（全件取得）の結果：3件
ステップ3（絞り込み）の結果：1件
絞り込み道場 ～7つの例～
取引先一覧を、いろんな条件で絞り込んでみるコーナーです。
＜取引先一覧APIのレスポンス例＞
{
"partners": [
{
"id": 1,
"code": "code001",
"company_id": 1,
"name": "ABC商店",
"update_date": "2019-12-17",
"available": true,
"shortcut1": "ABC",
"shortcut2": "501",
"org_code": 1,
"country_code": "JP",
"long_name": "新しい取引先正式名称",
"name_kana": "アタラシイトリヒキサキメイショウ",
"default_title": "御中",
"phone": "03-1234-xxxx",
"contact_name": "営業担当",
"email": "contact@example.com",
"payer_walletable_id": 1,
"transfer_fee_handling_side": "payer",
"qualified_invoice_issuer": false,
"invoice_registration_number": "T1000000000001",
"address_attributes": {
"zipcode": "000-0000",
"prefecture_code": 4,
"street_name1": "ＸＸ区ＹＹ１−１−１",
"street_name2": "ビル１Ｆ"
},
"partner_doc_setting_attributes": {
"sending_method": "posting"
},
"partner_bank_account_attributes": {
"bank_name": "freee銀行",
"bank_name_kana": "フリーギンコウ",
"bank_code": "0001",
"branch_name": "銀座支店",
"branch_kana": "ギンザシテン",
"branch_code": "999",
"account_type": "ordinary",
"account_number": "1010101",
"account_name": "フリータロウ",
"long_account_name": "freee太郎"
}
}
]
}
freee会計API 公式リファレンスより、上記のExample Valueをお借りしました。
詳細なフィールド定義については、以下を参照ください。
インボイス制度適格請求書発行事業者である
取引先リスト.where(qualified_invoice_issuer: true).to_json
インボイス制度適格請求書発行事業者だが、登録番号が未設定
取引先リスト.where(qualified_invoice_issuer: true).where(invoice_registration_number: null).to_json
銀行情報を持つ
取引先リスト.where.not(partner_bank_account_attributes: null).to_json
銀行情報を持ち、銀行名が 「freee銀行」 である
取引先リスト.where('partner_bank_account_attributes.bank_name': 'freee銀行').to_json
取引先住所の都道府県が愛知県である
取引先リスト.where('address_attributes.prefecture_code': 22).to_json
取引先住所の都道府県が東京都or大阪府である
取引先リスト.where('address_attributes.prefecture_code': [12,26]).to_json
電話番号が「03」から始まる
取引先リスト.where(phone: /^03/).to_json
おわりに
今回は絞り込みに特化しましたが、同様の方法を用いてformulaを自在に操れば、データを並び替えたり、グループ化したりできます。
いろんな場面で役立つので、ぜひやってみてください。