こんにちは。CData Software Japan リードエンジニアの杉本です。
CData Driverのような、APIに強く依存したプロダクト開発を行っていると「APIがバージョンアップしたんだけど、古いバージョンとは何が違うの？」という質問を受けることがよくあります。
今回はその中でもよく質問をうける「Dataverse / Dynamics 365」のWeb APIのバージョンに絞って解説してみたいと思います。
- 現在使っている環境で Web APIのバージョンを確認する
- APIのバージョンで何が違うの？
- 古いバージョンは利用できないの？
- CData Dynamics 365 / Dataverse Driversでの対応方法について
- Tips
現在使っている環境で Web APIのバージョンを確認する
なにはともあれ、まず現在利用している環境で利用できる最新のWeb API バージョンがいくつなのか？ を確認してみましょう。
バージョンの確認は、Power AppsまたはDynamics 365 の「詳細設定」で行います。
「設定」→「カスタマイズ」にある「開発者リソース」に移動すると、Web APIサービスのルートURLがあり、ここで確認できます。
2021年5月6日現在では、「v9.2」が最新のようでした。
APIのバージョンで何が違うの？
それでは、本筋となる API のバージョンによる違いを確認してみましょう。
ちなみに Dynamics 365 / Dataverse の Web APIはSOAPから切り替わって、v8.0から利用できるようになりました。
v8.0 以前は存在しません。（というか位置づけ的にはSOAP APIのことを指すのかもしれませんが）
Web API のバージョンに関する情報は、以下のドキュメントで確認できます。
現時点（2021/05/06）では、主な変更箇所は以下の通りとなっています。
思ったよりも、あまり大きな変更は無いかなーという印象でした。破壊的なものや過去バージョンが使えなくなっているという記述もないようですね。ただ、上記に抵触するような利用をしている場合は、注意しましょう。
名前がかぶっている場合とかは要注意ですね。
ちなみに、ここのドキュメントはあくまでAPIバージョンに伴う変更情報のみなので、それ以外のWeb APIに関する制限は以下のドキュメントを参照しましょう。
古いバージョンは利用できないの？
さて、もう一つ気になる点は「古いバージョン」どこまで利用できるかどうか？ というところではないでしょうか。
今の所前述のドキュメントには特に記述はありませんでしたが、せっかくなのでどのくらいのバージョンまでアクセスできるのか？ 実際に試してみました。
確認方法は簡単です。例えば、取引先企業を取得するためのリクエストはブラウザから簡単に実行できます。以下のように先程確認したWeb API のエンドポイントに「accounts」という形でリソース名を指定するだけです。
https://XXXXX.api.crm7.dynamics.com/api/data/v9.2/accounts
以下のように取得できました。
続いて、v8.0でアクセスしてみましょう。
https://XXXXX.api.crm7.dynamics.com/api/data/v8.0/accounts
普通に取得できていますね。
ここでせっかくなので存在しないバージョン「v7.0」を指定してみました。
https://XXXXX.api.crm7.dynamics.com/api/data/v7.0/accounts
すると、以下のように 「Requested API Version 'v7.0' is not available」と怒られてしまいました。わかりやすいですね。「v9.3」とかもやってみましたが、同様でした。
ついでに、「v8.0」と「v9.2」で取得した内容をCompareしてみました。左が「v8.0」で右が「v9.2」です
主な違いは下記3点。レスポンスに含まれるodata.contextのバージョンが違った部分と（そりゃそうですが）
なぜかいくつかの項目で並び順が異なりました。
一番顕著な違いは「teamsfollowed」という項目が追加されていたことですね。これはMS Teams関連の機能追加ですね。v8.0リリース時点ではMS Teamsが無かった（もしくは出たばかり？）かなと思うので、わかりやすい変更箇所です。
CData Dynamics 365 / Dataverse Driversでの対応方法について
それでは、CData Dynamics 365 / Dataverse Driversでもどのような仕組みになっているか確認しておきましょう。
CData Driverでは以下のAPI Version の接続プロパティで対象のWeb API Versionを変更できます。初期値はダウンロードした時のDriverによって決まっていますが、任意の変更することも可能です。
ただ、API Versionによっては、古いビルドのままだとうまく接続できない場合があります。Dynamics 365 / Dataverseの場合は、今の所大きな変更はWeb APIで発生していませんが、もしAPI Versionをアップする場合は、Driverも最新のビルドに切り替えるようにしてください。
最新ビルドが必要な場合は、「テクニカルサポートフォーム」 までお気軽にどうぞ。
Tips
ちなみに前述したドキュメントで「エンティティおよび属性と同じ名称」だった場合に、「v8.X」と「v9.X」では名称の提供方法が異なるという変更点がありましたね。
CData Driverはその性質上、最初にエンティティや属性の情報を自動的に取得して、テーブル情報を構成し、内部でキャッシュを持ちます。
もし最新のバージョンに切り替えて、名前が変わってしまった場合は「reset schema CACHE;」というクエリを実行することで、キャッシュされたテーブル情報をリフレッシュすることができます。
