by CData Software Japan | September 09, 2021

freee 人事労務 API をドライバー化:各種ツールから接続してみた

f:id:sugimomoto:20210908171036p:plain

こんにちは。CData Software Japanリードエンジニアの杉本です。

本記事では、各種 Web APIODBC / JDBC / ADO.NET といった標準のDB接続規格でアクセスできるようにするCData API Driverを用いて、freee 人事労務API を各種ツールから接続する方法を紹介します。

ExcelAccess・Power BIなどのエンドユーザーが利用するUIベースのツールはもちろん、Visual StduioやEclipseといった開発ツールからも接続することが可能です。

対象 API

freee 人事労務 とは freee株式会社が提供する 中小企業の人事労務管理のためのクラウド型ソフトウェアです。

www.freee.co.jp

f:id:sugimomoto:20210908171042p:plain

freee 人事労務では、freee 人事労務 と同様にAPIが提供されており、タイムレコーダーの情報や、給与明細、勤怠データの操作ができるようになっています。

developer.freee.co.jp

f:id:sugimomoto:20210908171051p:plain

今回はこのAPIを用いて様々なツールとの連携を実現します。

実現イメージ

この記事では freee 人事労務 APIに対してBIやETL/EAIなど、様々なツールから接続します。しかしながら、各APIは単純にツールと接続・連携することはできません。

各ツールがどのようにWeb API側へリクエストを投げるべきかの判断材料や各種認証方法の処理、メタデータの情報等が無いためです。そのためには基本的にカスタムコネクタを作るか、プログラムを組まなければいけません。

f:id:sugimomoto:20210908171057p:plain

そこで、CData API Driver を用いて、このボトルネックを解決します。

まず、各ツールからはODBCJDBCインタフェースでSQL(Select文)をCData API Driverに向けて発行してもらいます。そのリクエストを受け取った CData API Driverは、freee 人事労務API のエンドポイントに対して、SQL文を解釈し、HTTPリクエスト発行します。

リクエスト後、JSONフォーマットで返ってきたデータをCData API Driverが各種インタフェースフォーマットにデータを変換してツールに返します。

f:id:sugimomoto:20210908171102p:plain

これにより、各種ツールからアドホックSQLによるリクエストがあったタイミングで最新のデータをfreee 人事労務 API から取得することが可能となります。

各種接続シナリオと必要なツール

CData API Driver は様々なツールとの接続に利用できますが、今回は以下のツールを用いて接続する方法を解説していきます。

なお、CData API Driverは上記以外にも様々なツールと連携することが可能です。

www.cdata.com

f:id:sugimomoto:20201120133303p:plain

テーブル(ビュー)一覧

CData API Drvier で freee 人事労務 APIに接続するためには専用の設定ファイル(Profile)が必要になります。

freee 人事労務 API Profile では、以下のテーブル(ビュー)を提供しています。用途に合わせて、接続してみてください。

Name Resource API Reference
BounsesEmployeePayrollStatements 指定した事業所に所属する従業員の賞与明細の取得 Link
EmployeeDetails 指定したIDの従業員の取得 Link
EmployeeGroupMemberships 指定した事業所の指定日付時点における所属情報の取得 Link
Employees 従業員一覧の取得 Link
SalariesEmployeePayrollStatements 給与明細一覧の取得 Link
TimeClocks 打刻情報の一覧取得 Link
UsersMe ログインユーザの取得 Link
WorkRecords 指定した従業員・日付の勤怠情報の取得 Link
WorkRecordSummaries 指定した従業員、月の勤怠情報のサマリの取得 Link

freee 人事労務 API 利用準備

最初にfreee 人事労務APIを利用するために、freee 人事労務側でアプリケーション登録を行います。

詳しくは以下の記事を参照してみてください。

https://developer.freee.co.jp/tutorials/starting-api

アプリを作成したら、コールバックURLを設定しましょう。

