|
[What and why]
We are updating the behavior of the Microsoft Graph driveItem.webUrl property for content stored in SharePoint Embedded.
After this change, driveItem.webUrl will return the URL used to open a file in a browser rather than being treated as a stable file location or identifier. Depending on the file type and your SharePoint Embedded configuration, the returned URL may be:
- A Microsoft 365 web viewer URL
- A SharePoint Embedded PDF viewer URL
- A redirect URL generated from your configured urlTemplate
- A Microsoft help page URL
This update aligns driveItem.webUrl with its intended purpose as a browser launch URL. Applications that require a stable identifier for a file should use driveItemId, which remains the only unique and stable identifier for an item within a drive. The SharePoint Embedded documentation describes driveItem.webUrl as the URL used to launch supported files in Microsoft 365 experiences.
[Rollout schedule]
- Targeted Release: Beginning in mid-August 2026
- General Availability (Worldwide): Beginning in mid-February 2027
- Temporary opt-out available until: August 17, 2026
- Customers who opt out before August 17, 2026, will have an additional six months to transition to the new behavior.
- Temporary opt-out support ends February 22, 2027
- After February 22, 2027, all customers will receive the updated
driveItem.webUrl behavior.
[Impact on your organization]
Who is affected
Organizations that develop, manage, or use SharePoint Embedded applications that rely on driveItem.webUrl as a permanent file location, stable URL, or file identifier
Platforms and services
- SharePoint Embedded
- Microsoft Graph
- Microsoft 365 web viewers
- SharePoint Embedded PDF viewer
What will happen
After this change:
- Word, Excel, PowerPoint, and other supported Microsoft 365 file types will return a Microsoft 365 viewer URL.
- PDF files will return a SharePoint Embedded PDF viewer URL.
- Unsupported file types with a configured urlTemplate will return a redirect URL generated from that template.
- Unsupported file types without a configured urlTemplate will return a Microsoft help page URL.
Applications are not expected to require changes if driveItem.webUrl is used only to open files in a browser.
Your application may require updates if it:
- Stores
driveItem.webUrl as a permanent file location.
- Uses
driveItem.webUrl as a file identifier.
- Compares
driveItem.webUrl values over time to determine file identity or location.
- Passes
driveItem.webUrl to services that require a stable storage URL.
- Assumes
driveItem.webUrl remains unchanged across file types, viewer support scenarios, or redirect configurations.
[Action required and recommendations]
Review how your SharePoint Embedded applications use driveItem.webUrl.
No action is required if driveItem.webUrl is used only to open files in a browser.
We recommend:
- Identify any application dependencies on
driveItem.webUrl as a stable identifier or permanent URL.
- Update applications to use
driveItemId when a stable item identifier is required.
- Review redirect behavior for unsupported file types.
- Configure
urlTemplate if users should be redirected back to your application. Review: Configure redirect behavior
- Validate application behavior against the updated
driveItem.webUrl experience before enforcement begins.
- Remove dependencies on the legacy
driveItem.webUrl behavior before temporary opt-out support ends.
Use driveItem.webUrl when your application needs a URL that opens the file in a browser. Use the driveItemId when you need a stable, unique reference to an item.
Organizations that need additional migration time can temporarily retain the current behavior for a SharePoint Embedded container type by setting UseLegacyItemWebUrl to true. Review: Set-SPOContainerTypeConfiguration
The temporary opt-out is intended only as a migration aid and will no longer be honored after February 22, 2027.
Learn more
[Compliance considerations]
No compliance considerations identified. Review as appropriate for your organization.
|