Changelog in SharePoint abfragen und auf Veränderungen reagieren

by Oliver-Zoufahl on Sep 10, 2024 in SharePoint

Der SharePoint Changelog speichert alle Arten an Veränderungen in der Site und in Listen.

Was im Changelog abgefragt werden kann, ergibt sich aus der SP.ChangeType Enumeration. Hier ein Auszug:

Member Value Description
add 1 Enumeration whoese values speicify that an object has beend added within the scope of a list, site, site collection, or content database
assignmentAdd 11 Enumeration whose values specifiy that a auser has been given permissions to al ist. The list must have unique permissions enabled.
assignmentDelete 12 Enumeration whose values specify that a user has lost permissions to a list. The list must have unique permissions enabled.
deleteObject 3 Enumeration whose values specify that an object has been deleted within the scope of a list, site, site collection, or content database.
listContentTypeAdd undefined  
listContentTypeDelete undefined  
memberAdd 13 Enumeration whose values specify that a user has been added to a group.
memberDelete 14 Enumeration whose values specify that a user has been removed from a group.
moveAway 5 Enumeration whose values specify that a non-leaf section within a URL has been renamed. The object was moved away from the location within the site specified by the change.
moveInto 6 Enumeration whose values specify that a non-leaf section within a URL has been renamed. The object was moved into the location within the site specified by the change.
navigation 16 Enumeration whose values specify that a change in the navigation structure of a site collection has been made.
noChange 0 Enumeration whose values indicate that no change has taken place.
rename 4 Enumeration whose values specify that the leaf in a URL has been renamed.
restore 7 Enumeration whose values specify that an object has restored from a backup or from the recycle bin.
roleAdd 8 Enumeration whose values specify that a role definition has been added.
roleDelete 9 Enumeration whose values specify that a role definition has been deleted.
roleUpdate 10 Enumeration whose values specify that a role definition has been updated.
scopeAdd 17 Enumeration whose values specify that a change in permissions scope has been made to break inheritance from an object's parent.
scopeDelete 18 Enumeration whose values specify that a change in permissions scope has been made to revert back to inheriting permissions from an object's parent.
systemUpdate 18 Enumeration whose values specify that a change has been made to an item using the SystemUpdate method.
update 2 Enumeration whose values specify that an object has been modified within the scope of a list, site, site collection, or content database.
registerEnum Undefined  

Aus der ChangeType Enumeration lässt sich erkennen, dass viele Informationen über den Changelog abfragbar sind. Diese Informationen sind allerdings nur asynchron und zeitlich versetzt verfügbar. Das heißt, wenn ein Listenelement in einer Bibliothek oder Liste hinzugefügt, geändert oder gelöscht wurde, sind diese Informationen nicht sofort im Changelog, sondern etwas später. Der Changelog enthält auch nur den Zeitpunkt der Veränderung in der Site, Liste oder Bibliothek.

Der Changelog lässt sich sowohl über CSOM als auch über die REST API abfragen.

SharePoint ChangeLog über REST API abfragen

ChangeLog Query Objekt

var query = { "Item": true, "Add": true, "Update": true, "DeleteObject": true, "ChangeTokenStart": null };

ChangeLog Abfragen

var requestUrl = "[SHAREPOINT-SITE-URL]/_api/web/lists(guid'[LIST-ID]')/GetChanges(@qry)?@qry=" + JSON.stringify(query)

Die Abfrage der ChangeLog Elemente muss in einem gesicherten Kontext erfolgen. Daher ist es notwendig im Vorfeld ein Request Digest für den ausführenden Nutzer zu generieren. Den Request Digest erhält man über die Abfrage des ContextInfo Objekts, und verwendet dann die Eigenschaft FormDigestValue.

POST requestUrl
headers:
    Content-Type: application/json; charset=utf8
    Accept: application/json; odata=nometadata
    X-RequestDigest: [REQUEST DIGEST]

