次の方法で共有

directoryObject: delta

  • [アーティクル]

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

名前空間: microsoft.graph

directoryObject コレクション全体の完全な読み取りを実行せずに、新しく作成、更新、または削除されたディレクトリ オブジェクトを取得します。 詳細については、「 デルタ クエリを使用して Microsoft Graph データの変更を追跡する 」を参照してください。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

次の表は、この API を呼び出すときに各リソースの種類に必要な最小特権のアクセス許可を示しています。 アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。

サポートされているリソース 委任 (職場または学校のアカウント) アプリケーション 委任 (個人用 Microsoft アカウント)
application Application.Read.All Application.Read.All 非サポート
administrativeUnit AdministrativeUnit.Read.All AdministrativeUnit.Read.All 非サポート
device Device.Read.All Device.Read.All サポート対象外
directoryRole RoleManagement.Read.Directory RoleManagement.Read.Directory 非サポート
グループ Group.Read.All Group.Read.All 非サポート
orgContact OrgContact.Read.All OrgContact.Read.All 非サポート
servicePrincipal Application.Read.All Application.Read.All 非サポート
user User.Read.All User.Read.All サポート対象外

HTTP 要求

ディレクトリ オブジェクト型のコレクションの変更を追跡します。

GET /directoryObjects/delta?$filter=isof('microsoft.graph.application')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.administrativeUnit')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.device')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.directoryRole')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.group')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.orgContact')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.servicePrincipal')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.user')

ディレクトリ オブジェクトの変更を追跡します。

GET /directoryObjects/delta?$filter=id eq '{id}'

OData クエリ パラメーター

このメソッドは、応答のカスタマイズに役立つオプションの OData クエリ パラメーターをサポートします。

  • GET 要求と同様にクエリ パラメーターを $select 使用して、最適なパフォーマンスを得るために必要なプロパティのみを指定できます。 id プロパティは常に返されます。
  • たとえば /directoryObjects/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'、複数のオブジェクトをフィルター処理する場合、フィルター式は 50 個に制限されています。
  • 構文を $filter 組み合わせることができます。 たとえば、「 $filter=isof('{resource type}') or id eq '{id}' 」のように入力します。 これにより、 の一致{resource type}とリソースの種類で指定されたオブジェクトの{id}積集合が提供されます。

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。
Content-Type application/json
Prefer return=minimal.

このヘッダーを指定する要求を使用すると、@odata.deltaLink は、最後のラウンド以降に変更されたオブジェクトのプロパティのみを返します。 省略可能です。

要求本文

このメソッドには、要求本文を指定しません。

応答

成功した場合、このメソッドは 200 OK 応答コードと directoryObject コレクション オブジェクトを応答本文で返します。 応答には、URL または @odata.deltaLink URL である@odata.nextLink状態トークンも含まれます。

  • もし@odata.nextLink URL が返された場合:

    • これは、セッションで取得するデータのページが増え続ける可能性があることを示します。 URL が応答に含まれるまで@odata.deltaLink、@odata.nextLinkアプリケーションは URL を使用して要求を行い続けます。
    • 応答には、最初のデルタクエリ要求と同じ一連のプロパティが含まれています。 これにより、デルタサイクルを開始するときに、オブジェクトの現在の完全な状態をキャプチャできます。

  • もし@odata.deltaLink URL が返された場合:

    • これは、返されるリソースの既存の状態に関するデータがそれ以上ないことを示します。 @odata.deltaLink URL を、次回のラウンドでリソースへの変更について学ぶために保存して使ってください。
    • Prefer:return=minimal ヘッダーを指定して、@odata.deltaLink発行後に変更されたプロパティのみをレスポンス値に含めるように選択することもできます。

デフォルト：初期デルタリクエストと同じプロパティを返します

デフォルトでは、@odata.deltaLinkまたは@odata.nextLinkを使用したリクエストは、最初のデルタクエリで選択されたものと同じプロパティを次のように返します:

  • プロパティを変更した場合は、応答には新しい値が含まれます。 これには、null 値に設定されているプロパティが含まれます。
  • プロパティが変更されていない場合は、古い値が応答に含まれます。
  • プロパティが設定されたことがない場合は、応答にまったく含まれません。

注意:この動作では、応答を見ても、プロパティが変化しているかどうかを判断することはできません。 また、デルタ応答は、 例 3 に示すように、すべてのプロパティ値が含まれているため、大きくなる傾向があります。

代替案：変更されたプロパティのみを返す

オプションのリクエストヘッダを追加すると、- prefer:return=minimal - 次のようになります:

  • プロパティを変更した場合は、応答には新しい値が含まれます。 これには、null 値に設定されているプロパティが含まれます。
  • プロパティが変更されていない場合、プロパティは応答にまったく含まれません。 (既定の動作と異なる)

