Dynamics CRM Web API レコード取得編 Part.Ⅲ
だ、だ、だ、Dynamics 365 がリリースされました。
まだ、詳しく見れてないのですが、ライセンスの変更があるようですね。トライアル版で取得したんですが、SharePoint Online だけでなくProject Online も一緒にプロビジョニングされていてビックリしました。CRM部分については配色が変わってました。
と、キャッチアップせねばならないと思いながら別件に手を妬いている Harada です。(あーしんどっ!w)
前回は取得するフィールドを指定するということと、検索条件を指定してレコードを取得するという事を行いました。Web API には慣れてきましたでしょうか?
慣れると使い勝手のいいものなので、是非是非ご活用ください。
そして今回は『レコード取得編』のPart.Ⅲとして$select、$filterオプション以外のオプションについて少し触れてみたいと思います。(最終回と予告してたんですが、まだまだボリュームがありましたw)
では、いったいどんなシステムクエリオプションがあるのでしょうか・・・
- $orderby
- $top
- $count
- $expand
- $ref
ボリューミーなので、2回に分けてご説明することになると思いますが、お付き合いください。
Dynamics CRM Web API 取得レコードの並び順の指定
レコードを取得する際に登録されたのが新しいレコードから取得したいや売上額が高いレコードから取得したいなどあることと思います。その際に使用するのが、『$orderby』システムクエリオプションです。フィールド名の後ろにasc(昇順)、または、desc(降順)を指定します。昇順・降順の既定値は昇順(asc)となっています。
[API URL]/accounts?$orderby=accountnumber desc,name asc
取引先企業エンティティの取引先企業番号の降順と取引先企業名の昇順を指定しています。ふたつのフィールドを指定する際は『,(カンマ)』で連携つします。
このようにレコード取得時に並び順を指定することが可能ということがお分かりいただけると思います。
Dynamics CRM Web API 取得レコード数の制限
最新レコードのみ取得したい場合などに1レコードのみ取得したいや10レコードのみ取得したいなどがあると思います。そういった場合は『$top』システムクエリオプションを指定します。$select オプションの説明時にも触れましたが、必要な分だけ取得するのがパフォーマンスやリソースに優しい事は明白なので$select や $filter、$orderby と併用して使用することをお勧めします。
[API URL]/accounts?$orderby=accountnumber desc,name asc&$top=1
$orderby で使用したURLに「$top=1」を追加しました。この指定をすることにより1件を超えるレコードを取得することはなくなります。
MSDN では後述する $count システムクエリオプション と同時に使用してはならないと記載があるのですが、理由はよくわからないです。試しに併用してみましたが、特に不可解な動きはなかったので問題なさそう・・・
また、取得レコード数の制限はHTTPリクエストヘッダにPreferを指定して「odata.maxpagesize=1」と指定することで同じことを実現することが可能ですが、こちらも$top オプションとodata.maxpagesize を同時に使用することはできないと記載があります。
Dynamics CRM Web API 取得レコード数の取得
ここでは『$count』システムクエリオプションを説明するのですが、良い使い方がありません。とりあえず記載方法からどうぞ。
[API URL]/accounts?$orderby=accountnumber desc,name asc&$count=true
このように指定すると、レスポンスデータの中に『@odata.count』という項目があり、こちらで件数を取得することが可能なのですが、実際のデータもレスポンスデータ内にあるので、そのデータの件数を確認すればいいのではないかと思います。また、5,000件を超えるデータは5,000件で取得することになるので、総データ数を確認できません。(いったい何のためにあるオプションなんだぁ!)
と、いうわけで、使用方法がわからにオプションですm(_ _)m
$top オプションで説明した通り、$count と $top を同時使用しないでくださいとの記載があります。
Dynamics CRM Web API 関連エンティティの取得
『$expand』『$ref』を使用して関連エンティティを取得することが可能です。関連エンティティとは検索フィールドの先にあるエンティティレコードです。関連エンティティは取得方法がいくつかあるので、次回ご説明しますので、ここではシステムクエリオプションに関連エンティティに関するものがあるという事をご理解頂ければと思います。
Dynamics CRM Web API 事前定義クエリ
事前定義クエリとは、「システムビュー」「ユーザービュー」および「FetchXML」を指します。すでに定義されているクエリを使用してレコードの取得を行う事ができます。ビューを使用する場合は、使用したいビューのGUIDが必要となります。
- ビューを使用したクエリ
-
[API URL]/accounts?savedQuery=[GUID]
- FetchXMLを使用したクエリ
-
[API URL]/accounts?fetchXml=[FetchXML]
このように既に定義済みのクエリを再利用するのことで、カスタマイズに強いアドオンが可能になります。ただ、FetchXMLについてはその限りではないですね。
FetchXMLだと集計が可能だったりというメリットもありますので、そういった部分を踏まえてご利用いただければと思います。
次回の内容
次回こそDynamics CRM Web API レコード取得編 最終回となります。乞うご期待!w
※ 記事の内容は個人発信の参考情報です。記事内容のご利用は、ご自身の判断でお願いします。