エクスポート (0) 印刷
すべて展開

Azure AD Graph API の差分クエリ

更新日: 2014年10月

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

テナントのディレクトリに対して差分クエリ要求を行うには、アプリケーションはテナントによって承認される必要があります。詳細については、「アプリケーションの追加、更新、および削除」を参照してください。

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

  • 有効な要求 URL。テナントの Graph エンドポイントと該当するクエリ文字列パラメーターが含まれます。

  • 承認ヘッダー。Azure Active Directory によって発行される有効なアクセス トークンが含まれます。Graph API の認証の詳細については、「Azure AD の認証シナリオ」を参照してください。

差分クエリ要求の 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:クエリ文字列パラメーター

Parameter 説明

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。<resourceSet> が “directoryObjects” の場合にのみ有効です。それ以外の場合は、<resourceSet> はフィルターをオーバーライドします。たとえば、<resourceSet> が “users” で、$filter パラメーターも指定されている場合、指定されたフィルター選択値に関係なく、ユーザーに対する変更のみが返されます。<resourceSet> が “directoryObjects” で、$filter パラメーターが指定されていない場合、サポートされるすべてのエンティティの種類への変更が返されます。

単一のエンティティの種類を指定するには、次のいずれかの方法を使用します。

  • $filter=isof(‘Microsoft.WindowsAzure.ActiveDirectory.Contact’)

  • $filter=isof(‘Microsoft.WindowsAzure.ActiveDirectory.User’)

  • $filter=isof(‘Microsoft.WindowsAzure.ActiveDirectory.Group’)

複数のエンティティの種類を指定するには、or 演算子を使用します。たとえば、$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group') です。

(Graph API のプレビュー バージョンで objectScope クエリ文字列パラメーターを置き換えます)。

Important重要
バージョン 1.5 以降では、Graph API の名前空間は Microsoft.WindowsAzure.ActiveDirectory から Microsoft.DirectoryServices に変更されます。これより前のバージョンの Graph API では、引き続き以前の名前空間を使用します。たとえば、$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact') のようになります。

$select

応答に含めるプロパティを指定します。$select を指定しない場合、すべてのプロパティが含められます。

プロパティは、完全修飾または非完全修飾のいずれかで指定できます。複数のプロパティはコンマで区切ります。

  • 完全修飾プロパティには、エンティティの種類が指定されます (たとえば、User/displayName)。<resourceSet> が “directoryObjects” に指定されている場合、完全修飾プロパティを使用する必要があります。たとえば、https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description です。

  • 非完全修飾プロパティには、エンティティの種類が指定されません (たとえば、displayName)。<resourceSet> が “directoryObjects” 以外の値に指定されている場合にのみ使用できます。たとえば、https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle です。

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

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

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グループ、または 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
noteメモ
いずれの要求例も、$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"
    }
  ]
}

関連項目

表示:
© 2015 Microsoft