次の方法で共有


group: delta

名前空間: microsoft.graph

重要

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

グループ コレクション全体の完全な読み取りを実行することなく、グループ メンバーシップの変更を含む、新しく作成、更新、または削除されたグループを取得します。 詳細については、「 デルタ クエリを使用して Microsoft Graph データの変更を追跡する 」を参照してください。

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

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

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類 最小特権アクセス許可 より高い特権のアクセス許可
委任 (職場または学校のアカウント) GroupMember.Read.All Directory.Read.All、Directory.ReadWrite.All、Group.Read.All、Group.ReadWrite.All
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション GroupMember.Read.All Directory.Read.All、Directory.ReadWrite.All、Group.Read.All、Group.ReadWrite.All

HTTP 要求

変更の追跡を開始するには、グループ リソースにデルタ関数を含む要求を実行します。

GET /groups/delta

クエリ パラメーター

グループ内の変更を追跡すると、1 つ以上の デルタ 関数呼び出しのラウンドが発生します。 任意のクエリ パラメーター ($deltatoken$skiptoken以外) を使用する場合は、最初のデルタ要求でこれを指定する必要があります。 Microsoft Graph は、応答で提供される @odata.nextLink または @odata.deltaLink の URL のトークン部分に指定したパラメーターを自動的にエンコードします。

必要なクエリ パラメーターを前もって 1 回指定しておくだけで済みます。

その後の要求では、前の応答で得られた @odata.nextLink@odata.deltaLink の URL をコピーして適用します。エンコード済みの必要なパラメーターがこの URL に既に含まれているためです。

クエリ パラメーター 種類 説明
$deltatoken string 同じグループ コレクションに対する@odata.deltaLink前のデルタ関数呼び出しの URL で返された状態トークン。変更追跡のラウンドの完了を示します。 このコレクションについて、このトークンを含む、@odata.deltaLink URL 全体を次の変更追跡のラウンドの最初の要求に保存し、適用します。
$skiptoken string 前のデルタ関数呼び出しの @odata.nextLink URL で状態トークンが返され、同じグループ コレクションに追跡すべき変更が他にもあることを示します。

OData クエリ パラメーター

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

  • GET 要求と同様にクエリ パラメーターを $select 使用して、最適なパフォーマンスを得るために必要なプロパティのみを指定できます。 id プロパティは常に返されます。
  • を使用 $select=members して、メンバーシップの変更を取得できます。 さらに、directoryObject コレクション型の任意のグループリレーションシップを選択することで、所有権などの他の変更を追跡することもできます。
  • のサポート $filterは限られています。
    • サポートされている唯一の $filter 式は、特定のオブジェクトでの変更を追跡する $filter=id+eq+{value} です。 複数のオブジェクトをフィルター処理することができます。 たとえば、https://graph.microsoft.com/beta/groups/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff' などです。 フィルター処理されたオブジェクトは 50 個に制限されています。

要求ヘッダー

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

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

要求本文

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

応答

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

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

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

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

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

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

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

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

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

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

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

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

要求 1

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

GET https://graph.microsoft.com/beta/groups/delta

応答 1

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

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

グループ内のメンバー オブジェクトの ID を含む members@delta プロパティが存在する点に注意してください。

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvY1FSSc_",
  "value":[
    {
      "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",
      "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

次の例は、既定の応答動作を使用して、変更追跡用に 3 つのプロパティを選択する最初の要求を示しています。

GET https://graph.microsoft.com/beta/groups/delta?$select=displayName,description,mailNickname

応答 2

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

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "All Company",
      "description": null,
      "mailNickname": "allcompany@contoso.com"
    }
  ]
}

要求 3

次の例では、変更追跡用に 3 つのプロパティを選択する最初の要求を示します。代替の応答動作は最小限です。

GET https://graph.microsoft.com/beta/groups/delta?$select=displayName,description,mailNickname
Prefer: return=minimal

応答 3

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

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "Everyone",
      "description": null
    }
  ]
}