差分クエリ | Graph API の概念

[アーティクル]
2021/10/21

適用対象: Graph API | Azure Active Directory

このトピックでは、Azure AD Graph API の差分クエリ機能について説明します。差分クエリ要求は、2 つの連続した要求の間に指定されたエンティティに行われたすべての変更を返します。たとえば、前回の差分クエリ要求の 1 時間後に差分クエリ要求を行う場合、その 1 時間で行われた変更のみが返されます。この機能は、テナントディレクトリデータとアプリケーションのデータストアを同期させるときに特に便利です。

テナントのディレクトリに対して差分クエリ要求を行うには、アプリケーションはテナントによって承認される必要があります。詳細については、「Azure Active Directory とアプリケーションの統合」を参照してください。

重要

Azure Active Directory のリソースにアクセスするには、Azure AD Graph API ではなく Microsoft Graph を使用することを強くお勧めします。現在は Microsoft Graph を中心にして開発が進められており、Azure AD Graph API の今後の機能強化は予定されていません。Azure AD Graph API の使用が適切である場合もありますが、非常にまれです。詳細については、Office Dev Center の Microsoft Graph または Azure AD Graph ブログの記事をご覧ください。

差分クエリ要求

ここでは、差分クエリ要求について説明します。すべての要求に次のコンポーネントが必要です。

有効な要求 URL。テナントの Graph エンドポイントと該当するクエリ文字列パラメーターが含まれます。
承認ヘッダー。Azure Active Directory によって発行される有効なアクセストークンが含まれます。 Graph API への認証の詳細については、「Azure AD の認証シナリオ」を参照してください。

差分クエリ要求 URL

差分クエリ要求の URL の形式を次に示します。角かっこ [] は省略可能な要素を示しています。

https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]

URL は、キーと値のペアで表される一連のクエリ文字列パラメーターが後に続く階層セグメントで構成されています。

URL: 階層セグメント

セグメント	説明
tenantId	クエリが実行される対象のテナントの一意の ID。通常、テナントの確認済みのドメイン (verifiedDomains プロパティ) の 1 つですが、テナントのオブジェクト ID (objectId プロパティ) である場合もあります。大文字と小文字は区別されません。
resourceSet	このクエリが実行される対象のテナントリソースの特定のセット。クエリの応答で返されるリソースを決定します。サポートされている値は、“directoryObjects”、“users”、“contacts”、または “groups” です。これらの値は大文字と小文字が区別されます。

URL: クエリ文字列パラメーター

パラメーター	説明
api-version	要求の発行対象となる Graph API のバージョンを指定します。必須。バージョン 1.5 以降では、この値は数値のバージョン番号として表されます (たとえば、api-version=1.5)。これより前のバージョンでは、この値は YYYY-MM-DD という形式の文字列です (たとえば、api-version=2013-04-05)。 (Graph API のプレビューバージョンで x-ms-dirapi-data-contract-version ヘッダーの使用を置き換えます)。
deltaLink	前回の応答で deltaLink プロパティまたは nextLink プロパティのどちらかに返されたトークン。必須ですが、最初の要求では空になります。 (Graph API のプレビューバージョンで skipToken クエリ文字列パラメーターを置き換えます)。
$filter	応答に含める必要があるエンティティの種類を指定します。任意。サポートされているエンティティの種類は、User、Group、および Contact です。 &ltresourceSet&gt が “directoryObjects” の場合にのみ有効です。それ以外の場合は、&ltresourceSet&gt はフィルターをオーバーライドします。たとえば、&ltresourceSet&gt が “users” で、$filter パラメーターも指定されている場合、指定されたフィルター選択値に関係なく、ユーザーに対する変更のみが返されます。 &ltresourceSet&gt が “directoryObjects” で、$filter パラメーターが指定されていない場合、サポートされるすべてのエンティティの種類 (User、Group、および Contact) への変更が返されます。単一のエンティティの種類を指定するには、次のいずれかの方法を使用します。 `$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')` `$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')` `$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Group')` 複数のエンティティの種類を指定するには、または演算子を使用します (たとえば、`$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')`)。 (Graph API のプレビューバージョンで objectScope クエリ文字列パラメーターを置き換えます)。重要: バージョン 1.5 以降では、Graph API の名前空間は Microsoft.WindowsAzure.ActiveDirectory から Microsoft.DirectoryServices に変更されます。これより前のバージョンの Graph API では、引き続き以前の名前空間を使用します (たとえば、`$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')`)。
$select	応答に含めるプロパティを指定します。 *$select^ を指定しない場合、すべてのプロパティが含められます。プロパティは、完全修飾または非完全修飾のいずれかで指定できます。複数のプロパティはコンマで区切ります。完全修飾プロパティには、エンティティの種類が指定されます (たとえば、`User/displayName`)。 &ltresourceSet&gt を “directoryObjects” として指定した場合、完全修飾プロパティを使用する必要があります (たとえば、 `https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description`)。非完全修飾プロパティには、エンティティの種類が指定されません (たとえば、`displayName`)。 &ltresourceSet&gt を "directoryObjects" 以外の値として指定した場合にのみ使用できます (たとえば、`https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle`)。