注意: ヘッダーは、デルタサイクルのどの時点でも @odata.deltaLink要求に追加できます。 ヘッダーは応答に含まれる一連のプロパティにのみ影響し、デルタクエリの実行方法には影響しません。 例 4 を参照してください。

例

例 1: ユーザーとグループのコレクションの変更を取得する

要求

次の例は、ユーザーとグループの パラメーターを使用した $filter=isof('{resource type}') 要求を示しています。 パラメーターがないため $select 、プロパティの既定のセットが追跡され、返されます。

GET https://graph.microsoft.com/beta/directoryObjects/delta?filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')

応答

クエリの初期化$filter=isof('{resource type}')から取得した を 使用@odata.deltaLinkする場合の応答の例を次に示します。 グループ内のメンバー オブジェクトの ID を含む members@delta プロパティが存在する点に注意してください。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects","@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvY1FSSc_",
  "value":[
    {
      "@odata.type": "#microsoft.graph.user",
      "businessPhones": [
          "+1 425 555 0109"
      ],
      "displayName": "Adele Vance",
      "givenName": "Adele",
      "jobTitle": "Retail Manager",
      "mail": "AdeleV@contoso.com",
      "mobilePhone": "+1 425 555 0109",
      "officeLocation": "18/2111",
      "preferredLanguage": "en-US",
      "surname": "Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    },
    {
      "@odata.type": "#microsoft.graph.group",
      "createdDateTime":"2021-03-12T10:36:14Z",
      "description":"This is the default group for everyone in the network",
      "displayName":"All Company",
      "groupTypes": [
        "Unified"
      ],
      "mail": "allcompany@contoso.com",
      "id": "72052a9a-c466-4995-8210-95a1c1221995",
      "members@delta": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "693acd06-2877-4339-8ade-b704261fe7a0"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49320844-be99-4164-8167-87ff5d047ace"
        }
      ]
    }
  ]
}

例 2: ディレクトリ オブジェクトの変更のコレクションを取得する

要求

次の例は、 パラメーターを使用した要求を $filter=id eq '{id}' 示しています。 パラメーターがないため $select 、プロパティの既定のセットが追跡され、返されます。

GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=id eq '87d349ed-44d7-43e1-9a83-5f2406dee5bd'

応答

クエリの初期化$filter=id eq '{id}'から取得した を 使用@odata.deltaLinkする場合の応答の例を次に示します。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "@odata.type": "#microsoft.graph.group",
      "createdDateTime":"2021-03-12T10:36:14Z",
      "description":"This is the default group for everyone in the network",
      "displayName":"All Company",
      "groupTypes": [
        "Unified"
      ],
      "mail": "allcompany@contoso.com",
      "id": "72052a9a-c466-4995-8210-95a1c1221995",
      "members@delta": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "693acd06-2877-4339-8ade-b704261fe7a0"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49320844-be99-4164-8167-87ff5d047ace"
        }
      ]
    }
  ]
}

例 3: ユーザーとグループのコレクションの特定のプロパティに対する変更を取得する

要求

次の例は、既定の応答動作を使用して、変更追跡のためにユーザーとグループからそれぞれ 1 つのプロパティを選択する最初の要求を示しています。

GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')&$select=microsoft.graph.user/surname,microsoft.graph.group/displayName

応答

クエリの初期化から取得した を使用 @odata.deltaLink する場合の応答の例を次に示します。 どちらのプロパティも応答に含まれており、 が取得されてから @odata.deltaLink 変更されたものは不明です。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "@odata.type": "#microsoft.graph.user",
      "surname": "Vance",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    },
    {
      "@odata.type": "#microsoft.graph.group",
      "displayName":"All Company",
      "id": "72052a9a-c466-4995-8210-95a1c1221995",
    }
  ]
}

例 4: ユーザーとグループのコレクションに対して特定のプロパティが変更された場合にのみ取得する

要求

次の例は、変更追跡のためにユーザーとグループからそれぞれ 1 つのプロパティを選択する最初の要求を示しています。代替の最小限の応答動作を使用します。

GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')&$select=microsoft.graph.user/surname,microsoft.graph.group/displayName
Prefer: return=minimal

応答

クエリの初期化から取得した を使用 @odata.deltaLink する場合の応答の例を次に示します。 プロパティは microsoft.graph.user/surname 含まれていません。つまり、最後のデルタ クエリ microsoft.graph.group/displayName 以降は変更されていません。これは、値が変更されたことを意味します。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "@odata.type": "#microsoft.graph.group",
      "displayName":"Everyone",
      "id": "72052a9a-c466-4995-8210-95a1c1221995",
    }
  ]
}

関連コンテンツ