ノーコードでクラウド上のデータとの連携を実現。
詳細はこちら →
CData Arc を使ってfreee の仕訳帳データを自動連携する
こんにちは。CData Software Japanの色川です。
クラウド会計ソフトの中でもfreee 会計は人気ですね。freee 会計では初期からAPI が提供されており、CData ではAPI Driver で使えるfreee 会計用のAPI Profile を提供しています。
ただ、現在提供しているfreee 会計向けのAPI Profile では、仕訳帳のダウンロードなど一部のAPI にはまだ対応していません。仕訳帳API は非同期でのダウンロード要求・実行が必要、かつCSV 形式での取得となり、他のfreee 会計API とはスタイルが少し異なるAPI です。
この記事では、CData Arc を使って、freee 会計から仕訳帳データのダウンロードを自動化する方法をご紹介します。
- freee 会計とは
- CData Arc とは？
- この記事のシナリオ
- 必要なものと準備
- freee 会計から仕訳帳データをダウンロードして、SQL Server に登録する
- 連携フローの実行と確認
- シナリオの自動実行
- この記事で作成したフロー（テンプレート）の入手
- おわりに
freee 会計とは
freee 会計は、めんどうな経理作業を楽にするクラウド会計ソフトです。
freee 会計では製品リリースの初期から API が提供されており、CData ではAPI Driver で使えるfreee 会計用のAPI Profile を提供しています。
CData Arc とは？
ファイル転送（MFT）とSaaSデータ連携をノーコードで実現できるデータ連携ツールです。ファイル・データベース・SaaS API、オンプレミスやクラウドにある様々なデータをノーコードでつなぐ事ができます。
この記事のシナリオ
この記事では「freee 会計から仕訳帳データをダウンロードして、SQL Server に連携する」シナリオを作成します。
この記事では、SQL Server を例にしていますが、仕訳帳データを活用したい場面は色々あるかと思います。CData Arc を利用すれば、CSV でダウンロードしたデータの変換や加工もスピーディに実現できます。
必要なものと準備
CData Arc は30日間フル機能を利用できるトライアルライセンスが提供されています。ぜひお手元で試してみてください。
製品のインストール等はこちらの記事を参考にしてください。
freee API 利用準備
OAuth アプリケーションの登録
この記事では、事業所にはfreee で用意してくれている開発用テスト事業所を利用します。freee API を利用するには、事前にOAuth アプリケーションの登録が必要です。こちらのチュートリアルを参考に進めてください。
コールバックURL には [CData Arc のWebConsole のURL]/src/oauthCallback.rst を指定します。この記事の環境では、http://localhost:8001/src/oauthCallback.rst と指定しています。
アプリケーションを作成したら、コールバックURL/Client ID/Client Secret/Webアプリ認証用URL をそれぞれ控えておいてください。連携フローの中で認証設定に利用します。
また、この記事では仕訳帳データを参照しますので 権限設定 として [会計] 仕訳帳 への許可（チェック）が必要です。
事業所ID の取得
freee 会計では多くのAPI で事業所ID (company_id) が必須となっており、この記事で利用する仕訳帳API でも必要です。スタートガイドの案内にそって、事業所ID を取得して控えておいてください。
SQL Server の準備
この記事では、シナリオの流れを分かりやすくするために、仕訳ファイル（汎用CSV 形式） と同じ構成のテーブルを用意しました。
CData Arc の基本的な使い方
CData Arc の起動方法や基本的なフローの作り方についてはこちらをご覧ください。
それでは実際に連携フローを作成していきます。
freee 会計から仕訳帳データをダウンロードして、SQL Server に登録する
freee 会計のAPI から仕訳帳データをダウンロードするには「ダウンロード要求」「ステータス確認」「ダウンロード実行」の一連の流れが必要です。ダウンロード要求が受け付けられてからダウンロード準備完了となるまで非同期のため、freee 側で準備している間の待機や準備が完了してダウンロードできるようになったかの判断なども必要です。そのため、この記事のシナリオは少し長めですが、それぞれのコネクタが実施していることはシンプルで、シンプルに設定されたコネクタの組合せで実現することができます。
このシナリオで作成する連携フローは以下のような流れになっています。
| コネクタ | 内容 | |
|---|---|---|
| 1 | REST (journals) | ダウンロード要求API を実行 |
| 2 | Script | 1．のレスポンスから、受け付けID と status_url を取得してメッセージヘッダに設定 |
| 3 | Schedule | 一定時間待機（この記事では1分） |
| 4 | REST (status) | 2. で取得した情報を利用して ステータス確認API を実行 |
| 5 | JSON | 4. のレスポンス（json）をXML 形式に変換 |
| 6 | Branch | 5. のXMLからダウンロードステータスが準備完了（uploaded）を判断（準備中なら3 へ） |
| 7 | Script | 5．のXMLからdownload_url を取得してメッセージヘッダに設定 |
| 8 | REST (download) | 7. で取得した情報を利用して ダウンロード実行 API を実行 |
| 9 | Script | ダウンロードしたCSV (Shift-JIS) をUTF-8 に変換 |
| 10 | CSV Map | 9 で変換したCSV と 11 をマッピング |
| 11 | SQL Server | SQL Server に登録（Upsert） |
1. REST (journals)
最初にフローの起点となる ダウンロード要求API を実行するために、REST コネクタを設定します。コアカテゴリから「REST コネクタ」を選択し、フローキャンバスへ配置します。
コネクタを選択して、プロパティを設定していきます。メソッドは「GET」。URL には ダウンロード要求API を指定します。この記事では、download_type には generic(freee Webからダウンロードできるものと同じ) を指定します。
https://api.freee.co.jp/api/1/journals?download_type=generic&company_id=`事前準備で取得した事業所ID`
認証は以下のように設定します。
| プロパティ | 設定値 |
|---|---|
| 認可タイプ | OAuth 2.0 |
| グラントの種別 | Authorization Code |
| コールバックURL | 事前準備で指定したコールバックURL |
| 認証URL | 事前準備で指定したWebアプリ認証用URL |
| アクセストークンURL | https://accounts.secure.freee.co.jp/public_api/token |
| クライアントID | 事前準備で指定したClient ID |
| クライアントシークレット | 事前準備で指定したClient Secret |
新しいアクセストークンを取得 で、アプリ連携の開始を許可します。
変更を保存 でコネクタ設定を保存します。アウトプットタブから受信を実行して、リクエストの成功とレスポンスを確認します。
2. Script
CData Arcは、「メッセージ」という概念を利用して、自動化されたフローを通過するデータが定義されます。メッセージは、主にファイルペイロードデータ（CData Arcが処理しているデータ）とメタデータ（CData Arcがアプリケーションを通過するデータの流れを追跡するために使用する情報）で構成されます。CData Arc でのメッセージの仕組みは以下のドキュメントも参考にしてください。
ここでは「ダウンロード要求API のレスポンス」に含まれる受け付けID と status_url（当該の受け付けID のステータス確認エンドポイント） を取得し、メタデータ（カスタムのメッセージヘッダ）として設定します。これは後続のコネクタで扱いやすいようにするためです。
コアカテゴリから「Script コネクタ」を選択し、フローキャンバスへ配置します。
コネクタを選択して、スクリプト欄へ以下のように追記します。
<arc:set attr="json.uri" value="[Filepath]" /> <arc:set attr="json.map:status_url" value="/json/journals/status_url" /> <arc:set attr="json.map:id" value="/json/journals/id" /> <arc:call op="jsonDomGet" in="json" out="result"> <arc:set attr="output.header:status_url" value="[result.status_url]" /> <arc:set attr="output.header:id" value="[result.id]" /> </arc:call> <arc:push item="output" />
ここでは、CData Arc の中で柔軟に使えるArcScript を利用して、入力ファイル（ダウンロード要求API のレスポンス）から受け付けID と status_url の値を取得して、追加のメッセージヘッダとして設定しています。入力ファイルはそのまま次のコネクタへの出力としてPush しています。ArcScript やJSON ドキュメントからの値取得で利用しているjsonDOMGet オペレーションについてはこちらのドキュメントもご覧ください。
3. Schedule
ダウンロードを要求してから、freee 側で準備完了となるまで一定の時間が必要です。ここではフローの流れを一定時間待機するために使える Schedule コネクタを設定します。
コアカテゴリから「Schedule コネクタ」を選択し、フローキャンバスへ配置します。
コネクタを選択して、プロパティを設定していきます。ここでは1分待機するように設定します。送信間隔を「Minute」に。分を「1」に設定します。
4. REST (state)
次にダウンロード要求の状態を確認します。2. で取得した情報を利用して ステータス確認API を実行するために、REST コネクタを設定します。コアカテゴリから「REST コネクタ」を選択し、フローキャンバスへ配置します。
コネクタを選択して、プロパティを設定していきます。メソッドは「GET」。URL には、2. で取得した情報を利用して以下のように設定します。
[_message.header:status_url]?company_id=`事前準備で取得した事業所ID`&id=[_message.header:id]
認証は1.と同じ流れで設定してください。
このコネクタでは、先ほどのようにURL にArcScript を利用するため、Advanced タブの高度な設定から「URL 内のArcScript を許可」します。
ここまでの流れを確認するために、1-4 のフローをつないで、ワークスペースを保存します。
- のアウトプットタブから受信を実行します。
おおよそ1分後に、4. のアウトプットタブでステータス確認API のレスポンスが得られていることを確認します。
続いて、ステータス状況を判断し、準備完了ならダウンロード実行へ。準備中なら 3. で待機した後に再びステータス確認へと進むようにフローを作っていきます。
5. JSON
まずは、この後のコネクタで扱いやすくするように、4. で得るステータス確認のレスポンスをJSON コネクタでXML に変換します。コアカテゴリから「JSON コネクタ」を選択し、フローキャンバスへ配置します。
プロパティは特に変更せず、デフォルトのままで利用します。
6. Branch
次に、5. でXML 変換したステータス確認API のレスポンスから、ダウンロードステータスが準備完了（uploaded）かを判断して、状態によって分岐します。フローを判断分岐するにはBranch コネクタを利用します。コアカテゴリから「Branch コネクタ」を選択し、フローキャンバスへ配置します。
コネクタを選択して、プロパティを設定していきます。以下のように設定します。
| プロパティ | 設定値 |
|---|---|
| マッチするタイプ | XPath |
| データ型 | String |
| XPath | /Items/journals/status |
| 演算子 | Equals |
| マッチする値 | uploaded |
これで、ステータス確認API のレスポンスでstatus がuploaded（準備完了）なら青いフローへ。そうでなければグレーのフローへ流れます。準備完了でない場合（準備中）なら、3. で待機した後に再びステータス確認へと進むように繋げます。
7. Script
ここでは「準備完了時、ステータス要求API のレスポンス」に含まれる download_url（当該の受け付けID のダウンロード実行エンドポイント） を取得し、メタデータ（カスタムのメッセージヘッダ）として設定します。これは後続のコネクタで扱いやすいようにするためです。
5. でXML 変換したステータス要求API のレスポンス
コアカテゴリから「Script コネクタ」を選択し、フローキャンバスへ配置します。
コネクタを選択して、スクリプト欄へ以下のように追記します。
<arc:set attr="xml.uri" value="[FilePath]" /> <arc:set attr="xml.map:download_url" value="/Items/journals/download_url"/> <arc:call op="xmlDOMGet" in="xml" out="result"> <arc:set attr="output.header:download_url" value="[result.download_url]" /> </arc:call> <arc:push item="output" />
ここでは、CData Arc の中で柔軟に使えるArcScript を利用して、入力ファイル（5. でXML 変換したステータス要求API のレスポンス）から download_url の値を取得して、追加のメッセージヘッダとして設定しています。入力ファイルはそのまま次のコネクタへの出力としてPush しています。ArcScript やJSON ドキュメントからの値取得で利用しているxmlDOMGet オペレーションについてはこちらのドキュメントもご覧ください。
8. REST (download)
ここまでの流れでダウンロード準備完了が確認できていますので、7. で取得した情報を利用して ダウンロード実行 API を実行するために、REST コネクタを設定します。コアカテゴリから「REST コネクタ」を選択し、フローキャンバスへ配置します。
コネクタを選択して、プロパティを設定していきます。メソッドは「GET」。URL には、2. で取得した情報を利用して以下のように設定します。
[_message.header:download_url]?id=[_message.header:id]&company_id=`事前準備で取得した事業所ID`
認証は1.と同じ流れで設定してください。
このコネクタでも、URL にArcScript を利用するため、Advanced タブの高度な設定から「URL 内のArcScript を許可」します。
ここまでのフローをつなぐと、仕訳帳のダウンロード要求からダウンロード実行までの流れが出来上がります。
- のアウトプットタブから受信を実行します。一定の時間を経たのちに、8. のアウトプットタブで仕訳帳データのCSV がダウンロードされていることを確認します。
ここまでの流れで、freee 会計から仕訳帳データのダウンロードを自動化することができました。続いて、CSV を読み込んでSQL Server に連携するフローを作っていきます。
9. Script
CData Arc の内部ではデータをUTF-8 で扱います。仕訳帳のダウンロードで得られるCSV はShift-JIS のため、最初にUTF-8 に変換します。コアカテゴリから「Script コネクタ」を選択し、フローキャンバスへ配置します。
コネクタを選択して、スクリプト欄へ以下のように追記します。
<arc:set attr="file.file" value="[FilePath]" /> <arc:set attr="file.encoding" value="Shift-JIS" /> <arc:call op="fileRead" in="file" out="out"> <arc:set attr="fileOut.data" value="[out.file:data]" /> </arc:call> <arc:check attr="fileOut.data"> <arc:set attr="fileOut.filename" value="[FileName]" /> <rsb:set attr="fileOut.encoding" value="UTF-8" /> <arc:push item="fileOut" /> <arc:else> <arc:throw code="NoData" desc="No File Data."/> </arc:else> </arc:check>
ここでは、CData Arc の中で柔軟に使えるArcScript を利用して、入力ファイル（仕訳帳のダウンロードCSV）をShift-JIS で読み込んで、UTF-8 で書き出しています。
ここまでのフローをつないだら、仕訳帳の取得からSQL Server へのマッピング手前までの流れが出来上がります。
- のアウトプットタブから受信を実行します。一定の時間を経たのちに、9. のアウトプットタブで仕訳帳がUTF-8 のCSV データとして取得できることを確認します。
（10 の前に）11. SQL Server
次にフローの終点となるSQL Server コネクタを配置し「SQL Server の仕訳帳テーブルを更新する設定」をします。Database カテゴリから「SQL Server コネクタ」を選択し、フローキャンバスへ配置します。
Connection でSQL Server の接続情報を設定します。「Test Connectoin」で接続の確認ができます。
Action は「Upsert」。対象に「仕訳帳」テーブルを選択します。
10. CSV Map
最後にCSV ファイルの情報を、SQL Server コネクタにマッピングします。
コアカテゴリから「CSV Map」コネクタを配置します。9.のScript コネクタと 11.のSQL Serer コネクタをつなぎ、ワークスペースを保存します。これでスキーマが設定されているSQL Server コネクタ側の構成がCSV Map に伝わります。
コネクタの設定で、ソースファイルに、9. のアウトプットタブで得られたCSV ファイルをアップロードしてソースのスキーマを設定した後、マッピングを設定します。このシナリオでは同名項目をシンプルにマッピングしています。
これで「freee 会計から仕訳帳データをダウンロードして、SQL Server に連携する」シナリオが出来あがりました。
連携フローの実行と確認
起点となるREST コネクタからフローを実行してみます。アウトプットタブから「受信」を実行します。
一定時間の後、フローの終点となるSQL Server コネクタのインプットタブの結果を確認します。実行されていれば成功です。
SQL Server の仕訳帳テーブルに連携されていることが確認できます。
シナリオの自動実行
CData Arc ではフローを定期実行するスケジューラ機能を持っています。今回のシナリオであれば、フローの起点となるREST コネクタの「オートメーション」タブで設定することができます。1時間に1度、毎時0分に定期実行する場合は、このように設定します。
この記事で作成したフロー（テンプレート）の入手
この記事で作成したフローについては、こちら からテンプレートとして使える arcflow がダウンロードできます。
ダウンロードしたarcflow は ワークスペースをインポート から登録できます。こちらのテンプレートの内、各REST コネクタでのfreee の接続情報やSQL Server コネクタで利用する接続情報を、お使いの環境に併せて編集して、ぜひ試してみてください。
おわりに
この記事のようなシナリオは、Web API もファイルもDB アクセスも、いずれも上手く扱える必要があります。
CData Arc はシンプルで拡張性の高いコアフレームワークに、豊富なMFT・EDI・エンタープライズコネクタを備えたパワフルな製品です。CData Drivers との組み合わせで250を超えるアプリケーションへの連携を実現できます。必要な連携を低価格からはじめられる事も大きな特長です。
皆さんのつなぎたいシナリオでぜひ CData Arc を試してみてください。
お試しいただく中で何かご不明な点があれば、テクニカルサポートへお気軽にお問い合わせください。
この記事では CData Arc™ 2021 - 21.0.8054 を利用しています。