はじめに

楽楽明細の Web API 連係機能を利用して帳票データを登録するサンプルシナリオ（以降、本サンプルシナリオ）について説明します。

本サンプルシナリオの概要

本サンプルシナリオは楽楽明細の Web API 連係機能を利用して帳票データを登録します。
Web API 連係機能は curl コマンドを利用して実行します。

実施する処理

本サンプルシナリオは、以下の処理を行います。

• 楽楽明細の「帳票データ CSV 一括取込」API を実行するための curl コマンドオプション文字列を生成します。
  curl コマンドオプションは　WinActor の変数一覧 にて定義された値から生成します。
• curl コマンドを実行し、帳票データの取込を行います。

使用するWinActorモジュール

本サンプルシナリオでは、以下のWinActorモジュールを使用します。

• ノード/フロー/変数値設定
• 01_WinActor制御/08_実行ログ/ログメッセージ出力.ums6
• 13_ファイル関連/02_ファイル操作/ファイル存在有無チェック.ums6
• 13_ファイル関連/05_ファイル名/フォルダパスとファイル名の連結.ums6
• 25_WinActorノート/01_シェルツール/コマンドプロンプトを開く.ums6
• 25_WinActorノート/01_シェルツール/コマンドを実行する(PowerShell,コマンドプロンプト).ums6
• 25_WinActorノート/01_シェルツール/PowerShell・コマンドプロンプトを閉じる.ums6
• 98_構造データ関連/01_JSON/JSON変数 新規オブジェクト.ums6
• 98_構造データ関連/01_JSON/JSON変数 要素追加.ums6
• 98_構造データ関連/01_JSON/JSON変数 ファイル保存.ums6
• プチライブラリ/ファイルパスからフォルダパスとファイル名を取得するライブラリ

(プチライブラリはこちらからダウンロードできます)

本サンプルシナリオの入力ファイル

帳票データが記載されたCSVファイルを入力ファイルとします。
※入力ファイルについては入力ファイルについてを参照ください。

本サンプルシナリオの想定レベル

本ドキュメントは、以下の技術レベルのユーザを対象としています。

• 楽楽明細の「帳票データ CSV 一括取込」 API について理解している。
• curlコマンドについて理解している。

動作確認環境

本サンプルシナリオは以下の環境で確認しています。

• Windows 10(ver 1903)
• WinActor 6.3.0
• 楽楽明細 Ver6.0.0

制約事項

• 本サンプルシナリオを実行するためには、楽楽明細にアクセスするためのインターネット環境が必要です。
• 本サンプルシナリオおよびドキュメントは、楽楽明細にログインやマニュアルを参照出来る状態を前提に記載されています。

本サンプルシナリオの使い方

本サンプルシナリオの実施方法は以下の通りです。

Step 1. 楽楽明細で事前設定を行う

本サンプルシナリオを実行するために楽楽明細の「管理画面」で「帳票の設定」を行う必要があります。

• "基本設定 > 帳票の設定"にて帳票を登録し、以下の設定を行います。
  ①CSV設定
  ②レイアウト設定

設定方法については楽楽明細のマニュアルを参照ください。

• "基本設定 > 帳票の設定"にて登録した帳票の「詳細」ボタンをクリックし、「帳票種別ID」の値を確認してください。"Step 7." で使用します。
• "基本設定 > API設定"にて APIトークンを作成してください。"Step 5." で使用します。

Step 2. 入力ファイルをディレクトリに配置

任意のディレクトリに入力ファイルを配置します。

Step 3. WinActorで本サンプルシナリオを読み込み

WinActorを起動し、本サンプルシナリオを読み込みます。

Step 4. 動作に必要な変数を設定1 (必須)

本サンプルシナリオを実行するために必要な値を、変数一覧で設定します。
帳票データが記述されたCSVファイルを指定する変数は下記の通りです。

• 対象CSVファイルパス
  • "Step 2"で配置した入力ファイルのファイルパスを、絶対パスで指定します。
    例) C:\sample\input\input.csv
    　※データ形式はStep 1「①CSV設定」の設定内容に合わせます。

本サンプルシナリオ変数一覧1

Step 5. 動作に必要な変数を設定2 (必須)

楽楽明細の API 連係機能を実行するために設定が必要な変数は下記の通りです。

• curlパス
  • curlコマンドのフルパスを指定します。

• 送信先URL
  • 帳票データCSV一括取込 API の URL を指定します。

• APIトークン
  • "Step 1" で取得したトークンを指定します。

