こんにちは。CData Software Japanリードエンジニアの杉本です。
本記事では、各種 Web API を ODBC / JDBC / ADO.NET といった標準のDB接続規格でアクセスできるようにするCData API Driverを用いて、SmartHR の API を各種ツールから接続する方法を紹介します。
ExcelやAccess・Power BIなどのエンドユーザーが利用するUIベースのツールやAsteriaなどのETLツールはもちろん、Visual StduioやEclipseといった開発ツールからも接続することが可能です。
SmartHR とは？
雇用契約や入社手続きがペーパーレスで完結できるクラウドベースの労務管理サービスです。
外部サービスと連携するためのAPIも充実しており、従業員情報から、部署・役職・事業所といった各種マスタデータまで幅広いデータの取得・登録・更新が可能です。
https://developer.smarthr.jp/api/index.html
実現イメージ
この記事では SmartHR APIに対してExcelやPower BIといった各種ツールやIDEからの接続方法を紹介します。しかしながら、各APIは単純にツールと接続・連携することはできません。
各ツールがどのようにWeb API側へリクエストを投げるべきかの判断材料や各種認証方法の処理、メタデータの情報等が無いためです。そのためには基本的にカスタムコネクタを作るか、プログラムを組まなければいけません。
そこで、CData API Driver を用いて、このボトルネックを解決します。
まず、各ツールからはODBCやJDBCインタフェースでSQL（Select文）をCData API Driverに向けて発行してもらいます。そのリクエストを受け取った CData API Driverは、SmartHR の API のエンドポイントに対して、SQL文を解釈し、HTTPリクエスト発行します。
リクエスト後、JSONフォーマットで返ってきたデータをCData API Driverが各種インタフェースフォーマットにデータを変換してツールに返します。
これにより、各種ツールからアドホックにSQLによるリクエストがあったタイミングで最新のデータをSmartHR API から取得することが可能となります。
各種接続シナリオと必要なツール
CData API Driver は様々なツールとの接続に利用できますが、今回は以下のツールを用いて接続する方法を解説していきます。
- Excel（Excel-addin で利用）
- Access（ODBC 接続で利用）
- PowerBI （Power BI Connector 接続で利用）
- ASTERIA Warp（JDBC Driver 接続で利用）
上記以外のツールからの接続に関しては、以下のページで各種接続方法記事を公開しています。
テーブル（ビュー）一覧
SmartHR API Profileでは、以下のテーブル（ビュー）を提供しています。用途に合わせて、接続してみてください。
| テーブル名 | 対応API | 備考 |
|---|---|---|
| BankAccountSettings | 口座情報 | |
| BizEstablishments | 事業所 | |
| CrewCustomFieldTemplateGroups | 従業員カスタム項目グループ | |
| CrewCustomFieldTemplates | 従業員カスタム項目テンプレート | |
| CrewInputForms | 従業員情報収集フォーム情報 | |
| Crews | 従業員 | |
| CrewsBankAccounts | 従業員- 口座情報 | |
| CrewsCustomFields | 従業員 - カスタムフィールド | |
| CrewsDepartments | 従業員- 部署 | |
| CrewsProfileImages | 従業員- プロフィール画像 | |
| Departments | 部署 | |
| DependentRelations | 続柄 | |
| Dependents | 家族情報 | データを取得する場合、Where句でCrewIdを指定する必要があります。 |
| EmploymentTypes | 雇用形態 | |
| JobTitles | 役職 | |
| MailFormats | メールフォーマット | |
| PaymentPeriods | 給与支給形態 | |
| Users | ユーザ |
SmartHR API 利用準備
最初にSmartHRのAPIを利用するために、SmartHR側でAPIキーを作成します。
SmartHRの画面にアクセスして、右上のユーザー画面から「共通設定」をクリックし
メニュー一覧から「アプリケーション連携」を選択します。
この画面からアクセストークンの発行・管理が実施できます。今回はWeb APIを利用するので、「アクセストークン」をクリックして
「新規発行」をクリックします。
任意のアクセストークン名とアクセスリソースを指定して登録します。CData API Driverではそれぞれのデータに対して参照を行うので、すべてのリソースに参照権限を付与することができます。
API データ処理用 設定ファイルを作成
続いて、SmartHR の API を CData API Deiver が解釈できるように設定ファイル（API Profile）を作成します。
すでに私が作成したものがあるので、以下のURLからダウンロードしてください。
https://cdatajbuilds.s3-ap-northeast-1.amazonaws.com/APIProfiles/SmartHR.apip
保存先フォルダは後ほど使用するので「C:\API Profiles」といった書き込み可能な任意のフォルダに配置してください。
CData API Driver のインストール
各種ツールと SmartHR API を繋ぐために必要となる CData API Driverをインストールします。
基本的なインストール・設定方法は各種Driver共通ですので、ここではODBC Driverを例に説明します。
まず、CData API ODBC Driverの30日間の評価版をダウンロードします。ダウンロードの際には、Emailの登録が必要となります。
https://www.cdata.com/jp/apidriver/download/
ダウンロードしたsetup.exeファイルをBIツールがインストールされているマシンにインストールします。インストールウィザードに従い、EULAを確認した上でインストールを完了します。
※途中、ライセンスサーバーへのオンラインアクティベーションが行われるためネットワーク環境に接続されている必要があります。
インストールが完了すると、ODBCのDSN設定のウィンドウが立ち上がります。
以下の項目をセットし、保存します。
| プロパティ名 | 値 | 備考 |
|---|---|---|
| Profile | C:\API Profiles\SmartHR.apip | 予めダウンロードしたSmartHR.apipのパスを指定します。 |
| ProfileSettings | APIKey=MazivbNgaMrXXNSH8BuhMUV4MNbRWzQB;TenantId=16e046a9515a1045fef201d5; | 接続対象のSmartHR のAPI TokenとTenantIdを指定します。 |
SmartHRのURLが「https://16e046a9515a1045fef201d4.smarthr.jp/」の場合、TenantIdには「TenantId=16e046a9515a1045fef201d4;」入力して、指定します。
なお、Sandbox環境に接続したい場合は、ProfileSettings に UseSandbox=true;を追加してください。
以上で、CData API Driverの準備は完了です。
Excel から SmartHR API に接続（Excel Add-in for API）
CData Excel Add-in for API をインストール後、Excelを立ち上げるとCDataタブが追加されていることがわかります。このタブから各種操作を実施します。
接続を開始するには、CDataタブから［取得元 API］をクリックします。
最初に接続するためのウィザードが表示されるので、「CData API Driverのインストール」の内容と同様に各種パラメータを入力します。
接続後、対象テーブルを選択し、「OK」をクリックします。また、ここの画面で細かなフィルターやJOINの指定を行うことも可能です。
クリック後、対象のデータが一括で取得できます。
Access リンクテーブル から SmartHR API に接続（CData REST ODBC Driver）
次はCData ODBC Driverを利用して、Access リンクテーブルから接続してみたいと思います。
あらかじめ新規にAccessを立ち上げて、空のデータベースを作成しておきましょう。
続いて「外部データ」タブから「新しいデータ ソース」→「他のソースから」→「ODBC データベース」を選択します。
ウィザードが表示されるので「リンクテーブルを作成」を選択し、「OK」をクリックします。
データソースの選択では「コンピューターデータソース」から事前に作成したCData API Driver用DSNを選択し「OK」をクリック
テーブルの一覧が表示されるので、任意のテーブルを選択し「OK」をクリックします。
設定後、リンクテーブルが追加され、以下のようにSmartHRのデータを閲覧することができるようになります。もちろん、通常通りクエリデザイナーでも使用可能です。
なお、Accessでうまくデータが取得できない場合は「Other」の項目に「SupportAccessLinkedMode = False;」を設定してみてください。
PowerBI から SmartHR API に接続（CData API Driver for Power BI）
続いて CData Power BI Connector を用いて、Power BIからSmartHRのデータを取得します。
PowerBI Desktopを起動して、「データを取得」をクリックします。
データ接続先一覧の中から「CData API」を選択し、「接続」をクリックします。
データソース名は先程登録したSmartHRのDSNを入力し「OK」をクリックします。
テーブルの一覧から対象となるテーブルを選択し「読み込み」をクリックします。
以下のようにSmartHRのデータを読み込みことができます。
あとはPoewr BIの機能を用いて、ビジュアライズに利用することができます。
ASTERIA Warp から SmartHR 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）に登録します。
その後、ASTERIA Warpを立ち上げて、フローデザイナーにアクセスし、CData JDBC Driverを使用するために接続を追加します。
画面左のコネクションペイン上にある電源ボタンをクリックをクリックすると、「コネクションの作成」ダイアログが表示されます。
「接続種別」として「RDB」を選択、「名前」に分かりやすい名前を設定し「OK」をクリックします。
作成したコネクションをダブルクリックすると、画面右のインスペクタに接続プロパティが表示されます。 「基本」タブでドライバーのパスとURLをそれぞれ設定します。
| プロパティ名 | 値 | 備考 |
|---|---|---|
| ドライバーのパス | 例）C:\asteriahome5\system\lib\drivers\cdata.jdbc.api.jar | 前節でインストールした API JDBC Driverファイルへの参照を指定します。 |
| URL | jdbc:api:ProfileSettings='APIKey=XXXX;TenantId=XXXX;';Profile=C:\Publish\lib\v20\APIProfiles\SmartHR.apip; | SmartHRに接続するための接続文字列を指定します。 |
これでコネクションの作成は完了です。あとは、フロー上でデータベースタブにある「RDBGet」のコンポーネントを使って、データの取得が行なえます。
「RDBGet」フローに配置し、ダブルクリックします。
コネクションの選択ウインドウが表示されるので、先程作成したSmartHRのコネクションを選択しましょう。
その後、SQLビルダーが表示されるので、取得したいデータが格納されている、任意のテーブルとカラムを選択します。
あとは、「モデルにSQLを適用する」をクリックし「SELECTテスト」でデータが正常に取得できているかを確認します。
以下のようにデータが参照できれいればOKです。設定を保存してSQLビルダーを閉じます。
終わりに
これら以外にもCData API Driverは各種ETLツールや帳票ツールなどからも接続することが可能です。
以下のCData オンラインナレッジベースには、各種ツールからの接続方法を紹介した記事が多数掲載されているので、是非見てみてください。
また、こういったツールとはどう連携すればいいの？ といった問い合わせはテクニカルサポートフォームまでお気軽にどうぞ！
