クラウド人事労務ソフトSmartHR API を各種ツールから連携可能なコネクタ・ドライバー化:CData API Driver

f:id:sugimomoto:20210218151806p:plain

こんにちは。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 とは?

雇用契約や入社手続きがペーパーレスで完結できるクラウドベースの労務管理サービスです。

smarthr.jp

f:id:sugimomoto:20210218151815p:plain

外部サービスと連携するためのAPIも充実しており、従業員情報から、部署・役職・事業所といった各種マスタデータまで幅広いデータの取得・登録・更新が可能です。

https://developer.smarthr.jp/api/index.html

f:id:sugimomoto:20210218151824p:plain

実現イメージ

この記事では SmartHR APIに対してExcelやPower BIといった各種ツールやIDEからの接続方法を紹介します。しかしながら、各APIは単純にツールと接続・連携することはできません。

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

f:id:sugimomoto:20210218151831p:plain

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

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

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

f:id:sugimomoto:20210218151840p:plain

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

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

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

  • Excel(Excel-addin で利用)
  • Access(ODBC 接続で利用)
  • PowerBI (Power BI Connector 接続で利用)
  • ASTERIA Warp(JDBC Driver 接続で利用)

上記以外のツールからの接続に関しては、以下のページで各種接続方法記事を公開しています。

www.cdata.com

f:id:sugimomoto:20201124135144p:plain

テーブル(ビュー)一覧

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の画面にアクセスして、右上のユーザー画面から「共通設定」をクリックし

f:id:sugimomoto:20210218151850p:plain

メニュー一覧から「アプリケーション連携」を選択します。

f:id:sugimomoto:20210218151855p:plain

この画面からアクセストークンの発行・管理が実施できます。今回はWeb APIを利用するので、「アクセストークン」をクリックして

f:id:sugimomoto:20210218151901p:plain

「新規発行」をクリックします。

f:id:sugimomoto:20210218151906p:plain

任意のアクセストークン名とアクセスリソースを指定して登録します。CData API Driverではそれぞれのデータに対して参照を行うので、すべてのリソースに参照権限を付与することができます。

f:id:sugimomoto:20210218151913p:plain

これでAPIアクセス用のトークンが生成されます。

f:id:sugimomoto:20210218151920p:plain

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

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

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

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

保存先フォルダは後ほど使用するので「C:\API Profiles」といった書き込み可能な任意のフォルダに配置してください。

f:id:sugimomoto:20210218152121p:plain

CData API Driver のインストール

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

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

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

https://www.cdata.com/jp/apidriver/download/

f:id:sugimomoto:20201027111336p:plain

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

f:id:sugimomoto:20201027111341p:plain

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

インストールが完了すると、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;」入力して、指定します。

f:id:sugimomoto:20210218152127p:plain

なお、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]をクリックします。

f:id:sugimomoto:20201116171024p:plain

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

f:id:sugimomoto:20210218152133p:plain

接続後、対象テーブルを選択し、「OK」をクリックします。また、ここの画面で細かなフィルターやJOINの指定を行うことも可能です。

f:id:sugimomoto:20210218152138p:plain

f:id:sugimomoto:20210218152142p:plain

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

f:id:sugimomoto:20210218152148p:plain

Access リンクテーブル から SmartHR API に接続(CData REST ODBC Driver)

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

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

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

image.png

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

image.png

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

f:id:sugimomoto:20210218152154p:plain

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

f:id:sugimomoto:20210218152200p:plain

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

f:id:sugimomoto:20210218152204p:plain

なお、Accessでうまくデータが取得できない場合は「Other」の項目に「SupportAccessLinkedMode = False;」を設定してみてください。

f:id:sugimomoto:20201124134536p:plain

PowerBI から SmartHR API に接続(CData API Driver for Power BI)

続いて CData Power BI Connector を用いて、Power BIからSmartHRのデータを取得します。

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

f:id:sugimomoto:20201027111449p:plain

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

f:id:sugimomoto:20201027111519p:plain

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

f:id:sugimomoto:20210218152212p:plain

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

f:id:sugimomoto:20210218152216p:plain

以下のようにSmartHRのデータを読み込みことができます。

f:id:sugimomoto:20210218152222p:plain

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

f:id:sugimomoto:20210218152229p:plain

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)に登録します。

f:id:sugimomoto:20210218152238p:plain

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

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

f:id:sugimomoto:20210216154030p:plain

「接続種別」として「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」フローに配置し、ダブルクリックします。

f:id:sugimomoto:20210216180653p:plain

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

f:id:sugimomoto:20210218152245p:plain

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

f:id:sugimomoto:20210218152252p:plain

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

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

f:id:sugimomoto:20210218152257p:plain

終わりに

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

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

www.cdata.com

また、こういったツールとはどう連携すればいいの? といった問い合わせはテクニカルサポートフォームまでお気軽にどうぞ!

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

トライアル・お問い合わせ

関連コンテンツ