user: deltauser: delta

Rufen Sie neu erstellt, aktualisierte oder gelöschte Benutzer ab, ohne ein vollständiges Lesen der gesamten Benutzersammlung durchführen zu müssen.Get newly created, updated, or deleted users without having to perform a full read of the entire user collection. Weitere Informationen finden Sie unter Änderungen nachverfolgen.See Track changes for details.

BerechtigungenPermissions

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.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

BerechtigungstypPermission type Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged)
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.AllUser.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) User.Read, User.ReadWriteUser.Read, User.ReadWrite
AnwendungApplication User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.AllUser.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

HTTP-AnforderungHTTP request

Um Änderungen nachzuverfolgen, führen Sie zunächst eine Anforderung einschließlich der delta-Funktion für die Benutzerressource aus.To begin tracking changes, you make a request including the delta function on the users resource.

GET /users/delta

AbfrageparameterQuery parameters

Beim Nachverfolgen von Änderungen in Benutzern wird eine Runde von einem oder mehreren delta-Funktionsaufrufen ausgeführt.Tracking changes in users incurs a round of one or more delta function calls. Wenn Sie Abfrageparameter (außer $deltatoken und $skiptoken) verwenden, müssen Sie sie in der ursprünglichen Delta-Anforderung angeben.If you use any query parameter (other than $deltatoken and $skiptoken), you must specify it in the initial delta request. Microsoft Graph codiert automatisch alle angegebenen Parameter in den Tokenteil der in der Antwort enthaltenen nextLink- oder deltaLink-URL.Microsoft Graph automatically encodes any specified parameters into the token portion of the nextLink or deltaLink URL provided in the response.

Sie müssen alle gewünschten Abfrageparameter nur einmal im Vorfeld angeben.You only need to specify any desired query parameters once upfront.

In nachfolgenden Anforderungen können Sie die nextLink- oder deltaLink-URL aus der vorherigen Antwort kopieren und anwenden, da diese URL bereits die codierten gewünschten Parameter enthält.In subsequent requests, copy and apply the nextLink or deltaLink URL from the previous response, as that URL already includes the encoded, desired parameters.

AbfrageparameterQuery parameter TypType BeschreibungDescription
$deltatoken$deltatoken stringstring Ein Statustoken, das in der deltaLink-URL des vorhergehenden delta-Funktionsaufrufs für dieselbe Benutzersammlung zurückgegeben wird und den Abschluss dieser Runde der Änderungsnachverfolgung anzeigt. Speichern Sie die gesamte deltaLink-URL einschließlich dieses Tokens, und wenden Sie sie in der ersten Anforderung der nächsten Änderungsnachverfolgungsrunde für diese Sammlung an.A state token returned in the deltaLink URL of the previous delta function call for the same user collection, indicating the completion of that round of change tracking. Save and apply the entire deltaLink URL including this token in the first request of the next round of change tracking for that collection.
$skiptoken$skiptoken stringstring Ein Statustoken, das in der nextLink-URL des vorhergehenden delta-Funktionsaufrufs zurückgegeben wird und anzeigt, dass in derselben Benutzersammlung weitere Änderungen zum Nachverfolgen vorliegen.A state token returned in the nextLink URL of the previous delta function call, indicating there are further changes to be tracked in the same user collection.

OData-AbfrageparameterOData query parameters

Diese Methode unterstützt die optionalen OData-Abfrageparameter zur Anpassung der Antwort.This method supports optional OData Query Parameters to help customize the response.

  • 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.You can use a $select query parameter as in any GET request to specify only the properties your need for best performance. The id property is always returned.
  • Es besteht eingeschränkte Unterstützung für $filter:There is limited support for $filter:
    • Der einzige unterstützte $filter-Ausdruck dient zum Nachverfolgen von Änderungen an einem bestimmten Objekt: $filter=id+eq+{value}.The only supported $filter expression is for tracking changes on a specific object: $filter=id+eq+{value}. Sie können mehrere Objekte filtern.You can filter multiple objects. Beispiel: https://graph.microsoft.com/v1.0/users/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'.For example, https://graph.microsoft.com/v1.0/users/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.There is a limit of 50 filtered objects.

