More than 3 years have passed since last update.

Microsoft Graph で使える Delta Query とは

Last updated at 2021-05-11Posted at 2021-05-03

経緯

前回、Delta Query を使って差分取得を試してみたが、改めて Delta Query のドキュメントをななめ読みしたメモ

Delta Query の説明は公式ではこのように記載されている

デルタクエリを使用すると、アプリケーションは、要求ごとにターゲットリソースをすべて読み取ることなく、新しく作成、更新、または削除されたエンティティを検出できます。Microsoft Graph アプリケーションはデルタクエリを使用して、変更をローカルデータストアと効率的に同期させることができます。

Delta Query でのフローはこんな感じ

パターンA：初回、データをすべて取得する必要がある時
1. Microsoft Graph の目的のリソースで Delta Query を使ってリクエストを送る
2. deltaLink URL が返ってくるまで nextLink URL でリクエストを送る
パターンB：初回、データをすべて取得する必要がない時
1. Microsoft Graph の目的のリソースで Delta Query を使い、パラメータに $deltaToken=latest をつけてリクエストを送ると deltaLink URL が返ってくる
deltaLink URL 取得後の動作
1. delta Link URL でリクエストを送ることで、変更点が返ってくる
2. パターンB の 2 を繰り返すことで次の deltaLink URL を取得

あくまで個人的にこんな感じ ※詳しくは公式ドキュメントを読んで♪

クエリパラメーターを使って絞り込みなどを行いたい時には、初回のリクエスト時にパラメーターをつける
特定の変更を追跡するために $select クエリパラメーターを使う
- 選択されていないプロパティが変更されてもレスポンスにデータが入ってこない
- manager と members もサポートされる
$filter で特定のユーザーやグループの変更を追うことが可能
- $filter でサポートされているのは、特定のオブジェクトを追跡する $filter=id+eq+{value} のみ
- フィルター処理の上限は 50
ユーザーとグループでは、クエリーパラメーターでは、$expand , $top , $orderby はサポートされていない

あくまで個人的に（ｒｙ

更新されたは少なくとも更新されたプロパティを持つ ID が返る
削除されたインスタンスは ID と @removed オブジェクトが返る
- reason が changed の時は削除されているが、deletedItems から復元可能
- reason が deleted の時は完全に削除され、復元不可能
1 つのエンティティが複数回変更された時、レスポンスに複数回含まれる可能性があり、統合は不可能
- 複数回返ってくる可能性を考慮する必要がある

気になるのが deltaLink の状態トークンが消えることはないか？というところだけど、そこはこの辺りに気をつける必要がありそう

リセットがかかることがある
- リセットがかかった時には、応答コード 410 と空の deltaLink が送られてくる模様
- ターゲットテナント内部のメンテナンスなどで起きるので防ぎようがないので、可能性を考慮する必要がある
トークン期間がある
- Directory オブジェクトは 7 日
- Education オブジェクトは 7 日
- Outlook エンティティは上限はなしだが、内部的なキャッシュ容量を超えたら古いトークンは削除される ※ハッキリと理解できていない...