本サンプルシナリオ変数一覧2

Step 6. 動作に必要な変数を設定3 (任意)

プロキシ を使用している場合に設定が必要な変数は下記の通りです。

• プロキシ
  • プロキシを使用している場合は設定します。使用していない場合は空欄のままとします。
    
    
• プロキシユーザ
  • プロキシを使用していて且つ、認証が必要な場合はプロキシのユーザとパスワードを指定します。

当該変数の値を設定した場合は、本サンプルシナリオ内で実行する curlコマンドラインに プロキシ指定オプション（-x および -U）が反映されます。
curl コマンドラインについては、API を実行するためのcurl コマンドラインに記載しています。

本サンプルシナリオ変数一覧3

Step 7. 動作に必要な変数を設定4 (任意)

楽楽明細 の API を呼び出す際に必要な設定値を指定します。

• param_帳票種別ID
  • "Step 1" で登録した帳票の帳票種別IDを指定します。
    楽楽明細「管理画面」の "基本設定 > 帳票の設定 > 帳票の詳細" にて確認できます。
    
    
• param_取込方法
  • 帳票データを新規に発行する場合は「1」、差し替える場合は「0」を指定します。

本サンプルシナリオ変数一覧4

Step 8. WinActorで本サンプルシナリオを実行

本サンプルシナリオを実行します。帳票データ（入力ファイル）を楽楽明細に登録すると、本サンプルシナリオは終了します。

curl コマンドライン確認方法にて、本サンプルシナリオ内で実行される curl コマンドライン の確認方法を記載しています。
また、curlコマンドの実行結果は curlコマンド実行結果ファイルに出力されます。
curlコマンド実行結果ファイルは、WinActor の変数「cmd_curl実行結果ファイル」で指定したファイル名で生成され、WinActor の変数「対象CSVファイルパス」で指定したファイルと同じフォルダに出力されます。

Step 9. サンプルシナリオ終了後

サンプルシナリオ終了後は登録結果について以下の画面上から確認を行います。
登録結果確認画面 ： 帳票データ取込一覧 > 取込履歴

取込履歴画面

トラブルシューティング

帳票データを登録出来ない場合、以下を確認してください。

サンプルシナリオ解説

本サンプルシナリオで使用している実装テクニックについて説明します。

入力ファイルについて

本サンプルシナリオで使用する入力ファイルについて記載します。
Step 1. 楽楽明細で事前設定を行うにて設定した形式に合わせて、CSVファイルを作成します。
具体例を下記に示します。

帳票CSVの取込フォーマット設定

API を実行するためのcurl コマンドライン

本サンプルシナリオでは、楽楽明細 API 連携機能の API 仕様に従って curl コマンドを実行しています。
具体的には下記のようなコマンドラインをシナリオ内で生成しています。

-----------
C:\Windows\System32\curl.exe -Ss
　-F "json=<apiconf.json;type=application/json"
　-F "files[0]=@input.csv;type=text/csv"
　-H "X-WB-apitoken:<API token>"
　-o response.json
　https://*****.eco-serv.jp/ACCOUNT/api/v1/reports/imports > cmd_curl実行結果.log 2>&1
-----------

なお、上記の太字は WinActor の変数で設定されています。

curl コマンドライン確認方法

本サンプルシナリオでは、 curl コマンドラインを WinActor の「ログ出力」画面に出力しており、curl コマンドラインが想定どおりに生成されているか確認できます。
また、curl コマンドは下図で示すノード （メイン処理 > 楽楽API 実行 (curl) > コマンドを実行する(PowerShell,コマンドプロンプト)） で実行されます。
当該のノードを「実行抑止」すると、楽楽明細 API を実行せずに curl コマンドラインを確認できます。

curlコマンド実行ノード

API の multipart/form-data(JSON部)をカスタマイズ

本サンプルシナリオ内の「API設定(JSON)生成」グループでは、API の multipart/form-data (JSON部) を生成しています。
「JSON変数 新規オブジェクト」および「JSON変数 要素追加」ライブラリで JSON のデータを生成し、「JSON」変数 ファイル保存」ライブラリで apiconf.json に保存しています。
apiconf.json は curl コマンド実行時に multipart/form-data (JSON部) を指定するための JSONファイルです。

「JSON変数 要素追加」 では下記の要素を設定しています。
　isNewIssues 帳票の新規発行/差替発行
　reportTypeId 帳票種別ID

「JSON変数 要素追加」 を追加すれば上記以外の任意要素を追加できます。

JSON変数設定ノード