Freigeben über

directoryObject: delta

  • Artikel

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Namespace: microsoft.graph

Rufen Sie neu erstellte, aktualisierte oder gelöschte Verzeichnisobjekte ab, ohne die gesamte directoryObject-Auflistung vollständig zu lesen. Weitere Informationen finden Sie unter Verwenden von Deltaabfragen zum Nachverfolgen von Änderungen in Microsoft Graph-Daten .

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ✅ ✅ ✅

Berechtigungen

In der folgenden Tabelle sind die Berechtigungen mit den geringsten Berechtigungen aufgeführt, die für jeden Ressourcentyp erforderlich sind, wenn diese API aufgerufen wird. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie unter Berechtigungen.

Unterstützte Ressource Delegiert (Geschäfts-, Schul- oder Unikonto) App Delegiert (persönliches Microsoft-Konto)
application Application.Read.All Application.Read.All Nicht unterstützt
administrativeUnit AdministrativeUnit.Read.All AdministrativeUnit.Read.All Nicht unterstützt
device Device.Read.All Device.Read.All Nicht unterstützt
directoryRole RoleManagement.Read.Directory RoleManagement.Read.Directory Nicht unterstützt
group Group.Read.All Group.Read.All Nicht unterstützt
orgContact OrgContact.Read.All OrgContact.Read.All Nicht unterstützt
servicePrincipal Application.Read.All Application.Read.All Nicht unterstützt
user User.Read.All User.Read.All Nicht unterstützt

HTTP-Anforderung

Nachverfolgen von Änderungen für eine Auflistung eines Verzeichnisobjekttyps.

GET /directoryObjects/delta?$filter=isof('microsoft.graph.application')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.administrativeUnit')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.device')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.directoryRole')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.group')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.orgContact')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.servicePrincipal')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.user')

Nachverfolgen von Änderungen für ein Verzeichnisobjekt.

GET /directoryObjects/delta?$filter=id eq '{id}'

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.
  • Beim Filtern mehrerer Objekte, z. B. , /directoryObjects/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'gilt ein Grenzwert von 50 Filterausdrücken.
  • Sie können die $filter Syntaxen kombinieren. Beispiel: $filter=isof('{resource type}') or id eq '{id}'. Dadurch wird eine Schnittmenge von -Objekten bereitgestellt, die durch den Abgleich {resource type} und den Ressourcentyp von {id}angegeben werden.

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
Content-Type application/json
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 keinen Anforderungstext für diese Methode an.

Antwort

Bei erfolgreicher Ausführung gibt die Methode den Antwortcode und das directoryObject-Auflistungsobjekt im Antworttext zurück200 OK. Die Antwort enthält auch ein Zustandstoken, das entweder eine @odata.nextLink URL oder eine @odata.deltaLink URL ist.

  • Wenn eine @odata.nextLink-URL zurückgegeben wird:

    • Dies deutet darauf hin, dass in der Sitzung weitere Seiten mit Daten abgerufen werden sollen. Die Anwendung stellt weiterhin Anforderungen mithilfe der @odata.nextLink URL, bis eine @odata.deltaLink URL in der Antwort enthalten ist.
    • 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 deutet darauf hin, dass keine Weiteren Daten zum vorhandenen Zustand der Ressource vorhanden sind, die zurückgegeben werden soll. 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 sich die Eigenschaft nicht geändert hat, wird der alte Wert in die Antwort aufgenommen.
  • Wenn eine Eigenschaft zuvor nie festgelegt wurde, ist sie überhaupt nicht in der Antwort enthalten.

Hinweis: Durch das Betrachten der Antwort kann nicht festgestellt werden, ob sich eine Eigenschaft ändert oder nicht. Außerdem sind die Deltaantworten in der Regel groß, da sie alle Eigenschaftswerte enthalten (siehe Beispiel 3).

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. (Anders als beim Standardverhalten).

Hinweis: Die Kopfzeile kann zu jedem Zeitpunkt im Delta-Zyklus zu einer @odata.deltaLink-Abfrage hinzugefügt werden. 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. Siehe Beispiel 4.

Beispiele

Beispiel 1: Abrufen von Änderungen für eine Sammlung von Benutzern und Gruppen

Anforderung

Das folgende Beispiel zeigt eine Anforderung, die den $filter=isof('{resource type}') Parameter für Benutzer und Gruppen verwendet. Da kein $select Parameter vorhanden ist, wird ein Standardsatz von Eigenschaften nachverfolgt und zurückgegeben.