AnforderungsheaderRequest headers

NameName BeschreibungDescription
AuthorizationAuthorization Bearer <token>Bearer <token>
Content-TypeContent-Type application/jsonapplication/json
PreferPrefer return=minimalreturn=minimal

Wenn Sie für diese Kopfzeile eine Aufforderung festlegen, die ein deltaLink verwendet, würden nur die Objekteigenschaften zurückgegeben werden, die seit der letzten Runde geändert wurden.Specifying this header with a request that uses a deltaLink would return only the object properties that have changed since the last round. Optional.Optional.

AnforderungstextRequest body

Geben Sie für diese Methode keinen Anforderungstext an.Do not supply a request body for this method.

AntwortResponse

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und das user-Sammlungsobjekt im Antworttext zurückgegeben.If successful, this method returns 200 OK response code and user collection object in the response body. Die Antwort enthält auch eine nextLink-URL oder eine deltaLink-URL.The response also includes a nextLink URL or a deltaLink URL.

  • Wenn eine nextLink-URL zurückgegeben wird:If a nextLink URL is returned:

    • Dies bedeutet, es gibt zusätzliche Seiten mit Daten, die in der Sitzung abgerufen werden müssen.This indicates there are additional pages of data to be retrieved in the session. Die Anwendung nimmt weiterhin Anforderungen über die nextLink-URL vor, bis eine deltaLink-URL in der Antwort zurückgegeben wird.The application continues making requests using the nextLink URL until a deltaLink URL is included in the response.
    • Die Antwort enthält die gleiche Gruppe von Eigenschaften, wie in der ersten Anforderung einer Delta-Abfrage.The response includes the same set of properties as in the initial delta query request. Dadurch können Sie den vollständigen aktuellen Status der Objekte beim Initiieren des Delta-Zyklus erfassen.This allows you to capture the full current state of the objects when initiating the delta cycle.
  • Wenn eine deltaLink-URL zurückgegeben wird:If a deltaLink URL is returned:

    • Dies bedeutet, es gibt keine weiteren Daten über den derzeitigen Status der zurückzugebenden Ressource.This indicates there is no more data about the existing state of the resource to be returned. Speichern Sie und verwenden Sie die deltaLink-URL, um Informationen über die Änderungen an der Ressource in der nächsten Runde zu erhalten.Save and use the deltaLink URL to learn about changes to the resource in the next round.
    • 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 deltaLink erstellt wurde.You have a choice to specify the Prefer:return=minimal header, to include in the response values for only the properties that have changed since the time the deltaLink was issued.

Standard: Es werden dieselben Eigenschaften zurückgegeben wie die der ursprünglichen Delta-AnfrageDefault: return the same properties as initial delta request

Standardmäßig geben Abfragen, die deltaLink oder nextLink verwenden, dieselben Eigenschaften zurück, wie sie in der ersten Delta-Abfrage ausgewählt wurden. Diese geschieht wie folgt:By default, requests using a deltaLink or nextLink return the same properties as selected in the initial delta query in the following ways:

  • Wenn die Eigenschaft geändert wurde, ist der neue Wert in der Antwort enthalten.If the property has changed, the new value is included in the response. Dies schließt Eigenschaften ein, die auf einen Null-Wert festgelegt werden.This includes properties being set to null value.
  • Wenn die Eigenschaft nicht geändert wurde, ist der alte Wert in der Antwort enthalten.If the property has not changed, the old value is included in the response.
  • Wenn eine Eigenschaft zuvor nie festgelegt wurde, ist sie überhaupt nicht in der Antwort enthalten.If the property has never been set before it will not be included in the response at all.

Hinweis: Durch das Betrachten der Antwort kann nicht festgestellt werden, ob sich eine Eigenschaft ändert oder nicht.Note: With this behavior, by looking at the response it is not possible to tell whether a property is changing or not. Darüber hinaus sind Delta-Antworten in der Regel groß, da sie alle Eigenschaftenwerte enthalten, wie in Beispiel 2 gezeigt.Also, the delta responses tend to be large because they contain all property values - as shown in the second example below.

Alternative: nur die geänderten Eigenschaften zurückgebenAlternative: return only the changed properties

