Dient zum Abrufen inkrementeller Änderungen für Benutzer.

Artikel
03/09/2023
8 Minuten Lesedauer

Mit der Delta-Abfrage in Microsoft Graph können Sie Ergänzungen, Löschungen oder Aktualisierungen unterstützter Ressourcen abfragen. Sie wird durch eine Reihe von Delta -Anforderungen aktiviert. Bei Benutzern können Sie mit der Delta-Abfrage Änderungen feststellen, ohne den gesamten Satz von Benutzern abrufen zu müssen, um Änderungen zu vergleichen.

Clients, die Benutzer mit einem lokalen Profilspeicher synchronisieren, können die Delta-Abfrage sowohl für ihre anfängliche vollständige Synchronisierung als auch für nachfolgende schrittweise erfolgende Synchronisierungen verwenden. Normalerweise führt ein Client eine erste vollständige Synchronisierung aller Benutzer in einem Mandanten durch und erhält dann regelmäßig schrittweise erfolgende Änderungen an den Benutzern.

Nachverfolgen von Änderungen an Benutzern

Nachverfolgen von Benutzeränderungen über eine oder mehrere GET-Anforderungen mit der Delta-Funktion. Die GET-Anforderung ähnelt einer Nutzerlisten-Anforderung, mit Ausnahme der folgenden zusätzlichen Objekte in der URL:

Die Delta-Funktion.
Ein Statustoken (deltaToken oder skipToken) aus dem vorherigen GET-Delta-Funktionsaufruf.

Beispiel: Nachverfolgung von Änderungen an Benutzern

Das folgende Beispiel zeigt eine Reihe von Anforderungen zum Nachverfolgen von Änderungen an Benutzern:

Eine ursprüngliche Anforderung und Antwort
Eine nextLink-Anforderung und Antwort
Eine letzte nextLink-Anforderung und Antwort
Eine deltaLink-Anforderung und deltaLink-Antwort

Notieren Sie sich Folgendes aus den Antworten:

Wenn der Benutzer gelöscht wurde, enthält das Element eine Anmerkung: @removed mit einem Wert von "reason": "changed".
Wenn der Benutzer dauerhaft gelöscht wurde, enthält das Element eine Anmerkung: @removed mit einem Wert von "reason": "deleted".
Wenn der Benutzer erstellt oder wiederhergestellt wird, gibt es keine Anmerkung.

Ursprüngliche Anforderung

Um Änderungen in der Benutzerressource nachzuverfolgen, stellen Sie eine Anforderung, und schließen Sie die Delta-Funktion als URL-Segment ein.

Beachten Sie die folgenden Elemente:

Der optionale $select-Abfrageparameter wird in die Anforderung eingeschlossen, um zu veranschaulichen, wie Abfrageparameter automatisch in zukünftige Anforderungen eingeschlossen werden.
Die ursprüngliche Anforderung enthält keinen Zustands-Token. Statustoken werden in nachfolgenden Anforderungen verwendet.

GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,givenName,surname


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.Delta.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","givenName","surname" };
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/users/delta')
	.select('displayName,givenName,surname')
	.get();


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

UserDeltaCollectionPage delta = graphClient.users()
	.delta()
	.buildRequest()
	.select("displayName,givenName,surname")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphconfig.UsersDelta()RequestBuilderGetQueryParameters{
	Select: [] string {"displayName","givenName","surname"},
}
configuration := &graphconfig.UsersDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Delta().Get(context.Background(), configuration)


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();

$queryParameters = new DeltaRequestBuilderGetQueryParameters();
$queryParameters->select = ["displayName","givenName","surname"];

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->users()->delta()->get($requestConfiguration);

Ursprüngliche Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und das user-Sammlungsobjekt im Antworttext zurückgegeben. Wenn der gesamte Satz von Benutzern zu groß ist, enthält die Antwort auch einen @odata.nextLink Status-Token in einem @odata.nextLink Parameter.

In diesem Beispiel wird eine @odata.nextLink URL zurückgegeben, die angibt, dass in der Sitzung weitere Seiten mit Daten abgerufen werden müssen. Der $select Abfrageparameter aus der ursprünglichen Anforderung wird in der @odata.nextLink URL codiert.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users(displayName,givenName,surname)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa",
  "value": [
    {
      "displayName":"Cameron White",
      "givenName":"Cameron",
      "surname":"White",
      "id":"ffff7b1a-13b6-477b-8c0c-380905cd99f7"
    },
    {
      "displayName":"Delia Dennis",
      "givenName":"Delia",
      "surname":"Dennis",
      "id":"605d1257-ffff-40b6-8e6f-528a53f5dc55"
    },
    {
      "id": "86462606-fde0-4fc4-9e0c-a20eb73e54c6",
      "@removed": {
        "reason": "deleted"
      }
    },
    {
      "displayName": "Conf Room Adams",
      "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
    }
  ]
}

nextLink-Anforderung

Die zweite Anforderung gibt das aus der vorherigen Antwort zurückgegebene skipToken an. Beachten Sie, dass der $select Parameter codiert und in der skipTokenenthalten ist.

GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.Delta.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Skiptoken = "oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/users/delta')
	.skiptoken('oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa')
	.get();


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

