Skip to content

Commit

Permalink
Update guide on delta query parameters.
Browse files Browse the repository at this point in the history
  • Loading branch information
andrueastman committed Aug 22, 2023
1 parent 74d64fc commit 526537c
Showing 1 changed file with 48 additions and 1 deletion.
49 changes: 48 additions & 1 deletion docs/upgrade-to-v5.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<Group>();
// create a page iterator to iterate through the pages of the response
var pageIterator = PageIterator<Group, Microsoft.Graph.Beta.Groups.Delta.DeltaResponse>.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.
Expand Down Expand Up @@ -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();
```
Expand Down

0 comments on commit 526537c

Please sign in to comment.