orgContact: delta

Artikel
07/18/2022
9 Minuten Lesedauer

Namespace: microsoft.graph

Rufen Sie neu erstellte, aktualisierte oder gelöschte Organisationskontakte ab, ohne die gesamte Sammlung vollständig lesen zu müssen. Details finden Sie unter Änderungsnachverfolgung.

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.

Berechtigungstyp	Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto)	OrgContact.Read.All, Directory.Read.All, Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto)	Nicht unterstützt
Anwendung	OrgContact.Read.All, Directory.Read.All, Directory.ReadWrite.All

HTTP-Anforderung

Um mit der Nachverfolgung von Änderungen zu beginnen, stellen Sie eine Anforderung einschließlich der Delta-Funktion für die Kontaktressource.

GET /contacts/delta

Abfrageparameter

Das Nachverfolgen von Änderungen an Organisationskontakten verursacht eine Runde von einem oder mehreren Delta-Funktionsaufrufen. Wenn Sie Abfrageparameter (außer $deltatoken und $skiptoken) verwenden, müssen Sie sie in der ursprünglichen Delta-Anforderung angeben. Microsoft Graph codiert automatisch alle angegebenen Parameter in den Tokenteil der in der Antwort enthaltenen @odata.nextLink- oder @odata.deltaLink-URL.

Sie müssen abfrageparameter nur einmal im Voraus angeben.

Kopieren Sie in nachfolgenden Anforderungen die URL @odata.deltaLink aus der @odata.nextLink vorherigen Antwort, und wenden Sie sie an. Diese URL enthält bereits die codierten Parameter.

Abfrageparameter	Typ	Beschreibung
$deltatoken	string	Ein Statustoken, das in der `@odata.deltaLink` URL des vorherigen Delta-Funktionsaufrufs für dieselbe Kontaktsammlung der Organisation zurückgegeben wird und den Abschluss dieser Runde der Änderungsnachverfolgung angibt. Speichern Und wenden Sie die gesamte `@odata.deltaLink` URL, einschließlich dieses Tokens, in der ersten Anforderung der nächsten Runde der Änderungsnachverfolgung für diese Sammlung an.
$skiptoken	string	Ein Statustoken, das in der `@odata.nextLink` URL des vorherigen Delta-Funktionsaufrufs zurückgegeben wird und angibt, dass weitere Änderungen in derselben Organisationskontaktsammlung nachverfolgt werden müssen.

OData-Abfrageparameter

Diese Methode unterstützt optionale OData-Abfrageparameter, um die Antwort anzupassen.

Sie können wie bei jeder GET-Anforderung den Abfrageparameter $select verwenden, um zwecks Leistungsoptimierung nur die benötigten Eigenschaften anzugeben. Die Eigenschaft id wird immer zurückgegeben.
Es besteht eingeschränkte Unterstützung für $filter:
- Der einzige unterstützte $filter-Ausdruck dient zum Nachverfolgen von Änderungen an einem bestimmten Objekt: $filter=id+eq+{value}. Sie können mehrere Objekte filtern. Beispiel: https://graph.microsoft.com/v1.0/contacts/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'. Es gilt ein Grenzwert von 50 gefilterten Objekten.

Anforderungsheader

Name	Beschreibung
Authorization	Bearer <token>. Erforderlich.
Prefer	return=minimal Wenn Sie für diese Kopfzeile eine Aufforderung festlegen, die ein `@odata.deltaLink` verwendet, würden nur die Objekteigenschaften zurückgegeben werden, die seit der letzten Runde geändert wurden. Optional.

Anforderungstext

Geben Sie für diese Methode keinen Anforderungstext an.

Antwort

Wenn die Methode erfolgreich verläuft, werden der 200 OK Antwortcode und das objekt der ab orgContact-Auflistung im Antworttext zurückgegeben. Die Antwort enthält auch eine @odata.nextLink-URL oder eine @odata.deltaLink-URL.

Wenn eine @odata.nextLink-URL zurückgegeben wird:
- Dies gibt an, dass in der Sitzung zusätzliche Seiten mit Daten abgerufen werden müssen. Die Anwendung nimmt weiterhin Anforderungen über die @odata.nextLink-URL vor, bis eine @odata.deltaLink-URL in der Antwort zurückgegeben wird.
- Die Antwort enthält die gleiche Gruppe von Eigenschaften, wie in der ersten Anforderung einer Delta-Abfrage. Dadurch können Sie den vollständigen aktuellen Status der Objekte beim Initiieren des Delta-Zyklus erfassen.
Wenn eine @odata.deltaLink-URL zurückgegeben wird:
- Dies weist darauf hin, dass keine weiteren Daten über den vorhandenen Zustand der zurückzugebenden Ressource vorhanden sind. Speichern Sie und verwenden Sie die @odata.deltaLink-URL, um Informationen über die Änderungen an der Ressource in der nächsten Runde zu erhalten.
- Sie können die Prefer:return=minimal-Kopfzeile so festlegen, dass in der Antwort nur die Eigenschaften Werte enthalten sind, die seit dem Zeitpunkt geändert wurden, an dem die @odata.deltaLink erstellt wurde.

