Change API
Getting changes, synchronisation scenarios
When it comes to synchronization or delta processing Change API is for the rescue. There is no need in any sort of logic that used modified date comparison to detect what has been changed since the last processing time. There is no need to wait until the search crawl is done to check changes through web or site collection. And not only these benefits but also tracking permissions changes restores from recycle bin, system updates and much more.
Changes API is what is used together with Webhooks (in SPO), by having a context (scope) and change token(s) you can easily retrieve what has been changed and run the custom logic based on the nature of changes.
Changes can be requested from within different scopes: lists, webs, sites, etc. Change API operates change tokens to establish start and end anchors.
Change tokens received from a specific entity type (e.g. Site) can't be used with another entity type (e.g. List) while sending change query.
Getting current change token
Getting changes
Knowing what root entities' token(s) you have the specific changes query can be crafted and sent, e.g.:
Change results are strongly typed with Gosip's API, the changes
variable in the sample is an array of api.ChangeInfo
struct pointers.
Change into struct contains the following properties:
ChangeType
is an important piece of information, it's an enumerator describing a nature of a change. See more.
Change API doesn't return what specifically was changed but only where it was changed. For instance, when an item is changed the API will return its identities information but not the metadata.
In a synchronization scenario or a Webhook after getting information which items are changed the corresponding request(s) should be sent for getting specifics.
Change query
When getting the changes the API requires some clarifications about what exactly should be retrieved. This is defined within a change query which is implemented api.ChangeQuery
struct.
Pagination
Sometimes it can be lots of changes since a provided token. Gosip implements pagination helper using "jumping" between different change tokens under the hood. When last change item's token is used as a start token to get the "next page". This approach is used in GetNextPage
:
Summary
Change API is a powerful mechanism and a robust way for processing delta changes that can and should be used in advanced and optimised synchronizations and business processes withing external workers.
Last updated