microsoftgraph / microsoftgraph/msgraph-sdk-powershell
Additional Delta documentation
Nobody has claimed this yet.
- Dominant language
- C#
- Stars
- 898
- Forks
- 230
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 31
Description
Is your feature request related to a problem? Please describe.
I have many questions around the use of the delta cmdlets - such as Get-MgUserDelta. Being unaware of how this works properly, or the pitfalls surround the use of this means I am hesitant to use these cmdlets. For example, the Get-MgUserDelta page is very light on detail.
Describe the solution you'd like
Supplementary documentation against the cmdlets (whether via get-help, or website) providing further detail on how to use them, what to look out for, and how the SDK handles certain situations. i.e. Supply a specific PowerShell SDK lens to the use of these endpoints. Further detail in the next section.
Describe alternatives you've considered
While providing a link back to the Graph API documentation (E.g. Incremental changes for Users) is a good start, it lacks some of the context as to how the PowerShell SDK will handle these. For example:
- What happens when the token expires 7 days after creation? Does the cmdlet throw an error, or will it automatically re-run a full synchronisation and cache the new token?
- The same question to if an HTTP 410 is returned. Currently, the only way for me to get an answer to these questions is to just run a test over 7 days to ascertain the answers myself.
- Will the SDK simply ignore properties which are stored outside the main data store (This should return 501, but what happens if it's combined with 3 other attributes, e.g. Get-MgUserDelta -Property UserPrincipalName,AccountEnabled,Skills)
It's important for scripting to know how to handle these, so that either a try/catch can be established to catch any token related errors, and prepare any script for a full synchronisation of data, rather than just the delta, as backend systems may respond adversely to an unplanned 10,000 user dump, when it is used to receiving 20.
Additional context
As a side note, it is noted that the Graph API does not currently support the parameter lastmodifieddatetime. While outside the scope of this forum, use of this parameter may have alleviated the requirement to use the delta cmdlets, but not the need for additional documentation
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Get-MgUserDelta documentation and the linked Microsoft Graph delta-query pages. Determine and document the PowerShell SDK behavior for expired delta tokens, HTTP 410 responses, and unsupported or mixed properties, including what users should handle themselves. Done means the cmdlet documentation explains these cases with actionable scripting guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- powershell
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100