Das Hinzufügen eines optionalen Anfrage-Headers – prefer:return=minimal – führt zu folgendem Verhalten:Adding an optional request header - prefer:return=minimal - results in the following behavior:

  • Wenn die Eigenschaft geändert wurde, ist der neue Wert in der Antwort enthalten.If the property has changed, the new value is included in the response. Dies schließt Eigenschaften ein, die auf einen Null-Wert festgelegt werden.This includes properties being set to null value.
  • Wenn die Eigenschaft nicht geändert wurde, ist die Eigenschaft überhaupt nicht in der Antwort enthalten.If the property has not changed, the property is not included in the response at all. (Anders als beim Standardverhalten).(Different from the default behavior.)

Hinweis: Die Kopfzeile kann zu jedem Zeitpunkt im Delta-Zyklus zu einer deltaLink-Abfrage hinzugefügt werden.Note: The header can be added to a deltaLink request at any point in time in the delta cycle. Die Kopfzeile wirkt sich nur auf die Gruppe von Eigenschaften, die in der Antwort enthalten sind, aus und beeinflusst nicht, wie die Delta-Abfrage ausgeführt wird.The header only affects the set of properties included in the response and it does not affect how the delta query is executed. Siehe Beispiel 3.See Example 3.

BeispieleExamples

Beispiel 1: StandardeigenschaftenExample 1: Default properties

AnforderungRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request. Es gibt keinen $select-Parameter, daher wird Standardsatz von Eigenschaften nachverfolgt und zurückgegeben.There is no $select parameter, so a default set of properties is tracked and returned.

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

AntwortResponse

Im folgenden finden Sie ein Beispiel für die Antwort bei Verwendung von deltaLink aus der Abfrage-Initialisierung.The following is an example of the response when using deltaLink obtained from the query initialization.

Hinweis: Das hier gezeigte Antwortobjekt wurde möglicherweise zur besseren Lesbarkeit gekürzt. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "businessPhones": [
          "businessPhones-value"
      ],
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "jobTitle": "jobTitle-value",
      "mail": "mail-value",
      "mobilePhone": "mobilePhone-value",
      "officeLocation": "officeLocation-value",
      "preferredLanguage": "preferredLanguage-value",
      "surname": "surname-value",
      "userPrincipalName": "userPrincipalName-value",
      "id": "id-value"
    }
  ]
}

Beispiel 2: Auswählen von drei EigenschaftenExample 2: Selecting three properties

AnforderungRequest

Das nächste Beispiel zeigt die ursprüngliche Anforderung mit drei ausgewählten Eigenschaften für Änderungen nachverfolgen und standardmäßigem Antwortverhalten.The next example shows the initial request selecting 3 properties for change tracking, with default response behavior:

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

AntwortResponse

Im folgenden finden Sie ein Beispiel für die Antwort bei Verwendung von deltaLink aus der Abfrage-Initialisierung.The following is an example of the response when using deltaLink obtained from the query initialization. Beachten Sie, dass alle drei Eigenschaften sind in der Antwort enthalten sind, und nicht bekannt ist, welche seit dem Abrufen von deltaLink geändert wurden.Note that all 3 properties are included in the response and it is not known which ones have changed since the deltaLink was obtained.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": "jobTitle-value",
      "mobilePhone": null
    }
  ]
}

Beispiel 3: Alternatives minimales AntwortverhaltenExample 3: Alternative minimal response behavior

AnforderungRequest

Das nächste Beispiel zeigt die ursprüngliche Anforderung mit drei ausgewählten Eigenschaften für Änderungen nachverfolgen und alternativem minimalen Antwortverhalten.The next example shows the initial request selecting 3 properties for change tracking, with alternative minimal response behavior:

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

AntwortResponse

Im folgenden finden Sie ein Beispiel für die Antwort bei Verwendung von deltaLink aus der Abfrage-Initialisierung.The following is an example of the response when using deltaLink obtained from the query initialization. Beachten Sie, dass die mobilePhone-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.Note that the mobilePhone property is not included, which means it has not changed since the last delta query; displayName and jobTitle are included which means their values have changed.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": null
    }
  ]
}

Siehe auchSee also