orgContact: delta

[アーティクル]
05/06/2022

名前空間: microsoft.graph

コレクション全体の完全な読み取りを実行することなく、新しく作成、更新、または削除された組織の連絡先を取得します。詳細については、変更履歴をご覧ください。

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。

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

HTTP 要求

変更の追跡を開始するには、連絡先リソースのデルタ関数を含む要求を行います。

GET /contacts/delta

クエリパラメーター

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

前もってクエリパラメーターを指定するだけで済みます。

後続の要求では、前の応答の URL を@odata.deltaLinkコピーして適用@odata.nextLinkします。その URL には、エンコードされたパラメーターが既に含まれています。

クエリパラメーター	種類	説明
$deltatoken	string	同じ組織の連絡先コレクションの前のデルタ関数呼び出しの URL で`@odata.deltaLink`返された状態トークン。変更のラウンド追跡が完了したことを示します。このトークンを含む URL 全体 `@odata.deltaLink` を保存し、そのコレクションの次のラウンドの変更追跡の最初の要求に適用します。
$skiptoken	string	前のデルタ関数呼び出しの URL で`@odata.nextLink`返された状態トークン。同じ組織の連絡先コレクションで追跡する変更がさらに存在することを示します。

OData クエリパラメーター

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

任意の GET リクエストと同様に $select クエリパラメーターを使用して、最善のパフォーマンスを得るために必要なプロパティのみを指定することができます。Id プロパティは常に返されます。
$filter に対するサポートには制限があります。
- サポートされている唯一の $filter 式は、特定のオブジェクトでの変更を追跡する $filter=id+eq+{value} です。複数のオブジェクトをフィルター処理することができます。たとえば、https://graph.microsoft.com/v1.0/contacts/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff' などです。フィルター処理されるオブジェクトには 50 の数量制限があります。

要求ヘッダー

名前	説明
Authorization	ベアラー <トークン>。必須。
Prefer	return=minimal. `@odata.deltaLink` を使用するリクエストでこのヘッダーを指定すると、前回のラウンド以降に変更されたオブジェクトプロパティのみが返されます。オプションです。

要求本文

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

応答

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

もし@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 値に設定されているプロパティが含まれます。
プロパティが変更されていない場合は、古い値が応答に含まれています。
プロパティが設定されたことがない場合は、応答にまったく含まれません。

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

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

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

例

例 1: 既定のプロパティ

要求

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

GET https://graph.microsoft.com/v1.0/contacts/delta


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Contacts
    .Delta()
    .Request()
    .GetAsync();


const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/contacts/delta')
    .get();


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/contacts/delta"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphOrgContact *orgContact = [[MSGraphOrgContact alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

OrgContactDeltaCollectionPage delta = graphClient.contacts()
    .delta()
    .buildRequest()
    .get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

result, err := graphClient.Contacts().Delta()().Get()


Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgContactDelta

応答

以下は、クエリ初期化から取得した@odata.deltaLink を使用した場合の応答の例です。

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#contacts",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/contacts/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "companyName": "companyName-value",
      "department": "department-value",
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "id": "string (identifier)",
      "jobTitle": "jobTitle-value",
      "mail": "mail-value",
      "mailNickname": "mailNickname-value",
      "surname": "surname-value"
    }
  ]
}

例 2: 3 つのプロパティの選択

要求

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

GET https://graph.microsoft.com/v1.0/contacts/delta?$select=displayName,jobTitle,mail


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Contacts
    .Delta()
    .Request()
    .Select("displayName,jobTitle,mail")
    .GetAsync();


const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/contacts/delta')
    .select('displayName,jobTitle,mail')
    .get();


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/contacts/delta?$select=displayName,jobTitle,mail"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphOrgContact *orgContact = [[MSGraphOrgContact alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

OrgContactDeltaCollectionPage delta = graphClient.contacts()
    .delta()
    .buildRequest()
    .select("displayName,jobTitle,mail")
    .get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DeltaRequestBuilderGetQueryParameters{
    Select: "displayName,jobTitle,mail",
}
options := &msgraphsdk.DeltaRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
}
result, err := graphClient.Contacts().Delta()().GetWithRequestConfigurationAndResponseHandler(options, nil)


Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgContactDelta -Property "displayName,jobTitle,mail"

応答

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

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#contacts",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/contacts/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": "jobTitle-value",
      "mail": null
    }
  ]
}

例 3: 代替の最小限の応答の動作

要求

次の例は、最初のリクエストが代替の最小限の応答の変更追跡のために 3 つのプロパティを選択していることを示しています。

GET https://graph.microsoft.com/v1.0/contacts/delta?$select=displayName,jobTitle,mail
Prefer: return=minimal


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Contacts
    .Delta()
    .Request()
    .Header("Prefer","return=minimal")
    .Select("displayName,jobTitle,mail")
    .GetAsync();


const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/contacts/delta')
    .header('Prefer','return=minimal')
    .select('displayName,jobTitle,mail')
    .get();


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/contacts/delta?$select=displayName,jobTitle,mail"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"return=minimal" forHTTPHeaderField:@"Prefer"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphOrgContact *orgContact = [[MSGraphOrgContact alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("Prefer", "return=minimal"));

OrgContactDeltaCollectionPage delta = graphClient.contacts()
    .delta()
    .buildRequest( requestOptions )
    .select("displayName,jobTitle,mail")
    .get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DeltaRequestBuilderGetQueryParameters{
    Select: "displayName,jobTitle,mail",
}
headers := map[string]string{
    "Prefer": "return=minimal"
}
options := &msgraphsdk.DeltaRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
    Headers: headers,
}
result, err := graphClient.Contacts().Delta()().GetWithRequestConfigurationAndResponseHandler(options, nil)


Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgContactDelta -Property "displayName,jobTitle,mail"

応答

以下は、クエリ初期化から取得した@odata.deltaLink を使用した場合の応答の例です。このmailプロパティは含まれていないことに注意してください。つまり、最後のデルタクエリ以降変更されていません;displayNameとjobTitle が含まれており、それらの値は変更されていることを意味します。

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#contacts",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/contacts/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": null
    }
  ]
}

orgContact: delta

アクセス許可

HTTP 要求

クエリパラメーター

OData クエリパラメーター

要求ヘッダー

要求本文

応答

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

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

例

例 1: 既定のプロパティ

要求

応答

例 2: 3 つのプロパティの選択

要求

応答

例 3: 代替の最小限の応答の動作

要求

応答

関連項目

フィードバック

orgContact: delta

アクセス許可

HTTP 要求

クエリ パラメーター

OData クエリ パラメーター

要求ヘッダー

要求本文

応答

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

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

例

例 1: 既定のプロパティ

要求

応答

例 2: 3 つのプロパティの選択

要求

応答

例 3: 代替の最小限の応答の動作

要求

応答

関連項目

フィードバック

クエリパラメーター

OData クエリパラメーター