response:
{
    "value": [
        {
            "ChangeToken": {
                "StringValue": "1;3;ee496550-61f2-4ec2-9cba-ab94bea1083e;638608712817200000;8625136"
            },
            "ChangeType": 1,
            "SiteId": "7a210832-9909-4984-a695-fe2b2d938ee3",
            "Time": "2024-09-02T10:54:42Z",
            "Editor": "",
            "ItemId": 1,
            "ListId": "ee496550-61f2-4ec2-9cba-ab94bea1083e",
            "ServerRelativeUrl": "",
            "WebId": "33cf9a56-c832-4e14-a5e7-5086b29544cf"
        },
        {
            "ChangeToken": {
                "StringValue": "1;3;ee496550-61f2-4ec2-9cba-ab94bea1083e;638608754051170000;8625156"
            },
            "ChangeType": 2,
            "SiteId": "7a210832-9909-4984-a695-fe2b2d938ee3",
            "Time": "2024-09-02T12:03:25Z",
            "Editor": "",
            "ItemId": 2,
            "ListId": "ee496550-61f2-4ec2-9cba-ab94bea1083e",
            "ServerRelativeUrl": "",
            "WebId": "33cf9a56-c832-4e14-a5e7-5086b29544cf"
        },
        {
            "ChangeToken": {
                "StringValue": "1;3;ee496550-61f2-4ec2-9cba-ab94bea1083e;638608713485170000;8625137"
            },
            "ChangeType": 3,
            "SiteId": "7a210832-9909-4984-a695-fe2b2d938ee3",
            "Time": "2024-09-02T10:55:48Z",
            "Editor": "",
            "ItemId": 1,
            "ListId": "ee496550-61f2-4ec2-9cba-ab94bea1083e",
            "ServerRelativeUrl": "",
            "WebId": "33cf9a56-c832-4e14-a5e7-5086b29544cf"
        }
    ]
}

Die Abfrage gibt ein vollständiges Resultset zurück, welches Alle Veränderungen an Listenelementen innerhalb der Liste enthält. In der folgende Tabelle wird das Changlog Objekt erklärt:

Eigenschaft Typ Beschreibung
ChangeToken SP.ChangeToken Gets a value that specifies a change token that identifies the changed object.
StringValue String Gets or sets a string value that contains the serialized representation of the change token generated by the protocol server.
ChangeType SP.ChangeType Contains the value of the type of change
SiteId Guid Gets a value that identifies the site that contains the changed object.
Time DateTime Gets a value that specifies the time that the object was modified.
ItemId Number Gets a value that identifies the changed item.
ListId Guid Gets a value that identifies the list that contains the changed item. In the case of a change that includes moving the item between lists, ListId must contain the value it had before the move.
WebId Guid Gets a value that identifies the site that contains the changed item.

Die Eigenschaften Editor und ServerRelativeUrl sind nicht beschrieben.

An Hand des Change Token kann auch festgelegt werden, ab welchen Zeitpunkt die Changelog Einträge zurückgegeben werden sollen. Dazu ist es lediglich notwendig den Startzeitpunkt an der Eigenschaft ChangeTokenStart des Changelog Query Objekts festzulegen:

query.ChangeTokenStart = { "StringValue": "1;3;ee496550-61f2-4ec2-9cba-ab94bea1083e;638608713485170000;-1" }

Der ChangeToken Start Wert besteht aus fünf Elementen, die durch ein Semikolon getrennt sind:

Eigenschaft Typ Wert
Version Number 1
Scope Number 0 - Content Database, 1 - site collection, 2 - site, 3 - list
GUID Guid GUID of the item the scope applies to (for example, GUID of the list)
Time DateTime Time (in UTC) from when changes occurred. Must be the universal time
Item Number Initialize the change item on the ChangeToken using a default value of -1

Bei der Angabe von -1 im Item-Teil, werden alle Elemente ab dem Zeitstempel zurückgegeben. Der Wert ist gut für die erste Iteration durch den Changelog. Möchte man die Werte in der nächsten Iteration nicht mehr haben, so muss der ChangeToken aus dem letzen Changelog Eintrag der letzten Iteration in der neuen Query übergeben werden.

query.ChangeTokenStart = { "StringValue": "1;3;ee496550-61f2-4ec2-9cba-ab94bea1083e;638617503070600000;8735668" }

Die Anzahl der zurückzugebenen Werte ist durch weitere Parameter in der REST API Url eingrenzbar. Durch die Angabe von $top=10, werden beispielsweise nur 10 Changelog Elemente zurückgeben.

Kommentar schreiben