コールバックURLはドライバーの場合だと「http://localhost:33333」、CData Sync の場合は「http://localhost:8019/src/oauthCallback.rst」を指定します。

f:id:sugimomoto:20210813162341p:plain

権限は上記テーブルの一覧から、利用する機能に併せて設定してください。

f:id:sugimomoto:20210813162406p:plain

設定後、ClientId・Client Secretを控えておきます。

API データ処理用 設定ファイルを作成

続いて、freee 人事労務API を CData API Deiver が解釈できるように設定ファイル(API Profile)を作成します。

すでに私が作成したものがあるので、以下のURLからダウンロードしてください。

https://cdatajbuilds.s3.ap-northeast-1.amazonaws.com/APIProfiles/FreeeHR.apip

保存先フォルダは後ほど使用するので「C:\APIProfiles\FreeeHR.apip」といったツールからアクセスが可能な任意のフォルダに配置してください。

CData API Driver のインストール

各種ツールとfreee 人事労務 API を繋ぐために必要となるCData API Driverをインストールします。

基本的なインストール・設定方法は各種Driver共通ですので、ここではODBC Driverを例に説明します。

まず、CData API ODBC Driverの30日間の評価版をダウンロードします。ダウンロードの際には、Emailの登録が必要となります。

www.cdata.com

f:id:sugimomoto:20201027111336p:plain

ダウンロードしたsetup.exeファイルをBIツールがインストールされているマシンにインストールします。インストールウィザードに従い、EULAを確認した上でインストールを完了します。

f:id:sugimomoto:20201027111341p:plain

※途中、ライセンスサーバーへのオンラインアクティベーションが行われるためネットワーク環境に接続されている必要があります。

インストールが完了すると、ODBCのDSN設定のウィンドウが立ち上がります。

以下の項目をセットし、「接続のテスト」をクリックします。

プロパティ名 備考
Profile C:\APIProfiles\FreeeHR.apip 予めダウンロードしたfreee 人事労務 .apipのパスを指定します。
ProfileSettings CompanyId=XXXXX; 接続先となるCompanyIdを指定します。
Auth Scheme OAuth
Initiate OAuth GETANDREFRESH
OAuth Client Id 例)3cdebb30b42c77a56970f6e58740 登録したアプリのClient IDを指定します。
OAuth Client Secret 例)a931e9558edb8020c003074523512 登録したアプリのClient Secret を指定します。
Callback URL http://localhost:33333 Redirect URL を指定します。

f:id:sugimomoto:20210908171115p:plain

入力後「接続のテスト」をクリックすると、ブラウザが立ち上がり、freee へのログインおよび認可が求められます。

設定されている情報を確認し「許可する」をクリックしましょう。

f:id:sugimomoto:20210813162419p:plain

これで CData API Driver から freee API への接続が完了します。

f:id:sugimomoto:20210813162426p:plain

それでは実際に各種ツールからの接続方法を解説していきましょう。

