クラウド帳票サービスoproartsによる帳票出力をDataSpiderでやってみた

## はじめに
こんにちは、すぎもんです:smiley:　今回は、DataSpiderとoproartsをつないでみます。

## oproartsとは　
[oproarts(オプロアーツ)](https://oproarts.opro.net/)は、クラウド帳票ツールとして高いシェアを持ち、設定レベルの簡単な操作で、複数のクラウドサービスと連携ができるサービスです。数年前のパンデミックが後押しとなり、働き方改革が大きく進む中、業務の自動化やクラウド化の需要はより一層増え、サービス市場は大きく変化しました。クラウド帳票系サービスは拡大した市場の一つとなります。

## 今回やること

下記の手順でDataSpiderからoproartsにリクエストをして、指定したテンプレートでの帳票出力をしてみます。<font color=blue>※リクエスト形式は、oproartsからのレスポンス挙動（※後述あり）を踏まえて、POST→GETで実行しました。</font>

<strong>＜①POST実行＞</strong>
 　　DataSpiderからoproartsに帳票作成に必要なデータをPOSTリクエストする
　　 →ドキュメント取得のための「リダイレクトURL」をレスポンスヘッダから取得
<strong>＜②GET実行＞</strong>
　　 →①で取得した「リダイレクトURL」に対してGETリクエストをして帳票を取得

## 事前準備

oproartsを利用するためには、オプロ社から発行される下記４つが必要です。
　　・顧客ID（CID）
　　・ユーザーID（UID）
　　・ユーザーパスワード（UPW）
　　・HTTPSリクエストのURL

また、電子帳票の出力には下記2つが必要です。
　　・テンプレート（帳票デザインが定義されたファイル）
　　・CSVファイル（帳票に出力するデータ）

:::note warn
今回使用する環境は、オプロ社にて事前に設定された環境を用意していただいて実施しています。
そのため、oproartsの利用で必要となる各情報は、今回は全てオプロ社から提供されたものです。
:::

## 検証手順
＜DataSpiderの設定＞
手順は以下の通りです。今回はPOST実行＋GET実行が必要です。（※詳細は別途後述）

　　　①スクリプト変数の作成
　　　②POST実行の設定
　　　③POST実行のためのマッピングの設定
　　　④GET実行の設定のためのマッピング設定
　　　⑤GET実行の設定

## DataSpiderの設定
oproarts側の必要情報の準備が完了したら、DataSpiderの設定をしていきましょう。
始めに、任意の名前でプロジェクトとスクリプトを作成してください。

##### ①スクリプト変数の作成
まずは、ロジック作成に必要となる値をスクリプト変数として定義します。
顧客ID（CID）,ユーザーID（UID）,ユーザーパスワード（UPW）など、オプロ社から発行された顧客IDなどの情報は固定値なのでスクリプト変数として定義しておくと良いでしょう。

今回作成したスクリプト変数は下記です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/44b8f927-c8bf-f63f-144f-905853550d22.png)
スクリプト変数に設定する値は、「初期値」の部分に入力して設定します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/7e38ad52-02af-d2e7-01c0-fa5c9861c805.png)


##### ②POST実行の設定
oproartsに帳票用のデータをPOSTする設定をしていきます。

DataSpiderのデザイナ画面右側にあるツールパレットメニューから、[ネットワーク]＞[REST]＞[POST実行]をデザイナ画面中央にドラッグ＆ドロップし設定画面を開きます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/42869479-65fd-362b-3481-669bccc3fa32.png)
まずは、必須設定タブです。
「接続先」のプルダウンリストから[追加]を選択し、下記の通り設定します。
「接続テスト」を押下し、入力したURLがDataSpiderと通信可能か確認してください。
　　　・接続名　：　`OPROARTS`
　　　・URL　　 ：　`https://www.oproarts.com/`
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/c8592d81-70f2-57b0-2f21-b9d43c52a158.png)

:::note warn
「接続先」は、DataSpider Studioの「コントロールパネル」>「グローバルリソースの設定」から事前に設定することも可能です。
※DataSpiderとつなげるサービスとの<strong>　”接続情報” </strong>を設定できます。
:::

POST実行処理の必須設定画面は下記の通り設定します。「パス」には、OPPROARTS社から受領した「URL」情報の内、"接続先"の残りの部分を設定します。
　　　・パス　　：　`Facade`
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/5caac7fb-ca42-aa59-d8cb-972f966f7337.png)

次に、リクエスト設定タブです。

