Microsoft Graph で使える Delta Query とは

経緯

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

Delta Query の仕様

Delta Query とは

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

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

Delta Query でデータアクセスするには

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

レスポンスで個人的な注目点

あくまで個人的に（ｒｙ

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

状態トークンって消えないの？と気になる

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

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

参考

CloudComptingMicrosoft Graph API

Posted by みやみや