Excel から freee 人事労務 API に接続(Excel Add-in for API

CData Excel Add-in for API をインストール後、Excelを立ち上げるとCDataタブが追加されていることがわかります。このタブから各種操作を実施します。

接続を開始するには、CDataタブから[取得元 API]をクリックします。

f:id:sugimomoto:20201116171024p:plain

最初に接続するためのウィザードが表示されるので、「CData API Driverのインストール」の内容と同様に各種パラメータを入力します。

f:id:sugimomoto:20210908171120p:plain

接続後、対象テーブルを選択し、クエリを編集の上、「OK」をクリックします。

f:id:sugimomoto:20210908171124p:plain

f:id:sugimomoto:20210908171129p:plain

クリック後、対象のデータが一括で取得できます。

f:id:sugimomoto:20210908171133p:plain

Access リンクテーブル から freee 人事労務 API に接続(CData API ODBC Driver)

次はCData ODBC Driverを利用して、Access リンクテーブルから接続してみたいと思います。

あらかじめ新規にAccessを立ち上げて、空のデータベースを作成しておきましょう。

続いて「外部データ」タブから「新しいデータ ソース」→「他のソースから」→「ODBC データベース」を選択します。

f:id:sugimomoto:20210813162454p:plain

ウィザードが表示されるので「リンクテーブルを作成」を選択し、「OK」をクリックします。

f:id:sugimomoto:20210813162459p:plain

データソースの選択では「コンピューターデータソース」から事前に作成したCData API Driver用DSNを選択し「OK」をクリック

f:id:sugimomoto:20210908171217p:plain

テーブルの一覧が表示されるので、任意のテーブルを選択し「OK」をクリックします。

f:id:sugimomoto:20210908171221p:plain

設定後、リンクテーブルが追加され、以下のようにfreee 人事労務のデータを閲覧することができるようになります。もちろん、通常通りクエリデザイナーでも使用可能です。

f:id:sugimomoto:20210908171225p:plain

PowerBI から freee 人事労務 API に接続(CData API Driver for Power BI)

最後にCData Power BI API Connector を用いて、Power BIからfreee 人事労務の商品データを取得します。

PowerBI Desktopを起動して、「データを取得」をクリックします。

f:id:sugimomoto:20201027111449p:plain

データ接続先一覧の中から「CData API」を選択し、「接続」をクリックします。

f:id:sugimomoto:20201027111519p:plain

データソース名は先程登録したfreee 人事労務のDSNを入力し「OK」をクリックします。

f:id:sugimomoto:20210908171231p:plain

テーブルの一覧から対象となるテーブルを選択し「読み込み」をクリックします。

f:id:sugimomoto:20210908171236p:plain

以下のようにfreee 人事労務のデータを読み込みことができます。

f:id:sugimomoto:20210908171240p:plain

あとはPoewr BIの機能を用いて、ビジュアライズに利用することができます。

f:id:sugimomoto:20210908171245p:plain

ASTERIA Warp から freee 人事労務 API に接続(CData JDBC API Driver)

ASTERIA Warpでは、フローデザイナーを使って、データ処理のプロセスを作成します。

フローデザイナーの基本的な利用方法についてはWarpフローデザイナー操作ガイドをご覧ください。

CData JDBC API Driver はインストール後、「cdata.jdbc.api.jar」と「cdata.jdbc.api.lic」のファイルをAsteriaのドライバーフォルダ(asteriahome5\system\lib\drivers)に登録します。

f:id:sugimomoto:20210218152238p:plain

その後、ASTERIA Warpを立ち上げて、フローデザイナーにアクセスし、CData JDBC Driverを使用するために接続を追加します。

画面左のコネクションペイン上にある電源ボタンをクリックをクリックすると、「コネクションの作成」ダイアログが表示されます。

f:id:sugimomoto:20210216154030p:plain

「接続種別」として「RDB」を選択、「名前」に分かりやすい名前を設定し「OK」をクリックします。

f:id:sugimomoto:20210908171251p:plain

作成したコネクションをダブルクリックすると、画面右のインスペクタに接続プロパティが表示されます。 「基本」タブでドライバーのパスとURLをそれぞれ設定します。

プロパティ名 備考
ドライバーのパス 例)C:\asteriahome5\system\lib\drivers\cdata.jdbc.api.jar 前節でインストールした API JDBC Driverファイルへの参照を指定します。
URL jdbc:api:Profile=C:\Publish\lib\v21\APIProfiles\FreeeHR.apip;
ProfileSettings="CompanyId=XXX";
AuthScheme=OAuth;
InitiateOAuth=GETANDREFRESH;
OAuthClientId=XXXX;OAuthClientSecret=XXXXX;
callbackurl=http://localhost:33333;

f:id:sugimomoto:20210908171257p:plain

構成後、「接続のテスト」を実行して、成功すればOKです。