:::note warn 
リクエスト設定タブでは、POSTリクエストでのbody部の設定をします。今回は、ファイルアップロード形式なので`multipart/form-data`形式でリクエストします。
:::

　　　・データ入力元　：　`データ`
　　　・データ形式　　：　`マルチパートフォーム`

＜マルチパートフォーム設定＞
「追加」ボタンで設定値を入力します。「上へ」「下へ」で項目順の変更も可能です。
利用できるパラメータの詳細は、[OPROARTS readme](https://www2.opro.net/jp_arts/docs/oproarts_readme.html)に記載があります。
| 名前| 種類 |
|:-----------|:------------|
| CID|文字列| 
| UID|文字列| 
| UPW|文字列| 
| OP|文字列| 
| FE|文字列| 
| TP|文字列|
| TD1|ファイル| 
| TD2|ファイル| 

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/5e9939bb-9435-c88a-3ddb-c7d89ee61dfe.png)

:::note info
オプロ社から提供されたテンプレート（TP)に対して、2つのCSV（ヘッダ用、明細用）が必要です。そのため、「TD1」と「TD2」を設定しています。
:::

続いて、レスポンス設定タブを設定します。今回は「電子帳票のダウンロード」をするので、データ出力先はファイルとしたいところですが、下記の通り設定します。

:::note warn
マルチパートフォーム形式なので、「データ」形式でのレスポンス設定をします。
:::
　　　・データ出力先　　　　　　　：　`データ`
　　　・データ形式　　　　　　　　：　`その他のデータ形式`
　　　・自動でリダイレクトする　　：　`✓なし`
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/77c99e56-4e66-de99-bff6-1011c77b9e36.png)
最後に、ヘッダ設定です。レスポンスヘッダに「`Location`」を追加します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/e2d9c84a-a819-9e7a-9689-fd89ed00032d.png)

:::note warn
レスポンスヘッダ「Location」でリダイレクトURLを取得して「GET処理（帳票ダウンロード）」で使います。
:::

以上で、POST設定は完了です。

##### ③POST実行のためのマッピングの設定
POSTリクエストを実行するためのマッピング設定をします。マルチパートフォーム形式でのデータ入力に必要となる値（固定値）はスクリプト変数で冒頭に定義済みなので、それらをマッピングします。

デザイナ画面右側のツールパレットメニューから、[変換]>[基本]＞[マッピング]を、デザイナ中央のPOST実行アイコンの左側にドラッグ＆ドロップします。

マッピングアイコンをクリックし、POST実行アイコンの上にドラッグ＆ドロップして線をつなぎましょう。「フローの作成」のポップアップ画面が表示されるので「`プロセスフローとデータフローを引くに✓`」をします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/6913919f-f1f2-b565-8ec5-bbe1fe656b73.png)

:::note warn
DataSpiderは処理アイコンを並べて、線でつないで一連の処理を作成します。アイコン同士をつなぐ黒い線が「プロセスフロー」（処理の流れ）で、黄色い線が「データフロー」（データの流れ）です。
:::

マッピングアイコンをダブルクリックして、マッピング設定をします。

出力先にPOST実行の設定内の「リクエスト設定タブ」で追加したマルチパートフォームの項目が設定されていることが確認できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/02688050-6f5f-6011-d83f-d5c0a9c8b771.png)
それぞれの出力項目にマッピングをしていきましょう。

各入力項目と出力項目は、下記の通り値を設定します。（項目同士を線でつなぎデータをマッピングします。）
出力先項目「TD」は「file-path」に、TD以外の項目は「value」に値を設定しましょう。

|入力元|出力先|内容|
|:-----------|:------------|:------------|
|スクリプト変数「OPPROARTS_CID」|CID|発行された顧客ID※|
|スクリプト変数「OPPROARTS_UID」|UID|発行されユーザーID※|
|スクリプト変数「OPPROARTS_UPW」|UPW|発行されたユーザーパスワード※|
|単一行文字列定数「dlp」|OP|操作指示のパラメータでPDFのダウンロード|
|単一行文字列定数「true」|FE|PDFにフォント埋め込みtrueかfalseか(省略可)|
|スクリプト変数「テンプレート名」| TP|発行されたテンプレート名※|
|スクリプト変数「ファイルフォルダ」と「リクエストファイル名（ヘッダ）」の連結|TD|/data/oproarts/nouhin_header.csv|
|スクリプト変数「ファイルフォルダ」と「リクエストファイル名（明細）」の連結|TD|/data/oproarts/nouhin_meisai.csv|