注: クエリ文字列のキーと値のペアでは、大文字と小文字が区別されますが、その順序は重要ではありません。

最も簡単な差分クエリの例を次に示します。これは最初の同期中に使用されます。

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=

後続の要求の例を次に示します。

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`

差分クエリ応答

ここでは、差分クエリ要求が行われたときに返される差分クエリ応答の内容について説明します。次の一覧は応答の内容を示しています。

0 ～ 200 個の DirectoryObject エンティティ。それぞれのエンティティに特定の User、Group、または Contact オブジェクトに対する変更が含まれます。
0 ～ 3000 個の DirectoryLinkChange エンティティ。それぞれのエンティティに特定の Member または Manager リンクに対する変更が含まれます。
deltaLink または nextLink プロパティのいずれかです。いずれの場合も、ディレクトリで発生した変更の保持に関して、クライアントに返されたディレクトリ変更の設定に関する状態情報が埋め込まれた URL エンコード文字列です。この値は大文字と小文字が区別されます。この文字列 (トークン) は、次の差分クエリ要求内の deltaLink クエリ文字列パラメーターに含める必要があります。
- deltaLink プロパティが返された場合、この応答の後に同期するアプリケーションへのディレクトリ変更はありません。アプリケーションは、次の差分クエリ要求を行うための独自の要件に従って、あらかじめ定義した時間待機させることができます。
- nextLink プロパティが返された場合、この応答の後に同期するためにアプリケーションへのディレクトリ変更が保持されます。アプリケーションは、できる限り早く次の差分クエリ要求を発行する必要があります。

応答は常に JSON 形式で返されます。

差分クエリを使用する際の注意事項

次の一覧は、差分クエリを使用するアプリケーションに関する重要な注意事項を示しています。

差分クエリによって返される変更は、応答時のディレクトリオブジェクトの状態を表します。お使いのアプリケーションで、これらの変更を応答に対するトランザクションログとして扱うことはできません。
変更は発生順に表示されます。オブジェクトが複数回更新された場合でも、前回変更されたオブジェクトが最後に表示されます。また、クライアントが変更を受信しても、この順序に影響はありません。結果として、順序どおりに表示されない複数の変更を最初にディレクトリで発生した状態と比較することができます。
お使いのアプリケーションは応答の準備をする必要があります。この応答は同じ変更が後続の応答に表示される場合に発生します。差分クエリが応答を減らすために最も適している場合、継続して使用できます。
お使いのアプリケーションは、認識していなかったオブジェクトへの削除変更を処理するために準備する必要があります。
差分クエリは、まだ他の応答によって返されていないソースオブジェクトまたはターゲットオブジェクトへのリンクを返すことができます。
要求ヘッダーでクエリを制限してパフォーマンスを向上させる方法の詳細については、下記の「差分クエリの追加機能」セクションを参照してください。

要求と応答の例

最初の差分クエリ要求の例を次に示します。

GET https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink= HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net

増分の差分クエリ要求の例を次に示します。

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U
 HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net

注: いずれの要求例も、$filter クエリパラメーターは、デモの目的のためだけに示されています。フィルターは差分クエリに可能なターゲットの種類をすべて指定するため (User、Group、および Contact)、フィルターは省略することができ、既定ではクエリはすべてのエンティティの種類に対する変更を返します。

次の応答の例は、返される JSON を示しています。

{
  "odata.metadata": "https://graph.windows.net/contoso.com/$metadata#directoryObjects",


  # This is the deltaLink to be used for the next query
  "aad.deltaLink": "https://graph.windows.net/contoso.com/directoryObjects?deltaLink=XARBN7ivjcS6QIhSZDQR3OkT15SO1eeY-01BZSS0sOct6sh5oEyqOLLKRVhRmBMLHhePUF... [Truncated]",
  "value": [

    # User object for John Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.User",
      "objectType": "User",
      "objectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "accountEnabled": true,
      "displayName": "John Smith",
      "givenName": "John",
      "mailNickname": "johnsmith",
      "passwordPolicies": "None",
      "surname": "Smith",
      "usageLocation": "US",
      "userPrincipalName": "johnsmith@contoso.com"
    },

    # Group object for IT Administrators
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Group",
      "objectType": "Group",
      "objectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "description": "IT Administrators",
      "displayName": "Administrators",
      "mailNickname": "Administrators",
      "mailEnabled": false,
      "securityEnabled": true
    },

    # Contact object for Jane Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Contact",
      "objectType": "Contact",
      "objectId": "d711a1f8-21cf-4dc0-834a-5583e5324c44",
      "displayName": "Jane Smith",
      "givenName": "Jane",
      "mail": "johnsmith@contoso.com",
      "mailNickname": "johnsmith",
      "proxyAddresses": [
        "SMTP:janesmith@fabrikam.com"
      ],
      "surname": "Smith"
    },

    # Member link indicating John Smith is a member of IT Admin Group
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.DirectoryLinkChange",
      "objectType": "DirectoryLinkChange",
      "objectId": "00000000-0000-0000-0000-000000000000",
      "associationType": "Member",
      "sourceObjectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "sourceObjectType": "Group",
      "sourceObjectUri": "https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8",
      "targetObjectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "targetObjectType": "User",
      "targetObjectUri": "https://graph.windows.net/contoso.com/users/dca803ab-bf26-4753-bf20-e1c56a9c34e2"
    }
  ]
}

差分クエリのその他の機能

差分クエリで、更新されたプロパティとリンクのみを返すことができるようになりました。これにより、差分クエリの呼び出しの処理を高速化し、ペイロードを削減できます。このオプションを有効にするは、次の例で示すように、ヘッダー ocp-aad-dq-include-only-changed-properties を true に設定します。

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= furK18V1T….
HTTP /1.1
ocp-aad-dq-include-only-changed-properties : true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

たとえば、ユーザーの "displayName" プロパティのみが変更された場合、次のようなオブジェクトが返されます。

{     
          "displayName" : "AnUpdatedDisplayName",
         "objectId" :  "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
         "objectType" :  "User",
          "odata.type" :  "Microsoft.WindowsAzure.ActiveDirectory.User"
},

"現時点" から同期する差分同期サポート - 最新の deltaToken のみを取得することを要求する特殊なヘッダーを指定できます。このトークンは、後続のクエリで使用でき、 "現時点" からの変更のみを返します。呼び出しの例を次に示します。

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= smLYT8V1T…
HTTP /1.1
ocp-aad-dq-include-only-delta-token: true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

応答には、次のように、deltaLink が含まれますが、変更されたオブジェクトは含まれません。

{   …  "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43......   }

削除された項目を検出する – 応答を使用して、削除された項目を検出することもできます。削除されたオブジェクトと削除されたリンクは、"aad.isDeleted" プロパティの値が true に設定されていることで示されます。これは、アプリケーションが、以前に作成したオブジェクトとリンクの削除について学習できるようにするために必要です。

その他のリソース

Azure AD Graph API リファレンス

次の方法で共有

差分クエリ | Graph API の概念

差分クエリ要求

差分クエリ要求 URL

URL: 階層セグメント

URL: クエリ文字列パラメーター

差分クエリ応答

差分クエリを使用する際の注意事項

要求と応答の例

差分クエリのその他の機能

その他のリソース

その他のリソース