Standard: Es werden dieselben Eigenschaften zurückgegeben wie die der ursprünglichen Delta-Anfrage

Standardmäßig geben Abfragen, die @odata.deltaLink oder @odata.nextLink verwenden, dieselben Eigenschaften zurück, wie sie in der ersten Delta-Abfrage ausgewählt wurden. Diese geschieht wie folgt:

Wenn die Eigenschaft geändert wurde, ist der neue Wert in der Antwort enthalten. Dies schließt Eigenschaften ein, die auf einen Null-Wert festgelegt werden.
Wenn die Eigenschaft nicht geändert wurde, ist der alte Wert in der Antwort enthalten.
Wenn die Eigenschaft noch nie zuvor festgelegt wurde, wird sie überhaupt nicht in die Antwort einbezogen.

Alternative: nur die geänderten Eigenschaften zurückgeben

Das Hinzufügen eines optionalen Anfrage-Headers – prefer:return=minimal – führt zu folgendem Verhalten:

Wenn die Eigenschaft geändert wurde, ist der neue Wert in der Antwort enthalten. Dies schließt Eigenschaften ein, die auf einen Null-Wert festgelegt werden.
Wenn die Eigenschaft nicht geändert wurde, ist die Eigenschaft überhaupt nicht in der Antwort enthalten. (Im Gegensatz zum Standardverhalten.)

Beispiele

Beispiel 1: Standardeigenschaften

Anforderung

Nachfolgend sehen Sie ein Beispiel der Anforderung. Es gibt keinen $select-Parameter, daher wird Standardsatz von Eigenschaften nachverfolgt und zurückgegeben.

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

Antwort

Im folgenden finden Sie ein Beispiel für die Antwort bei Verwendung von @odata.deltaLink aus der Abfrage-Initialisierung.

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"
    }
  ]
}

Beispiel 2: Auswählen von drei Eigenschaften

Anforderung

Das nächste Beispiel zeigt die ursprüngliche Anforderung mit drei ausgewählten Eigenschaften für Änderungen nachverfolgen und standardmäßigem Antwortverhalten.

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"

Antwort

Im folgenden finden Sie ein Beispiel für die Antwort bei Verwendung von @odata.deltaLink aus der Abfrage-Initialisierung. Beachten Sie, dass alle drei Eigenschaften sind in der Antwort enthalten sind, und nicht bekannt ist, welche seit dem Abrufen von @odata.deltaLink geändert wurden.

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
    }
  ]
}

Beispiel 3: Alternatives minimales Antwortverhalten

Anforderung

Das nächste Beispiel zeigt die ursprüngliche Anforderung mit drei ausgewählten Eigenschaften für Änderungen nachverfolgen und alternativem minimalen Antwortverhalten.

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"

Antwort

Im folgenden finden Sie ein Beispiel für die Antwort bei Verwendung von @odata.deltaLink aus der Abfrage-Initialisierung. Beachten Sie, dass die mail-Eigenschaft nicht enthalten ist, was bedeutet, dass sie seit der letzten Delta-Abfrage nicht geändert wurde; displayName und jobTitle sind enthalten, was bedeutet, dass sich diese Werte geändert haben.

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
    }
  ]
}

Siehe auch

Verwenden einer Delta-Abfrage zum Nachverfolgen von Änderungen in Microsoft Graph-Daten.

orgContact: delta

Berechtigungen

HTTP-Anforderung

Abfrageparameter

OData-Abfrageparameter

Anforderungsheader

Anforderungstext

Antwort

Standard: Es werden dieselben Eigenschaften zurückgegeben wie die der ursprünglichen Delta-Anfrage

Alternative: nur die geänderten Eigenschaften zurückgeben

Beispiele

Beispiel 1: Standardeigenschaften

Anforderung

Antwort

Beispiel 2: Auswählen von drei Eigenschaften

Anforderung

Antwort

Beispiel 3: Alternatives minimales Antwortverhalten

Anforderung

Antwort

Siehe auch

Feedback