<font color = blue>※必要情報の一部はオプロ社から発行されたものを利用します。</font>

:::note warn
POSTリクエストで設定したCSVファイルはオプロ社から提供されたものを使っていますが、実運用などでは、CSVファイル作成の部分をDataSpiderを使って実装することも可能です。
:::

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/4bcda8e9-f962-a72d-3710-db12788be1cc.png)

以上で、マッピング設定は完了です。
提供された情報など固定の情報はスクリプト変数で用意し、そのままマッピングします。
また、「dlp」や「true」の様に、マッピング設定内で「文字列定数」アイコンを使うこともできます。

##### ④GET実行のためのマッピングの設定
「POST+GET方式」するために、後続のGET実行をするためのマッピング設定をします。

まずは、GETリクエストで使うURLのためのスクリプト変数を作成します。GET実行の「パス」に指定する変数です。

:::note warn
POST実行のレスポンスで「Location」ヘッダにリダイレクトURLが設定されます。
その値を、スクリプト変数「リダイレクトURL」に設定しましょう。
:::
　　・名前　　　：　`リダイレクトURL`
　　・変数の型　：　`文字列`

デザイナ画面右側のツールパットメニューから、[変換]＞[基本]＞[マッピング]を「POST実行アイコン」の右側にドラッグ＆ドロップします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/3938be33-f9ea-d169-c0db-8647b63f2e66.png)

[プロセスフローとデータフローを引く]に「`✓`」を入れます。

POST実行のレスポンスで「Location」ヘッダに設定する値には、接続情報で指定される「https://･････」も含まれるので、必要な部分のみを残して抽出する必要があります。

下記が「Location」ヘッダに実際に設定される値です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/6d5ac174-a872-1058-15e3-2684a6f3d56a.png)
接続情報で設定したURL部分「<strong>https://www.oproarts.com</strong>」（＝先頭25文字）が不要なので、<strong>26</strong>文字目から末尾までの<strong>「Output***.pdf」が必要な文字列</strong>です。

右側のツールパレットの[文字列]＞[関数]＞[指定位置以降]を使用して、必要な部分のみを抽出します。

[指定位置以降]を中央部分にドラッグ＆ドロップして、ダブルクリックでプロパティ設定画面を開きます。「開始位置」を「`26`」と設定します。

:::note info 
「指定位置以降ロジック」アイコンで「開始位置」に設定した桁数以降の値を扱えます。
:::
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/e3aa2c6e-fee5-2345-f484-63b7a0626d26.png)

POST実行のヘッダ設定にあるレスポンスヘッダ「Location」が、入力元のコンポーネント変数の「execute_http_post」の変数としてありますので、下記の通り、スクリプト変数「リダイレクトURL」と線でつなぎましょう。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/275782ca-d317-f68a-ccea-12414ed16063.png)

##### ⑤GET実行の設定

POST実行で取得した「リダイレクトURL」の準備ができましたので、GET実行の設定をします。

デザイナ画面右側のツールパレットから、[ネットワーク]＞[REST]＞[GET実行]アイコンを中央部分にドラック＆ドロップして、設定画面を開きます。

まずは、必須設定タブです。
前章のマッピング設定で準備したスクリプト変数「リダイレクトURL」を「パス」に設定します。（※「パス」入力欄の右端▶をクリックして、スクリプト変数を選択できます。）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/8ec153a6-1f3a-f54f-2743-74b391b5c7e2.png)
下記の通り設定されます。
　　・接続先　　：　`OPROARTS`
　　・パス　　　：　`${リダイレクトURL}`
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/5875edf3-cb0f-dabe-0a57-51b9887bf268.png)
次は、レスポンス設定タブです。

ファイルをダウンロードするので、下記の通り設定します。
　　・データ出力先　：　`ファイル`
　　・ファイルパス　：　`/data/oproarts/SampleTemplateResponse.pdf`
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/2d7ef247-5eb3-dc17-8614-439b648688ef.png)
以上で、GET実行の設定は完了です。

全ての処理アイコンの設定が完了したので、下記の通り、アイコンをつなぎます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/40310e42-f88b-4533-b82b-693a6229c409.png)

