こんにちは。CData Software Japan リードエンジニアの杉本です。
すでにスマレジAPIをご利用中の方であれば、ご存知かとは思いますが、現在いくつかのテーブルでデータを取得する際のクエリ制限がアップデートの中で追加されています。
詳しい対応内容については、以下の記事をご覧ください。
スマレジAPI の仕様変更に伴うドライバーの対応のお知らせ その1
スマレジAPI の仕様変更に伴うドライバーの対応のお知らせ その2
今回の記事では実際にCData スマレジ DriverやCData Syncで利用する際のポイント・注意点をお届けしたいと思います。
- CData Driver はどのようにスマレジAPIにリクエストするのか?
- クエリ方法の確認
- Driver での設定ポイント
- Exce Add-in での設定ポイント
- Power BI Connector での設定のポイント
- CData Sync での設定ポイント
- CData Sync で全件取得かつ定期的に差分を取得したい場合どうするべきか
- おわりに
CData Driver はどのようにスマレジAPIにリクエストするのか?
まず、CData Driver内部の動きを追ってみましょう。
CData Driver・CData Syncではその特性上、SQLでスマレジのデータを取得できます。
さらにスマレジAPIでサポートされている条件式にマッチングするようなクエリはスマレジAPIに適切に変換されて、リクエストが行われます。
例えば以下のようなクエリを実行すると
SELECT * FROM TransactionDetails WHERE TransactionDateTime >= '2021/03/01 00:00' and TransactionDateTime <= '2021/03/31 00:00';
内部的には以下のようなリクエストが生成され、データ取得を行います。
conditionsオブジェクトで「transactionDateTime」に対する範囲指定が行われていることがわかるかなと思います。
POST https://webapi.smaregi.jp/access/ HTTP/1.1 Host: webapi.smaregi.jp Accept: application/json Accept-Encoding: gzip, deflate User-Agent: CData Data Provider Engine - www.cdata.com - Accepts: gzip Content-Type: application/x-www-form-urlencoded Content-Length: 255 X-access-token: XXXXXXXX X-contract-id: XXXXX proc_name=transaction_ref¶ms={ "page": 1, "limit": 500, "table_name": "TransactionDetail", "conditions": [ { "transactionDateTime >=": "2021/03/01 00:00:00", "transactionDateTime <=": "2021/03/31 00:00:00" } ] }
ちなみに条件指定がない場合は、「conditions」が指定されないままスマレジAPIにリクエストされますので、以下のようなエラーメッセージが表示されます。
[Code: 0, SQL State: HY000] [41] [conditions] transactionHeadId,transactionDateTime,updDateTimeのうち、いずれか必須です.
クエリ方法の確認
回避策については、案内でも記載している通り、必要な条件式をSQLで指定するだけです。
例えば「取引(TransactionHead)」は以下のような条件式を適用する必要があります。
取引情報参照 > 取引(TransactionHead):OR条件
下記の絞り込み条件のうち、1つ以上の条件がリクエストに設定されていないとエラーになります。
・取引ID [transactionHeadId] ID指定,From-To(From-To指定可能範囲は10万以内)
・取引日時[transactionDateTime] From-To(期間は31日間(1ヶ月ではありません))
・端末取引日時[terminalTranDateTime] From-To(期間は31日間(1ヶ月ではありません))
・締め日時[sumDateTime] 日付直接指定 または From-To(期間は31日間(1ヶ月ではありません))
・更新日時[updDateTime] From-To(期間は31日間(1ヶ月ではありません))
この条件式をCData Driver では以下のようにSQLのWHERE句で表現します。
SELECT * FROM TransactionHeads WHERE TransactionHeadId >= 1 and TransactionHeadId <= 100000; SELECT * FROM TransactionHeads WHERE TransactionHeadId = 1; SELECT * FROM TransactionHeads WHERE TransactionDateTime > '2020/06/01 00:00' and TransactionDateTime < '2020/06/30 00:00'; SELECT * FROM TransactionHeads WHERE TerminalTranDateTime >= '2020/06/01 00:00' and TerminalTranDateTime <= '2020/06/31 00:00'; SELECT * FROM TransactionHeads WHERE SumDateTime => '2021/03/01' and SumDateTime <= '2021/03/31'; SELECT * FROM TransactionHeads WHERE UpdDateTime => '2021/03/01' and UpdDateTime <= '2021/03/31';
利用できるクエリについてはドキュメントの各種テーブルのページで記載しているので、参考にしてみてください。
例えば取引情報(TransactionHeads)の場合は、以下のようなイメージです。
併せて各Driver・Syncなどでの設定方法を見ていきましょう。
Driver での設定ポイント
CData JDBC Driver や ADO.NET 等、SQLを直接記述して利用しているシチュエーションの場合は、そのまま適用可能なWHEREの条件文を追加して、実行します。
SELECT * FROM TransactionDetails WHERE TransactionDateTime >= '2021/03/01 00:00' and TransactionDateTime <= '2021/03/31 00:00';
EntityFramework などの O/R マッパーを利用する場合は最終的に生成されるSQLでフィルター条件が適切に付与されているかどうかがポイントになります。
CData Driverが受け取っているSQLを確認したい場合は、ログを見る方法もあります。
Exce Add-in での設定ポイント
Excel Add-in はUI上でクエリ編集ができるので、パット見気軽に編集できそうなのですが、~~以上かつ~~以下といった範囲指定ができないため注意が必要です。
そのため、後付でWhere句のみを追加すると良いでしょう。
WHERE TransactionDateTime >= '2021/03/01 00:00' and TransactionDateTime <= '2021/03/31 00:00';
Power BI Connector での設定のポイント
Power BI Smaregi Connectorは接続設定画面の「Advanced Options」でSQLを指定することができます。
ここで必要な条件指定をしたSQLを入力して、データを取得してください。
CData Sync での設定ポイント
CData Sync ではタスク設定のフィルター条件を指定する部分で以下のように入力することが可能です。
もちろんカスタムクエリでSQLを記述してもかまいません。
REPLICATE [TransactionHeads] SELECT * FROM [TransactionHeads] WHERE TransactionDateTime > '2020/06/01 00:00' and TransactionDateTime < '2020/06/30 00:00';
CData Sync で全件取得かつ定期的に差分を取得したい場合どうするべきか
CData Sync でよく相談を受けるのは、過去の取引データを全部BigQueryなどのDWHに持っていきたいという内容です。
その際にまず必要になるのは過去のデータのレプリケーションです。
これは例えば以下のように「TransactionHeadId」を使って、範囲指定を行い、何回かに分けてレプリケーションすることで持っていくことができます。
REPLICATE [TransactionHeads] SELECT * FROM [TransactionHeads] WHERE ([TransactionHeadId] >= 1) AND ([TransactionHeadId] <= 100000)
その後、例えば1日1回差分だけ取得する場合は、以下のようにSQLの関数を駆使して動的にレプリケーション範囲を決めることができます。
REPLICATE [TransactionHeads] SELECT * FROM [TransactionHeads] WHERE ([TransactionDateTime] >= DATEADD('hh', -24, CURRENT_TIMESTAMP)) AND ([TransactionDateTime] <= DATEADD('hh', -0, CURRENT_TIMESTAMP));
これを1日1回実行すれば、日々の取引データが追加で蓄積されていきます。
ただし最初にレプリケーションした過去分のデータと重複しないように、レプリケーション結果が適切かどうか、RDBで都度確認すると良いでしょう。
おわりに
その他、利用方法で悩むことがあれば、お気軽にテクニカルサポートデスクまでお問い合わせください。