Wie greift man das "Changelog" (Office 365 API) aller Aktivitäten innerhalb eines Office 365 Tenants ab?

21. Januar 2016

Der Changelog von Office 365 wird verwendet, um sich Änderungen im laufenden System ausgeben zu lassen. Diese können sowohl zeitlich (ChangeToken) als auch inhaltlich (ChangeQuery) eingeschränkt werden. Die Office 365 REST API funktioniert im Kern genau wie das äquivalente Gegenstück von SharePoint On-Premise. Der größte Unterschied liegt wohl darin, dass sich die API nur über REST-Requests ansprechen lässt und nicht wie beispielsweise in SharePoint On-Premise über C#-Code ansprechen da die Server in der Cloud gehostet werden.

Umsetzung

Um Änderungen aus Office 365 zu beziehen, muss der REST-Endpunkt /_api/site/getchanges angesprochen werden. Dies geschieht mit einem Post-Request, welcher mit einem Access Token authentifiziert sein muss. Als Request-Body muss hierbei ein Objekt als String übergeben werden, welches genauere Informationen zu den gewünschten Responses enthält. Es beinhaltet die Art der Änderungen, welche abgefragt werden sollen, somit lassen sich die Ergebnisse einschränken. Es könnte beispielsweise so aussehen:
 
{
'__metadata': {
'type': 'SP.ChangeQuery'
},
'Update': true,
'Add': true,
'DeleteObject': true,
'Rename': true,
"ChangeTokenStart": null
}
 
Objekte, welche in der ChangeQuery angegeben werden können, um die Ergebnisse einzuschränken, sind:
 
  • Site
  • Web
  • Alert
  • ContentType
  • Folder
  • Field
  • File
  • List
  • Item
  • Navigation
  • View
  • Group
  • SecurityPolicy
  • User
 
 
Actions, welche in der ChangeQuery angegeben werden können, um die Ergebnisse einzuschränken, sind:
 
  • Add
  • GroupMembershipAdd
  • GroupMembershipDelete
  • Move
  • DeleteObject
  • Rename
  • Restore
  • SystemUpdate
  • Update
  • RoleAssignmentAdd
  • RoleAssignmentDelete
  • RoleDefinitionAdd
  • RoleDefinitionDelete
  • RoleDefinitionUpdate
 
Actions und Objekte können zusammen verwendet werden (z.B. List und Add), jedoch sind nicht alle Angaben untereinander kompatibel.
 
Der Wert von "ChangeTokenStart" entspricht dem Zeitstempel, ab wann die Änderungen abgefragt werden sollen. Wenn null als Wert angegeben wird, werden alle Änderungen, welche sich im Log befinden ausgegeben. Änderungen werden derzeit für gewöhnlich zwei Monate gespeichert, es sind also nicht unbedingt alle Änderungen seit erstellen des Tenants gespeichert. Zudem werden lediglich 1000 Änderungen als Antwort pro Anfrage zurückgegeben [1].
 
Wenn weitere 1000 Änderungen erfasst werden sollen, muss also der ChangeToken des letzten Objektes aus dem Array als ChangeTokenStart in einem neuen Request angegeben werden. Die nächsten Ergebnisse starten dann mit dem Item, nach dem angegeben ChangeToken. Über diese Möglichkeit lässt sich ein Paging also simpel realisieren, um sich zum aktuellen Zeitpunkt vorzuarbeiten. Wenn lediglich Änderungen zwischen zwei Zeitpunkten gewünscht sind, kann außerdem ein zweites ChangeToken übergeben werden, welches dann die letzte Änderung darstellt.
 
Das Change-Objekt Das Change-Objekt besteht aus einem Array mit bis zu 1000 Feldern. Es beinhaltet für jede Änderung ein Objekt, welches wie folgt aufgebaut ist (je nach Typ der Änderung (Site, List, ListItem, etc.)):
 
{
"__metadata": {
"id": "<ID>",
"uri": "<URI>",
"type": "SP.ChangeWeb"
},
"ChangeToken": {
"__metadata": {
"type": "SP.ChangeToken"
},
"StringValue": "1;1;0e8e4dda-485c-439f-af5d-4e75ed41abc4;635797256951300000;151200970"
},
"ChangeType": 2,
"SiteId": "0e8e4dda-485c-439f-af5d-4e75ed41abc4",
"Time": "2015-10-06T10:54:55.13Z",
"WebId": "8eb781f0-1327-43ef-9440-54950ef9e8d4"
}
 
An dem Objekt befinden sich die entsprechenden Ids, sowie Informationen über den Status des Items (Wurde es gelöscht, neu angelegt oder bearbeitet?).
 

Fazit

Über den GetChanges-Endpunkt lassen sich die letzten Änderungen, welche in der Office 365 Umgebung stattfanden simpel abfragen. Durch das ChangeTokenStart Attribut lässt sich genau eingrenzen, ab wann Änderungen abgefragt werden sollen, um zum Beispiel einen inkrementell arbeitenden Service zu erstellen.
 
 
Referenzen

Neuen Kommentar schreiben