##### ★DataSpiderの小ネタ（マッピングアイコンの名称変更）★
マッピングアイコンの名称は、DataSpiderのデザイナ画面左下の「プロパティインスペクタ」で変更できます。【基本設定】にある「名前」-「値」に入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/90533ef5-7673-4228-eccc-54667b48aec1.png)
例えば、名前の値が「mapping(1)」となっているのを「リダイレクトURLの設定」に変更してみます。入力した値は、他の項目をクリックして確定させます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/35f88f2e-1773-fc77-30d5-e0dc5b4daec3.png)
下記のように、処理概要をアイコン名称にすることで、該当アイコンがどんな処理をしているのかが、一目でわかります。
他のアイコンも全て処理概要に応じて、アイコン名称を付与すれば、スクリプト全体がどのような処理で構成されているのかが一目でわかるようになりますね。スクリプト自体の可読性が上がりますし、分岐があるなど処理が複雑になればなるほど、各処理アイコンに対する名称付けは有効です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/b26c8c82-7557-7553-64b8-2d0d37fd9b37.png)
マッピングアイコンの名称変更は、「プロパティインスペクタ」から設定するので、小ネタとして挟ませていただきました。是非ご活用ください！

## テスト実行
本題に戻りまして、完成したスクリプトをテスト実行してみましょう。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/524372e3-990e-177e-3258-a754873bbe53.png)
DataSpiderのエクスプローラで「/data/oproarts」フォルダを確認します。`SampleTemplateResponse.pdf`が作成されていました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/cce2cde4-3c0d-c0a8-7af1-f223a4c7545e.png)

DataSpiderからoproartsにAPIを使って連携したCSVファイルは下記です。
　　　■CSVテンプレート：nouhin_header.csv, nouhin_meisai.csv
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/eef7a9c8-8a80-4d91-c72b-77f6d71d1624.png)

指定したCSVとテンプレート等（oproarts側の設定）から作成されたファイルは下記です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/a06511b8-737c-aeba-0a33-fa9d4749d626.png)
正しく出力されていることを確認できました。

## oproartsからのレスポンスの注意点（補足）

今回の一連の処理は「POST実行」＋「GET実行」でファイルをダウンロードしました。背景として、oproartsのレスポンスに注意点があったのでメモしておきます。

[OPPROARTS readme](https://www2.opro.net/jp_arts/docs/oproarts_readme.html)を確認すると、oproartsからのレスポンスは、「リダイレクトレスポンスとしてドキュメントURLが返却される」とあります。

:::note warn
DataSpiderのGET実行とPOST実行を試しにやってみて、下記の通り違いがありました。
<strong>＜GET実行の場合＞</strong>
　　自動リダイレクトのリクエストで電子帳票ファイルがダウンロードできる。
<strong>＜POST実行の場合＞</strong>
　　自動リダイレクトのリクエストに対するレスポンスが返らずエラーとなる。
:::

<font color=blue>POST実行を単独実行するだけでは、「ファイルの取得」ができないようです。</font>

そこで、まずはPOST実行で、ドキュメントURLを取得するためのURLをレスポンスヘッダから取得し、次に、取得したURLに対してGET実行でリクエストをする方法を試してみると、無事ファイルダウンロードの成功したという経緯がありました。ご参考にしてください。

## 最後に
いかがでしたでしょうか。DataSpiderからoproartsのAPIを使って、帳票の元となるデータを送り、指定した帳票でのファイルを取得することができました。

１度何かしらのツールなどで処理を自動化することは、「継続的な作業負荷の軽減」につながります。
例えば、DataSpiderのHTTPトリガー機能を使った<strong>リアルタイム連携</strong>。

　　①DataSpiderのHTTPトリガー（指定URL(<font color=green>ex.納品書作成リンク</font>)にアクセス）を使って、
　　　DataSpiderに対してPOSTリクエストを送信。
　　②①をトリガーにしてDataSpiderからoproartsなどの帳票サービスにリクエストを送信。
　　③帳票サービスからDataSpiderが②のリクエストに対するレスポンスを受け取る
　　④③でDataSpiderが受け取ったレスポンスを、Webシステム（<font color=green>ex.)販売管理システム</font>）に返す。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/7d745281-e97d-8489-4c08-f8010e61a8a1.png)

要は、DataSpiderがあらゆるデータとのI/Fを一挙に担うのです。もし、oproartsに渡すファイル情報として、DBやワークフローなどのSaaSサービスの情報取得が必要ならば、DataSpiderを介して連携することもできます。

処理アイコンを並べて作成された業務フローは、データ連携を一元管理し、視覚的な利便性も向上させます。つまり、I/F開発の全てをDataSpiderにお任せするということです。「今あるちょっとした作業の自動化」だけでなく、「SaaSサービスとのインターフェイス開発の自動化」をDataSpiderで実現する参考になれば幸いです。

ここまで読んでいただきありがとうございました。ではまた！