diff --git a/docs/upgrade-to-v5.md b/docs/upgrade-to-v5.md index f45a47957d9..f0ba6c6369d 100644 --- a/docs/upgrade-to-v5.md +++ b/docs/upgrade-to-v5.md @@ -190,6 +190,53 @@ await pageIterator.IterateAsync(); ``` +### `$skipToken` and `$deltaToken` query parameters in delta requests +Given the API guidance [here](https://github.com/microsoft/api-guidelines/blob/vNext/graph/patterns/change-tracking.md#considerations), the metadata used to generate the SDK does not include the `$skipToken` and `$deltaToken` query parameters. +The entire url is documented as opaque and the change of the url structure (e.g. using alternative query parameters) is not considered a breaking change. +Due to this, urls returned from a delta response should be used entirely by either + +1. Using the inbuilt request builders to make subsequent requests from the `@odata.nexlink`(OdataDeltaLink property) or `@odata.deltaLink`(OdataNextLink property) returned from the delta request. +```cs +// make the first request +var deltaResponse = await graphClient.Groups.Delta.GetAsync((requestConfiguration) => +{ + requestConfiguration.QueryParameters.Select = new string[] { "displayName", "description", "mailNickname" }; +}); + +// use the deltaResponse.OdataDeltaLink/deltaResponse.OdataNextLink to make the next request. +var deltaRequest = new Microsoft.Graph.Beta.Groups.Delta.DeltaRequestBuilder(deltaResponse.OdataDeltaLink, graphClient.RequestAdapter); +var secondDeltaResponse = await deltaRequest.GetAsync(); +``` +1. Using the PageIterator +```cs +//fetch the first page of groups +var deltaResponse = await graphClient.Groups.Delta.GetAsync((requestConfiguration) => +{ + requestConfiguration.QueryParameters.Select = new string[] { "displayName", "description", "mailNickname" }; +}); + +// create a list to hold the groups +var groups = new List(); +// create a page iterator to iterate through the pages of the response +var pageIterator = PageIterator.CreatePageIterator(graphClient, deltaResponse, group => +{ + groups.Add(group); + return true; +}); + +// This will iterate follow through the odata.nextLink until the last page is reached with an odata.deltaLink +await pageIterator.IterateAsync(); + +if (pageIterator.State == PagingState.Delta) +{ + await Task.Delay(30000);// wait for some time for changes to occur. + // call delta again with the deltaLink to get the next page of results + Console.WriteLine("Calling delta again with deltaLink"); + Console.WriteLine("DeltaLink url is: " + pageIterator.Deltalink); + await pageIterator.IterateAsync(); +} +``` + ### Error handling Errors and exceptions from the new generated version will be exception classed derived from the [ApiException](https://github.com/microsoft/kiota-abstractions-dotnet/blob/8a136e509c7a71ef889643f047938bdbc3c752be/src/ApiException.cs#L11) class from the Kiota abstrations library. Typically, this will be an instance of [OdataError](https://github.com/microsoftgraph/msgraph-sdk-dotnet/blob/6d1a78fe1ca7d883667b5f231395651e24581653/src/Microsoft.Graph/Generated/Models/ODataErrors/ODataError.cs#L9) and can be handled as below. @@ -226,7 +273,7 @@ var children = await graphServiceClient.Drives[userDriveId].Items["itemId"].Chil > NOTE: /drive/root is a shorthand for /drive/items/root so the `itemId` can be replaced with `root` to make a call to get the root folder. -``` +```cs // List children in the root drive var children = await graphServiceClient.Drives[userDriveId].Items["root"].Children.GetAsync(); ```