f:id:sugimomoto:20210813162555p:plain

これでコネクションの作成は完了です。あとは、フロー上でデータベースタブにある「RDBGet」のコンポーネントを使って、データの取得が行なえます。

「RDBGet」フローに配置し、ダブルクリックします。

f:id:sugimomoto:20210216180653p:plain

コネクションの選択ウインドウが表示されるので、先程作成したfreee 人事労務のコネクションを選択しましょう。

f:id:sugimomoto:20210908171302p:plain

その後、SQLビルダーが表示されるので、取得したいデータが格納されている、任意のテーブルとカラムを選択します。

f:id:sugimomoto:20210908171306p:plain

あとは、「モデルにSQLを適用する」をクリックし「SELECTテスト」でデータが正常に取得できているかを確認します。

以下のようにデータが参照できれいればOKです。設定を保存してSQLビルダーを閉じます。

f:id:sugimomoto:20210908171311p:plain

あとは Asteria Warp の機能で様々なサービスと freee のデータの連携を実現できます。

CData Sync から freee 人事労務 に接続

www.cdata.com

CData Sync ではデータソースとして、freee 人事労務に接続することができます。

なお、CData Sync Windows版の場合は「freeeHR.apip」のプロファイルをSyncの本体が存在するフォルダの「www\app_data\profiles」に配置してください。profilesフォルダが存在しない場合は手動で作成してください。

C:\ProgramData\CData\sync\profiles

Cross-Platform版の組み込みJettyで構成している場合は、以下のフォルダにapipファイルを配置します。

/opt/sync/profiles

配置後、CDataSyncを起動すると以下のようにデータソースとして freee 人事労務が利用できるようになります。

f:id:sugimomoto:20210908171317p:plain

また、接続する前にコールバックURLに「http://localhost:8019/src/oauthCallback.rst」を指定しておきましょう。

f:id:sugimomoto:20210813162659p:plain

接続プロパティは以下の通り設定します。

プロパティ名 備考
Other ComapnyIdy=XXXXX;
OAuth Client Id 例)3cdebb30b42c77a56970f6e58740 登録したアプリのClient IDを指定します。
OAuth Client Secret 例)a931e9558edb8020c003074523512 登録したアプリのClient Secret を指定し
Auth Scheme OAuth Advancedタブの項目です。

入力後、「接続」ボタンをクリックし、接続テストが完了すればOKです。

f:id:sugimomoto:20210908171323p:plain

併せて、任意の同期先の接続情報も構成しておきましょう。

f:id:sugimomoto:20210311162106p:plain

接続完了後、新しくジョブを作成します。

f:id:sugimomoto:20210311162114p:plain

先程作成した freee 人事労務 のコネクションを選択します。

f:id:sugimomoto:20210908171328p:plain

ジョブを作成した後は、freee 人事労務 の同期対象となる任意のテーブルを選択しましょう。

f:id:sugimomoto:20210908171332p:plain

データのプレビュー画面で、実際に取得が成功しているかどうかを確認できました。

f:id:sugimomoto:20210908171337p:plain

あとは、任意のスケジュールを指定してデータのレプリケーションを実行できます。

f:id:sugimomoto:20210311162149p:plain

試しに手動で実行してみると、それぞれのレプリケーション件数が結果として表示されます。

f:id:sugimomoto:20210908171342p:plain

RDBの中でもレプリケーションされたデータが確認できました。

f:id:sugimomoto:20210908171347p:plain

終わりに

これら以外にもCData API Driverは各種ETLツールや帳票ツールなどからも接続することが可能です。

以下のCData オンラインナレッジベースには、各種ツールからの接続方法を紹介した記事が多数掲載されているので、是非見てみてください。

https://www.cdata.com/jp/kb/

不明な点があれば、テクニカルサポートまでお気軽にどうぞ!

https://www.cdata.com/jp/support/submit.aspx