GET https://graph.microsoft.com/beta/directoryObjects/delta?filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')

Antwort

Hier sehen Sie ein Beispiel für die Antwort bei Verwendung von @odata.deltaLink , die aus der Abfrageinitialisierung mit $filter=isof('{resource type}')abgerufen wird. Beachten Sie das Vorhandensein der members@delta-Eigenschaft , die die IDs von Memberobjekten in der Gruppe enthält.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects","@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvY1FSSc_",
  "value":[
    {
      "@odata.type": "#microsoft.graph.user",
      "businessPhones": [
          "+1 425 555 0109"
      ],
      "displayName": "Adele Vance",
      "givenName": "Adele",
      "jobTitle": "Retail Manager",
      "mail": "AdeleV@contoso.com",
      "mobilePhone": "+1 425 555 0109",
      "officeLocation": "18/2111",
      "preferredLanguage": "en-US",
      "surname": "Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    },
    {
      "@odata.type": "#microsoft.graph.group",
      "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",
      "id": "72052a9a-c466-4995-8210-95a1c1221995",
      "members@delta": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "693acd06-2877-4339-8ade-b704261fe7a0"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49320844-be99-4164-8167-87ff5d047ace"
        }
      ]
    }
  ]
}

Beispiel 2: Abrufen einer Auflistung von Änderungen für ein Verzeichnisobjekt

Anforderung

Das folgende Beispiel zeigt die Anforderung mit dem $filter=id eq '{id}' -Parameter. Da kein $select Parameter vorhanden ist, wird ein Standardsatz von Eigenschaften nachverfolgt und zurückgegeben.

GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=id eq '87d349ed-44d7-43e1-9a83-5f2406dee5bd'

Antwort

Hier sehen Sie ein Beispiel für die Antwort bei Verwendung von @odata.deltaLink , die aus der Abfrageinitialisierung mit $filter=id eq '{id}'abgerufen wird.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "@odata.type": "#microsoft.graph.group",
      "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",
      "id": "72052a9a-c466-4995-8210-95a1c1221995",
      "members@delta": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "693acd06-2877-4339-8ade-b704261fe7a0"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49320844-be99-4164-8167-87ff5d047ace"
        }
      ]
    }
  ]
}

Beispiel 3: Abrufen von Änderungen an bestimmten Eigenschaften für eine Sammlung von Benutzern und Gruppen

Anforderung

Das folgende Beispiel zeigt die anfängliche Anforderung, die jeweils eine Eigenschaft eines Benutzers und einer Gruppe für die Änderungsnachverfolgung mit standardem Antwortverhalten auswählt:

GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')&$select=microsoft.graph.user/surname,microsoft.graph.group/displayName

Antwort

Hier sehen Sie ein Beispiel für die Antwort, wenn sie aus @odata.deltaLink der Abfrageinitialisierung abgerufen wird. Beide Eigenschaften sind in der Antwort enthalten, und es ist nicht bekannt, welche sich seit dem Abrufen von @odata.deltaLink geändert haben.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "@odata.type": "#microsoft.graph.user",
      "surname": "Vance",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    },
    {
      "@odata.type": "#microsoft.graph.group",
      "displayName":"All Company",
      "id": "72052a9a-c466-4995-8210-95a1c1221995",
    }
  ]
}

Beispiel 4: Abrufen bestimmter Eigenschaften nur, wenn sie für eine Sammlung von Benutzern und Gruppen geändert wurden

Anforderung

Das folgende Beispiel zeigt die anfängliche Anforderung, die jeweils eine Eigenschaft eines Benutzers und einer Gruppe für die Änderungsnachverfolgung mit einem alternativen minimalen Antwortverhalten auswählt:

GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')&$select=microsoft.graph.user/surname,microsoft.graph.group/displayName
Prefer: return=minimal

Antwort

Hier sehen Sie ein Beispiel für die Antwort, wenn sie aus @odata.deltaLink der Abfrageinitialisierung abgerufen wird. Die microsoft.graph.user/surname -Eigenschaft ist nicht enthalten, was bedeutet, dass sie sich seit der letzten Deltaabfrage nicht geändert hat. microsoft.graph.group/displayName Ist eingeschlossen, was bedeutet, dass sich ihr Wert geändert hat.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "@odata.type": "#microsoft.graph.group",
      "displayName":"Everyone",
      "id": "72052a9a-c466-4995-8210-95a1c1221995",
    }
  ]
}

Verwandte Inhalte