HULFT SquareでJSONファイルを読み込むにはどうすればいいか

昨年末セゾンテクノロジーに入社し、今年(2025年)に入って[HULFT Square](https://www.hulft.com/service/hulft-square)を触る機会があったが、JSONをファイルから直接読み込むための[コネクター](https://www.hulft.com/help/ja-jp/HULFTSquare/Content/Designer/Connector/connector.htm)がないことに驚いた。

公式ドキュメントに情報はあるものの、点在しており把握しにくかったため、まとめたものをメモ。

## 結論から

2025年3月、 HULFT Square 2024.2.1 の時点では以下の状況。

- JSONを文字列やファイルから直接読み込み、パースすることはできない
  - DataSpider Servista(以下DataSpider)では、外部アプリケーション起動処理が使えたため、バッチやシェルを通じてJSONのパースなどが行えたが、HULFT Squareでは任意のバッチやシェルを実行する同様の処理が存在しない
- [REST関連コネクター](https://www.hulft.com/help/ja-jp/HULFTSquare/Content/Designer/Connector/network_rest.htm)を使うことで、限定的にJSONを扱うことができる
  - レスポンスボディをJSONからXMLに変換し、後述の処理で扱える
  - POST,PUT,PATCHの場合、リクエストボディとしてファイルからJSONを読み込み、XMLに変換できる
  - [JSONスキーマ](https://www.hulft.com/help/ja-jp/HULFTSquare/Content/HULFT_Square/HS_Resources/resources_Schemas.htm)は、これらのJSONとXMLの変換に使用可能

よって、REST API実行時のリクエストボディやレスポンスボディとしてJSONを扱うことはできるものの、ファイルから直接JSONを読み込むことはできない。

暫定的に、既存のコネクターを用いてファイルから直接JSONを読み込む場合、以下2通りの方法を使用する。

- 配列などで同一のキーが含まれない場合や、1行あたりにキーが1つしか含まれないような整形済み(Pretty)のJSONであれば、ファイル読み取りコネクターを使って行単位で読み込み、デリミタを `:` にしたり正規表現で値を取得
- Minifyされ改行を含まないなど、複雑な形式であれば、JSONパース用のスクリプトをREST APIジョブとし、POSTコネクターなどで呼び出し、XMLやCSVなどHULFT Squareが扱いやすい形式に変換する
  - 正規表現で頑張れなくもないがしんどい

## 経緯

ユースケースとして、オブジェクトストレージに保存されたJSONファイルを読み取る必要があった。

[S3](https://www.hulft.com/help/ja-jp/HULFTSquare/Content/Designer/Connector/amazons3_get.htm), [Azure Blob](https://www.hulft.com/help/ja-jp/HULFTSquare/Content/Designer/Connector/azure_storage_blob_get.htm)など、オブジェクトストレージからのファイルダウンロードは可能だが、いざダウンロードしたJSONを読もうと思うと、対応するコネクターが見当たらない。

今日日JSONが読めないわけはないだろうと思い、調査を開始。

## 調査した内容

以下、JSON読み取りについて調べた内容。すべて公開情報に基づく。

### 公式ドキュメントの確認

まずコネクター一覧を見るが、「JSONファイル読み取り」はない。

https://www.hulft.com/help/ja-jp/HULFTSquare/Content/Designer/Connector/connector.htm

続いて、[テクニカルFAQ](https://support.square.hulft.com/hc/ja/categories/360004779431)を「JSON」で検索すると、30件弱の検索結果が得られる。

https://support.square.hulft.com/hc/ja/search?category=360004779431&query=JSON

1件目に表示されるのが「[JSON形式のファイル読み取り/書き出しは可能ですか](https://support.square.hulft.com/hc/ja/articles/19125400526996)」。読み取りに関しては以下の記載。

> JSONファイルを [可変長ファイル読み取り] 処理や [CSVファイル読み取り] 処理 で1行ずつ読み込み、Mapperの [連結] ロジックで1つの文字列に結合することで、テキストとしてJSONファイルの中身を取得することができます。

また、JSONファイルの書き出しについて、以下の記載がある。

> 1. RESTコネクター
[APIプロジェクト] に向けてRESTリクエストを送信し、そのレスポンスボディをファイルとして出力することでJSONファイルを書き出すことが可能です。

2件目が「[JSONファイル内で1回のみ出現するKeyの値を抽出する方法](https://support.square.hulft.com/hc/ja/articles/32327613984020)」。こちらでは、可変長ファイル読み取りと正規表現の組み合わせでの方法が記載されている。

### RESTコネクターの詳細確認

RESTコネクターであればレスポンスボディを書き出せる、ということで、該当の処理を確認する。

https://www.hulft.com/help/ja-jp/HULFTSquare/Content/Designer/Connector/network_rest.htm

どうやら、リクエストボディを設定可能なPOST,PUT,PATCHの場合、リクエストボディとしてファイルからJSONを読み込むことが可能。ただし、直接JSONとして読み込めるわけではなく、XMLに変換される模様。

また、レスポンスについても同様に、JSONをXMLに変換して扱うことが可能。

JSONとXML変換の使用は、各コネクターのドキュメントに記載。いずれも内容は同じ。

ただ、今回はファイルからJSONを読み込み、内容を確認したいだけなので、この方法は使えない。

### DataSpiderのFAQの確認

参考になるかと思い、DataSpiderのFAQも確認。

[取得したデータを別スクリプトに渡さずにJSON形式に変換することはできますか](https://faq2.hulft.com/faq/show/35004)や、[DataSpider で JSON 形式のファイルを読み取って処理する方法はありますか](https://faq2.hulft.com/faq/show/35621)など、同様の質問があったが、やはり回答も同様のもの。

DataSpiderでは[外部アプリケーション起動](https://www.hulft.com/help/ja-jp/DataSpider/latest/help/ja/adapter/basic/launch.html)アダプタ[^1]である程度自由に処理できたが、HULFT Squareでは同様の処理は存在しない模様。

[^1]: HULFT Squareのコネクターに相当

## 対応

以上の結果から、現時点でファイルから構造化データとしてJSONを読み込むことはできないため、単純にテキストとして読み込んで手動で解析することにした。

今回ファイルから読み込みたいJSONは整形済みで、キーおよび値ごとに改行で区切られた状態だった。

```json:読み込みたいJSONのイメージ
{
  "id": 1,
  "name": "name",
  "values": [
    "value1",
    "value2"
  ],
  "error": {
    "code": 0,
    "message": ""
  }
}
```

また、参照したいキーおよび値には `:` が含まれないことが事前にわかっていたため、 `:` をデリミタとした[CSVファイル読み取り](https://www.hulft.com/help/ja-jp/HULFTSquare/Content/Designer/Connector/csv_get_data.htm)コネクターを用い、 `key,value` の2列に分割。

1行ずつ読み取り、特定のキーであれば値に対して処理をすることで対応できた。

## 振り返り

JSONをファイルから読み込めないというのは、想定していなかったため、正直言って大変驚いた。

幸い `:` をデリミタとして処理できたものの、改行やキーの出現順といった、テキストとしての形式に依存しているのはなかなかまずい状態。

スクリプトをREST API化し、そこにJSONファイルから読み込んだデータをPOSTすることで、HULFT Squareで完結した読み取りができそうではあるが、JSONの読み取り程度でそこまで手間をかけるのは本末転倒な気がする。

## 余談: SkyOnDemandでのJSON読み込み

2018年ごろに、株式会社テラスカイが提供していたSkyOnDemand[^2]を利用していた。

[^2]: 2021年9月30日にサービス終了

DataSpiderをベースにしており、実行環境はCentOSだったため、以下のようなシェルスクリプトを[外部アプリケーション起動処理](https://doc.skyondemand.net/v4/help/ja/adapter/basic/launch.html)アダプターで呼び出し、 `jq` を(自己責任で)使うことができた。

```bash
#!/bin/bash

# 当時のjqはStephen Dolan氏のリポジトリ管理だったので、現在とはパスが異なる。
# 経緯はこちらに詳しい: https://itchyny.hatenablog.com/entry/2023/05/30/090000
jq --version || (wget -O jq https://github.com/stedolan/jq/releases/download/jq-1.5/jq-linux64 && chmod +x ./jq)

# 以降、JSONファイルをjqで操作
```

HULFT Squareでは外部アプリケーション起動処理が削除されているが、DataSpiderであれば、同様に `jq` をインストールしておくことで利用できるかもしれない。