UserDeltaCollectionPage delta = graphClient.users()
	.delta()
	.buildRequest()
	.skipToken("oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestSkiptoken := "oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa"

requestParameters := &graphconfig.UsersDelta()RequestBuilderGetQueryParameters{
	Skiptoken: &requestSkiptoken,
}
configuration := &graphconfig.UsersDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Delta().Get(context.Background(), configuration)


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();

$queryParameters = new DeltaRequestBuilderGetQueryParameters();
$queryParameters->skiptoken = "oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->users()->delta()->get($requestConfiguration);

nextLink-Antwort

Die Antwort enthält einen anderen @odata.nextLink mit einem neuen skipToken Wert, der angibt, dass weitere Änderungen, die für Benutzer nachverfolgt wurden, verfügbar sind. Verwenden Sie die @odata.nextLink URL in weiteren Anforderungen, bis @odata.deltaLink in der endgültigen Antwort eine URL (in einem @odata.deltaLink Parameter) zurückgegeben wird, auch wenn der Wert eine leere Anordnung ist.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"Mallory Cortez",
      "givenName":"Mallory",
      "surname":"Cortez",
      "id":"d8c37826-ffff-4cae-b348-e2725b1e814b"
    },
    {
      "displayName":"Diego Sicilian",
      "givenName":"Diego",
      "surname":"Sicilian",
      "id":"8b1ee412-cd8f-4d59-ffff-24010edb9f1f"
    }
  ]
}

Letzte nextLink-Anforderung

Die dritte Anforderung verwendet die neueste skipToken, die von der letzten Synchronisierungsanforderung zurückgegeben wurde.

GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.Delta.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Skiptoken = "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/users/delta')
	.skiptoken('pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7')
	.get();


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

UserDeltaCollectionPage delta = graphClient.users()
	.delta()
	.buildRequest()
	.skipToken("pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestSkiptoken := "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7"

requestParameters := &graphconfig.UsersDelta()RequestBuilderGetQueryParameters{
	Skiptoken: &requestSkiptoken,
}
configuration := &graphconfig.UsersDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Delta().Get(context.Background(), configuration)


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();

$queryParameters = new DeltaRequestBuilderGetQueryParameters();
$queryParameters->skiptoken = "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->users()->delta()->get($requestConfiguration);

Letzte nextLink-Antwort

Wenn eine @odata.deltaLink URL zurückgegeben wird, gibt es keine weiteren Daten über den vorhandenen Status der Benutzerobjekte. Für zukünftige Anforderungen verwendet die Anwendung die @odata.deltaLink URL, um von weiteren Änderungen an Benutzern zu erfahren. Speichern Sie die deltaToken und verwenden Sie diese in der nachfolgenden Anforderungs-URL, um weitere Änderungen an Benutzern zu ermitteln.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460",
  "value": [
    {
      "displayName":"Lidia Holloway",
      "givenName":"Lidia",
      "surname":"Holloway",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "displayName":"Patti Fernandez",
      "givenName":"Patti",
      "surname":"Fernandez",
      "id":"f6ede700-27d0-4c42-bfb9-4dffff43c74a"
    }
  ]
}

deltaLink-Anforderung

Mithilfe der deltaToken aus der letzten Antwort erhalten Sie Änderungen (Ergänzungen, Löschungen oder Aktualisierungen) an Benutzern seit der letzten Anforderung.

GET https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.Delta.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Deltatoken = "oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460";
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


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

UserDeltaCollectionPage delta = graphClient.users()
	.delta()
	.buildRequest()
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestDeltatoken := "oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460"

requestParameters := &graphconfig.UsersDelta()RequestBuilderGetQueryParameters{
	Deltatoken: &requestDeltatoken,
}
configuration := &graphconfig.UsersDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Delta().Get(context.Background(), configuration)


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();

$queryParameters = new DeltaRequestBuilderGetQueryParameters();
$queryParameters->deltatoken = "oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->users()->delta()->get($requestConfiguration);

deltaLink-Antwort

Wenn keine Änderungen aufgetreten sind, wird eine @odata.deltaLink ohne Ergebnisse zurückgegeben - Die Wert-Eigenschaft ist eine leere Anordnung.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=MF1LuFYbK6Lw4DtZ4o9PDrcGekRP65WEJfDmM0H26l4v9zILCPFiPwSAAeRBghxgiwsXEfywcVQ9R8VEWuYAB50Yw3KvJ-8Z1zamVotGX2b_AHVS_Z-3b0NAtmGpod",
  "value": []
}

Wenn Änderungen aufgetreten sind, ist eine Auflistung geänderter Benutzerobjekte enthalten. Die Antwort enthält zudem @odata.nextLink – falls mehrere Seiten mit Änderungen abgerufen werden müssen – oder @odata.deltaLink. Implementieren Sie das gleiche Muster, dem @odata.nextLink endgültigen Aufruf folgen und behalten Sie es für zukünftige Aufrufe @odata.deltaLink bei.

Hinweis

Bei dieser Anforderung kann es zu Replikationsverzögerungen für Benutzer kommen, die kürzlich erstellt, aktualisiert oder gelöscht wurden. Wiederholen Sie die @odata.nextLink oder @odata.deltaLink nach einiger Zeit, um die neuesten Änderungen abzurufen.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=MF1LuFYbK6Lw4DtZ4o9PDrcGekRP65WEJfDmM0H26l4v9zILCPFiPwSAAeRBghxgiwsXEfywcVQ9R8VEWuYAB50Yw3KvJ-8Z1zamVotGX2b_AHVS_Z-3b0NAtmGpod",
  "value": [
    {
      "displayName":"MOD Administrator",
      "givenName":"MOD",
      "surname":"Administrator",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "id":"8ffff70c-1c63-4860-b963-e34ec660931d",
      "@removed": {
         "reason": "changed"
      }
    }
  ]
}

Siehe auch

Microsoft Graph-Delta-Abfrage – Übersicht.