diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 8a82f0f726..a611cb721e 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -117,17 +117,17 @@ }, { "source_path": "docs/embedded/concepts/admin-exp/billing.md", - "redirect_url": "/sharepoint/dev/embedded/concepts/admin-exp/billing/billing", + "redirect_url": "/sharepoint/dev/embedded/plan/choose-billing-model", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/admin-exp/cta.md", - "redirect_url": "/sharepoint/dev/embedded/concepts/admin-exp/consuming-tenant-admin/cta", + "redirect_url": "/sharepoint/dev/embedded/admin/consuming-tenant-admin", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/admin-exp/dev-admin.md", - "redirect_url": "/sharepoint/dev/embedded/concepts/admin-exp/developer-admin/dev-admin", + "redirect_url": "/sharepoint/dev/embedded/admin/create-apps-powershell", "redirect_document_id": false }, { @@ -147,127 +147,307 @@ }, { "source_path": "docs/embedded/concepts/admin-exp/adminrole.md", - "redirect_url": "/sharepoint/dev/embedded/administration/adminrole", + "redirect_url": "/sharepoint/dev/embedded/admin/admin-overview", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/admin-exp/billing/billing.md", - "redirect_url": "/sharepoint/dev/embedded/administration/billing/billing", + "redirect_url": "/sharepoint/dev/embedded/plan/choose-billing-model", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/admin-exp/billing/billingmanagement.md", - "redirect_url": "/sharepoint/dev/embedded/administration/billing/billingmanagement", + "redirect_url": "/sharepoint/dev/embedded/admin/monitor-usage-billing-cost", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/admin-exp/billing/meters.md", - "redirect_url": "/sharepoint/dev/embedded/administration/billing/meters", + "redirect_url": "/sharepoint/dev/embedded/reference/billing-meters", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/admin-exp/consuming-tenant-admin/cta.md", - "redirect_url": "/sharepoint/dev/embedded/administration/consuming-tenant-admin/cta", + "redirect_url": "/sharepoint/dev/embedded/admin/consuming-tenant-admin", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/admin-exp/consuming-tenant-admin/ctaUX.md", - "redirect_url": "/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctaUX", + "redirect_url": "/sharepoint/dev/embedded/admin/manage-containers-sharepoint-admin-center", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/admin-exp/consuming-tenant-admin/ctapowershell.md ", - "redirect_url": "/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell", + "redirect_url": "/sharepoint/dev/embedded/admin/manage-containers-powershell", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/admin-exp/developer-admin/dev-admin.md", - "redirect_url": "/sharepoint/dev/embedded/administration/developer-admin/dev-admin", + "redirect_url": "/sharepoint/dev/embedded/admin/create-apps-powershell", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/security-and-compliance.md", - "redirect_url": "/sharepoint/dev/embedded/compliance/security-and-compliance", + "redirect_url": "/sharepoint/dev/embedded/plan/security-compliance-governance", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/app-concepts/app-architecture.md", - "redirect_url": "/sharepoint/dev/embedded/development/app-architecture", + "redirect_url": "/sharepoint/dev/embedded/plan/app-tenant-architecture", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/app-concepts/auth.md", - "redirect_url": "/sharepoint/dev/embedded/development/auth", + "redirect_url": "/sharepoint/dev/embedded/build/configure-authentication-authorization", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/content-experiences/office-experience.md", - "redirect_url": "/sharepoint/dev/embedded/development/content-experiences/office-experience", + "redirect_url": "/sharepoint/dev/embedded/build/open-office-files", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/content-experiences/search-content.md", - "redirect_url": "/sharepoint/dev/embedded/development/content-experiences/search-content", + "redirect_url": "/sharepoint/dev/embedded/build/search-containers-files", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/content-experiences/user-experiences-overview.md", - "redirect_url": "/sharepoint/dev/embedded/development/content-experiences/user-experiences-overview", + "redirect_url": "/sharepoint/dev/embedded/build/open-office-files", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/fluid.md", - "redirect_url": "/sharepoint/dev/embedded/development/fluid", + "redirect_url": "/sharepoint/dev/embedded/build/fluid-framework", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/app-concepts/limits-calling.md", - "redirect_url": "/sharepoint/dev/embedded/development/limits-calling", + "redirect_url": "/sharepoint/dev/embedded/plan/limits-calling-patterns", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/app-concepts/sharing-and-perm.md", - "redirect_url": "/sharepoint/dev/embedded/development/sharing-and-perm", + "redirect_url": "/sharepoint/dev/embedded/build/share-files-manage-permissions", "redirect_document_id": false }, { "source_path": "docs/embedded/tutorials/doc-processing-acs.md", - "redirect_url": "/sharepoint/dev/embedded/development/tutorials/doc-processing-acs", + "redirect_url": "/sharepoint/dev/embedded/build/manage-files", "redirect_document_id": false }, { "source_path": "docs/embedded/tutorials/launch-experience.md", - "redirect_url": "/sharepoint/dev/embedded/development/tutorials/launch-experience", + "redirect_url": "/sharepoint/dev/embedded/build/open-office-files", "redirect_document_id": false }, { "source_path": "docs/embedded/tutorials/metadata.md", - "redirect_url": "/sharepoint/dev/embedded/development/tutorials/metadata", + "redirect_url": "/sharepoint/dev/embedded/build/container-metadata", "redirect_document_id": false }, { "source_path": "docs/embedded/tutorials/migrate-abs-to-spe.md", - "redirect_url": "/sharepoint/dev/embedded/development/tutorials/migrate-abs-to-spe", + "redirect_url": "/sharepoint/dev/embedded/build/migrate-azure-blob-storage", "redirect_document_id": false }, { "source_path": "docs/embedded/tutorials/using-file-preview.md", - "redirect_url": "/sharepoint/dev/embedded/development/tutorials/using-file-preview", + "redirect_url": "/sharepoint/dev/embedded/build/preview-files", "redirect_document_id": false }, { "source_path": "docs/embedded/tutorials/using-webhooks.md", - "redirect_url": "/sharepoint/dev/embedded/development/tutorials/using-webhooks", + "redirect_url": "/sharepoint/dev/embedded/build/respond-to-changes-webhooks", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/app-concepts/containertypes.md", - "redirect_url": "/sharepoint/dev/embedded/getting-started/containertypes", + "redirect_url": "/sharepoint/dev/embedded/build/create-container-type", "redirect_document_id": false }, { "source_path": "docs/embedded/concepts/app-concepts/register-api-documentation.md", - "redirect_url": "/sharepoint/dev/embedded/getting-started/register-api-documentation", + "redirect_url": "/sharepoint/dev/embedded/build/register-application-permissions", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/administration/adminrole.md", + "redirect_url": "/sharepoint/dev/embedded/admin/admin-overview", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/administration/billing/billing.md", + "redirect_url": "/sharepoint/dev/embedded/plan/choose-billing-model", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/administration/billing/billingmanagement.md", + "redirect_url": "/sharepoint/dev/embedded/admin/monitor-usage-billing-cost", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/administration/billing/meters.md", + "redirect_url": "/sharepoint/dev/embedded/reference/billing-meters", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/administration/consuming-tenant-admin/cta.md", + "redirect_url": "/sharepoint/dev/embedded/admin/consuming-tenant-admin", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/administration/consuming-tenant-admin/ctapowershell.md", + "redirect_url": "/sharepoint/dev/embedded/admin/manage-containers-powershell", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/administration/consuming-tenant-admin/ctaUX.md", + "redirect_url": "/sharepoint/dev/embedded/admin/manage-containers-sharepoint-admin-center", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/administration/developer-admin/dev-admin.md", + "redirect_url": "/sharepoint/dev/embedded/admin/create-apps-powershell", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/compliance/audit-events.md", + "redirect_url": "/sharepoint/dev/embedded/reference/audit-events", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/compliance/security-and-compliance.md", + "redirect_url": "/sharepoint/dev/embedded/plan/security-compliance-governance", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/app-architecture.md", + "redirect_url": "/sharepoint/dev/embedded/plan/app-tenant-architecture", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/auth.md", + "redirect_url": "/sharepoint/dev/embedded/build/configure-authentication-authorization", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/content-experiences/configure-redirect-behavior.md", + "redirect_url": "/sharepoint/dev/embedded/build/open-office-files", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/content-experiences/office-experience.md", + "redirect_url": "/sharepoint/dev/embedded/build/open-office-files", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/content-experiences/search-content.md", + "redirect_url": "/sharepoint/dev/embedded/build/search-containers-files", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/content-experiences/user-experiences-overview.md", + "redirect_url": "/sharepoint/dev/embedded/build/open-office-files", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/declarative-agent/sharepoint-embedded-knowledge-source.md", + "redirect_url": "/sharepoint/dev/embedded/build/sharepoint-embedded-knowledge-source", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/declarative-agent/spe-da-adv.md", + "redirect_url": "/sharepoint/dev/embedded/build/agent-experiences", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/declarative-agent/spe-da.md", + "redirect_url": "/sharepoint/dev/embedded/build/agent-experiences", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/fluid.md", + "redirect_url": "/sharepoint/dev/embedded/build/fluid-framework", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/limits-calling.md", + "redirect_url": "/sharepoint/dev/embedded/plan/limits-calling-patterns", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/sharing-and-perm.md", + "redirect_url": "/sharepoint/dev/embedded/build/share-files-manage-permissions", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/support-archival-of-containers.md", + "redirect_url": "/sharepoint/dev/embedded/build/archive-restore-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/tutorials/doc-processing-acs.md", + "redirect_url": "/sharepoint/dev/embedded/build/manage-files", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/tutorials/launch-experience.md", + "redirect_url": "/sharepoint/dev/embedded/build/open-office-files", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/tutorials/metadata.md", + "redirect_url": "/sharepoint/dev/embedded/build/container-metadata", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/tutorials/migrate-abs-to-spe.md", + "redirect_url": "/sharepoint/dev/embedded/build/migrate-azure-blob-storage", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/tutorials/spe-da-vscode.md", + "redirect_url": "/sharepoint/dev/embedded/build/agent-experiences", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/tutorials/using-file-preview.md", + "redirect_url": "/sharepoint/dev/embedded/build/preview-files", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/tutorials/using-webhooks.md", + "redirect_url": "/sharepoint/dev/embedded/build/respond-to-changes-webhooks", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/tutorials/vendor-install-app-customer.md", + "redirect_url": "/sharepoint/dev/embedded/publish/customer-tenant-setup-guide", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/getting-started/containertypes.md", + "redirect_url": "/sharepoint/dev/embedded/build/create-container-type", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/getting-started/microsoft-365-archive-support-for-containers.md", + "redirect_url": "/sharepoint/dev/embedded/build/archive-restore-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/getting-started/register-api-documentation.md", + "redirect_url": "/sharepoint/dev/embedded/build/register-application-permissions", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/getting-started/spembedded-for-vscode.md", + "redirect_url": "/sharepoint/dev/embedded/build/quickstart-vscode", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/SharePoint Embedded Documentation.md", + "redirect_url": "/sharepoint/dev/embedded/sharepoint-embedded-documentation", "redirect_document_id": false }, { diff --git a/docs/embedded/admin/admin-overview.md b/docs/embedded/admin/admin-overview.md new file mode 100644 index 0000000000..d12c433b43 --- /dev/null +++ b/docs/embedded/admin/admin-overview.md @@ -0,0 +1,226 @@ +--- +title: Admin Overview +description: Learn how administrators manage SharePoint Embedded apps, containers, billing, and compliance in Microsoft 365. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Admin overview + +**Applies to:** Consuming tenant admin — SharePoint Embedded admin / Global admin / Compliance admin / Security admin + + + +SharePoint Embedded is an API-only document platform built on Microsoft 365. + +Organizations use SharePoint Embedded apps to store files and documents in containers that inherit Microsoft 365 security, compliance, and administration controls. + +Administrators manage those apps and containers through the SharePoint admin center and SharePoint Online Management Shell. + +Use this overview to decide which administrator role and management surface to use. + +Then follow the linked how-to articles for app creation, installation, billing, container lifecycle, and compliance operations. + +> [!IMPORTANT] +> Assign the **SharePoint Embedded Administrator** role before delegating SharePoint Embedded administration. +> +> Global Administrators already have the permissions of this role, but should use least-privileged delegation for daily operations. + +## Admin roles + +SharePoint Embedded administration commonly involves the following roles. + +| Role | Use it for | +| --- | --- | +| Global Administrator | Assign the SharePoint Embedded Administrator role and perform any SharePoint Embedded admin task when needed. | +| SharePoint Embedded Administrator | Manage SharePoint Embedded apps and containers through SharePoint admin center and supported SharePoint PowerShell cmdlets. | +| Tenant administrator | Manage apps and settings in the consuming Microsoft 365 tenant. | +| Compliance administrator | Configure Microsoft Purview audit, retention, DLP, eDiscovery, and related policies. | +| Security administrator | Configure security policies and investigate security events that apply to SharePoint Embedded content. | + +The SharePoint Embedded Administrator role is available in Microsoft Entra and the Microsoft 365 admin center. + +It is dedicated to SharePoint Embedded administration. + +It doesn't grant regular SharePoint site management access. + +For example, a SharePoint Embedded Administrator doesn't see the **Active sites** or **Deleted sites** pages in the SharePoint admin center and cannot run site-specific SharePoint PowerShell cmdlets. + +Likewise, the SharePoint administrator role doesn't administer SharePoint Embedded apps or containers. + +### Assign the SharePoint Embedded Administrator role + +A Global Administrator assigns the SharePoint Embedded Administrator role in either Microsoft Entra or the Microsoft 365 admin center. + +**Microsoft Entra** + +1. Sign in to Microsoft Entra as a Global Administrator. +1. Select **Users**, then select **All users**. +1. Select the user to assign the role to. +1. Select **Assigned roles**. +1. Select **Add assignments**, then search for **SharePoint Embedded**. +1. Select **SharePoint Embedded Administrator**, then select **Add**. + +**Microsoft 365 admin center** + +1. Sign in to the Microsoft 365 admin center as a Global Administrator. +1. Select **Users**, then select **Active users**. +1. Select the user to assign the role to. +1. Under **Roles**, select **Manage roles**. +1. Select **Admin center access**, then under **Collaboration**, select **SharePoint Embedded Administrator**. +1. Select **Save changes**. + +## Developer tenant and consuming tenant responsibilities + +SharePoint Embedded administration differs depending on whether the tenant owns the app or consumes the app. + +A developer tenant owns or builds the SharePoint Embedded application. + +Developer tenant admins can create container types, configure billing for standard billing scenarios, and manage container type properties. + +A consuming tenant uses a SharePoint Embedded application in its Microsoft 365 tenant. + +Consuming tenant admins manage installed applications, containers, sharing settings, sensitivity labels, deleted containers, and compliance controls. A Global Administrator sets up billing for pass-through apps. + +For the consuming tenant admin model, see [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md). + +## What admins can do + +Administrators can perform these SharePoint Embedded management tasks. + +### App administration + +- View SharePoint Embedded applications registered in the tenant. +- View details for a specific SharePoint Embedded application. +- Review owning and guest application permissions. +- Install or register a SharePoint Embedded app in a consuming tenant. +- Configure application-level external sharing settings when supported. +- Create apps from the SharePoint admin center when the tenant owns the app. + +Start with [Create apps in SharePoint admin center](create-apps-sharepoint-admin-center.md) for owned apps. + +Use [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md) for consuming tenant installation. + +### Permission and consent administration + +Admin consent installs the application service principal in the consuming tenant and grants the requested permissions. + +For container type registration, the owning application must have admin consent and the required SharePoint application permission before it can register permissions in the consuming tenant. + +Review consent guidance in [Grant admin consent and permissions](grant-admin-consent-permissions.md). + +### Billing administration + +SharePoint Embedded uses pay-as-you-go billing through Azure. + +Cost is driven by storage, API transactions, and egress. + +Developer tenants configure billing for standard billing container types. + +Consuming tenants configure billing for pass-through apps before users can access those apps. + +Only a Global Administrator can set up billing in the Microsoft 365 admin center. The SharePoint Embedded Administrator role can't configure billing. + +Set up pass-through billing with [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md). + +Monitor usage with [Monitor usage, billing, and cost](monitor-usage-billing-cost.md). + +### Container administration + +Containers hold the content used by SharePoint Embedded apps. + +Admins can view active containers, archive containers, reactivate archived containers, inspect metadata, set sensitivity labels, manage membership in the admin center, delete containers, restore deleted containers, and permanently delete deleted containers. + +Use the graphical experience in [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md). + +Use cmdlets and scripting in [Manage containers with PowerShell](manage-containers-powershell.md). + +### Compliance administration + +SharePoint Embedded content participates in Microsoft Purview capabilities. + +Compliance admins can use audit, retention, DLP, eDiscovery, and sensitivity labels in ways that are similar to SharePoint. + +Some scenarios that need end-user interaction depend on the owning app to provide the user experience. + +Review [Review audit events](review-audit-events.md) and [Apply security and compliance controls](apply-security-compliance-controls.md). + +## SharePoint admin center versus PowerShell + +Use both management surfaces. + +They're complementary. + +| Surface | Best for | +| --- | --- | +| SharePoint admin center | Interactive app inventory, container views, container details, deleted container operations, sensitivity labels, and membership management. | +| SharePoint Online Management Shell | Repeatable administration, inventory exports, sorting containers by storage, application permission review, and lifecycle scripts. | + +The SharePoint admin center exposes SharePoint Embedded-specific pages such as **Apps**, **Active containers**, and **Deleted containers**. + +A SharePoint Embedded Administrator sees the SharePoint Embedded administration pages but not general SharePoint site management pages. + +SharePoint Online Management Shell provides SharePoint Embedded cmdlets for application and container administration. + +Use the latest version before running container administration cmdlets. + +For command details, see [Manage containers with PowerShell](manage-containers-powershell.md) and the linked cmdlet reference. + +> [!TIP] +> Use the admin center for one-time review and confirmation. +> Use PowerShell when you need repeatable inventory, reporting, or bulk operations. + +## Common administration paths + +Use this path when you own a SharePoint Embedded app: + +1. Confirm the admin role. See [Assign the SharePoint Embedded Administrator role](#assign-the-sharepoint-embedded-administrator-role). +1. Create the app in [Create apps in SharePoint admin center](create-apps-sharepoint-admin-center.md). +1. Choose and configure billing. +1. Install the app if it must be available in a consuming tenant. +1. Grant admin consent and register required permissions. +1. Monitor usage and cost. + +Use this path when your tenant consumes a SharePoint Embedded app: + +1. Assign or confirm the SharePoint Embedded Administrator role. +1. Install or approve the app in [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md). +1. Grant admin consent when required. +1. Set up pass-through billing in [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md). +1. Manage containers in the SharePoint admin center or with PowerShell. +1. Apply compliance controls in Microsoft Purview. + +## Operational guardrails + +Before making changes, identify the owning application and affected containers. + +Container deletion can break links, remove content, and interrupt the app that depends on the container. + +Deleted containers can be restored from the deleted container collection within the supported retention period unless they're permanently deleted or retention policies change the behavior. + +> [!WARNING] +> Permanently deleting a container removes it from the deleted container collection and it can't be restored. +> Notify app owners before deleting containers. + +## Related content + +- [Create apps in SharePoint admin center](create-apps-sharepoint-admin-center.md) +- [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md) +- [Grant admin consent and permissions](grant-admin-consent-permissions.md) +- [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) +- [Manage containers with PowerShell](manage-containers-powershell.md) +- [Monitor usage, billing, and cost](monitor-usage-billing-cost.md) +- [Apply security and compliance controls](apply-security-compliance-controls.md) + +## Next steps + +Create an owned app in [Create apps in SharePoint admin center](create-apps-sharepoint-admin-center.md). diff --git a/docs/embedded/admin/apply-security-compliance-controls.md b/docs/embedded/admin/apply-security-compliance-controls.md new file mode 100644 index 0000000000..b386161aea --- /dev/null +++ b/docs/embedded/admin/apply-security-compliance-controls.md @@ -0,0 +1,256 @@ +--- +title: Apply Security and Compliance Controls +description: Apply Microsoft Purview and SharePoint controls to protect and govern SharePoint Embedded content. +ms.date: 07/13/2026 +ms.reviewer: dilucesr +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Apply security and compliance controls + +**Applies to:** Consuming tenant admin — Compliance admin / Security admin / SharePoint admin + + + +Apply security and compliance controls to SharePoint Embedded content by using Microsoft Purview and supported SharePoint administration features. + +SharePoint Embedded uses Microsoft 365 compliance and data governance capabilities so organizations can protect, govern, and investigate content stored by embedded applications. + +Some compliance scenarios require the owning application to provide the end-user experience because SharePoint Embedded is API-only and doesn't have its own user interface. + +> [!IMPORTANT] +> Coordinate compliance controls with the SharePoint Embedded app owner. +> A policy can protect content, but app behavior must be implemented by the owning app to handle the effects of those policies. + +## Before you begin + +Confirm these prerequisites. + +- You can access Microsoft Purview with the required compliance role. +- You can access SharePoint administration tools when container details are needed. +- You can identify the SharePoint Embedded application and containers in scope. +- You can retrieve container site URLs for targeted policies. +- App owners understand the policy impact on their user experience. +- Legal, records management, and security stakeholders approve the control design. + +For supported controls, see [Plan Security, Compliance, and Governance](../plan/security-compliance-governance.md). + +## Get container details for policy scope + +Many compliance tasks need a container URL or container identifier. + +Use PowerShell to retrieve application and container details. + +1. View SharePoint Embedded applications registered in the tenant. + + ```powershell + Get-SPOApplication + ``` + +1. Retrieve containers for an application. + + ```powershell + Get-SPOContainer -OwningApplicationId + ``` + +1. Retrieve details for a container. + + ```powershell + Get-SPOContainer -OwningApplicationId -Identity + ``` + +Use the container site URL to target policies at specific SharePoint Embedded containers. + +For cmdlet details, see [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer). + +## Apply audit controls + +Audit capabilities for SharePoint Embedded mirror existing SharePoint audit capabilities. User and admin operations performed in SharePoint Embedded applications are captured in the unified audit log. + +Use Microsoft Purview audit to search activity and investigate file, user, app, and admin operations. + +![Microsoft Purview audit search results for SharePoint Embedded activity, including the ContainerInstanceId and ContainerTypeId fields.](../images/sc1.png) + +For audit review steps, see [Review audit events](review-audit-events.md). For a detailed list of container type and container type registration audit events, see [SharePoint Embedded audit log events](../reference/audit-events.md). + +## Apply eDiscovery + +Compliance admins can use Microsoft Purview eDiscovery to search, hold, and export content hosted in SharePoint Embedded. + +To search all SharePoint Embedded content with SharePoint content: + +1. Open the eDiscovery experience in Microsoft Purview. +1. Configure the search. +1. Select **All** SharePoint sites for the SharePoint workload. +1. Run the search. +1. Review results according to your eDiscovery process. + +![Microsoft Purview eDiscovery search configured with All SharePoint sites selected to include all SharePoint Embedded containers.](../images/sc2.png) + +To limit the search to selected SharePoint Embedded containers: + +1. Retrieve the container site URL. +1. In the SharePoint sites workload, choose specific sites. +1. Add the container URL. +1. Run and validate the search. + +![Microsoft Purview eDiscovery search using Choose sites under the SharePoint sites workload to target a specific container URL.](../images/sc3.png) + +For product guidance, see [Microsoft Purview eDiscovery solutions](/purview/ediscovery). + +## Apply retention and holds + +SharePoint Embedded supports retention and hold policies on content stored in applications through Microsoft Purview. +Use these scoping options: + +| Scope | Effect | +| --- | --- | +| All SharePoint sites | Applies to SharePoint sites and SharePoint Embedded containers. | +| Selected locations | Applies to specific SharePoint locations, including selected SharePoint Embedded container URLs. | + +Use broad scope when a policy applies to all SharePoint and SharePoint Embedded content. + +Use selected container URLs when a policy applies only to specific data. + +![Microsoft Purview retention policy configured for All sites, which enforces it on all SharePoint sites and SharePoint Embedded containers.](../images/sc4.png) + +![Microsoft Purview retention policy scoped to selected SharePoint Embedded container URLs.](../images/sc5.png) + +> [!NOTE] +> SharePoint Embedded doesn't provide a native end-user interface for retention label interactions. +> If users need to apply or respond to retention labels in an app, the owning app must provide that experience. + +For Microsoft Purview Data Lifecycle Management, see [Learn about Microsoft Purview Data Lifecycle Management](/purview/data-lifecycle-management). + +## Apply DLP policies + +Use Microsoft Purview Data Loss Prevention (DLP) to identify, monitor, and automatically protect sensitive items stored in SharePoint Embedded applications. + +To apply DLP broadly: + +1. Create or edit a DLP policy in Microsoft Purview. +1. Choose the SharePoint sites workload. +1. Select **All sites** when the policy should include all SharePoint sites and SharePoint Embedded containers. +1. Configure rules, actions, and alerts. +1. Test and then enable the policy according to your rollout process. + +To apply DLP to selected SharePoint Embedded containers: + +1. Retrieve the container URLs. +1. Configure the DLP policy for selected SharePoint locations. +1. Add the container URLs. +1. Validate policy behavior with the app owner. + +![Microsoft Purview DLP policy configured for All sites to include all SharePoint sites and SharePoint Embedded containers.](../images/sc6.png) + +![Microsoft Purview DLP policy scoped to selected SharePoint Embedded container URLs.](../images/sc7.png) + +Some DLP scenarios require user interaction, such as business justification for override or policy tips. + +Because SharePoint Embedded doesn't provide a native user interface, the client app must implement the required user experience, often by using Microsoft Graph where applicable. + +For DLP details, see [Learn about data loss prevention](/purview/dlp-learn-about-dlp). + +## Apply sensitivity labels to containers + +Global Administrators and SharePoint Embedded Administrators can set or remove sensitivity labels on SharePoint Embedded containers with SharePoint PowerShell. + +Set a label: + +```powershell +Set-SPOContainer -Identity -SensitivityLabel +``` + +Remove a label by using the supported container label command documented in [Manage containers with PowerShell](manage-containers-powershell.md). + +Before applying labels: + +- Confirm the label is published. +- Confirm the label is appropriate for the container. +- Confirm app behavior with the app owner. +- Confirm compliance requirements with data owners. + +For label concepts, see [Learn about sensitivity labels](/purview/sensitivity-labels). + +## Apply block download policy + +SharePoint Administrators and Global Administrators can block file downloads from SharePoint Embedded containers with the SharePoint site policy cmdlet. + +```powershell +Set-SPOSite -Identity -BlockDownloadPolicy $true +``` + +A SharePoint Advanced Management license is needed to enforce this policy. + +Read the SharePoint documentation before enabling it in production. + +For more information, see [Block download policy for SharePoint sites and OneDrive](/sharepoint/block-download-from-sites). + +## Apply Conditional Access policy + +SharePoint Embedded supports basic Conditional Access policy configurations. + +The `ConditionalAccessPolicy` parameter supports these values: + +- `AllowFullAccess` +- `AllowLimitedAccess` +- `BlockAccess` + +Use this SharePoint PowerShell cmdlet: + +```powershell +Set-SPOContainer -Identity -ConditionalAccessPolicy +``` + +Review tenant access policies before changing container access. + +Test app behavior for web, desktop, and mobile clients. + +For related guidance, see [Control access from unmanaged devices](/sharepoint/control-access-from-unmanaged-devices). + +## Clarify responsibilities + +Security and compliance controls often span multiple teams. + +| Team | Responsibilities | +| --- | --- | +| Compliance admins | Configure Purview audit, eDiscovery, retention, DLP, and policy scope. | +| SharePoint Embedded admins | Retrieve container details and apply supported container settings. | +| SharePoint Embedded app owners | Implement app user experiences for policy tips, overrides, labels, and error handling. | +| Security admins | Review Conditional Access and access restrictions. | +| Legal or records teams | Approve holds, retention, and deletion decisions. | + +Document the owner for each control before rollout. + +## Validate policy behavior + +After applying a control: + +1. Confirm the policy is published or enabled. +1. Confirm the target container URL or all-sites scope is correct. +1. Ask the app owner to test common user workflows. +1. Review audit records for policy-related activity. +1. Review DLP alerts, eDiscovery results, or retention state as applicable. +1. Record the change in your compliance operations log. + +> [!TIP] +> Pilot controls on a small set of containers before applying them broadly to all SharePoint sites and SharePoint Embedded containers. + +## Related content + +- [Review audit events](review-audit-events.md) +- [Manage containers with PowerShell](manage-containers-powershell.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) +- [Plan Security, Compliance, and Governance](../plan/security-compliance-governance.md) +- [Troubleshooting](../reference/troubleshooting.md) + +## Next steps + +Review troubleshooting guidance in [Troubleshooting](../reference/troubleshooting.md). diff --git a/docs/embedded/administration/consuming-tenant-admin/cta.md b/docs/embedded/admin/consuming-tenant-admin.md similarity index 65% rename from docs/embedded/administration/consuming-tenant-admin/cta.md rename to docs/embedded/admin/consuming-tenant-admin.md index 1c79ef333d..d04c73c063 100644 --- a/docs/embedded/administration/consuming-tenant-admin/cta.md +++ b/docs/embedded/admin/consuming-tenant-admin.md @@ -1,11 +1,15 @@ --- title: Consuming Tenant Admin description: This article describes the role and responsibilities of Consuming Tenant Admin in SharePoint Embedded. -ms.date: 08/13/2025 +ms.date: 07/13/2026 +ms.reviewer: shsaravanan ms.localizationpriority: high +ai-usage: ai-assisted --- -# Consuming Tenant Admin +# Consuming tenant admin + +**Applies to:** Consuming tenant admin — SharePoint Embedded admin / Global admin > [!IMPORTANT] > Assign the SharePoint Embedded Administrator role available in Microsoft 365 Admin Center or Microsoft Entra ID to execute SharePoint Embedded Container cmdlets mentioned in this article. @@ -14,12 +18,20 @@ ms.localizationpriority: high > > A global administrator can assign a user the SharePoint Embedded administrator role to act as a consuming tenant admin for SharePoint Embedded. -The organizations that use the SharePoint Embedded applications on their Microsoft 365 (Microsoft 365) tenants are the consuming tenants, and the persona that is responsible for managing these applications on their Microsoft 365 tenancy is the consuming tenant administrator. Consuming tenant administrators can perform various administrative actions on the SharePoint Embedded applications registered on their Microsoft 365 tenant and on the containers that hold the content. They can also manage tenant level configurations and ensure that data is stored in a secure, protected way that meets customers’ business and compliance policies. In this article, we describe the enterprise manageability features that are supported and can be performed by the consuming tenant administrator. They can do so either using the PowerShell cmdlets or through the SharePoint Administrator Center (SPAC). +Organizations that use SharePoint Embedded applications in their Microsoft 365 tenants are consuming tenants. The consuming tenant administrator manages these applications and the containers that hold content. Consuming tenant administrators can manage applications registered in their tenant, tenant-level configurations, and security and compliance settings. This article describes enterprise manageability features that consuming tenant administrators can use through PowerShell cmdlets or the SharePoint admin center. + + ## Consuming Tenant Admin Role -Microsoft 365 SharePoint Embedded Administrator serves as the consuming tenant admin. Global Administrators in Microsoft 365 can assign users the SharePoint Embedded Administrator. The Global Administrator role already has all the permissions of the SharePoint Embedded Administrator role. The SharePoint Embedded Role is available in Microsoft Entra ID and Microsoft 365 Admin Center. -For information on [SharePoint Embedded Admin](../adminrole.md) +Microsoft 365 SharePoint Embedded Administrator serves as the consuming tenant admin. Global Administrators in Microsoft 365 can assign users the SharePoint Embedded Administrator role. The Global Administrator role already has all the permissions of the SharePoint Embedded Administrator role. The SharePoint Embedded Role is available in Microsoft Entra ID and Microsoft 365 Admin Center. + +For information on the SharePoint Embedded Administrator role, see [Admin overview](admin-overview.md). ## Administration Tools @@ -45,7 +57,7 @@ On PowerShell, the SharePoint Embedded Admin can run the following cmdlets: 1. Edit the sensitivity label on a container 1. Set the sharing capability configuration on a container -For information on consuming tenant admin in [PowerShell](../consuming-tenant-admin/ctapowershell.md) +For information on consuming tenant admin in PowerShell, see [Manage containers with PowerShell](manage-containers-powershell.md). ### SharePoint Administrator Center @@ -58,19 +70,19 @@ The SharePoint Embedded Admin can access the Active and Deleted containers page 1. Archive and reactivate containers 1. Soft delete, restore, and purge deleted containers -For information on consuming tenant admin in SharePoint Admin, see [container management](ctaUX.md) +For information on consuming tenant admin in SharePoint admin center, see [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md). ## Security and compliance administration -SharePoint Embedded uses Microsoft’s comprehensive compliance and data governance solutions to help organizations manage risks, protect, and govern sensitive data, and respond to regulatory requirements. Security and compliance solutions work in a similar manner in the SharePoint Embedded platform as they do today in the Microsoft 365 platform, so that data is stored in a secure, protected way that meets customers’ business and compliance policies while making it easy for Compliance and SharePoint Administrators to enforce critical security and compliance policies on the content. For information on supported security and compliance capabilities, see [Security and Compliance](../../compliance/security-and-compliance.md). +SharePoint Embedded uses Microsoft’s comprehensive compliance and data governance solutions to help organizations manage risks, protect, and govern sensitive data, and respond to regulatory requirements. Security and compliance solutions work in a similar manner in the SharePoint Embedded platform as they do today in the Microsoft 365 platform, so that data is stored in a secure, protected way that meets customers’ business and compliance policies while making it easy for Compliance and SharePoint Administrators to enforce critical security and compliance policies on the content. For information on supported security and compliance capabilities, see [Plan security, compliance, and governance](../plan/security-compliance-governance.md). -## Set up billing for passthrough container type +## Set up billing for pass-through container type -To use passthrough billing SharePoint Embedded app, the SharePoint Embedded Admin needs to set up Microsoft Syntex billing in the [Microsoft 365 admin center](https://admin.microsoft.com/). No user can access any passthrough SharePoint Embedded apps before a valid billing is set up for the SharePoint Embedded platform. +To use a pass-through billing SharePoint Embedded app, the SharePoint Embedded admin needs to set up Microsoft Syntex billing in the [Microsoft 365 admin center](https://admin.microsoft.com/). No user can access any pass-through SharePoint Embedded apps before valid billing is set up for the SharePoint Embedded platform. -### [Meters](../billing/meters.md) +### [Meters](../reference/billing-meters.md) -SharePoint Embedded employs a pay-as-you-go (PAYG) billing model through an Azure subscription. Billing is determined by how much data in GB you store in SharePoint Embedded in active and archived states, transactions used to access and modify the container and container contents, and data that is egressed from the SharePoint Embedded platform. Each of these factors contributes to the overall cost, ensuring that you only pay for the resources and services you use. You can view this usage and billing details in the [Microsoft Cost Management](https://ms.portal.azure.com/). +SharePoint Embedded employs a pay-as-you-go (PAYG) billing model through an Azure subscription. Billing is determined by how much data in GB you store in SharePoint Embedded in active and archived states, transactions used to access and modify the container and container contents, and data that's egressed from the SharePoint Embedded platform. Each of these factors contributes to the overall cost, ensuring that you only pay for the resources and services you use. You can view this usage and billing details in the [Microsoft Cost Management](https://portal.azure.com/). SharePoint Embedded has three billing meters, as shown. Refer to the [product page](https://adoption.microsoft.com/en-us/sharepoint/embedded/) for pricing details @@ -85,21 +97,26 @@ SharePoint Embedded has three billing meters, as shown. Refer to the [product pa 1. A valid Azure subscription is required. You can create one by following the steps here to [create an Azure subscription](/azure/cloud-adoption-framework/ready/azure-best-practices/initial-subscriptions). 1. A valid Azure resource group is required. You can create one by following the steps here to [create a resource group](/azure/azure-resource-manager/management/manage-resource-groups-portal). -1. In [Microsoft 365 admin center](https://admin.microsoft.com/), select **Setup**, and the view the **Files and Content** section. Select **Automate Content with Microsoft Syntex.** +1. In [Microsoft 365 admin center](https://admin.microsoft.com/), select **Setup**, and then view the **Files and Content** section. Select **Automate Content with Microsoft Syntex.** - ![Microsoft 365 admin center Files and Content](../../images/DTCBilling1.png) + ![Microsoft 365 admin center Files and Content](../images/DTCBilling1.png) 1. Select **Go to Syntex settings**. 1. Select **Apps** under **Syntex services for**, select **SharePoint Embedded** - ![Microsoft 365 admin center SharePoint Embedded Billing setting](../../images/DTCBilling2.png) + ![Microsoft 365 admin center SharePoint Embedded Billing setting](../images/DTCBilling2.png) 1. Follow the instructions on the **SharePoint Embedded** flyer to turn on SharePoint Embedded apps. -### [Billing Management](../billing/billingmanagement.md) +### [Billing management](monitor-usage-billing-cost.md) The [Microsoft Cost Management portal](https://portal.azure.com/#view/Microsoft_Azure_CostManagement/Menu/~/overview/openedBy/AzurePortal) provides a comprehensive overview of your costs, allowing you to track and analyze your spending for the SharePoint Embedded application. This guide walks you through the steps to view your billing details and SharePoint Embedded consumption in the Microsoft Cost Management portal. ### Invalid Billing/Turn off SharePoint Embedded If you turn off SharePoint Embedded or disconnect the linked Azure subscription, all users will immediately lose access to any application built on the service along with any read and write permissions. + +## Next steps + +- [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) diff --git a/docs/embedded/admin/create-apps-powershell.md b/docs/embedded/admin/create-apps-powershell.md new file mode 100644 index 0000000000..b0d6edf082 --- /dev/null +++ b/docs/embedded/admin/create-apps-powershell.md @@ -0,0 +1,112 @@ +--- +title: Create apps with PowerShell +description: Create and configure SharePoint Embedded apps with SharePoint PowerShell. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Create apps with PowerShell + +**Applies to:** Owning tenant administrator — SharePoint Embedded admin / Global admin + + + +Use SharePoint PowerShell to create SharePoint Embedded container types for apps. Each container type is associated with one Microsoft Entra application. + +## Before you begin + +Make sure you have: + +- The SharePoint Embedded Administrator or Global Administrator role. +- The latest SharePoint Online Management Shell. +- The Microsoft Entra application ID that owns the container type. +- For standard billing setup, owner or contributor permissions on the Azure subscription. + +> [!IMPORTANT] +> Choose the billing method when you create the container type. You can't change the billing method after creation. + +## Create a standard billed app + +Use standard billing when the organization that owns the app pays for SharePoint Embedded usage. + +```powershell +New-SPOContainerType -ContainerTypeName -OwningApplicationId +``` + +Set up billing for the standard container type by assigning an Azure subscription, resource group, and region. + +```powershell +Add-SPOContainerTypeBilling -ContainerTypeId -AzureSubscriptionId -ResourceGroup -Region +``` + +## Create a pass-through billed app + +Use pass-through billing, also known as direct-to-customer billing, when the consuming tenant pays for SharePoint Embedded usage. + +```powershell +New-SPOContainerType -IsPassThroughBilling -ContainerTypeName -OwningApplicationId +``` + +For pass-through billing, the consuming tenant administrator must set up Microsoft 365 pay-as-you-go services before users can access the app. For more information, see [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md). + +## Create a trial app + +Use a trial app for evaluation and proof-of-concept work. + +```powershell +New-SPOContainerType -TrialContainerType -ContainerTypeName -OwningApplicationId +``` + +Trial apps are valid for 30 days. + +## View apps + +List SharePoint Embedded apps created in the owning tenant. + +```powershell +Get-SPOContainerType +Get-SPOContainerType -ContainerTypeId +``` + +## Update app properties + +Update supported container type properties. + +```powershell +Set-SPOContainerType -ContainerTypeId + [-ContainerTypeName ] + [-WhatIf] [-Confirm] +``` + +## Configure app behavior + +Configure supported container type settings, such as discoverability and sharing restrictions. + +```powershell +Set-SPOContainerTypeConfiguration -ContainerTypeId -DiscoverabilityDisabled $true +Set-SPOContainerTypeConfiguration -ContainerTypeId -SharingRestricted $true +``` + +View the current configuration. + +```powershell +Get-SPOContainerTypeConfiguration -ContainerTypeId +``` + +## Related content + +- [Create apps in SharePoint admin center](create-apps-sharepoint-admin-center.md) +- [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md) +- [PowerShell reference](../reference/powershell.md) + +## Next steps + +Install the app in the tenant: [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md). diff --git a/docs/embedded/admin/create-apps-sharepoint-admin-center.md b/docs/embedded/admin/create-apps-sharepoint-admin-center.md new file mode 100644 index 0000000000..9510bea579 --- /dev/null +++ b/docs/embedded/admin/create-apps-sharepoint-admin-center.md @@ -0,0 +1,245 @@ +--- +title: Create Apps in SharePoint Admin Center +description: Create a SharePoint Embedded app from the SharePoint admin center and validate the new app registration. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Create apps in SharePoint admin center + +**Applies to:** Owning tenant administrator — SharePoint Embedded admin / Global admin + + + +Use the SharePoint admin center **Apps** experience to create a SharePoint Embedded app that your organization owns. +The create flow can register a new Microsoft Entra app or associate an existing Entra app with a new SharePoint Embedded app. + +A **SharePoint Embedded Administrator** can complete this flow end to end. Creating a line-of-business app no longer depends on a Global Administrator granting consent first, so you can create an app and hand it off to developers quickly. You add up to three owners during creation, so developers you assign as owners can start building against the app right away. + +This article explains the administrator flow and calls out where command or API details affect app readiness. + +> [!IMPORTANT] +> You need the **SharePoint Embedded Administrator** role or Global Administrator privileges to create and manage SharePoint Embedded apps in the SharePoint admin center. For a line-of-business app, the SharePoint Embedded Administrator can create the app without Global Administrator consent. + +## Before you begin + +Confirm these prerequisites. + +- Your tenant has SharePoint available. +- You can sign in to the [SharePoint admin center](https://admin.microsoft.com/sharepoint). +- You have the SharePoint Embedded Administrator role or Global Administrator role. +- You know whether to create a new Microsoft Entra app or use an existing app registration. +- You know which owners should manage the app. +- You know which billing type applies to the app. +- For owner organization billing, you have owner or contributor access to the Azure subscription used for billing. + +For role details, see [SharePoint Embedded administrator](admin-overview.md). + +## Understand the Apps page + +In the SharePoint admin center, SharePoint Embedded apps are managed from **SharePoint Embedded** > **Apps**. +The page includes two app inventory views. + +| Tab | Use it for | +| --- | --- | +| Installed apps | Review SharePoint Embedded apps installed in the tenant. The list includes apps built by your organization and by external organizations. It currently doesn't include Microsoft-built SharePoint Embedded apps. | +| Owned apps | Review SharePoint Embedded apps created by your organization, regardless of installation status. | + +The **Installed apps** tab shows each app's publisher, billing type, billing status, and installed date. + +![SharePoint admin center Apps page on the Installed apps tab, listing installed apps with columns for app name, publisher, billing type, billing status, and installed date.](../images/installed-apps-page.png) + +*Figure 1: The Installed apps tab lists apps built by your organization and external organizations, with their publisher and billing status.* + +The **Owned apps** tab shows each app's actions, billing type, owners, and created date. +Use it to verify app creation and to start installation when an app is ready. + +![SharePoint admin center Apps page on the Owned apps tab, listing apps created by the organization with columns for app name, actions, billing type, owners, and created date.](../images/owned-apps-page.png) + +*Figure 2: The Owned apps tab lists every app your organization created, regardless of installation status.* + +> [!TIP] +> Use **Owned apps** as the tenant inventory for apps your organization builds. +> Use **Installed apps** as the tenant inventory for apps available in the tenant. + +## Create an app + +1. Sign in to the [SharePoint admin center](https://admin.microsoft.com/sharepoint). +1. In the left navigation, expand **SharePoint Embedded**. +1. Select **Apps**. +1. Select **+ Create app**. +1. Wait for the **Create app** panel to open. + +![SharePoint admin center Create app panel showing the Entra app registration options New app and Use an existing Entra app, a New Entra app name field, an Owners field, and the billing type section.](../images/create-app-panel-1.png) + +*Figure 3: The Create app panel registers a Microsoft Entra app, assigns owners, and sets the billing type in a single flow.* + +## Choose the Entra app registration option + +In **Entra app registration**, choose one option. + +| Option | Use it when | +| --- | --- | +| New app | You want the admin center flow to create a new Microsoft Entra application registration. | +| Use an existing Entra app | You already have a Microsoft Entra app and want to associate it with the SharePoint Embedded app. | + +If you choose **New app**, enter the new Entra app name. + +If you choose **Use an existing Entra app**, search by application ID or application name. + +Don't create duplicate app registrations unless your app architecture requires them. + +Use one owning application for the SharePoint Embedded app that owns its container type. + +## Add app owners + +Add up to three owners in the **Owners** field. + +Owners can manage app settings and billing configuration. + +Assign the developers who build the app as owners so you can hand the app off immediately after creation. + +Choose durable administrative owners instead of individual temporary project members when an owner must persist beyond the initial project. + +Record the owners in your internal operations documentation. + +If an owner leaves the organization, update ownership before removing their account. + +## Select billing type + +Billing type determines who pays for SharePoint Embedded consumption. + +Choose carefully because billing type can't be changed after app creation. + +| Billing type | Meaning | +| --- | --- | +| User org | The organization using the app sets up pay-as-you-go billing in the Microsoft 365 admin center. | +| Owner org | Usage is billed to the organization that owns the app. | + +Use **User org** for scenarios where each consuming tenant is responsible for billing. + +Use **Owner org** when your organization owns the app and manages billing directly. + +For billing concepts, see [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md) and [Monitor usage, billing, and cost](monitor-usage-billing-cost.md). + +## Configure owner organization billing + +If you select **Owner org**, choose when to connect the Azure billing subscription in **Billing subscription setup**. + +| Option | Result | +| --- | --- | +| Setup now | You provide the Azure subscription and resource group during app creation, and billing is attached when the app is created. | +| Setup later | The app is created without a billing subscription. You can attach billing later from the app details panel on the **Installed apps** tab. | + +1. Select **Setup now** or **Setup later**. +1. If you select **Setup now**, provide the subscription information requested by the admin center. +1. Confirm that the subscription and resource group are valid. + +![Create app panel scrolled to show an owner added, the Owner org billing type selected, and the Billing subscription setup options Setup now and Setup later, followed by Advanced settings.](../images/create-app-panel-2.png) + +*Figure 4: For Owner org billing, choose Setup now to attach an Azure subscription during creation, or Setup later to attach it from the app details panel afterward.* + +> [!NOTE] +> **User org** billing isn't set up in this panel. For a User org app, a Global Administrator in the consuming tenant sets up billing in the Microsoft 365 admin center before users can access the app. Only a Global Administrator can set up billing. + +## Configure advanced settings + +Expand **Advanced settings** when you need optional settings. + +The **Graph Explorer** toggle supports development and testing. + +Turn it on only when administrators or developers need to explore Microsoft Graph requests for the app. + +Turn it off when it isn't needed. + +For Graph Explorer documentation, see [Use Graph Explorer to try Microsoft Graph APIs](/graph/graph-explorer/graph-explorer-overview). + +## Submit the app + +1. Review the Entra app registration selection. +1. Review the app owners. +1. Review billing type. +1. Review advanced settings. +1. Select **Create app**. + +When you select **Create app**, the admin center completes these steps together: + +- Registers the Microsoft Entra app, or associates the existing Entra app you selected. +- Creates the SharePoint Embedded app, which is also called the container type. +- Installs the app in your tenant. +- Attaches billing when you select **Owner org** and **Setup now**. + +A successful create flow also installs the app, so the app appears on the **Installed apps** tab. If only the install step fails, the SharePoint Embedded app is created but not installed. In that case, install it later from the **Owned apps** tab. See [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md). + +The **Create app** button is available only after required fields are complete. + +If you cancel the panel, no app is created. + +## Validate app creation + +After the app is created, validate it in the SharePoint admin center. + +1. Return to **SharePoint Embedded** > **Apps**. +1. Open **Owned apps**. +1. Confirm that the app appears in the owned app inventory. +1. Confirm the owner list. +1. Confirm the billing type. +1. Check billing status. +1. If the app is also installed, confirm that it appears in **Installed apps**. + +Use the billing status to decide the next action. + +| Status | Action | +| --- | --- | +| Active | Continue with installation, consent, and operational validation. | +| Inactive | Complete billing setup or resolve the billing issue before production use. | + +## Prepare for installation + +App creation doesn't complete the consuming tenant setup by itself. + +Depending on the app model, the tenant still needs installation, consent, and permission registration. + +Continue with these tasks. + +1. Install or register the app in the tenant. +1. Grant admin consent for requested permissions. +1. Register container type application permissions when the owning app requires it. +1. Set up pass-through billing if the consuming tenant pays for usage. +1. Verify containers after the app creates content. + +## Troubleshoot app creation + +Use these checks if creation fails or the app isn't usable. + +- Confirm your account has the SharePoint Embedded Administrator role. +- Confirm the selected existing Entra app exists and is available in the tenant. +- Confirm owners resolve in the people picker. +- Confirm required billing fields are complete. +- Confirm owner organization billing uses a valid Azure subscription and resource group. +- If the app is inactive, complete or repair billing setup. +- If users can't access the app after creation, verify installation, admin consent, and container type permissions. + +> [!WARNING] +> Don't treat app creation as proof that the app is ready for users. +> Users may still be blocked by missing installation, missing consent, or invalid billing. + +## Related content + +- [Admin overview](admin-overview.md) +- [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md) +- [Grant admin consent and permissions](grant-admin-consent-permissions.md) +- [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) + +## Next steps + +Install the app by using [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md). diff --git a/docs/embedded/admin/grant-admin-consent-permissions.md b/docs/embedded/admin/grant-admin-consent-permissions.md new file mode 100644 index 0000000000..1cdbff056e --- /dev/null +++ b/docs/embedded/admin/grant-admin-consent-permissions.md @@ -0,0 +1,149 @@ +--- +title: Grant Admin Consent and Permissions +description: Review SharePoint Embedded permissions, grant admin consent, and verify the consent state in a consuming tenant. +ms.date: 07/13/2026 +ms.reviewer: dilucesr +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Grant admin consent and permissions + +**Applies to:** Consuming tenant admin — Global admin + + + +Grant admin consent when a SharePoint Embedded app needs high-privilege permissions in your Microsoft 365 tenant. Application permissions always require admin consent, while delegated permissions for SharePoint Embedded don't. To learn more, see [Grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal). + +Use this article to review requested permissions, grant consent, and troubleshoot common consent failures. + +> [!IMPORTANT] +> Grant consent only for apps and publishers your organization trusts. +> Review the app ID, publisher, and requested permissions before approving. + +## Before you begin + +Confirm these prerequisites: + +- You can grant admin consent (see [Grant tenant-wide admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal#prerequisites)). +- You know you Microsoft Entra tenant ID (see [How to find your Microsof Entra tenant ID](/entra/fundamentals/how-to-find-tenant)) +- You know the owning application client ID. +- You understand why the app needs each requested permission. +- The app owner has provided installation and consent instructions. +- Billing requirements are known for the app model. + +## Understand consent in SharePoint Embedded + +An owning application must meet two requirements before it can act on a consuming tenant. + +1. The owning app must have a service principal installed in the consuming tenant. +1. The owning app must be granted the permissions needed to register the container type and access its containers in the consuming tenant. + +Both requirements are typically satisfied when a tenant administrator grants admin consent to the owning application. However, admin consent isn't a hard requirement for the owning application to act on the consuming tenant. SharePoint Embedded apps that operate exclusively on behalf of a user don't need to be granted admin consent. Granting admin consent for apps that operate exclusively on behalf of a user may improve user experience as the app won't require consent from every user who wants to sign into the app. + +> [!CAUTION] +> You need to understand the implications of granting admin consent to an application. To learn more, see [Grant tenant-wide admin consent](/entra/identity/enterprise-apps/grant-admin-consent). + +These are the permissions that the owning application needs to act on the consuming tenant: + +| Permission | Why the app requests it | Consent note | +| --- | --- | --- | +| [`FileStorageContainerTypeReg.Selected`](/graph/permissions-reference#filestoragecontainertyperegselected) | Register the container type in the consuming tenant. | The app can request this as delegated or application permission. If delegated registration is used, no admin consent is required but the user performing the registration must be a SharePoint Embedded Administrator or Global Administrator. | +| [`FileStorageContainer.Selected`](/graph/permissions-reference#filestoragecontainerselected) | Access containers and content for its container type in the consuming tenant. | The app can request this as delegated or application permission. If delegated access is used, no admin consent is required but each user of the app will need to consent when signing into the app. | + +## Review requested permissions + +Before granting consent, review the requested permissions with the app owner. + +| Review item | Why it matters | +| --- | --- | +| Application client ID | Confirms you're consenting to the intended owning app. | +| Publisher | Helps validate trust and support ownership. | +| Permission list | Shows what the app can do after consent. | +| Container type ID | Identifies the container type the app owns. | +| Guest app access | Identifies other apps that may receive access through registration. | +| Billing model | Determines whether the tenant must configure billing before users can use the app. | + +Ask the app owner to explain any permission that doesn't align with the expected scenario. + +> [!CAUTION] +> - DON'T grant consent from a copied URL unless you've verified the `client_id` value in the URL. A consent URL grants permissions to the app identified by that client ID. +> +> - DON'T grant consent if you don't understand why each permission is being requested. + +## Grant admin consent from the consent endpoint + +The SharePoint Embedded may request admin consent on your tenant by providing you with, or redirecting you to, the admin consent URL. To learn more about the admin consent URL, see [Admin consent on the Microsoft identity platform](/entra/identity-platform/v2-admin-consent). + +```http +https://login.microsoftonline.com/{your-tenant-id}/v2.0/adminconsent?client_id={owning-app-clientid}&scope=https://graph.microsoft.com/.default&redirect_uri={spe-app-redirect-uri} +``` + +Confirm that in the admin consent URL: + +- `{your-tenant-id}` matches your Microsoft Entra tenant ID. +- `{owning-app-clientid}` matches the owning application client ID. +- `{spe-app-redirect-uri}` points to a URL in the SharePoint Embedded app. +- The scope value points to the `.default` Microsoft Graph scope. If the app owner gives you a different scope value, make sure you understand why. +- A `state` query parameter may or may not be present. + +For national cloud environments, the admin consent endpoint will vary. See [Microsoft Entra authentication endpoints on national clouds](/entra/identity-platform/authentication-national-cloud#microsoft-entra-authentication-endpoints) for more information. + +## Grant consent from Microsoft Entra admin experiences + +You can grant admin consent through the Microsoft Entra admin center only if the owning application already has a service principal in your tenant. For instructions on how to grant admin consent, see [Grant tenant-wide admin consent in Enterprise apps pane](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal#grant-tenant-wide-admin-consent-in-enterprise-apps-pane). + +## Verify the service principal + +After consent, confirm that the app is installed in your tenant. + +1. In the [Microsoft Entra admin center](https://entra.microsoft.com/), search for the owning application in the Enterprise pane by using its client ID. +1. Confirm that the application exists. +1. Confirm the publisher and application ID. +1. Confirm that permissions show the expected consent state. +1. Confirm that no unexpected permissions were granted. + +If the service principal is missing, consent didn't complete. + +## Troubleshoot consent failures + +Use these checks when consent fails. + +- Confirm the admin account can grant tenant-wide admin consent. +- Confirm the consent URL uses the correct consuming tenant ID. +- Confirm the `client_id` is the owning application client ID. +- Confirm the URL uses the expected `v2.0/adminconsent` endpoint and Graph `.default` scope. +- Confirm the app registration exists and is configured correctly by the app owner. +- Confirm the redirect URI or success handling is configured by the app owner. +- Confirm your tenant policies allow user or admin consent for the app. +- Confirm national cloud endpoints are correct when applicable. +- Confirm the app isn't blocked by publisher or enterprise app policies. + +## Troubleshoot access denied after consent + +Use these checks when consent succeeds but the app owner reports that API calls fail on your tenant. + +- Confirm the app owner registered the container type using the registration API. +- Confirm the app is the owning application for the container type when invoking the registration API. +- Confirm the app uses the expected `FileStorageContainer.Selected` permission for container and content access. +- Confirm the app uses app-only authentication when required. +- Confirm the app uses the correct delegated or app-only registration flow for its design. +- Confirm billing is active when the app uses pass-through billing. + +## Related content + +- [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md) +- [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md) +- [Manage containers with PowerShell](manage-containers-powershell.md) +- [Register file storage container type application permissions](../build/register-application-permissions.md) +- [Admin overview](admin-overview.md) + +## Next steps + +Configure billing in [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md). diff --git a/docs/embedded/admin/install-sharepoint-embedded-app.md b/docs/embedded/admin/install-sharepoint-embedded-app.md new file mode 100644 index 0000000000..f0df1373d4 --- /dev/null +++ b/docs/embedded/admin/install-sharepoint-embedded-app.md @@ -0,0 +1,249 @@ +--- +title: Install a SharePoint Embedded App +description: Install or register a SharePoint Embedded app in a consuming tenant and validate the tenant setup. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Install a SharePoint Embedded app + +**Applies to:** Consuming tenant admin — SharePoint Embedded admin / Global admin + + + +Install a SharePoint Embedded app when a consuming Microsoft 365 tenant needs to use the app. + +Installation makes the app visible for tenant administration, but the tenant may still need admin consent, container type permission registration, and billing setup before users can access content. + +This article focuses on the consuming-tenant administrator path in the SharePoint admin center. + +> [!IMPORTANT] +> A consuming tenant admin is typically a user assigned the **SharePoint Embedded Administrator** role. +> Global Administrators can also perform SharePoint Embedded administration tasks. + +Use this article with [Choose an App Model: Single-Tenant or Multitenant](../plan/choose-app-model.md) and the app creation guidance. + +The app model determines who owns the app, who installs or onboards it, where containers are created, who pays, and which admins must consent or configure billing. + +## Before you begin + +Confirm these prerequisites. + +- You can sign in to the consuming tenant. +- Your account has the SharePoint Embedded Administrator role or Global Administrator role. +- The SharePoint Embedded app exists in the owning tenant. +- You have the app identity or installation link provided by the app owner. +- You know whether billing is handled by the app owner or by the user organization. +- You know which permissions the app requests. +- You can complete admin consent if the installation flow requires it. +- You know whether the app is a single-tenant line-of-business app or a multitenant ISV app. + +For role information, see [Admin overview](admin-overview.md). + +## Understand the consuming tenant path + +A consuming tenant is the Microsoft 365 tenant where users run the SharePoint Embedded app and where the app stores content in containers. + +The consuming tenant admin manages the app and containers in that tenant. + +For a single-tenant line-of-business app, the owning tenant and consuming tenant are usually the same. + +For a multitenant ISV app, each customer tenant is a consuming tenant and customer files remain in the customer Microsoft 365 tenant boundary. + +Consuming tenant administrators use two administration surfaces. + +| Surface | Use it for | +| --- | --- | +| SharePoint admin center | View installed apps, active containers, deleted containers, and container details. | +| SharePoint Online Management Shell | Enumerate applications, enumerate containers, update labels, configure sharing, and manage lifecycle operations. | + +Use the SharePoint admin center when you need guided installation and validation. + +Use PowerShell for repeatable inventory and operations after installation. + +## Install from the SharePoint admin center + +Use the SharePoint Embedded **Apps** experience in the SharePoint admin center when the app is available to install. + +The **Installed apps** tab lists SharePoint Embedded apps built by your organization and by external organizations. It currently doesn't include Microsoft-built SharePoint Embedded apps. + +1. Sign in to the [SharePoint admin center](https://admin.microsoft.com/sharepoint). +1. In the left navigation, expand **SharePoint Embedded**. +1. Select **Apps**. +1. Review **Installed apps** to confirm whether the app is already installed. +1. If you own the app, review **Owned apps** and locate the app. +1. Select the available install action for the app. +1. Review the app name, publisher, and billing information. +1. Continue through the installation prompts. +1. Complete admin consent if the flow directs you to consent. +1. Finish the installation. + +The exact installation prompts can vary by app ownership and billing model. + +Don't continue if the app identity or publisher is unexpected. + +> [!CAUTION] +> Install only apps that your organization trusts. +> A SharePoint Embedded app can create and access containers according to the permissions granted to it. + +## Install an owned app that didn't install + +A successful create flow installs the app automatically, so you don't usually install an owned app separately. + +Only when the install step in the create flow fails is the SharePoint Embedded app created but not installed. + +In that case, install the app from the **Owned apps** tab. + +1. Go to **SharePoint Embedded** > **Apps**. +1. Open **Owned apps**. +1. Locate the app that isn't installed. +1. Select the install action for the app. +1. Complete the installation prompts. + +After installation completes, the app appears on the **Installed apps** tab. + +## Validate installation + +After installation, validate the app inventory. + +1. Return to **SharePoint Embedded** > **Apps**. +1. Open **Installed apps**. +1. Confirm that the app is listed. +1. Confirm the app name and publisher. +1. Confirm the billing type and billing status. +1. If the app is owned by your organization, open **Owned apps** and confirm ownership metadata. +1. Record the owning application ID for future PowerShell and permission review. + +Select an app on the **Installed apps** tab to open its details panel. The panel shows the app's status, Entra app ID, SharePoint Embedded app ID, publisher, and billing information. + +![App details panel for an installed app, showing an Active status, the Entra app ID, the SharePoint Embedded app ID, the publisher, and billing info that includes billing status, Azure subscription ID, resource group, and billing type.](../images/installed-app-details-panel.png) + +*Figure 1: The app details panel on the Installed apps tab shows identifiers and billing information, and lets you copy the Entra and SharePoint Embedded app IDs.* + +If the app isn't visible, refresh the page and confirm that installation completed successfully. + +If the app remains missing, contact the app owner and verify the app identity. + +## Complete admin consent + +Installation and consent are related but not always the same task. + +The owning app must have a service principal installed in the consuming tenant and admin consent before it can register container type application permissions. + +> [!NOTE] +> When you create the app in the SharePoint admin center, consent is granted as part of the create flow, so you don't complete the manual admin consent step in this section. Use this section when the app is created another way, such as an app that another organization owns or an app registered directly in Microsoft Entra. + +Use [Grant admin consent and permissions](grant-admin-consent-permissions.md) to review the requested permissions and complete consent. + +Admin consent may be requested through the Microsoft identity platform admin consent endpoint, for example: + +```http +https://login.microsoftonline.com/{your-tenant-id}/v2.0/adminconsent?client_id={owning-app-clientid}&scope=https://graph.microsoft.com/.default&redirect_uri={spe-app-redirect-uri} +``` + +Use the exact client ID provided by the app owner. +Don't substitute a different application ID. + +## Confirm billing requirements + +SharePoint Embedded supports standard and pass-through billing models. + +For pass-through billing, a Global Administrator in the consuming tenant must set up billing in the Microsoft 365 admin center before users can access the app. Only a Global Administrator can set up billing; the SharePoint Embedded Administrator role can't. + +If billing is invalid or SharePoint Embedded is turned off, users can no longer create new containers, although existing containers and their content remain accessible. + +### Attach or change billing from the details panel + +If billing was skipped during app creation, you can attach it later from the app details panel on the **Installed apps** tab. For an **Owner org** app that your organization owns, you can also change the billing subscription that's already attached from the same panel. + +1. Open **SharePoint Embedded** > **Apps** > **Installed apps**. +1. Select the app to open its details panel. +1. In **Billing info**, attach a billing subscription or update the existing one. + +For a **User org** app, billing isn't attached from this panel. A Global Administrator in the consuming tenant sets up billing in the Microsoft 365 admin center. See [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md). + +Use [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md) to configure billing for consuming-tenant scenarios. + +Use [Monitor usage, billing, and cost](monitor-usage-billing-cost.md) to review ongoing cost. + +## Verify containers after app use + +The app may not create containers until users or app processes start using it. +After containers exist, validate them. + +1. In the SharePoint admin center, go to **SharePoint Embedded** > **Active containers**. +1. Search or filter by application name. +1. Open a container details panel. +1. Review general metadata. +1. Review membership. +1. Confirm sensitivity label state if labels are required. +1. Review storage use. + +For detailed steps, see [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md). + +## Validate with PowerShell + +Use SharePoint Online Management Shell when you need a scripted check. + +Install the latest SharePoint Online Management Shell and connect to SharePoint Online. + +Then use the supported application inventory cmdlets. + +```powershell +Get-SPOApplication +``` + +To view details for a specific application, use the owning application ID. + +```powershell +Get-SPOApplication -OwningApplicationId +``` + +For command details, see [Manage containers with PowerShell](manage-containers-powershell.md) and [Get-SPOApplication](/powershell/module/sharepoint-online/get-spoapplication). + +## Manage container type registrations with Microsoft Graph + +Consuming tenant admins can also manage container type registrations programmatically. The [fileStorageContainerTypeRegistration](/graph/api/resources/filestoragecontainertyperegistration) resource represents the registration of a container type in a consuming tenant. Managing all registrations in the tenant requires the `FileStorageContainerTypeReg.Manage.All` delegated permission. + +| Operation | API | +| --- | --- | +| List registrations | [List container type registrations](/graph/api/filestorage-list-containertyperegistrations) | +| Get a registration | [Get container type registration](/graph/api/filestoragecontainertyperegistration-get) | +| Update a registration | [Update container type registration](/graph/api/filestoragecontainertyperegistration-update) | +| Delete a registration | [Delete container type registration](/graph/api/filestorage-delete-containertyperegistrations) | + +## Troubleshoot installation + +Use these checks when installation doesn't complete. + +- Confirm the administrator has the SharePoint Embedded Administrator role. +- Confirm the app identity and publisher. +- Confirm the app is available for your tenant. +- Confirm admin consent is granted for the correct application. +- Confirm the app has a service principal in the consuming tenant after consent. +- Confirm billing is active for pass-through apps. +- Confirm the app owner registered container type application permissions when required. +- Confirm users are assigned the required app roles or memberships. + +> [!NOTE] +> Access denied errors after installation often indicate missing consent, missing container type permission registration, or app-level permission configuration rather than a container problem. + +## Related content + +- [Admin overview](admin-overview.md) +- [Create apps in SharePoint admin center](create-apps-sharepoint-admin-center.md) +- [Grant admin consent and permissions](grant-admin-consent-permissions.md) +- [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) + +## Next steps + +Grant consent and verify permissions in [Grant admin consent and permissions](grant-admin-consent-permissions.md). diff --git a/docs/embedded/admin/manage-containers-powershell.md b/docs/embedded/admin/manage-containers-powershell.md new file mode 100644 index 0000000000..5509aa1038 --- /dev/null +++ b/docs/embedded/admin/manage-containers-powershell.md @@ -0,0 +1,275 @@ +--- +title: Manage Containers with PowerShell +description: Use SharePoint Online Management Shell to inventory and manage SharePoint Embedded apps and containers. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Manage containers with PowerShell + +**Applies to:** Consuming tenant admin — SharePoint Embedded admin / Global admin + + + +Use SharePoint Online Management Shell to automate SharePoint Embedded application and container administration. + +PowerShell is useful for inventory, reporting, lifecycle operations, sensitivity label updates, sharing configuration, and permission review. + +This article states the supported administrator cmdlets and links to canonical cmdlet references for deeper syntax details. + +> [!IMPORTANT] +> Use the latest version of SharePoint Online Management Shell before running SharePoint Embedded container administration cmdlets. + +## Before you begin + +Confirm these prerequisites. + +- Your account has the SharePoint Embedded Administrator role or Global Administrator role. +- You can connect to the tenant with SharePoint Online Management Shell. +- You know the tenant admin URL. +- You know the owning application ID when filtering application or container results. +- You understand the business impact before deleting containers. + +For role details, see [SharePoint Embedded administrator](admin-overview.md). + +## Install SharePoint Online Management Shell + +Install the [SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588). + +Open it from the Start menu or use a supported PowerShell host with the module available. + +Install the latest shell and connect to SharePoint Online before you run SharePoint Embedded cmdlets. + +For connection details, see [Connect-SPOService](/powershell/module/sharepoint-online/connect-sposervice). + +## Connect to SharePoint Online + +Connect to your tenant admin endpoint. + +```powershell +Connect-SPOService -Url https://-admin.sharepoint.com +``` + +Replace `` with your tenant name. + +Sign in with an account that has the required admin role. + +> [!TIP] +> Use a dedicated administrative account that follows your organization's privileged access policies. + +## Inventory SharePoint Embedded applications + +List SharePoint Embedded applications registered in the tenant. + +```powershell +Get-SPOApplication +``` + +View details for a specific owning application. + +```powershell +Get-SPOApplication -OwningApplicationId +``` + +For command details, see [Get-SPOApplication](/powershell/module/sharepoint-online/get-spoapplication). + +## View guest application permissions + +View guest application permissions for a SharePoint Embedded application. + +```powershell +Get-SPOApplication -OwningApplicationId -ApplicationId +``` + +`OwningApplicationId` is the ID of the SharePoint Embedded owning application. +`ApplicationId` is the guest application ID that has access to the SharePoint Embedded application. + +Application administration cmdlets don't apply to Microsoft Loop. + +## Configure application sharing + +Consuming tenant admins can configure the external sharing capability at the application level. + +```powershell +Set-SPOApplication -OwningApplicationId -SharingCapability -OverrideTenantSharingCapability +``` + +`SharingCapability` supports these values: + +- `Disabled` +- `ExistingExternalUserSharingOnly` +- `ExternalUserSharingOnly` +- `ExternalUserAndGuestSharing` + +The `OverrideTenantSharingCapability` value can be `$true` or `$false`. +Review your tenant sharing policy before overriding tenant sharing behavior. + +## List active containers + +List active containers for a SharePoint Embedded application. + +```powershell +Get-SPOContainer -OwningApplicationId | FT +``` + +The `OwningApplicationId` is the ID of the SharePoint Embedded application. + +For Microsoft Loop containers, use this owning app ID with container administration cmdlets: + +```text +a187e399-0c36-4b98-8f04-1edc167a0996 +``` + +For command details, see [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer). + +## List containers sorted by storage + +Sort containers by storage when investigating cost or growth. + +```powershell +Get-SPOContainer -OwningApplicationId -SortByStorage | FT +``` + +Use `Ascending` or `Descending` for ``. + +Use this view with [Monitor usage, billing, and cost](monitor-usage-billing-cost.md) to find high-growth apps or containers. + +## Get container details + +View details for a specific container by container ID or site URL. + +```powershell +Get-SPOContainer -Identity +Get-SPOContainer -Identity +``` + +The detailed result can include storage, ownership details, site URL, label information, and owner count. + +Use the site URL when configuring some compliance controls in Microsoft Purview. + +## Set or remove a sensitivity label + +Set the sensitivity label for a container. + +```powershell +Set-SPOContainer -Identity -SensitivityLabel +``` + +Remove the sensitivity label from a container. + +```powershell +Set-SPOContainer -Identity -RemoveLabel +``` + +Coordinate sensitivity label changes with compliance administrators. + +For compliance guidance, see [Apply security and compliance controls](apply-security-compliance-controls.md). + +## Manage container membership + +Consuming-tenant administrators can add, remove, or change a user's role on a container directly (September 2025): + +```powershell +Add-SPOContainerUser -ContainerId -LoginName -Role +Set-SPOContainerUser -ContainerId -LoginName -Role +Remove-SPOContainerUser -ContainerId -LoginName +``` + +For command details, see [Add-SPOContainerUser](/powershell/module/microsoft.online.sharepoint.powershell/add-spocontaineruser), [Set-SPOContainerUser](/powershell/module/microsoft.online.sharepoint.powershell/set-spocontaineruser), and [Remove-SPOContainerUser](/powershell/module/microsoft.online.sharepoint.powershell/remove-spocontaineruser). + +## Delete a container + +Move a container to the deleted container collection. + +```powershell +Remove-SPOContainer -Identity +``` + +Deleting a container can cause data loss, broken links, application failures, and permission issues. + +Notify container owners and app owners before deleting. + +> [!WARNING] +> Deleting a container may interrupt usage of the SharePoint Embedded application that owns it. + +For command details, see [Remove-SPOContainer](/powershell/module/sharepoint-online/remove-spocontainer). + +## View deleted containers + +List deleted containers in the deleted container collection. + +```powershell +Get-SPODeletedContainer +``` + +For command details, see [Get-SPODeletedContainer](/powershell/module/sharepoint-online/get-spodeletedcontainer). + +## Restore a deleted container + +Restore a deleted container from the deleted container collection. + +```powershell +Restore-SPODeletedContainer -Identity +``` + +After restore, validate the container in the SharePoint admin center and ask the app owner to test the app. + +## Permanently delete a container + +Permanently delete a container from the deleted container collection when recovery is no longer required. + +```powershell +Remove-SPODeletedContainer -Identity +``` + +For command details, see [Remove-SPODeletedContainer](/powershell/module/sharepoint-online/remove-spodeletedcontainer). + +> [!CAUTION] +> Permanent deletion can't be reversed. +> Confirm retention and legal requirements before running this command. + +## Manage guest application permissions + +If permitted, admins can add, edit, and remove guest application access to SharePoint Embedded applications. +Use `Set-SPOApplicationPermission` for this scenario. + +```powershell +Set-SPOApplicationPermission + [[-OwningApplicationId] ] + [[-GuestApplicationId] ] + [[-PermissionAppOnly] ] + [[-PermissionDelegated] ] +``` + +For command details, see [Set-SPOApplicationPermission](/powershell/module/sharepoint-online/set-spoapplicationpermission). + +## Script safely + +Follow these operational practices. + +- Export inventory before lifecycle changes. +- Test filters with read-only commands first. +- Use explicit container IDs for delete and restore operations. +- Log command output for change records. +- Notify app owners before deleting or restoring containers. +- Review storage-heavy containers before making cost decisions. +- Coordinate label and compliance changes with compliance admins. + +## Related content + +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) +- [Monitor usage, billing, and cost](monitor-usage-billing-cost.md) +- [Review audit events](review-audit-events.md) +- [Apply security and compliance controls](apply-security-compliance-controls.md) + +## Next steps + +Monitor consumption in [Monitor usage, billing, and cost](monitor-usage-billing-cost.md). diff --git a/docs/embedded/admin/manage-containers-sharepoint-admin-center.md b/docs/embedded/admin/manage-containers-sharepoint-admin-center.md new file mode 100644 index 0000000000..ba36214f30 --- /dev/null +++ b/docs/embedded/admin/manage-containers-sharepoint-admin-center.md @@ -0,0 +1,322 @@ +--- +title: Manage Containers in SharePoint Admin Center +description: View, inspect, delete, restore, and manage SharePoint Embedded containers in the SharePoint admin center. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Manage containers in SharePoint admin center + +**Applies to:** Consuming tenant admin — SharePoint Embedded admin / Global admin + + + +Use the SharePoint admin center to manage SharePoint Embedded containers through a graphical experience. + +The SharePoint Embedded container pages help consuming tenant admins view active containers, inspect details, manage membership, apply sensitivity labels, archive and reactivate containers, delete containers, restore deleted containers, and permanently delete containers. + +> [!IMPORTANT] +> To manage SharePoint Embedded containers, assign the **SharePoint Embedded Administrator** role. +> A Global Administrator can also perform these tasks. + +## Before you begin + +Confirm these prerequisites. + +- You can sign in to the [SharePoint admin center](https://admin.microsoft.com/sharepoint). +- Your account has the SharePoint Embedded Administrator role or Global Administrator role. +- The SharePoint Embedded app is installed in the tenant. +- Containers exist for the app. +- You understand the business impact before deleting or permanently deleting any container. + +For role context, see [Admin overview](admin-overview.md). + +## Open container management + +1. Sign in to the [SharePoint admin center](https://admin.microsoft.com/sharepoint). +1. In the left navigation, expand **SharePoint Embedded**. +1. Select **Active containers** to view active containers. +1. Select **Archived containers** to view containers in the archived state. +1. Select **Deleted containers** to view containers in the deleted container collection. + +A SharePoint Embedded Administrator sees only the SharePoint Embedded-specific pages that apply to the role. +The role doesn't expose general SharePoint **Active sites** or **Deleted sites** pages. + +![SharePoint admin center left navigation for a SharePoint Embedded Administrator, showing only the Active containers and Deleted containers pages.](../images/ctaux2.png) + +## View active containers + +The **Active containers** page shows active containers in the tenant. + +Use it for inventory, compliance review, and lifecycle decisions. + +The **Active containers** page shows these container properties. + +| Column or property | Meaning | +| --- | --- | +| Container name | Name provided by the container owner. | +| Application name | SharePoint Embedded application that the container belongs to. | +| Publisher | Organization that owns the application. | +| Ownership type | Tenant-owned, user-owned, or group-owned. | +| Principal owner | User or group whose lifecycle affects the container lifecycle, when applicable. | +| Storage | Storage used by files in the container. | +| Owners | Users assigned the owner role. | +| Owner count | Number of owners. | +| Sensitivity label | Label assigned to the container. | +| Created on | Date and time the container was created. | + +Use these fields to identify stale, large, unlabeled, or ownership-risk containers. + +![Active containers page listing containers with columns for name, application, publisher, ownership type, storage, owners, sensitivity label, and created date.](../images/ctaux3.png) + +## Search, sort, and filter active containers + +Use the active container page controls to narrow the inventory. + +1. Search by container name. +1. Sort by supported columns such as storage or created date. +1. Filter by application name. +1. Filter by publisher. +1. Filter by ownership type. +1. Filter by principal owner. +1. Filter by owner count. +1. Filter by created date. + +> [!NOTE] +> Filtering behavior on the **Active containers** page differs from the **Active sites** page in the SharePoint admin center. + +![Active containers page search box used to find a container by name.](../images/search.png) + +![Active containers page sort control applied to the storage and created-on columns.](../images/sorting.png) + +![Active containers page filter panel with options for application name, publisher, ownership type, principal owner, owner count, and created date.](../images/filter.png) + +## Inspect container details + +Open a container details panel when you need more information. + +The details view includes two tabs. + +| Tab | Use it for | +| --- | --- | +| General | Review container metadata, usage, and configuration settings. | +| Membership | Review and manage user permissions for roles associated with the container. | + +Review the general tab before lifecycle operations. + +Review membership before changing users or owner assignments. + +![Container details General tab showing container metadata, usage, and configuration settings.](../images/ctaux4.png) + +## Manage membership + +The SharePoint Embedded platform supports four roles: Owner, Manager, Writer, and Reader. + +An individual SharePoint Embedded application may not use all four roles and may display different role names in its own user experience. + +In the SharePoint admin center membership panel, administrators can: + +1. Add a user to a role. +1. Reassign a user from one role to another role. +1. Remove a user from a role. + +Use membership changes to maintain access continuity when owners change roles or leave the organization. +Coordinate with app owners when the app has its own membership workflow. + +![Container details Membership tab showing the Owner, Manager, Writer, and Reader roles with their assigned users.](../images/ctaux5.png) + +![Add-user picker used to select a tenant user and assign a container role.](../images/add-owners-one.png) + +![Reassign control used to move a user from one container role to another.](../images/reassign-user.png) + +![Remove control used to confirm removing a user from a container role.](../images/remove-user.png) + +## Set a sensitivity label + +Admins can set a sensitivity label on a container from the Active containers page. + +Open the container details panel and use the settings area. + +Before applying a label, confirm: + +- The label exists and is published to the right administrators. +- The label is appropriate for the content and app scenario. +- The app owner understands any access or protection impact. +- Compliance administrators approve the labeling approach. + +![Container details settings area with the sensitivity label selector for an active container.](../images/sensitivity-label.png) + +For broader controls, see [Apply security and compliance controls](apply-security-compliance-controls.md). + +## Archive a container + +Archive a container when it's no longer actively used but must be retained for legal, compliance, or business purposes. Documents in an archived container can't be accessed by any user or application until the container is reactivated. + +1. Open **Active containers**. +1. Select the container. +1. Select **Archive**. +1. Review the side panel that explains the archival implications and reactivation options. +1. Select **Archive** to confirm, or cancel to return to active containers. + +The container moves to the **Archived containers** page. + +![Archive action on the Active containers page with a container selected.](../images/active-containers-archive-action.png) + +## View archived containers + +The **Archived containers** page lists containers in the tenant's archived container collection. It shows the following metadata: + +- Container name +- Application name +- Publisher +- Status +- Time archived +- Archived by +- Storage (GB) +- Ownership type +- Principal owner + +Use this page to review archived containers, decide on reactivation timing, and manage their lifecycle. The Archived containers page also provides the same delete experience as active containers for selecting and deleting containers. + +![Archived containers page listing containers with columns for name, application, publisher, status, time archived, archived by, storage, ownership type, and principal owner.](../images/archived-containers-page.png) + +## Reactivate archived containers + +Archived containers aren't accessible to users or applications until reactivated. Reactivation time depends on how long the container has been archived. + +### Reactivate recently archived containers + +Containers archived within the last seven days are in the **Recently archived** state and reactivate quickly. + +1. Open **Archived containers**. +1. Select a Recently archived container. +1. Select **Reactivate**. +1. Review the side panel with reactivation timing. +1. Select **Reactivate** to confirm, or cancel to return. + +The container moves to the **Active containers** page. + +![Reactivate action on a recently archived container in the Archived containers page.](../images/reactivate-recently-archived-container.png) + +### Reactivate fully archived containers + +Containers archived longer than seven days are in the **Fully archived** state and require a 24-hour reactivation window. + +1. Open **Archived containers**. +1. Select a Fully archived container. +1. Select **Reactivate**. +1. Review the side panel that states the **24 hours** reactivation time. +1. Select **Reactivate** to submit the request, or cancel to return. + +The request displays as "Reactivating" on the Archived containers page. After 24 hours, the container moves to the **Active containers** page. + +![Reactivate action on a fully archived container, showing the 24-hour reactivation notice.](../images/reactivate-fully-archived-container.png) + +## Delete an active or archived container + +Delete a container only when there's a clear business reason. + +Container deletion can affect the SharePoint Embedded app that owns the container. + +Potential impacts include: + +- Content loss from the app experience. +- Broken links or references. +- Application errors if the app expects the container to exist. +- Permission or workflow disruption. + +To delete a container: + +1. Open **Active containers**. +1. Select the container. +1. Select the delete action when it becomes available. +1. Review the warning panel. +1. Confirm deletion only after validating business impact. + +The container moves to the deleted container collection. + +![Delete action enabled on the Active containers page after a container is selected.](../images/ctaux7.png) + +> [!WARNING] +> Deleting a container may interrupt the associated SharePoint Embedded application. +> +> Notify app owners before deleting containers. + +## View deleted containers + +The **Deleted containers** page lists containers in the tenant deleted container collection. +The **Deleted containers** page shows metadata similar to active containers and adds **Deleted on**. + +Use the deleted container view to: + +1. Confirm that a deleted container is recoverable. +1. Review storage and ownership. +1. Sort by supported columns such as storage, created date, or deleted date. +1. Filter by app, publisher, ownership type, principal owner, owner count, created date, or deleted date. +1. Decide whether to restore or permanently delete the container. + +Deleted containers are permanently purged after 93 days unless a retention policy changes the outcome. + +![Deleted containers page listing containers with a Deleted on column added.](../images/ctaux6.png) + +![Sort control on the Deleted containers page applied to storage, created-on, and deleted-on columns.](../images/sorting-on-deleted.png) + +![Filter panel on the Deleted containers page with options for application, publisher, ownership type, principal owner, owner count, created date, and deleted date.](../images/filter-on-delete.png) + +## Restore a deleted container + +Restore a container when deletion was accidental or the app still needs the content. + +1. Open **Deleted containers**. +1. Select the container. +1. Select **Restore**. +1. Wait for the background operation to complete. +1. Confirm the container appears on **Active containers**. +1. Ask the app owner to validate the app experience. + +![Restore link on the Deleted containers page for a selected container.](../images/ctaux10.png) + +## Permanently delete a container + +Permanently delete a container only when recovery is no longer required and retention policies allow deletion. + +1. Open **Deleted containers**. +1. Select the container. +1. Select **Permanently delete**. +1. Review the confirmation warning. +1. Confirm the action only if the organization no longer needs the content. + +After permanent deletion, the container is removed from the deleted container collection and can't be restored. + +![Permanently delete action enabled on the Deleted containers page for a selected container.](../images/ctaux12.png) + +> [!CAUTION] +> Permanent deletion is irreversible. +> Confirm retention, legal hold, and app owner requirements before proceeding. + +## When to use PowerShell instead + +Use PowerShell when you need automation or repeatable reporting. + +For example, use PowerShell to enumerate applications, list containers for an owning application, sort containers by storage, set sensitivity labels, delete containers, restore deleted containers, or permanently delete deleted containers. + +Continue with [Manage containers with PowerShell](manage-containers-powershell.md). + +## Related content + +- [Admin overview](admin-overview.md) +- [Manage containers with PowerShell](manage-containers-powershell.md) +- [Monitor usage, billing, and cost](monitor-usage-billing-cost.md) +- [Apply security and compliance controls](apply-security-compliance-controls.md) + +## Next steps + +Automate container management in [Manage containers with PowerShell](manage-containers-powershell.md). diff --git a/docs/embedded/admin/monitor-usage-billing-cost.md b/docs/embedded/admin/monitor-usage-billing-cost.md new file mode 100644 index 0000000000..5ef412ba43 --- /dev/null +++ b/docs/embedded/admin/monitor-usage-billing-cost.md @@ -0,0 +1,200 @@ +--- +title: Monitor Usage, Billing, and Cost +description: Monitor SharePoint Embedded usage and pay-as-you-go costs with billing meters and Azure Cost Management. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Monitor usage, billing, and cost + +**Applies to:** Billing administrator + + + +Monitor SharePoint Embedded usage and cost after billing is configured. + +SharePoint Embedded uses pay-as-you-go billing through an Azure subscription. + +Cost is based on usage meters, so administrators should review storage, archived storage, API transactions, and egress regularly. + +Use this article to understand cost drivers, review billing in Azure Cost Management, and establish operational controls. + +> [!IMPORTANT] +> Admin actions taken through the SharePoint admin center or SharePoint PowerShell aren't charged as SharePoint Embedded API transactions according to the SharePoint Embedded billing meters. + +## Before you begin + +Confirm these prerequisites. + +- SharePoint Embedded billing is configured for the app or tenant. +- You can access the Azure subscription linked to SharePoint Embedded billing. +- You can open [Azure Cost Management](https://portal.azure.com/#view/Microsoft_Azure_CostManagement/Menu/~/overview/openedBy/AzurePortal). +- You know the app IDs, tenant IDs, or container type IDs used for filtering when available. +- You can review container inventory in the SharePoint admin center or PowerShell. + +For billing setup, see [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md). + +## Understand SharePoint Embedded meters + +SharePoint Embedded uses these billing meters. + +Both standard billing and pass-through billing container types use the same meters. + +| Meter | Unit concept | Cost driver | +| --- | --- | --- | +| Storage | GB | Files, documents, metadata, versions, recycle bin content, and deleted container collection content. | +| Archived Storage | GB | Data in archived containers, held in a lower-cost cold storage tier. | +| API transactions | Transactions | Microsoft Graph calls made explicitly by the SharePoint Embedded application. | +| Egress | GB | Data downloaded from SharePoint Embedded to a customer's client device, subject to exemptions. | + +For related details, see [SharePoint Embedded Billing Meters](../reference/billing-meters.md). + +## Monitor storage + +Storage consumption includes more than current visible files. + +Storage includes files, documents, metadata, versions, recycle bin content, and deleted container collection content. + +Use these actions to manage storage. + +1. Review large containers in the SharePoint admin center. +1. Use PowerShell sorting to find containers by storage. +1. Review deleted containers that still contribute to storage. +1. Confirm whether retention policies require deleted content to remain. +1. Ask app owners to reduce unnecessary versions or obsolete content when appropriate. +1. Monitor storage growth after app releases or migrations. + +To sort containers by storage with PowerShell, see [Manage containers with PowerShell](manage-containers-powershell.md). + +## Monitor API transactions + +Each Microsoft Graph call made explicitly by the SharePoint Embedded application counts as one transaction. + +Calls made by internal services to containers aren't charged when the application has no control over those calls. + +Nonchargeable transactions include: + +- eDiscovery service queries that search container content for compliance or legal purposes. +- Admin actions taken by SharePoint Embedded Admins or Global Admins through SharePoint admin center or SharePoint PowerShell. + +Use app telemetry from the owning application to correlate app releases, user activity, and transaction growth. + +Work with app owners when transaction growth is unexpected. + +## Monitor egress + +Egress refers to data downloaded from SharePoint Embedded to a customer's client device. Some Microsoft service transfers are exempt. + +Exempt transfers include: + +- File downloads from the SharePoint Embedded application server to the customer's Office Desktop client. +- File downloads from the SharePoint Embedded application server to the Web Application Companion (WAC). + +Review app download behavior when egress grows. + +Large exports, sync-like patterns, or repeated downloads can increase egress. + +## Open Azure Cost Management + +1. Open the [Azure portal](https://portal.azure.com/). +1. Select **Cost Management + Billing**. +1. If you don't see it, search for **Cost Management + Billing**. +1. Select the subscription linked to SharePoint Embedded billing. +1. Open the subscription overview to review current spending, forecasted costs, and anomalies. + +![Azure portal with Cost Management + Billing selected in the left navigation.](../images/billmanag1.png) + +## Use Cost analysis + +1. In **Cost Management + Billing**, open **Cost analysis**. +1. Select the date range to review. +1. Group or filter by meter when available. +1. Use filters such as app ID, tenant ID, or container type ID when available. +1. Save views that your operations team uses repeatedly. +1. Export data if your organization uses a separate reporting process. + +![Azure Cost analysis view with filters to break down cost by meter, app ID, tenant ID, or container type ID.](../images/billmanag2.png) + +Compare cost trends to app deployment dates and usage campaigns. + +If cost increases suddenly, review storage, transaction volume, and egress separately. + +## Download invoices + +Use the **Invoices** area under Billing to view and download billing invoices for the billing period. + +Store invoices according to your organization's finance and procurement processes. + +If invoice values don't match expected usage, compare invoice periods with Cost analysis date ranges. + +## Configure budgets and alerts + +Use Azure Cost Management budgets to notify administrators before spend exceeds expected levels. + +1. In **Cost Management**, select **Budgets**. +1. Create a budget for the linked subscription or billing scope. +1. Set the amount and time period. +1. Configure alerts for warning and critical thresholds. +1. Include app owners and billing owners in notifications. + +![Azure Cost Management Budgets page for creating a budget and alerts on the linked subscription.](../images/billmanag3.png) + +> [!TIP] +> Create separate review views for storage-heavy apps and transaction-heavy apps. +> Different owners may need to respond to different cost drivers. + +## Review app and container inventory + +Billing review should include operational inventory. + +1. In the SharePoint admin center, review **SharePoint Embedded** > **Apps**. +1. Confirm billing status for installed apps. +1. Review **Active containers** for high-storage containers. +1. Review **Deleted containers** for deleted content that may still contribute to storage. +1. Use PowerShell for repeatable exports. + +For container management, see [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md). + +## Common cost questions + +Use these checks during cost review. + +- Which app generated the most consumption? +- Which meter increased since the last review? +- Did storage grow because of active content, versions, recycle bin content, or deleted containers? +- Did transaction volume increase after a feature release? +- Did egress increase after a new download workflow? +- Are budgets and alerts configured for the billing subscription? +- Are app owners aware of their cost drivers? + +## Operational guidance + +Establish a recurring review process. + +- Review cost weekly during pilot or migration. +- Review cost monthly after steady state. +- Track app IDs and container type IDs in an admin inventory. +- Notify app owners before large lifecycle cleanup. +- Coordinate deleted container cleanup with retention and legal requirements. +- Include SharePoint Embedded in Azure subscription budget reviews. +- Validate billing status after subscription or resource group changes. + +## Related content + +- [Set up billing in Microsoft 365 admin center](setup-billing-microsoft-365-admin-center.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) +- [Manage containers with PowerShell](manage-containers-powershell.md) +- [Review audit events](review-audit-events.md) +- [SharePoint Embedded Billing Meters](../reference/billing-meters.md) + +## Next steps + +Review compliance activity in [Review audit events](review-audit-events.md). diff --git a/docs/embedded/admin/review-audit-events.md b/docs/embedded/admin/review-audit-events.md new file mode 100644 index 0000000000..a6cfaa9062 --- /dev/null +++ b/docs/embedded/admin/review-audit-events.md @@ -0,0 +1,233 @@ +--- +title: Review Audit Events +description: Find and interpret SharePoint Embedded audit activity in Microsoft Purview audit. +ms.date: 07/13/2026 +ms.reviewer: dilucesr +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Review audit events + +**Applies to:** Consuming tenant admin — Compliance admin / Security admin / Audit reader + + + +Review SharePoint Embedded audit activity in Microsoft Purview audit when investigating user, admin, file, or container activity. + +SharePoint Embedded audit capabilities mirror existing SharePoint audit capabilities, and user and admin operations performed in SharePoint Embedded applications are captured in the organization's unified audit log. + +> [!IMPORTANT] +> Use Microsoft Purview audit as the authoritative investigation surface for audit records. +> Use SharePoint Embedded app and container identifiers to narrow results to embedded content. + +## Before you begin + +Confirm these prerequisites. + +- Audit is available for your Microsoft 365 organization. +- You can access Microsoft Purview audit with the required compliance permissions. +- You know the date range for the investigation. +- You know the SharePoint Embedded application, container, user, or file involved. +- You can obtain container details from the SharePoint admin center or PowerShell when needed. + +For supported SharePoint Embedded compliance capabilities, see [Security and Compliance](apply-security-compliance-controls.md). + +## Understand SharePoint Embedded audit coverage + +Audit capabilities in SharePoint Embedded mirror existing SharePoint audit capabilities. + +User and admin operations performed in applications hosted in SharePoint Embedded are captured, recorded, and retained in the unified audit log. + +Audit can help answer questions such as: + +- Who accessed a file? +- Who modified content? +- Who deleted or restored content? +- Which admin changed container settings? +- Which container was involved in an event? +- Which container type was involved in an event? + +Retention and availability depend on your Microsoft Purview audit licensing and configuration. + +For audit platform details, see [Auditing solutions in Microsoft Purview](/purview/audit-solutions-overview). + +## Identify SharePoint Embedded fields + +In addition to existing SharePoint file properties, SharePoint Embedded audit events include extra data that helps isolate SharePoint Embedded content. + +SharePoint Embedded audit events include these fields: + +| Field | Use it for | +| --- | --- | +| `ContainerInstanceId` | Identify the specific SharePoint Embedded container instance involved in the event. | +| `ContainerTypeId` | Identify the SharePoint Embedded container type involved in the event. | + +Use these fields with app and user context to scope an investigation. + +If a result set includes regular SharePoint and SharePoint Embedded activity, filter or inspect these fields to isolate embedded content. + +## SharePoint Embedded audit activities + +To view all SharePoint Embedded audit log activities, see [Audit events](../reference/audit-events.md). + +Container type events include the `ContainerTypeId` property. Unlike container-level file events, they don't include `ContainerInstanceId` because they apply at the type level, not to an individual container instance. + +You can search these events with the [`Search-UnifiedAuditLog`](/powershell/module/exchangepowershell/search-unifiedauditlog) cmdlet. For example: + +```powershell +Search-UnifiedAuditLog -Operations ContainerTypeCreated,ContainerTypeDeleted,ContainerTypeUpdated,ContainerTypeOwnersUpdated -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) +``` + +## Get container context + +Before searching audit, collect the context you have. + +1. Identify the SharePoint Embedded application name. +1. Identify the owning application ID when available. +1. Identify the container name or container ID. +1. Identify the container site URL when available. +1. Identify the users, groups, or app identities involved. +1. Identify the time period. +1. Identify the suspected operation, such as read, update, delete, restore, sharing, or label change. + +Use [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) to inspect container details. + +Use [Manage containers with PowerShell](manage-containers-powershell.md) to retrieve container IDs and URLs for repeatable investigations. + +## Search in Microsoft Purview audit + +Use Microsoft Purview audit to search activity. + +1. Open the Microsoft Purview portal. +1. Go to the audit solution. +1. Choose the date and time range. +1. Add users or app identities when known. +1. Add activities that match the investigation. +1. Search SharePoint-related activities when investigating file and container content. +1. Use **SharePoint Embedded Container Type activities** or **SharePoint Embedded Container Type Registration activities** when you know the investigation is about app setup or container type administration. +1. Run the search. +1. Open relevant results. +1. Inspect event details for SharePoint Embedded fields such as `ContainerInstanceId` and `ContainerTypeId`. + +Use the most restrictive filters that still capture the incident. + +Then widen the search if results are incomplete. + +> [!TIP] +> Start with a narrow time range and known users. +> Expand to container identifiers or broader SharePoint activity if the first search doesn't return enough context. + +## Interpret event details + +When reviewing an event, capture the fields needed for the investigation record. + +| Event detail | Why it matters | +| --- | --- | +| Operation or activity | Describes what happened. | +| User or actor | Identifies who performed the action. | +| Timestamp | Places the event on the investigation timeline. | +| Object or file path | Identifies the affected item. | +| Site or container URL | Helps map the item to a container. | +| `ContainerInstanceId` | Links the event to a specific SharePoint Embedded container. | +| `ContainerTypeId` | Links the event to a SharePoint Embedded container type. | +| Client or app context | Helps distinguish user action from app action when available. | + +Export or preserve results according to your compliance investigation process. + +## Common audit scenarios + +Use audit records for common SharePoint Embedded investigations. + +### Content access review + +Search for file access or read activity by user, date range, and container context. + +Use `ContainerInstanceId` to confirm the activity occurred in the expected SharePoint Embedded container. + +### Content change review + +Search for create, modify, rename, move, or delete activity. + +Review the sequence of operations to identify whether content was changed by a user, app, or admin process. + +### Container lifecycle review + +Search for admin operations related to deletion, restore, or permanent deletion. + +Correlate audit records with SharePoint admin center or PowerShell change records. + +### Sensitivity label review + +Search for label-related activity when investigating data classification changes. + +Correlate audit records with the container's current sensitivity label and any policy changes in Microsoft Purview. + +### External sharing review + +Search for sharing-related SharePoint activities when investigating access outside the organization. + +Also review application-level sharing settings when the app supports external sharing. + +## Correlate with eDiscovery and DLP + +Audit shows activity. + +Other Microsoft Purview tools help with content investigation and policy enforcement. + +- Use eDiscovery to search, hold, and export content in SharePoint Embedded containers. +- Use DLP to identify and protect sensitive information. +- Use retention policies to preserve or delete content according to policy. +- Use sensitivity labels to classify and protect containers. + +For broader controls, see [Apply security and compliance controls](apply-security-compliance-controls.md). + +## Troubleshoot missing audit results + +Use these checks when expected results are missing. + +- Confirm the date range includes the activity time. +- Confirm the correct user or app identity was searched. +- Confirm audit is available for the tenant and workload. +- Confirm the operation maps to SharePoint or file activity in Purview audit. +- Confirm the content is in a SharePoint Embedded container and not another storage location. +- Search with fewer filters, then inspect `ContainerInstanceId` and `ContainerTypeId`. +- Confirm your account has permissions to search audit records. +- Review Purview audit documentation for retention and search latency. + +> [!NOTE] +> Audit records can take time to appear. +> +> If an event is recent, retry after the normal audit ingestion delay for your environment. + +## Preserve investigation context + +For each investigation, record: + +1. Search date. +1. Search filters. +1. Exported result location. +1. Container identifiers. +1. App identifiers. +1. Users or app identities reviewed. +1. Actions taken after review. + +Keep records according to your compliance and legal process. + +## Related content + +- [Apply security and compliance controls](apply-security-compliance-controls.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) +- [Manage containers with PowerShell](manage-containers-powershell.md) +- [Security and Compliance](apply-security-compliance-controls.md) +- [Auditing solutions in Microsoft Purview](/purview/audit-solutions-overview) + +## Next steps + +Apply broader controls in [Apply security and compliance controls](apply-security-compliance-controls.md). diff --git a/docs/embedded/admin/setup-billing-microsoft-365-admin-center.md b/docs/embedded/admin/setup-billing-microsoft-365-admin-center.md new file mode 100644 index 0000000000..c135fcf7e7 --- /dev/null +++ b/docs/embedded/admin/setup-billing-microsoft-365-admin-center.md @@ -0,0 +1,207 @@ +--- +title: Set Up Billing in Microsoft 365 Admin Center +description: Configure SharePoint Embedded pass-through billing in the Microsoft 365 admin center for a consuming tenant. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Set up billing in Microsoft 365 admin center + +**Applies to:** Consuming tenant admin — Billing admin / Global admin + + + +Set up SharePoint Embedded billing in the Microsoft 365 admin center when your tenant uses an app with pass-through or user organization billing. + +No user can access a pass-through SharePoint Embedded app before valid billing is configured for the SharePoint Embedded platform in the consuming tenant. + +> [!IMPORTANT] +> Only a Global Administrator can set up SharePoint Embedded billing in the Microsoft 365 admin center. The SharePoint Embedded Administrator role can't configure billing. + +SharePoint Embedded billing is pay-as-you-go through Azure. + +Charges are based on supported meters such as storage, archived storage, API transactions, and egress. + +> [!IMPORTANT] +> If SharePoint Embedded is turned off or the linked Azure subscription is disconnected, users can no longer create new containers. Existing containers and their content remain accessible. + +## Before you begin + +Confirm these prerequisites. + +- You can sign in to the [Microsoft 365 admin center](https://admin.microsoft.com/). +- You have the Global Administrator role. Only a Global Administrator can set up billing in the Microsoft 365 admin center. +- You have owner or contributor permissions on the Azure subscription used for billing. +- You have an Azure subscription in the tenant. +- You have a resource group attached to the subscription. +- The SharePoint Embedded app is installed or ready to use in the consuming tenant. +- You understand whether the app uses pass-through billing. + +For tenant role context, see [Admin overview](admin-overview.md). + +For billing models, see [Choose a Billing Model](../plan/choose-billing-model.md). + +## Understand billing models + +SharePoint Embedded supports two billing models. + +| Billing model | Who pays | +| --- | --- | +| Standard | The tenant that owns or develops the app is billed for consumption. | +| Pass-through | The tenant registered to use the app is billed for consumption. | + +> [!NOTE] +> A container type's billing model is set when the container type is created and can't be changed later. To switch billing models, the developer creates a new container type with the wanted model. + +The following diagram shows standard billing, where consumption charges are billed to the tenant that owns or develops the app. + +![Standard billing model, where the developer or owning tenant is billed for all consumption.](../images/1bill521.png) + +The following diagram shows pass-through billing, where consumption charges are billed to the consuming tenant that's registered to use the app. + +![Pass-through billing model, where the consuming tenant is billed for all consumption.](../images/2bill521.png) + +For standard billing, a Global Administrator in the developer tenant sets up billing for the container type. + +For pass-through billing, a Global Administrator in the consuming tenant sets up billing in the Microsoft 365 admin center. + +This article focuses on the consuming tenant pass-through path. + +## Understand cost meters + +SharePoint Embedded uses a consumption-based model. + +SharePoint Embedded uses four primary meters. + +| Meter | What it measures | +| --- | --- | +| Storage | Data stored in files, documents, metadata, versions, recycle bin, and deleted container collection, in active and archived states. | +| Archived Storage | Storage consumed by archived containers. Archiving moves data to the cold storage tier, which costs less than active storage. | +| API transactions | Microsoft Graph calls made explicitly by the SharePoint Embedded application. | +| Egress | Data that exits SharePoint Embedded, such as documents downloaded to customer client devices or data transferred to customer-operated servers, subject to documented exemptions. | + +For cost monitoring, see [Monitor usage, billing, and cost](monitor-usage-billing-cost.md). + +## Open the billing setup experience + +1. Sign in to the [Microsoft 365 admin center](https://admin.microsoft.com/). +1. Select **Setup**. +1. In **Files and Content**, select **Automate Content with Microsoft Syntex**. +1. Select **Go to Syntex settings**. +1. Under **Syntex services for**, select **Apps**. +1. Select **SharePoint Embedded**. +1. Follow the instructions on the **SharePoint Embedded** panel to turn on SharePoint Embedded apps. + +The Microsoft 365 admin center **Files and Content** section provides the entry point. Select **Automate Content with Microsoft Syntex** to open Syntex settings. + +![Microsoft 365 admin center Files and Content section with the Automate Content with Microsoft Syntex option.](../images/DTCBilling1.png) + +In Syntex settings, under **Apps**, select **SharePoint Embedded** to open the panel that turns on SharePoint Embedded apps for the tenant. + +![Syntex settings Apps view with SharePoint Embedded selected to configure billing.](../images/DTCBilling2.png) + +Use this Microsoft 365 admin center path for consuming tenant billing setup. + +> [!NOTE] +> The admin center user interface can change. +> If labels differ, search the Microsoft 365 admin center for Syntex or SharePoint Embedded billing settings. + +## Select the billing profile + +During setup, connect SharePoint Embedded billing to the appropriate Azure billing resources. + +1. Select the Azure subscription approved for SharePoint Embedded usage. +1. Select or confirm the resource group. +1. Review the billing scope. +1. Confirm that the subscription is active. +1. Confirm that you have the required permissions. +1. Save the configuration. + +Use the same internal controls you use for other pay-as-you-go Microsoft 365 connected services. + +## Validate billing setup + +After setup, validate that billing is active. + +1. Return to the Microsoft 365 admin center SharePoint Embedded settings. +1. Confirm that SharePoint Embedded apps are turned on. +1. Confirm that the billing subscription remains connected. +1. Open the SharePoint admin center. +1. Go to **SharePoint Embedded** > **Apps**. +1. Confirm that the installed app doesn't show a billing issue. +1. Ask the app owner or a pilot user to validate app access. + +If the app remains inactive, review the app billing model and the selected billing resources. + +## Validate in Azure Cost Management + +Use Azure Cost Management to confirm usage and prepare monitoring. + +1. Open the [Azure portal](https://portal.azure.com/). +1. Go to **Cost Management + Billing**. +1. Select the subscription linked to SharePoint Embedded billing. +1. Open **Cost analysis**. +1. Filter or group costs using available dimensions such as meter, resource, app ID, tenant ID, or container type ID when available. +1. Save views or exports according to your operations process. + +For detailed monitoring steps, see [Monitor usage, billing, and cost](monitor-usage-billing-cost.md). + +## Common issues + +Use these checks when setup fails. + +- The admin doesn't have the Global Administrator role required to set up billing. +- The admin lacks owner or contributor permissions on the Azure subscription. +- The subscription is disabled or unavailable. +- No resource group is available for billing setup. +- The app uses pass-through billing but the consuming tenant hasn't turned on SharePoint Embedded apps. +- The app uses owner organization billing, so the app owner must resolve billing instead. +- Tenant policies restrict access to the Microsoft 365 admin center billing experience. + +## Common access symptoms + +Users may report access failures when billing isn't valid. + +Look for these symptoms. + +- The SharePoint Embedded app is installed but inactive. +- Users can't create new containers or store new content. +- The SharePoint admin center shows billing warnings for the app. +- Azure Cost Management shows no linked usage because setup hasn't completed. +- New container creation stops immediately after SharePoint Embedded is turned off or the subscription is disconnected, although existing containers remain accessible. + +> [!WARNING] +> Don't disconnect the linked Azure subscription during business hours unless you intend to block new container creation for SharePoint Embedded apps. Existing containers stay accessible, but users can't create new containers until billing is valid again. + +## Operational guidance + +After setup, establish a billing operations process. + +- Assign subscription owners who understand SharePoint Embedded usage. +- Create budgets and alerts in Azure Cost Management. +- Review storage growth for large containers. +- Review API transaction patterns after app releases. +- Review egress for download-heavy scenarios. +- Keep app owners informed when billing anomalies appear. +- Include SharePoint Embedded in tenant cost reviews. + +## Related content + +- [Grant admin consent and permissions](grant-admin-consent-permissions.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) +- [Monitor usage, billing, and cost](monitor-usage-billing-cost.md) +- [Choose a Billing Model](../plan/choose-billing-model.md) +- [SharePoint Embedded Billing Meters](../reference/billing-meters.md) +- [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md) + +## Next steps + +Manage containers in [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md). diff --git a/docs/embedded/administration/adminrole.md b/docs/embedded/administration/adminrole.md deleted file mode 100644 index 39ec3fc773..0000000000 --- a/docs/embedded/administration/adminrole.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: SharePoint Embedded administrator -description: This article explains the new admin role for SharePoint Embedded. -ms.date: 05/21/2024 -ms.localizationpriority: high ---- - -# The SharePoint Embedded administrator - -The SharePoint Embedded administrator is a dedicated role to manage SharePoint Embedded containers through [SharePoint PowerShell](/powershell/module/sharepoint-online/connect-sposervice) and SharePoint admin center. This role is required for [developer admins](./developer-admin/dev-admin.md) to create new container types through PowerShell cmdlets and also for consuming tenant admins to manage containers created in their tenants. - -The global administrator role already has all the permissions of the SharePoint Embedded administrator role. A global administrator can assign a user the SharePoint Embedded administrator role to act as a consuming tenant admin or a developer administrator for SharePoint Embedded. - -The SharePoint Embedded administrator role is available in Microsoft Entra and Microsoft 365 Admin Center. This role doesn't have access to site management. This means that a SharePoint Embedded administrator can't see 'Active sites' and 'Deleted sites' pages on the SharePoint Admin Center and also can't run site specific PowerShell cmdlets. - -## SharePoint Embedded administrator tasks in the developer tenant - -The following are some of the container-specific commands actions currently supported on PowerShell: - -- Creation of container types - - Creation of a Standard container type with standard billing - - Creation of a Standard container type with direct to customer billing - - Creation of a Trial container type - -- Container type management - - Viewing of container types in the developer tenant - - Editing properties of a container type in the developer tenant - - Configuration properties of a container type in the developer tenant - - Manage billing of applications/ container types for standard billing - -## SharePoint Embedded administrator tasks in consuming tenant - -The following are some of the container-specific commands actions currently supported on PowerShell: - -- Application administration - - Get details of all SharePoint Embedded applications in the tenant - - Get detail of a specific application in the tenant - - Get the permissions of owning applications in the tenant - - Configure External sharing setting of a container of an application in tenant - -- Container administration - - Get details of all containers of an application in the tenant - - Get details of all containers of an application in the tenant sorted by storage - - Get details of all archived containers of an application in the tenant - - Get details of a specific container of an application in the tenant - - Set Sensitivity label of a specific container of an application in the tenant - - Soft delete a container of an application in the tenant - - Get details of all soft deleted containers in the tenant - - Restore a soft deleted container of an application in the tenant - - Permanently delete a soft deleted container of an application in the tenant - -The following are some of the actions currently supported on SharePoint Admin Center: - -- View Active container page -- View Archived container page -- View Deleted container page -- View the detailed information of a container -- Archive an active container -- Reactivate an archived container -- Soft delete a container -- Restore a deleted container -- Purge a deleted container - -## Assigning the SharePoint Embedded administrator Role - -The Global admin can assign the SharePoint Embedded Admin role to users through both Entra and Microsoft admin center. - -### Through Entra - -Follow the following steps to assign the role of SharePoint Embedded administrator on Entra: - -1. Sign into Entra as a Global admin -1. Select the **“Users”** tab on the left-hand panel and select **“All users”** -1. Select the user to assign the role of SharePoint Embedded administrator under **“All users”** -1. Select the **“Assigned role”** tab on the left panel -1. Select on **“Add assignments”** button and search for **“SharePoint Embedded”** in the panel that opens -1. Select the 'SharePoint Embedded administrator' option and select on **“Add”** -1. The selected user is assigned the role of SharePoint Embedded administrator - -### Through Microsoft 365 Admin Center - -1. Sign into Microsoft 365 Admin Center as a Global admin -1. Select **“Users”** and select **“Active users”** under it -1. Select the user to assign the role of SharePoint Embedded administrator -1. Select on **“Manage roles”** option under Roles -1. Select **“Admin center access”** and under **“Collaboration”**, select **“SharePoint Embedded administrator”** -1. Select **"Save changes"**. Now the selected user is assigned the role of SharePoint Embedded administrator diff --git a/docs/embedded/administration/billing/billing.md b/docs/embedded/administration/billing/billing.md deleted file mode 100644 index bed44b63f0..0000000000 --- a/docs/embedded/administration/billing/billing.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Pay-as-you-go billing for SharePoint Embedded -description: This article explains the billing models and how to set up pay-as-you-go billing. -ms.date: 08/13/2025 -ms.localizationpriority: high ---- - -# SharePoint Embedded billing models - -SharePoint Embedded is a consumption-based, pay-as-you-go (PAYG) offering, meaning you pay only for what you use. SharePoint Embedded provides two billing models that the tenant developing the SharePoint Embedded application can select when creating their container type, tailoring it to their unique business requirements. The two billing models are Standard and Passthrough billing. - -> [!NOTE] -> Once a container type is created, its billing model can't be changed. To change the billing model, a new container type must be created with the desired billing model. - -## Standard billing - -With the standard billing model, all consumption-based charges are directly billed to the tenant who owns or develops the application. After creating the container type, the admin in the developer tenant must establish a valid billing profile before the container type can be used. This billing profile will be used to charge for all consumption incurred by any consuming tenant that uses the SharePoint Embedded application associated with this container type. To set up the billing profile for a standard container type, see [set the billing profile](../../getting-started/containertypes.md#set-the-billing-profile). - -![Standard billing](../../images/1bill521.png) - -## Passthrough billing - -With passthrough billing, consumption-based charges are billed directly to the consuming tenant registered to use the SharePoint Embedded application. Admins in the developer tenant don't need to set up a billing profile for a passthrough SharePoint Embedded container type. Once the container type is registered in the consuming tenant, the consuming tenant admin (SharePoint Admin or Global Admin) needs to set up the billing profile in the consuming tenant to use the SharePoint Embedded application. - -![PassThrough billing](../../images/2bill521.png) - -## Create a SharePoint Embedded container type - -For information on how to create a container type with billing enabled, see [creating a container type](../../getting-started/containertypes.md#creating-container-types). - -## View & edit billing properties of standard container type - -You can view the properties of a container type using the **fileStorageContainerType** APIs: - -- [List container types](/graph/api/filestorage-list-containertypes) -- [Get container type](/graph/api/filestoragecontainertype-get) - -To update the billing properties on a container type with standard billing, see [set the billing profile](../../getting-started/containertypes.md#set-the-billing-profile). - -## Set up billing for passthrough container types in consuming tenant - -To set up billing for a passthrough container type in the consuming tenant, see the [setup guide in the consuming tenant Admin Center](../consuming-tenant-admin/cta.md#set-up-billing-for-passthrough-container-type). - -## SharePoint Embedded meters - -To learn more about the supported pay-as-you-go meters, refer to the [SharePoint Embedded meters](meters.md) article. diff --git a/docs/embedded/administration/billing/billingmanagement.md b/docs/embedded/administration/billing/billingmanagement.md deleted file mode 100644 index b2e03cac54..0000000000 --- a/docs/embedded/administration/billing/billingmanagement.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: SharePoint Embedded Billing Management -description: This article describes how to view SharePoint Embedded application consumption in Azure portal. -ms.date: 05/21/2024 -ms.localizationpriority: high ---- - -# SharePoint Embedded Billing Management - -The Microsoft Cost Management portal provides a comprehensive overview of your costs, allowing you to track and analyze your spending for SharePoint Embedded application. This guide walks you through the steps to view your billing details and SharePoint Embedded consumption in the Microsoft Cost Management portal. - -## Step-by-Step Guide - -### Sign in to Azure portal - -1. Open your web browser and navigate to the [Azure portal](https://portal.azure.com/). -1. Sign in using your Azure account credentials. - -### Navigate to Cost Management + Billing - -1. Once signed in, locate the left-hand navigation menu. -1. Select on "Cost Management + Billing". If it's not visible, you can search for it using the search bar at the top of the portal. - - ![Cost Management](../../images/billmanag1.png) - -### Select Your Subscription - -1. In the Cost Management + Billing section, you see a list of your subscriptions. -1. Select the subscription for which you want to view the billing details. - -### View Billing Overview - -1. After selecting your subscription, you'll be taken to the Overview page. -1. Here, you can see a summary of your costs, including current spending, forecasted costs, and any spending anomalies. - -### Access Cost Analysis - -1. For a more detailed view, select "Cost analysis" under the Cost Management section. -1. In the Cost Analysis page, you can customize the date range to view costs for specific periods. -1. Use the filters to break down costs by tags - app ID, tenant ID or container type ID. Filters can also set by Meters, Resources etc. Refer to the [SharePoint Embedded meters](meters.md) article to learn more about the pay-as-you-go meters supported. - -![Meters](../../images/billmanag2.png) - -### Download Invoices - -1. To download invoices, go to the "Invoices" section under Billing. -1. Here, you can view and download your billing invoices for any billing period. - -### Set Up Budgets and Alerts - -1. To better manage your spending, you can set up budgets and alerts. -1. Select "Budgets" under the Cost Management section. - - ![Budgets](../../images/billmanag3.png) - -1. Create a new budget by specifying the amount and the time period. -1. Set up alerts to notify you when spending approaches or exceeds your budget. diff --git a/docs/embedded/administration/billing/meters.md b/docs/embedded/administration/billing/meters.md deleted file mode 100644 index 703f510fe6..0000000000 --- a/docs/embedded/administration/billing/meters.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: SharePoint Embedded Billing Meters -description: This article describes the meters in SharePoint Embedded. -ms.date: 01/20/2026 -ms.localizationpriority: high ---- - -# SharePoint Embedded billing meters - -SharePoint Embedded employs a pay-as-you-go (PAYG) billing model through an Azure subscription. Billing is determined by how much data in GB you store in SharePoint Embedded in active and archived states, transactions used to access and modify the container and container contents, and data that is egressed from the SharePoint Embedded platform. Each of these factors contributes to the overall cost, ensuring that you only pay for the resources and services you use. You can view this usage and billing details in the [Azure Cost Management](https://ms.portal.azure.com/). Both Standard Billing container type and Pass-through Billing container type will use the same meters. - -SharePoint Embedded has four billing meters as shown. Refer to the [product page](https://adoption.microsoft.com/en-us/sharepoint/embedded/) for pricing details. - -## Storage - -Storage consumption meters in SharePoint Embedded apply to the storage used by files and documents along with their metadata and versions. Storage consumption also includes all content in the recycle bin and deleted container collection within SharePoint Embedded. - -## Archived Storage - -Archived Storage meters in SharePoint Embedded measure the storage consumed by archived containers within a tenant. By archiving containers, data is moved to the cold storage tier, which offers lower storage costs compared to active storage. - -## API Transactions - -Each Microsoft Graph call made explicitly by the SharePoint Embedded application is counted as one transaction, and customers are billed based on the transaction count. See the [examples](/graph/api/resources/filestoragecontainer) of Microsoft Graph calls that can be made by a SharePoint Embedded application. - -However, calls made by internal services to the containers, which the application has no control over, are **not** charged. Some examples of such nonchargeable transactions include: - -1. Queries performed by the eDiscovery service to search through container content for compliance or legal purposes. -1. Admin actions taken by the SharePoint Embedded Admin or Global Admin on containers through SharePoint Admin Center or SPO PowerShell. - -## Egress - -Egress refers to the data that exits the SharePoint Embedded platform. For example, this can refer to a document downloaded into the customer's client device, such as a desktop or mobile device, or data transferred to a server operated by the customer. Egress charges are based on the total volume of data transferred out of SharePoint Embedded, measured in gigabytes (GB). - -However, certain types of data transfers are exempt from egress charges. These exemptions ensure that customers aren't billed for data transfers occurring within integrated Microsoft services, promoting seamless usage without extra costs for these specific internal operations. Some examples of these exemptions include: - -1. File downloads from the SharePoint Embedded application server to the customer's Office Desktop client aren't charged. -1. File downloads from the SharePoint Embedded application server to the Web Application Companion (WAC) aren't charged. - -## Pay-as-you-go message (private preview) - -SharePoint Embedded agents use the Copilot Studio meter for $0.01/message (messages are the unit that measures agent usage). Each interaction with the SharePoint Embedded agent will use twelve (12) messages (2 messages for the generative answer feature and 10 messages for the tenant graph grounding feature), so customers are billed at $0.12 per interaction with SharePoint Embedded agents. diff --git a/docs/embedded/administration/consuming-tenant-admin/ctaUX.md b/docs/embedded/administration/consuming-tenant-admin/ctaUX.md deleted file mode 100644 index 653a58708f..0000000000 --- a/docs/embedded/administration/consuming-tenant-admin/ctaUX.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -title: Manage containers in SharePoint Admin Center -description: This article describes how administrators can manage containers in the SharePoint Admin Center (SPAC). -ms.date: 07/09/2025 -ms.localizationpriority: high ---- -# Manage SharePoint Embedded containers in SharePoint Admin Center - -The organizations that use the SharePoint Embedded applications on their Microsoft 365 tenants are the consuming tenants and the persona that's responsible for managing these applications on their Microsoft 365 tenancy is the consuming tenant administrator (CTA). Consuming tenant administrators can manage containers through a graphical user interface (GUI) using the [SharePoint Administrator Center](https://go.microsoft.com/fwlink/?linkid=2185219). - -To manage SharePoint Embedded containers, the CTA needs to be assigned the SharePoint Embedded Administrator role. - -For information on the SharePoint Embedded Administrator role, see [SharePoint Embedded Admin](../adminrole.md). - -The following actions are supported in SharePoint Admin Center: - -1. View active containers in the tenant -2. View archived containers in the tenant -1. View deleted containers in the tenant -1. View detailed information about a container -1. Archive an active container -1. Reactivate an archived container -1. Delete an active or archived container -1. Restore a deleted container -1. Permanently deleted a container -1. Sort active containers in the tenant -1. Filter active containers in the tenant -1. Set sensitivity label on active containers -1. Add users to different roles on a container -1. Reassign users from existing roles on a container -1. Remove users from existing roles on a container - -![Active Containers global admin](../../images/ctaux1.png) - -**SharePoint Embedded Administrator** will only see the "Active containers" and "Deleted containers" page when they sign in to SharePoint Admin Center. - -![Active Containers SPE admin](../../images/ctaux2.png) - -## Active Containers - -The Active Containers page displays all the active containers within the tenant, providing a comprehensive overview and management capabilities. This page includes the following metadata for each container: - -1. **Container name:** Name of the container provided by the container owner. -1. **Application name:** Name of the SharePoint Embedded application the container belongs to. -1. **Publisher:** The name of the organization that owns the application. For all publishers other than Microsoft, the value is currently stored as "Other" -1. **Ownership type:** Mentions whether the container is tenant-owned, user-owned, or group-owned. -1. **Principal owner:** The user whose lifecycle impacts the lifecycle of the container. There's no principal owner for a tenant owned container, while it's a user for a user-owned container and a group for a group owned containers. -1. **Storage:** The total storage of the files stored in the containers. -1. **Owners:** Users assigned the owner role on the container. -1. **Owner count:** The count of number of owners of the container. -1. **Sensitivity label:** Name of the label assigned to the container. -1. **Created on:** Date and time when the container was created. - -![Active Container Properties](../../images/ctaux3.png) - -### View details of a container - -The detailed container view provides a deeper dive into container-specific metadata, organized under two tabs: - -1. **General:** This panel displays all the general metadata about a container, usage, and configuration settings. - - ![Container Details](../../images/ctaux4.png) - -1. **Membership:** This panel shows the user permissions for different users associated with the container. The admin can manage the membership on a container through this panel. - -> [!IMPORTANT] -> The SharePoint Embedded platform supports four distinct [roles](../../development/sharing-and-perm.md): Owner, Manager, Writer, and Reader. The SharePoint Embedded application on your tenant may not use all four roles and might refer to these roles using different names. - -![SharePoint Embedded Membership Roles](../../images/ctaux5.png) - -## Archived Containers - -The Archived containers page lists all containers in the tenant's archived container collection. It lists the following metadata: - -1. Container name -1. Application name -1. Publisher -1. Status -1. Time archived -1. Archived by -1. Storage (GB) -1. Ownership type -1. Principal owner - -![Archived Containers](../../images/archived-containers-page.png) - -## Archive a container - -A container can be archived when it’s no longer actively used but must be retained for legal, compliance, or business purposes. From the Active containers page, the CTA can select a container and choose Archive option to start the archival process. - -![Active Containers Archive action](../../images/active-containers-archive-action.png) - -This opens the side panel that educates admin about the implication of archival action and ways of getting back the archived content. The CTA can at this stage either cancel the panel and go back to the active containers page or proceed further with the archival by clicking on “Archive”. - -![Archive Containers Confirmation Panel](../../images/archive-container-confirmation-panel.png) - -The selected container is successfully archived and moved into the Archived containers page. - -![Container Archival confirmed](../../images/container-archived-confirmation.png) - -## Reactivate Archived Containers - -Archived containers aren’t accessible to users or applications until they’re reactivated. The time required to reactivate a container depends on how long it has been archived. Containers archived within the last seven days are in the Recently archived state. After this period, containers transition to the Fully archived state. - -### Reactivate Recently Archived Containers - -From the Archived containers page, the CTA can select a Recently archived container and choose Reactivate option to start the reactivation process. - -![Reactivate Recently Archived Container](../../images/reactivate-recently-archived-container.png) - -This opens a side panel that informs admin about the reactivation time. The CTA can at this stage either cancel the panel and go back to the Archived containers page or proceed further with the reactivation by clicking on “Reactivate”. - -![Reactivate Recently Archived Container Confirmation](../../images/reactivate-recently-archived-container-confirmation.png) - -The selected container is successfully reactivated and moved into the Active containers page. - -![Container Reactivated Confirmation](../../images/container-reactivated-confirmation.png) - -### Reactivate Fully Archived Containers - -From the Archived containers page, the CTA can select a Fully archived container and choose Reactivate option to start the reactivation process. - -![Reactivate Fully Archived Container](../../images/reactivate-fully-archived-container.png) - -This opens a side panel that informs admin about the reactivation time of __24 hours__. The CTA can at this stage either cancel the panel and go back to the Archived containers page or proceed further with the reactivation by clicking on “Reactivate”. - -![Reactivate Fully Archived Container Confirmation](../../images/reactivate-fully-archived-container-confirmation.png) - -Reactivation request gets submitted for the selected container and it's displayed on the Archived containers page in the "Reactivating" state. Once the reactivation completes after 24 hours, the container is moved to the Active containers page. - -![Reactivation Request Submission](../../images/reactivation-request-submission.png) - -## Deleted Containers - -The deleted containers page lists all containers in the tenant's deleted container collection. It lists the following metadata: - -1. Container name -1. Application name -1. Publisher -1. Ownership type -1. Principal owner -1. Storage -1. Owners -1. Sensitivity label -1. Created on -1. **Deleted on**: Date and time when the container was deleted. - -![Container Deletion](../../images/ctaux6.png) - -## Delete a container - -> [!WARNING] -> Deleting a container may cause unexpected issues for the SharePoint Embedded application it belongs to and may interrupt the application's usage. This action should only be performed by admins when necessary. - -Deleting a container can have implications on the functionality of a SharePoint Embedded app Here are some examples of the potential issues that an application can encounter when deleting a container. - -1. **Data Loss:** Deleting a container removes all its content. If the SharePoint Embedded application relies on the data stored within the deleted container, the app might no longer function as expected or might lose access to critical information. -1. **Broken Links:** If the SharePoint Embedded application contains links or references to the deleted container, those links become broken, leading to errors or malfunctioning features within the app. - -A container can be deleted from the Active containers page for any business reason by the CTA. By default, the delete button is deactivated. On selecting a container, the delete button is activated. The CTA can then select the delete button. - -![Container Deletion Process](../../images/ctaux7.png) - -This opens a side panel that warns the user about the effect on the associated SPE application due to the deletion of a container and informs the user about the restoration policy. The CTA can at this stage either cancel the panel and go back to the active containers page or proceed further with the deleting by clicking on “Delete container”. - -![Container deletion selection](../../images/ctaux8.png) - -The selected container is successfully deleted and moved into the deleted containers page. - -![Deleted SPE Container](../../images/ctaux9.png) - -**Deleted containers are permanently purged after 93 days unless there is a retention policy applied to the containers.** - -Archived containers page also provides the same delete experience for selecting archived containers and deleting. - -## Restore a container - -A container in the deleted container collection can be restored on the Deleted containers page by selecting the corresponding containers by selecting the "Restore" link - -![Restore Button SPE Container](../../images/ctaux10.png) - -Restoration of the container happens in the background and the status of the same is displayed on the top-right corner of the page. Upon successful restoration, the container will be available in the Active Containers page. If the container was in archived state at the time of deletion, then the container will be restored back to archived state. - -![Restored SPE Container](../../images/ctaux11.png) - -## Permanently delete a container - -> [!WARNING] -> Deleting a container may cause unexpected issues for the SharePoint Embedded application it belongs to and may interrupt the application's usage. This action should only be done by admins when necessary. - -The CTA can permanently delete a deleted container from the deleted container collection if they decide to. - -The CTA selects the container to be permanently deleted. The “Permanently delete” button is enabled. - -![Permanent SPE Container deletion](../../images/ctaux12.png) - -Upon selecting the button, a pop-up appears. warning the CTA on the action they're performing. If sure, the CTA can proceed and select “Delete”. Otherwise, the CTA can cancel the action. - -![Container Deletion warning](../../images/ctaux13.png) - -Upon selecting Delete, the container is permanently deleted, and the status of the same appears in the top-right corner of the page. Upon successful deletion, the container is permanently removed from the deleted container collection and can't be restored. - -![SPE Container Deleted](../../images/ctaux15-n.png) - -## Sorting on Active containers page - -The CTA can perform their compliance and storage management tasks better by using sorting capabilities on the Active containers page. Currently, sorting is supported on the following columns: - -1. Storage -1. Created on - -![ SPE Container Sorting](../../images/sorting.png) - -## Filtering on Active containers page - -The CTA can perform their compliance and storage management tasks better by using filtering capabilities on the Active containers page. Currently, filtering is supported on the following columns: - -1. Application name: The filter provides the list of all Microsoft SharePoint Embedded applications along with all SharePoint Embedded applications published by other publishers that is registered in the tenant. -1. Publisher: Describes whether the application is Microsoft-owned or published by an "Other" publisher. -1. Ownership type: The filter provides the options of Tenant, User, and Group, irrespective of the type of containers present in the tenant. -1. Principal owner: The filtering experience is a people picker experience. -1. Owner count: This filter provides a range of owner count for the administrator to choose from. -1. Created on: This filter provides a range of dates for the administrator to choose from. - -> [!IMPORTANT] -> The behavior of the filtering experience on the Active containers page differs from the experience on the Active sites page in SharePoint Admin Center. - -![ SPE Container Filtering](../../images/filter.png) - -## Searching on Active Containers Page - -The search bar on the Active Containers Page can be used to search containers in the active state by their "container name". -![SPE Container Search](../../images/search.png) - -## Editing the sensitivity label of a container on the Active containers page - -The sensitivity label of a container can be set on the Active container page, on the detailed panel of a container. Under the settings panel, the administrator can set the sensitivity label from a list of available sensitivity label. - -![SPE Container Sensitivity](../../images/sensitivity-label.png) - -## Managing user membership of a container - -The administrator can manage the membership of users of a container on the Active container page, on the detailed panel of a container. Under the membership panel, the administrator can view the four roles and the corresponding users in each role. The administrator can: - -**Add a user to a role:** The administrator can navigate to the desired role using the left panel and select on the Add option. This opens up a picker, using which the administrator can select a user from the tenant and assign the role. In case the selected user is already assigned to a different role, the role is displayed when the role is selected and the operation changes from Add to Reassign. - -![SPE Container owner-one](../../images/add-owners-one.png) - -![SPE Container owner-two](../../images/add-owners-two.png) - -**Reassign user to another role:** The administrator can navigate to the desired user under a role using the left panel. On selecting the user, the Reassign option appears. On selecting the option, a drop-down menu appears and the administrator can select the role to which the user needs to be reassigned to. - -![ SPE Container reassign](../../images/reassign-user.png) - -**Remove user from a role:** The administrator can navigate to the desired user under a role using the left panel. On selecting the user, the Remove option appears. On selecting the option, a pop-up screen appears, and the administrator can confirm the removal of the user from the role. - -![SPE Container remove](../../images/remove-user.png) - -## Sorting on the Deleted Containers Page - -Similar to the sorting experience on the Active containers page, the CTA can use sorting capabilities on the Deleted containers page. Currently, sorting is supported on the following columns: - -1. Storage -1. Created on -1. Deleted on - -![ SPE Container Sorting_on_Delete](../../images/sorting-on-deleted.png) - -## Filtering on the Deleted containers page - -The CTA can perform their compliance and storage management tasks better by using filtering capabilities on the Deleted containers page, on the following columns: - -1. **Application name**: The filter provides the list of all Microsoft SharePoint Embedded applications along with all SharePoint Embedded applications published by other publishers that is registered in the tenant. -1. **Publisher**: Describes whether the application is Microsoft-owned or published by an "Other" publisher. -1. **Ownership type**: The filter provides the options of Tenant, User, and Group, irrespective of the type of containers present in the tenant. -1. **Principal owner**: The filtering experience is a people picker experience. -1. **Owner count**: This filter provides a range of owner counts for the administrator to choose from. -1. **Created on**: This filter provides a range of dates for the administrator to choose from. -1. **Deleted on**: This filter provides a range of dates for the administrator to choose from. - -![ SPE Container Filter_on_Delete](../../images/filter-on-delete.png) - -## Upcoming features - -1. Search on the Deleted containers page -1. Sorting and filtering on the Sensitivity Label column diff --git a/docs/embedded/administration/consuming-tenant-admin/ctapowershell.md b/docs/embedded/administration/consuming-tenant-admin/ctapowershell.md deleted file mode 100644 index cb5c40f860..0000000000 --- a/docs/embedded/administration/consuming-tenant-admin/ctapowershell.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Consuming Tenant Admin PowerShell -description: This article describes how an admin can manage containers through SPO PowerShell. -ms.date: 03/03/2025 -ms.localizationpriority: high ---- - -# SharePoint Embedded container management in PowerShell - -The consuming tenant administrator can manage containers using PowerShell commands, designed for container management. To access these commands, they must be assigned the role of Microsoft 365 SharePoint Embedded Administrator. Global Administrators in Microsoft 365 can assign users the SharePoint Embedded Administrator role. The Global Administrator role inherently includes all permissions of the SharePoint Embedded Administrator role. The SharePoint Embedded Administrator role is available in both Microsoft Entra and the Microsoft 365 Admin Center. - -For more information on assigning the SharePoint Embedded admin role, see the [SharePoint Embedded Administrator](../adminrole.md). - -The following are some of the container-specific command actions currently supported on PowerShell: - -### Application administration - -- Get the details of all SharePoint Embedded applications registered in the tenant -- Get the details of all SharePoint Embedded applications in the tenant sorted by storage -- Get the details of a specific SharePoint Embedded application in the tenant -- Get details of all archived containers of a particular SharePoint Embedded application in the tenant -- Get the permissions of the owning applications in the tenant -- Configure the External sharing setting of a container of a SharePoint Embedded application in the tenant - -### Container administration - -- Get details of all containers of a particular SharePoint Embedded application in the tenant -- Get details of a specific container -- Set the Sensitivity label of a specific container -- Soft delete a container -- Get details of all soft deleted containers -- Restore a soft deleted container -- Permanently delete a soft deleted container - -## Administration through SharePoint PowerShell - -Consuming tenant admin can manage SharePoint Embedded applications with PowerShell commands using [SharePoint Online Management Shell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online). - -To get started using PowerShell to manage SharePoint Embedded, you have to install the [SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588) and [connect to SharePoint Online](/powershell/module/sharepoint-online/connect-sposervice). - -> [!IMPORTANT] -> You must use the latest version of SharePoint PowerShell to use container administration cmdlets. - - -## Application Administration - -With PowerShell cmdlets, tenant admin can get a list of SharePoint Embedded applications registered in their Microsoft 365 tenancy. They can also view all the applications that have "read" and/or "write" access and the level of access to these SharePoint Embedded applications. - -The following commands can be used to manage SharePoint Embedded applications registered on your Microsoft 365 tenants: - -```powershell -Get-SPOApplication -``` - -```powershell -Get-SPOApplication -OwningApplicationId -``` - -For more information, see [Get-SPOApplication cmdlet](/powershell/module/sharepoint-online/get-spoapplication). - -### View guest application permissions - -Admins can view the guest application permissions for any SharePoint Embedded application within their tenant using this command: - -```powershell -Get-SPOApplication -OwningApplicationId -ApplicationId -``` - -`OwningApplicationId` is the ID of the SharePoint Embedded application and ApplicationId is the guest application ID that has access to the SharePoint Embedded application. Application Administration cmdlets don't apply to Microsoft Loop. For more information, see [Get-SPOApplication cmdlet](/powershell/module/sharepoint-online/get-spoapplication). - -### Set sharing capability of applications - -Consuming tenant admins can set the sharing capability at an application level to determine whether files of the containers of the application be shared with external guests or not. - -```powershell -Set-SPOApplication -OwningApplicationId – SharingCapability - OverrideTenantSharingCapability <$ OverrideTenantSharingCapability > -``` - -`SharingCapability` can take the following values: `Disabled`; `ExistingExternalUserSharingOnly`; `ExternalUserSharingOnly`; ExternalUserAndGuestSharing - -`$OverrideTenantSharingCapability` can take the following values: `$true`; `$false` - -## Container Administration - -### View Containers - -Admins can get a list of all the containers for a SharePoint Embedded application using the following commands. This command lists all the active containers within the application: - -```powershell -Get-SPOContainer -OwningApplicationId | FT -``` - -The `OwningApplicationId` is the ID of the SharePoint Embedded application. For more information about using this command, see [Get-SPOContainer cmdlet](/powershell/module/sharepoint-online/get-spocontainer). - -Similarly, this command lists all the archived containers within the application with Id OwningApplicationId: - -```powershell -Get-SPOContainer -OwningApplicationId -ArchiveStatus Archived | FT -``` - -> [!NOTE] -> To enumerate Microsoft Loop containers, use Owning App ID: **a187e399-0c36-4b98-8f04-1edc167a0996** for all the cmdlets of container administration. - -### View containers sorted by storage -Consuming tenant admins can also get a list of all the containers of a SharePoint Embedded application sorted by storage using the following commands. - -```powershell -Get-SPOContainer -OwningApplicationId -SortByStorage | FT -``` - -`` can be `Ascending` or `Descending`. - -### View details of a Container - -Consuming tenant admins can get the details of a container within an application using the following command. This command returns more details of a container including StorageUsed, Ownership details, SiteURL, Label information, Owners count, etc. - -Consuming tenant admins can use the following command: - -```powershell -Get-SPOContainer -Identity -Get-SPOContainer -Identity -``` - -Here, the `containerId` is the ID of the container & `siteURL` is the URL of the SharePoint site that is associated with the container. - -### Sensitivity Label of a container - -Consuming tenant admins can set the sensitivity label of a container of an application using the following: - -```powershell -Set-SPOContainer -Identity -SensitivityLabel -``` - -Consuming tenant admins can remove the sensitivity label of a container of an application using the following: - -```powershell -Set-SPOContainer -Identity -RemoveLabel -``` - -The `ContainerId` is the ID of the container whose sensitivity label is being set. - -### Delete containers - -Deleting a container can have implications on the functionality of a SharePoint Embedded app, Here are some examples of the potential issues that an application can encounter when deleting a container. - -- Data Loss: Deleting a container removes all its content. If the SharePoint Embedded application relies on the data stored within the deleted container, the app might no longer function as expected or might lose access to critical information. -- Broken Links: If the SharePoint Embedded application contains links or references to the deleted container, those links become broken, leading to errors or malfunctioning features within the app. -- Permissions Issues: Deleting a container can affect permissions settings. If the SharePoint Embedded app relies on specific permissions granted to the deleted container, it might encounter permission issues and fail to function properly. - -Therefore, it's essential to carefully consider the consequences of deleting a container and ensure that appropriate measures are taken to mitigate any potential issues. - -### Permanent deletion - -When admins delete a Container, it goes into the Recycle Bin. A deleted container can be restored from the Recycle Bin within 93 days. If a container is deleted from the Recycle Bin, or it exceeds the 93-day retention period, it's permanently deleted. Deleting a container deletes everything within it, including all documents and files. - -Admins should notify the Container owners before they delete a Container so they can move their data to another location, and also inform users when the Container is deleted. - -> [!WARNING] -> Deleting a container may cause unexpected issues for the SharePoint Embedded application the Container belongs to and may interrupt usage of the application. - -```powershell -Remove-SPOContainer -Identity -``` - -The `ContainerId` is the ID of the container that is moved to the deleted container collection. For more information about using this command, see [Remove-SPOContainer cmdlet](/powershell/module/sharepoint-online/remove-spocontainer). - -### View deleted containers - -Admins can get a list of deleted containers on the deleted container collection using the following command. For more information about using this command, see [Get-SPODeletedContainer](/powershell/module/sharepoint-online/get-spodeletedcontainer). - -```powershell -Get-SPODeletedContainer -``` - -### Restore deleted containers - -Admins can restore a deleted container from the deleted container collection using the following command. For more information about using this command, see [Restore-SPODeletedContainer cmdlet](/powershell/module/sharepoint-online/get-spodeletedcontainer). - -```powershell -Restore-SPODeletedContainer -Identity -``` -If the container was in archived state at the time of deletion, it gets restored to archived state again. - -### Permanently delete containers - -Admins can permanently delete a container from the deleted container collection if the container has no further retention policies applied to it. For more information about using this command, see [Remove-SPODeletedContainer cmdlet](/powershell/module/sharepoint-online/remove-spodeletedcontainer). - -```powershell -Remove-SPODeletedContainer -Identity -``` - -### Guest application permission management - -If permitted, Admins can add, edit, and remove guest application access to SharePoint Embedded applications. A guest application is defined as any application within the enterprise applications of the owning tenant. For more information about using this command, see [Set-SPOApplicationPermission](/powershell/module/sharepoint-online/set-spoapplicationpermission). - -```powershell -Set-SPOApplicationPermission - [[-OwningApplicationId] ] - [[-ApplicationId] ] - [[-PermissionAppOnly] ] - [[-PermissionDelegated] ] -``` - -## Security and Compliance Administration - -SharePoint Embedded uses Microsoft’s comprehensive compliance and data governance solutions to help organizations manage risks, protect, and govern sensitive data, and respond to regulatory requirements. Security and compliance solutions work similarly in the SharePoint Embedded platform as they do today in the Microsoft 365 platform so that data is stored in a secure, protected way that meets customers’ business and compliance policies while making it easy for Compliance and SharePoint Administrators to enforce critical security and compliance policies on the content. For information on supported security and compliance capabilities, see [Security and Compliance](../../compliance/security-and-compliance.md). diff --git a/docs/embedded/administration/developer-admin/dev-admin.md b/docs/embedded/administration/developer-admin/dev-admin.md deleted file mode 100644 index 4969c7c427..0000000000 --- a/docs/embedded/administration/developer-admin/dev-admin.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: SharePoint Embedded developer administrator -description: This article describes the role and responsibilities of developer tenant admin in SharePoint Embedded. -ms.date: 11/21/2023 -ms.localizationpriority: high ---- -# SharePoint Embedded Developer Administrator - -## Overview - -Organizations that use SharePoint Embedded for file management are included in the developer ecosystem which developer administrators oversee. These administrators are responsible for managing applications and the container types that have containers, the foundation of an application that needs to store content. Additionally, they can connect billing profiles to their applications. This article describes the management features available to developer administrators. - -## Developer Admin role - -> [!IMPORTANT] -> Global Administrators can assign the SharePoint Embedded Administrator role available in Microsoft 365 Admin Center or Microsoft Entra ID to execute SharePoint Embedded container cmdlets mentioned in this article. -> -> Global Administrators can continue to execute SharePoint Embedded container cmdlets. - -A Microsoft 365 SharePoint Embedded Administrator serves as the developer admin. Global Administrators in Microsoft 365 can assign users the SharePoint Embedded Administrator role. The Global Administrator role already has all the permissions of the SharePoint Embedded Administrator role. The SharePoint Embedded Role is available in Microsoft Entra ID and Microsoft 365 Admin Center. For information on the [SharePoint Embedded Administrator](../adminrole.md) role. - -> [!NOTE] -> The PowerShell cmdlets in this article require the [SharePoint Embedded Administrator](../adminrole.md) or [Global Administrator](/entra/identity/role-based-access-control/permissions-reference#global-administrator) role. The equivalent Microsoft Graph container type endpoints (create, get, update, delete) don't require an administrator role. Any non-guest user in the owning tenant can [create a container type using Microsoft Graph](../../getting-started/containertypes.md#creating-container-types) and is automatically assigned as an [owner](../../development/auth.md#container-type-owner-capabilities). Other SharePoint Embedded Graph operations (for example, container management with `FileStorageContainer.Manage.All`) continue to require an administrator role. - -The following are some of the SharePoint Embedded actions currently supported on PowerShell: - -- Creation of container types - - Creation of a standard container type with standard billing - - Creation of a standard container type with passthrough billing - - Creation of a trial container type -- Container type management - - Viewing of container types in the tenant - - Editing properties of a container type in the tenant - - Configuration properties of a container type in the tenant - - Manage billing of applications/ container types for standard billing - - Removing a container type in the tenant - -### Billing responsibilities of the developer admin - -There are two types of billing models in SharePoint Embedded. To learn more, see [SharePoint Embedded billing](../billing/billing.md). - -#### Standard billing - -The developer admin is responsible for the billing of SharePoint Embedded applications. The developer admin needs to [set the billing profile for the container type](../../getting-started/containertypes.md#set-the-billing-profile) after its creation, provided they have owner or contributor permissions on an Azure subscription. To learn more about how to set up billing, read about [creating container types](../../getting-started/containertypes.md#creating-container-types) and [SharePoint Embedded billing](../billing/billing.md). - -#### Passthrough billing - -In this model, the customer, or the consuming tenant admin, is responsible for billing. For this reason, this billing model is also known as "direct-to-customer billing." To ensure the passthrough billing model is in place, the developer admin must set the `billingClassification` on the container type to `directToCustomer`. To learn more about how to set up passthrough billing in the container type, read about [creating container types](../../getting-started/containertypes.md#creating-container-types). To learn more about how to configure billing for SharePoint Embedded applications with passthrough billing in a consuming tenant, see [setup guide in the consuming tenant Admin Center](../consuming-tenant-admin/cta.md#set-up-billing-for-passthrough-container-type). - -## Administration Tools - -Developer admins are able to manage SharePoint Embedded applications with Microsoft Graph APIs and PowerShell commands using the SharePoint Online Management Shell. - -To get started using the Microsoft Graph APIs for SharePoint Embedded management, see: - -- [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) resource representing a container type and its related methods -- [fileStorageContainerTypeRegistration](/graph/api/resources/filestoragecontainertyperegistration) resource representing the registration of a container type in a consuming tenant and its related methods - -## PowerShell cmdlets for admin experience - -To get started using PowerShell to manage SharePoint Embedded, you have to install the SharePoint Online Management Shell and connect to SharePoint. - -> [!IMPORTANT] -> You must use the latest version of SharePoint PowerShell to use container type administration cmdlets. - -### Creation of container types - -The developer administrator can create a container type using PowerShell cmdlets. Each container type is associated with an application ID, a one-to-one mapping, and an Azure subscription ID. The developer administrator can also create trial container types that have a validity of 30 days to test out SharePoint Embedded. The following [commands](/powershell/module/sharepoint-online/new-spocontainertype) can be used to create SharePoint Embedded container types on the developer admin’s tenant: - -Standard billing container type: - -```powershell -New-SPOContainerType -ContainerTypeName -OwningApplicationId -Add-SPOContainerTypeBilling -ContainerTypeId -AzureSubscriptionId -ResourceGroup -Region ​ -``` - -Passthrough billing container type: - -```powershell -New-SPOContainerType -IsPassThroughBilling -ContainerTypeName -OwningApplicationId -``` - -Trial container type: - -```powershell -New-SPOContainerType –TrialContainerType -ContainerTypeName -OwningApplicationId -``` - -`OwningApplicationId` is the ID of the SharePoint Embedded application. `AzureSubscriptionId` is the ID of the Azure subscription for billing purposes. - -### Viewing of container types - -The developer administrator can view container types and the corresponding applications created in their tenant using PowerShell commandlets. The following commands can be used to view SharePoint Embedded applications created on the developer admin’s tenant: - -```powershell -Get-SPOContainerType​ -Get-SPOContainerType -ContainerTypeId -``` - -### Manage properties of container types - -The developer administrator can change the properties of container types, both standard and trial. The following commands can be used to change the properties of SharePoint Embedded applications created on the developer admin’s tenant: - -```powershell -Set-SPOContainerType -ContainerTypeId - [-OwningApplicationId ] - [-ContainerTypeName ] - [-WhatIf] [-Confirm] -``` - -### Container type configuration properties - -The developer administrator can change container type configuration settings using PowerShell commandlets. The following container type properties can be set: - -1. Discoverability Disabled: Controls if file items inside the container surface in other Microsoft 365 properties (MRU, etc.). -1. Sharing Restricted: Only manager and owner can share files in the container if restricted sharing is true. -2. Is Archive Enabled: If set to true, the application can support archival of containers. Default value is false. - -The following commands can be used to change the configuration settings of SharePoint Embedded applications created on the developer admin’s tenant: - -```powershell -Set-SPOContainertypeConfiguration -ContainerTypeId < ContainerTypeId > -DiscoverabilityDisabled $value -``` - -For `DiscoverabilityDisabled` `$value` can be set to `$true`; `$false` - -The default value `$true` - ensures all content is hidden. - -```powershell -Set-SPOContainertypeConfiguration -ContainerTypeId < ContainerTypeId > -SharingRestricted $value -``` - -For `SharingRestricted` `$value` can be set to `$true`; `$false` - -```powershell -Set-SPOContainertypeConfiguration -ContainerTypeId < ContainerTypeId > - DiscoverabilityDisabled $value -SharingRestriced $value -``` - -The developer admin can view the container type configuration settings using the following cmdlet: - -```powershell -Get-SPOContainertypeConfiguration -ContainerTypeId < ContainerTypeId > -``` - -## Manage billing profile of container types - -The developer administrator can change the billing profile of container types using PowerShell cmdlets. The following commands can be used to change the properties of SharePoint Embedded applications created on the developer admin’s tenant: - -```powershell -Set-SPOContainerType -ContainerTypeId - [-AzureSubscriptionId ] - [-ResourceGroup ]​[-WhatIf] - [-Confirm] -``` - -For more information about billing, see [Billing](../billing/billing.md). - -## Roles and Permissions - -The user or admin who creates the billing relationship for SharePoint Embedded needs to have owner or contributor permissions on an Azure subscription. - -If you don't have an Azure subscription, follow the steps here to [create a subscription](/azure/cloud-adoption-framework/ready/azure-best-practices/initial-subscriptions). diff --git a/docs/embedded/build/agent-experiences.md b/docs/embedded/build/agent-experiences.md new file mode 100644 index 0000000000..c8f15bce2c --- /dev/null +++ b/docs/embedded/build/agent-experiences.md @@ -0,0 +1,33 @@ +--- +title: Add Microsoft 365 Copilot and agent experiences +description: Ground Copilot-style agents in SharePoint Embedded content and expose SharePoint Embedded to Microsoft Foundry. +ms.date: 07/10/2026 +ms.reviewer: pemtaira +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Add Microsoft 365 Copilot and agent experiences + +**Applies to:** Developer + + + +SharePoint Embedded agent experiences let your app answer questions over files stored in SharePoint Embedded containers. The recommended path is to use **Microsoft Foundry Agent Service** with a **SharePoint knowledge source** configured for SharePoint Embedded. For setup steps, see [Set up SharePoint Embedded as a Foundry knowledge source](sharepoint-embedded-knowledge-source.md). + +> [!CAUTION] +> The earlier **SharePoint Embedded agent SDK** (the React `ChatEmbedded` control) was **deprecated in March 2026** and replaced by [Microsoft Foundry Agent Service](/azure/foundry/agents/overview) with a [SharePoint knowledge source (preview)](/azure/search/agentic-knowledge-source-how-to-sharepoint-remote) configured for SharePoint Embedded. Use the Foundry knowledge source for new work. + +## Test user experience + +Sign in with a user who has a Microsoft 365 Copilot license when required. Upload supported files to a container, wait for indexing, open the chat, and ask questions the file content can answer. If answers omit expected files, check discoverability, supported file formats, app access, user access, scope selection, and indexing delay. + +## Next steps + +- [Set up SharePoint Embedded as a Foundry knowledge source](sharepoint-embedded-knowledge-source.md) diff --git a/docs/embedded/build/archive-restore-containers.md b/docs/embedded/build/archive-restore-containers.md new file mode 100644 index 0000000000..808d07350a --- /dev/null +++ b/docs/embedded/build/archive-restore-containers.md @@ -0,0 +1,91 @@ +--- +title: Archive and Restore Containers +description: Archive inactive SharePoint Embedded containers and reactivate them with Microsoft Graph beta APIs. +ms.date: 07/13/2026 +ms.reviewer: jaeccles +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Archive and restore containers + +**Applies to:** Developer + + + +Use SharePoint Embedded container archival when a container must be retained but no longer needs to be active accessed or used for collaboration. Archival uses Microsoft 365 Archive, a cold-storage tier that reduces storage cost while keeping the same security, compliance, and search standards. For the Microsoft 365 Archive overview, see [Microsoft 365 Archive](/microsoft-365/archive/archive-overview). + +> [!IMPORTANT] +> Microsoft 365 Archive is in Preview for SharePoint Embedded. Validate tenant availability, billing, and API behavior before you expose archive actions to users. + +## Enable archival on a container type + +Archival must be enabled on the container type. Use SharePoint Embedded admin PowerShell for an existing container type. + +```powershell +Set-SPOContainerTypeConfiguration -ContainerTypeId -IsArchiveEnabled $true +``` + +Enable archival when you create a new container type by passing `-IsArchiveEnabled $true`. + +```powershell +New-SPOContainerType -ContainerTypeName -OwningApplicationId -IsArchiveEnabled $true +``` + +Only show archive commands in your app after the owning application and consuming tenant are configured for the container type. + +## Archive a container + +Call the Microsoft Graph beta archive action for the target container. + +```http +POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{containerId}/archive +``` + +The caller must have the `Owner` or `PrincipalOwner` role on the container. Global Administrators and SharePoint Embedded Administrators can act on all containers. The app must also have write permission on the container. + +An archived container is inaccessible until it's reactivated. Stop uploads, background processors, webhook-dependent workflows, and interactive edits before submitting the archive request. + +## Get archived containers + +Read one archived container with the normal container get operation. + +```http +GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{containerId} +``` + +List archived containers for a container type by filtering for containers that have archival details. + +```http +GET https://graph.microsoft.com/beta/storage/fileStorage/containers?$filter=containerTypeId eq {containerTypeId} and archivalDetails ne null +``` + +Use this list for lifecycle views, admin reports, or reactivation flows. Make the archived state visible in your UI so users understand why files can't be opened. + +## Reactivate a container + +Call the Microsoft Graph beta unarchive action to reactivate an archived container. + +```http +POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{containerId}/unarchive +``` + +Reactivation is instantaneous during the first seven days after archival. After seven days, reactivation can take up to 24 hours. Keep the container read and write actions disabled until the service reports that the container is active again. + +## Design lifecycle controls + +Require explicit user intent before archive and unarchive requests. Record the container ID, actor, timestamp, and Graph request correlation data in your application logs. Don't treat archive as deletion; retention, eDiscovery, audit, and compliance requirements still apply to archived data. + +If a lifecycle operation fails, check the caller role, app write permission, container type archival setting, and whether the target container is already in the requested state. + +## Next steps + +- [Upload, download, and manage files](manage-files.md) +- [Respond to file and container changes with webhooks](respond-to-changes-webhooks.md) +- [Manage containers with PowerShell](../admin/manage-containers-powershell.md) diff --git a/docs/embedded/build/configure-authentication-authorization.md b/docs/embedded/build/configure-authentication-authorization.md new file mode 100644 index 0000000000..3a0745a5de --- /dev/null +++ b/docs/embedded/build/configure-authentication-authorization.md @@ -0,0 +1,231 @@ +--- +title: Configure Authentication and Authorization +description: Configure Microsoft Entra ID authentication and SharePoint Embedded authorization for your application. +ms.date: 07/13/2026 +ms.reviewer: cindylay +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Configure authentication and authorization + +**Applies to:** Developer + + + +Configure authentication and authorization before your SharePoint Embedded application calls Microsoft Graph or SharePoint Embedded APIs. + +Complete [Register application permissions](register-application-permissions.md) first so the container type is registered in the consuming tenant. + +## Understand the access model + +SharePoint Embedded uses two permission layers. + +Microsoft Graph permissions allow the app to call SharePoint Embedded endpoints. + +Container type application permissions allow the app to access containers of a specific container type. + +Both layers are required. + +> [!IMPORTANT] +> Microsoft Graph consent alone doesn't grant access to containers. The app must also be granted permission to the container type. + +## Configure the Microsoft Entra ID app + +Start with a Microsoft Entra ID app registration. + +Configure it for your application type: + +1. Register or identify the owning application. +1. Add redirect URIs for development and production clients. +1. Add credentials for app-only flows when needed. +1. Add Microsoft Graph permissions for SharePoint Embedded access. +1. Add the Microsoft Graph permission required for registration scenarios. +1. Ask an administrator to grant consent where required. + +For general steps, see [Register an application with the Microsoft identity platform](/graph/auth-register-app-v2). + +## Request Microsoft Graph permissions + +SharePoint Embedded operations through Microsoft Graph require `FileStorageContainer.Selected`. + +Use delegated `FileStorageContainer.Selected` for access on behalf of a user. + +Use application `FileStorageContainer.Selected` for app-only access. + +Application `FileStorageContainer.Selected` requires admin consent in the consuming tenant. Delegated `FileStorageContainer.Selected` does not require admin consent. + +For administrative capabilities on behalf of an administrator user — such as enumerating, deleting, restoring, purging, and updating containers and managing their permissions across all governable container types in the consuming tenant — request `FileStorageContainer.Manage.All`. + +> [!NOTE] +> The combination of Microsoft Graph permissions and container type application permissions determines what the application can actually do. + +## Request the permission for registration + +Container type registration uses the Microsoft Graph container type registration API in v1.0. + +For registration, request the `FileStorageContainerTypeReg.Selected` Microsoft Graph permission (delegated or app-only). + +| Scope name | Type | Use | +|---|---|---| +| `FileStorageContainerTypeReg.Selected` | Delegated or Application | Enables container type registration on a consuming tenant. | + +For delegated registration calls, the signed-in user must have the SharePoint Embedded Administrator or Global Administrator role. + +Use this permission with [Register application permissions](register-application-permissions.md). + +## Prefer delegated access when possible + +Use access on behalf of a user whenever possible. + +Delegated access improves security, accountability, auditability, and alignment with the user's container membership. + +When using delegated access, effective permissions are the intersection of application permissions and user container permissions. + +The user must be a member of the container. + +Use a confidential client application to keep your app in control of actions taken on behalf of a user. A public client application can expose user tokens to the end user, which can lead to actions taken outside your app's control. For more information, see [Public client and confidential client applications](/entra/identity-platform/msal-client-applications). + +## Configure delegated token acquisition + +For delegated calls: + +1. Sign in the user with Microsoft identity platform. +1. Request delegated `FileStorageContainer.Selected`. +1. Confirm delegated consent is granted according to the consuming tenant's user consent policies. +1. Acquire an access token for Microsoft Graph. +1. Call Microsoft Graph SharePoint Embedded endpoints. +1. Verify the user is a member of the target container. + +If the user isn't a container member, the app can't access that container on the user's behalf. + +## Configure app-only token acquisition + +Use app-only access for service workloads that don't run as a user. + +For app-only calls: + +1. Configure an application credential, such as a certificate. +1. Request application `FileStorageContainer.Selected`. +1. Have a consuming tenant administrator grant admin consent. +1. Acquire a token using the client credentials flow. +1. Call Microsoft Graph SharePoint Embedded endpoints. +1. Limit container type permissions to the workload's needs. + +> [!CAUTION] +> An app-only token can access all containers enabled by its container type application permissions. Use least privilege. + +## Call Microsoft Graph APIs + +After token acquisition, call SharePoint Embedded operations through Microsoft Graph. +Useful references include: + +- [File storage container resource type](/graph/api/resources/filestoragecontainer) +- [Create fileStorageContainer](/graph/api/filestoragecontainer-post) +- [Microsoft Graph authentication and authorization basics](/graph/auth/auth-concepts) + +Continue with [Create and manage containers](create-manage-containers.md) for lifecycle operations. + +## Handle operations not exposed through Graph + +Some operations have exceptional access patterns. + +These operations use exceptional access patterns: + +- Container type management in the owning tenant through the Microsoft Graph container type API (`FileStorageContainerType.Manage.All` delegated permission). +- Container type registration in the consuming tenant through the Microsoft Graph container type registration API (`FileStorageContainerTypeReg.Selected`). +- SharePoint Embedded agent experiences through their own permission requirements. +- **Search**: Microsoft Search on SharePoint Embedded content requires the delegated `Files.Read.All` permission in addition to `FileStorageContainer.Selected`. +- **Operations that require a user license**: [List containers](/graph/api/filestorage-list-containers) returns `403 Forbidden` for a delegated user who doesn't have a OneDrive (app-only calls aren't affected), and users need a Microsoft 365 license to appear in the Office @mentions people picker. +- **Administrative actions on containers**: `FileStorageContainer.Manage.All` requires the signed-in user to be a SharePoint Embedded Administrator or Global Administrator. For a non-admin user it grants nothing — if only `Manage.All` is granted, the app gets access denied; if both `Manage.All` and `FileStorageContainer.Selected` are granted, `Manage.All` is ignored. + +> [!IMPORTANT] +> Don't assume every operation uses the same token or permission resource. Check exceptional access patterns before implementing a flow. + +## Grant container type application permissions + +The owning application grants container type application permissions through [container type registration](register-application-permissions.md) in a consuming tenant. These permissions determine what an application can do with containers of the container type. + +| Permission | Description | +|---|---| +| None | No permissions to any containers or content of this container type. | +| ReadContent | Read the content of containers of this container type. | +| WriteContent | Write content to containers of this container type. Requires ReadContent. | +| Create | Create containers of this container type. | +| Delete | Delete containers of this container type. | +| Read | Read the metadata of containers of this container type. | +| Write | Update the metadata of containers of this container type. | +| EnumeratePermissions | Enumerate the members of a container and their roles. | +| AddPermissions | Add members to a container. | +| UpdatePermissions | Change the roles of existing members. | +| DeletePermissions | Remove other members (but not self) from a container. | +| DeleteOwnPermission | Remove own membership from a container. | +| ManagePermissions | Add, remove (including self), or update members in container roles. | +| ManageContent | Manage container content (WriteContent plus discard checkout in app-only mode). | +| Full | All permissions for containers of this container type. | + +## Manage container type owners + +Any Microsoft Entra user that isn't an external identity can be a container type owner. Owners are managed through the [permissions](/graph/api/filestoragecontainertype-post-permissions) navigation property on the [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) resource. Each entry has the `owner` role and identifies the user through `grantedToV2`. + +- **Automatic assignment**: The user who [creates a container type](/graph/api/filestorage-post-containertypes) is automatically assigned as an owner. +- **Add owners**: Use [`POST /containerTypes/{id}/permissions`](/graph/api/filestoragecontainertype-post-permissions) to add up to three owners per container type. +- **Remove owners**: Use [`DELETE /containerTypes/{id}/permissions/{id}`](/graph/api/filestoragecontainertype-delete-permissions) to remove an owner. +- **Read owners**: Use [`GET /containerTypes/{id}?$expand=permissions`](/graph/api/filestoragecontainertype-get) or [`GET /containerTypes/{id}/permissions`](/graph/api/filestoragecontainertype-list-permissions) to retrieve owners. + +SharePoint Embedded Administrators can manage all applications created in the owning tenant and installed in the consuming tenant. Assign the least privileged role necessary; the SharePoint Embedded Administrator role is recommended over Global Administrator for these tasks. + +## Understand container permissions + +Container permissions apply only to delegated access. An app that accesses containers without a user gets the full access defined by its container type application permissions instead. + +Users get container membership in two ways: + +- **Direct membership** — the user is added directly to a container with specific permissions. +- **Transitive membership** — the user belongs to a [Microsoft 365 group](/microsoft-365/admin/create-groups/office-365-groups) that's a member of the container. + +A user must be a member of the container with one of these roles: + +| Role | Access summary | +|---|---| +| Reader | Read container properties and content. | +| Writer | Reader access plus create, update, and delete content and update applicable properties. | +| Manager | Writer access plus manage container membership. | +| Owner | Manager access plus delete containers. | + +When a user creates a container through delegated calls, that user is automatically assigned the Owner role. + +To share individual items without granting container access, use the [driveItem invite](/graph/api/driveitem-invite) or [permission create](/graph/api/driveitem-post-permissions) endpoints. Sharing an item doesn't grant access to the container or to any other item in it. + +## Validate authentication + +Validate the flow before feature code: + +1. Confirm admin consent completed successfully. +1. Acquire a delegated token. +1. Acquire an app-only token. +1. Call a simple Graph endpoint that matches the token type. +1. Confirm registration includes the calling app. +1. Confirm user membership for delegated calls. +1. Confirm app-only access is limited by container type permissions. + +## Troubleshoot authorization failures + +| Symptom | Check | +|---|---| +| Graph call returns unauthorized | Token is missing, expired, or for the wrong resource. | +| Graph call returns forbidden | Consent, Graph permission, or container type permission is missing. | +| Delegated call fails for one user | User isn't a container member or lacks the needed role. | +| App-only call has too much access | Container type permission is broader than necessary. | +| Registration call fails | Use `FileStorageContainerTypeReg.Selected`; for delegated calls the user needs the SharePoint Embedded Administrator or Global Administrator role. | +| Search call fails | Review search-specific exceptional access patterns. | + +## Next steps + +Use your configured flow to [Create and manage containers](create-manage-containers.md). diff --git a/docs/embedded/build/container-metadata.md b/docs/embedded/build/container-metadata.md new file mode 100644 index 0000000000..7e6b3de49a --- /dev/null +++ b/docs/embedded/build/container-metadata.md @@ -0,0 +1,135 @@ +--- +title: Store and Query Container Metadata +description: Define SharePoint Embedded metadata columns and query drive items by field values. +ms.date: 07/13/2026 +ms.reviewer: cindylay +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Store and query container metadata + +**Applies to:** Developer + + + +Use metadata when your app needs structured fields on files in a SharePoint Embedded container. Metadata is stored as columns on a `fileStorageContainer` and as field values on the container drive's items. Your application is responsible for creating and managing the column schema for each container instance. For the complete list of container resource properties, see [fileStorageContainer resource type](/graph/api/resources/filestoragecontainer). + +## Permissions and supported callers + +Call the metadata APIs with an app-only or delegated bearer token. Use `FileStorageContainer.Selected` for application and delegated calls. + +Container owners can create, update, and delete columns. Container members can read and list columns. + +## Choose column types + +SharePoint Embedded metadata supports these column type properties : `boolean`, `choice`, `currency`, `dateTime`, `hyperlinkOrPicture`, `number`, `personOrGroup`, and `text`. It also supports column settings such as `indexed`, `isDeletable`, `isSealed`, `name`, `readOnly`, and `type`. + +Column names must follow SharePoint rules. Don't use names that contain `!`, start with a digit or punctuation, contain spaces, look like spreadsheet cell references, represent localized true or false values, or use reserved names such as `Author`, `Created`, or `Description`. + +## Create a column + +Create a column on the container before writing field values on files. + +```http +POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns +Content-Type: application/json +``` + +```json +{ + "description": "test", + "displayName": "Title", + "enforceUniqueValues": false, + "hidden": false, + "indexed": false, + "name": "Title", + "text": { + "allowMultipleLines": false, + "appendChangesToExistingText": false, + "linesForEditing": 0, + "maxLength": 255 + } +} +``` + +The create request doesn't support `type`, and text `maxLength` must be less than or equal to 255. + +> [!NOTE] +> As of January 2026, the container column APIs (list, create, update, delete columns) are also generally available on the **v1.0** Microsoft Graph endpoint. You can replace `/beta/` with `/v1.0/` in the column requests below. The beta endpoint remains available. + +## Manage columns + +Use the column ID returned by the create or list operation. + +```http +GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns +GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id} +PATCH https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id} +DELETE https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id} +``` + +Patch supported properties when the schema changes. You can update any property of a column except the `id` property. + +```json +{ + "required": true, + "hidden": false, + "description": "This is my new column description" +} +``` + +## Read and write file metadata + +Field values are stored on the drive item's list item fields. Read all fields or select the ones your UI needs. + +```http +GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields +GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields?$select=Name,Color +``` + +Patch field values to update metadata. Use `null` to clear a field value when the column allows empty values. + +```http +PATCH https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields +Content-Type: application/json +``` + +```json +{ + "Color": "Fuchsia", + "Quantity": 934 +} +``` + +```json +{ + "Color": null +} +``` + +## Query files by metadata + +Use OData query options on custom columns when you need structured filtering or ordering inside a container drive. + +```http +GET https://graph.microsoft.com/beta/drives/{drive-id}/items?$orderby=listitem/fields/TestField asc&$filter=startswith(listitem/fields/TestField, '3')&$expand=listitem($expand=fields) +``` + +Use `$expand=listitem($expand=fields)` when the result needs field values in the response. Create indexed columns for high-cardinality filters that your app runs frequently. + +For full-text search across containers and custom metadata (using the `OWSTEXT` property suffix), see [Search containers and files](search-containers-files.md). Use OData `$filter` for structured queries inside a single container drive; use search for free-text queries across many containers. + +## Keep schema consistent + +Create required columns during container provisioning. Store the expected schema version in your app data, and run migrations when new columns are introduced. Avoid deleting columns until you know no workflows, queries, exports, or search experiences depend on their values. + +## Next steps + +- [Share files and manage permissions](share-files-manage-permissions.md) diff --git a/docs/embedded/build/create-container-type.md b/docs/embedded/build/create-container-type.md new file mode 100644 index 0000000000..6a521785d6 --- /dev/null +++ b/docs/embedded/build/create-container-type.md @@ -0,0 +1,211 @@ +--- +title: Create and configure a container type +description: Create a trial or production SharePoint Embedded container type and configure its owning app and billing model. +ms.date: 07/13/2026 +ms.reviewer: stpuceli +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- +# Create and configure a container type + +**Applies to:** Developer + + + +Create a SharePoint Embedded container type for your application to create containers or store files. A container type defines access, billing accountability, and selected behaviors for containers created by your app. + +If you're just starting, complete [Quickstart: Build your first app with VS Code](quickstart-vscode.md). Then use this article for trial, standard, and pass-through decisions. + +To decide between single-tenant and multitenant models first, see [Choose an app model](../plan/choose-app-model.md). + +## Understand the container type relationship + +A container type is strongly coupled with one Microsoft Entra ID application, called the owning application. + +SharePoint Embedded requires a one-to-one relationship between one owning application and one container type. + +The container type ID is stored on each container as an immutable property. + +The ID is used for access authorization, trial exploration, billing, and configurable behaviors. + +> [!NOTE] +> The Microsoft Graph API — [Create fileStorageContainerType](/graph/api/filestorage-post-containertypes) — is delegated-only and can be called by any non-guest owning-tenant user. The caller doesn't need an administrator role and is automatically assigned as an owner of the new container type. + +## Choose trial or production + +Choose the container type purpose when you create it. + +You can't convert a trial container type to production later. + +You can't convert a standard billing type to pass-through billing later. + +| Use case | Container type | +|---|---| +| Local proof of concept | Trial container type | +| App owner pays | Standard container type with billing profile | +| Customer tenant pays | Standard container type with pass-through billing | + +> [!IMPORTANT] +> If you choose the wrong purpose or billing model, you must recreate the container type. + +## Prerequisites + +Before you create a container type, make sure you have: + +- A Microsoft 365 tenant with SharePoint available. +- A Microsoft Entra ID app registration for the owning app. +- A non-guest member account in the owning tenant. +- For standard billing, an Azure subscription and resource group. +- For standard billing setup, owner or contributor permissions on the Azure subscription. + +> [!NOTE] +> - Creating a container type through Microsoft Graph requires only the `FileStorageContainerType.Manage.All` delegated permission. Any non-guest user in the owning tenant can create one and is automatically assigned as an [owner of that container type](../plan/authentication-permissions.md#container-type-owners). For tenant-wide administrative operations, see [Create apps with PowerShell](../admin/create-apps-powershell.md). +> +> - Users who authenticate into containers must exist in Microsoft Entra ID as members or guests. An Office license isn't required to collaborate on Office documents stored in a container, except for documented exceptional experiences such as mentions. + +## Create a trial container type + +Use a trial container type for evaluation. + +You can create one with the SharePoint Embedded Visual Studio Code extension or Microsoft Graph. + +The Visual Studio Code path is fastest for a first app. See [Quickstart: Build your first app with VS Code](quickstart-vscode.md). + +For Microsoft Graph, create the container type with the `trial` billing classification. + +The following restrictions are applied to trial container types: + +- The tenant can have up to five containers of the container type. This includes active containers and those in the recycle bin. +- Each container has up to 1 GB of storage space. +- The container type expires after 30 days, and access to any existing containers of that container type is then removed. +- The developer must permanently delete all containers of an existing container type in trial status to create a new container type for trial. This includes containers in the deleted container collection. +- The container type is restricted to work in the developer tenant. It can't be deployed in other consuming tenants. + +## Create a standard container type with app-owner billing + +Use standard billing when the developer or app owner tenant pays for consumption. + +Each tenant can have up to 25 standard container types at a time. + +1. Create or identify the owning Microsoft Entra ID application. +1. Create the container type with the `standard` billing classification. +1. Attach an Azure billing profile with the SharePoint Embedded Visual Studio Code extension or an administrator-managed billing flow. +1. Record the container type ID. +1. Continue to registration in the consuming tenant. + +> [!NOTE] +> If billing setup fails with `SubscriptionNotRegistered`, wait several minutes and retry. The `Microsoft.Syntex` resource provider registration can take time. + +## Create a pass-through billing container type + +Use pass-through billing when the consuming tenant pays for consumption. + +1. Create or identify the owning Microsoft Entra ID application. +1. Create the container type with the `directToCustomer` billing classification. +1. Register the container type in the consuming tenant. +1. Have the consuming tenant admin activate pay-as-you-go services. + +> [!IMPORTANT] +> The consuming tenant must complete billing setup before a pass-through application can be used successfully. + +The consuming tenant admin activates pay-as-you-go services in the Microsoft 365 admin center. In **Setup** > **Billing and licenses**, select **Activate pay-as-you-go services**. + +![Microsoft 365 admin center Billing and licenses section with the Activate pay-as-you-go services option.](../images/SyntexActivatePAYGSetup.png) + +Under **Syntex services for**, select **Apps**, then select **SharePoint Embedded** to enable billing for the app. + +![Microsoft 365 admin center Apps panel with SharePoint Embedded selected to activate pay-as-you-go billing.](../images/SyntexPAYGActivateSPE.png) + +## Configure the owning Entra app + +Configure the app so it can own exactly one container type. + +Request Microsoft Graph permissions for SharePoint Embedded access. + +Request Microsoft Graph `FileStorageContainerTypeReg.Selected` application permission for container type registration on consuming tenants. + +Use redirect URIs that match your development and production clients. + +Use credentials appropriate for delegated or app-only flows. + +For auth details, see [Configure authentication and authorization](configure-authentication-authorization.md). + +## Set basic properties + +| Property | Guidance | +|---|---| +| Container type name | Use a durable name that maps to your workload. | +| Owning application ID | Use the app registration that owns this type. | +| Application redirect URL | Use the URL where files from this app should redirect. | +| Billing model | Choose trial, standard, or pass-through at creation time. | + +> [!CAUTION] +> The container type ID and owning application ID can't be updated later. + +## Configure container type behavior + +Developers can configure selected behaviors after creation. + +Available settings include: + +- `ApplicationRedirectUrl` +- `DiscoverabilityDisabled` +- `SharingRestricted` + +Use the Microsoft Graph [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API for supported container type updates. For tenant-wide administrative settings, see [Create apps with PowerShell](../admin/create-apps-powershell.md). + +> [!IMPORTANT] +> Updating settings on a container type can take up to **24 hours** to replicate to all consuming tenants. If a consuming tenant applied setting overrides, those overrides remain in place. Some settings apply only to new content, not to existing content. + +## View and update container types + +Use Microsoft Graph to list and update container types. + +A non-administrator container type owner can update the container types they own. + +You need owner or contributor access to billing subscriptions for billing changes. + +### Manage container types with Microsoft Graph + +You can also manage container types with the `fileStorageContainerType` Microsoft Graph APIs. + +| Operation | API | +| --- | --- | +| Create a container type | [Create fileStorageContainerType](/graph/api/filestorage-post-containertypes) | +| List container types | [List fileStorageContainerType](/graph/api/filestorage-list-containertypes) | +| Update a container type | [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) | +| Delete a container type | [Delete fileStorageContainerType](/graph/api/filestorage-delete-containertypes) | + +List results are filtered by ownership. Non-administrator users see only the container types they've been granted permission on, while SharePoint Embedded Administrators and Global Administrators see every container type in the tenant. For the settings you can configure, see [fileStorageContainerTypeSettings](/graph/api/resources/filestoragecontainertypesettings). + +You can delete only trial container types; deletion of standard container types isn't yet supported. Before you delete a container type, remove every container of that type, including containers in the deleted container collection. + +## Understand billing dependency + +For app-owner billing, the developer tenant attaches an Azure subscription and resource group. + +For pass-through billing, the consuming tenant activates pay-as-you-go services. + +For details, see [SharePoint Embedded meters](../reference/billing-meters.md) and [SharePoint Embedded billing management](../admin/monitor-usage-billing-cost.md). + +## Link to multitenant onboarding + +A multitenant app usually has an owning tenant and one or more consuming tenants. + +Use this sequence for each consuming tenant: + +1. Create the container type in the owning tenant. +1. Ask the consuming tenant admin to grant admin consent. +1. Register container type application permissions. +1. Configure pass-through billing when the consuming tenant pays. +1. Validate container creation and access. + +## Next steps + +Register permissions in [Register application permissions](register-application-permissions.md). diff --git a/docs/embedded/build/create-manage-containers.md b/docs/embedded/build/create-manage-containers.md new file mode 100644 index 0000000000..9c35aecfac --- /dev/null +++ b/docs/embedded/build/create-manage-containers.md @@ -0,0 +1,206 @@ +--- +title: Create and Manage Containers +description: Create, list, update, recycle, restore, and delete SharePoint Embedded containers in your app. +ms.date: 07/13/2026 +ms.reviewer: jaeccles +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Create and manage containers + +**Applies to:** Developer + + + +Create and manage containers after your container type is created, registered, and authorized. Containers are the basic storage unit in SharePoint Embedded. + +Complete [Configure authentication and authorization](configure-authentication-authorization.md) before you call container APIs. + +## Understand containers + +All SharePoint Embedded files and documents are stored in containers. + +A container: + +- Belongs to a consuming Microsoft 365 tenant. +- Has an immutable container type ID. +- Stores content for your application. +- Defines a boundary for membership and permissions. +- Is accessed through Microsoft Graph. + +For the architecture overview, see [SharePoint Embedded app architecture](../plan/app-tenant-architecture.md). + +## Know the lifecycle + +A typical container lifecycle includes: + +1. Create a container. +1. Add or confirm members. +1. Upload and manage files. +1. Read or update container metadata. +1. Recycle a container when it's no longer active. +1. Restore a recycled container when needed. +1. Permanently delete containers during cleanup. + +Continue to [Upload, download, and manage files](manage-files.md) for content operations. + +## Prerequisites + +Before creating containers, make sure: + +- The container type exists. +- The container type is registered in the consuming tenant. +- The app has Microsoft Graph `FileStorageContainer.Selected` consent. +- The app has container type permissions for the operation. +- For delegated calls, the signed-in user can receive the needed container role. +- For trial container types, you're within trial limits. + +> [!IMPORTANT] +> Trial container types can create up to five containers, including active containers and containers in the recycle bin. + +## Choose delegated or app-only creation + +Use delegated access when a user initiates creation, the user should be accountable, or the creating user should become container Owner. + +Use app-only access when a service provisions containers, no user is present, and the app has permission to create containers. + +> [!NOTE] +> A user creating a new container through delegated calls is automatically assigned the Owner role. + +## Create a container + +Use Microsoft Graph to create a file storage container for your registered container type. + +For the canonical API shape, see [Create fileStorageContainer](/graph/api/filestoragecontainer-post). + +Implementation steps: + +1. Acquire a valid Microsoft Graph token. +1. Include the target container type information required by the API. +1. Send the create request. +1. Store the returned container ID. +1. Store display metadata your app needs. +1. Assign or confirm membership for delegated scenarios. + +> [!TIP] +> Store the container ID in your application database as the durable link between your business object and the SharePoint Embedded container. + +## Create a container in Visual Studio Code + +For trial development, the Visual Studio Code extension can create containers. + +1. Open the SharePoint Embedded view. +1. Expand the registered trial container type. +1. Right-click **Containers**. +1. Select **Create container**. +1. Enter a name. + +1. Confirm the container appears under the container type. + +See [Quickstart: Build your first app with VS Code](quickstart-vscode.md) for the extension flow. + +## List containers + +List containers to show available containers, validate provisioning, or run maintenance. + +For the canonical API shape, see [List containers](/graph/api/filestorage-list-containers?tabs=http). + +When listing containers: + +- Use app-only access for service inventory scenarios. +- Use delegated access only when the user context is appropriate. +- Handle paging. +- Map results to your application data. + +> [!NOTE] +> Delegated list containers currently returns `403 Forbidden` if the user doesn't have a OneDrive. This dependency doesn't apply to app-only list calls. + +## Get a container + +Get a container when you need the latest metadata before acting. + +Use this operation to confirm the container exists, read display properties, verify the container type, check state before file operations, and confirm restoration. + +Link implementations to [fileStorageContainer resource type](/graph/api/resources/filestoragecontainer). + +## Update container metadata + +Update metadata when supported properties change. + +Before updating: + +1. Confirm the app has container type `Write` permission. +1. Confirm the delegated user has an appropriate role. +1. Read the current container state. +1. Apply only intended changes. +1. Validate the response. + +## Delete or recycle a container + +Use delete behavior when a container is no longer active. + +Before deletion: + +- Confirm the caller has permission. +- Confirm your app has archived business references. +- Decide whether the container should be recycled first. +- Explain restore options. + +The Visual Studio Code extension includes recycle and recovery capabilities for trial development. + +## Restore a recycled container + +A restore flow should: + +1. Identify the recycled container. +1. Confirm the caller has permission. +1. Restore the container. +1. Refresh application state. +1. Confirm files and metadata are available. +1. Notify the user. + +> [!IMPORTANT] +> For trial container types, containers in the recycle bin still count toward the five-container limit. + +## Permanently delete containers + +Permanently delete only when you're sure the container is no longer needed. + +You must remove all containers of a container type, including deleted containers, before deleting the container type itself. + +Use permanent deletion for trial cleanup, test data removal, retiring a container type, or meeting lifecycle requirements. + +## Validate lifecycle operations + +Create a smoke test: + +1. Create a test container. +1. Retrieve it by ID. +1. List containers and confirm it appears. +1. Update a supported metadata value. +1. Upload a small file. +1. Recycle or delete the container. +1. Restore it if supported. +1. Permanently delete it during cleanup. + +## Troubleshoot lifecycle issues + +| Symptom | Check | +|---|---| +| Create fails | Registration and `Create` permission. | +| Delegated create fails | User consent and role assignment behavior. | +| List fails for delegated user | OneDrive dependency noted in the auth article. | +| Delete fails | `Delete` permission and user Owner role. | +| Trial create fails | Active plus recycled containers may have reached the limit. | +| Container type delete fails | All active and deleted containers must be removed first. | + +## Next steps + +Add file operations in [Upload, download, and manage files](manage-files.md). diff --git a/docs/embedded/build/fluid-framework.md b/docs/embedded/build/fluid-framework.md new file mode 100644 index 0000000000..cc71c42a27 --- /dev/null +++ b/docs/embedded/build/fluid-framework.md @@ -0,0 +1,75 @@ +--- +title: Add real-time collaboration with Fluid Framework +description: Use Fluid Framework with SharePoint Embedded for synchronized collaborative application state. +ms.date: 07/13/2026 +ms.reviewer: jaeccles +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Add real-time collaboration with Fluid Framework + +**Applies to:** Developer + + + +Use Fluid Framework when your SharePoint Embedded app needs real-time shared state, such as collaborative controls, live counters, cursors, annotations, or multi-user form state. Fluid provides client libraries for distributing, synchronizing, and saving shared data. + +## Prepare SharePoint Embedded + +Create or identify a SharePoint Embedded application before you run the Fluid sample. You need admin credentials for a Microsoft 365 tenant, the application client ID, the container type ID, and at least one container created for that container type. + +If you used the SharePoint Embedded Visual Studio Code extension, use the generated sample configuration to find `ContainerTypeId` and `ClientID`. You can also find the client ID in Microsoft Entra ID under **App registrations**. + +To try SharePoint Embedded at no cost, create a trial container type. See [Create and configure a container type](create-container-type.md). + +## Run the item counter sample + +The `item-counter-spe` sample lives in the Fluid Examples repository. + +```console +git clone https://github.com/microsoft/FluidExamples.git +cd FluidExamples\item-counter-spe +``` + +Create an empty `.env` file in the sample folder and add the SharePoint Embedded identifiers. + +```text +SPE_CLIENT_ID=YOUR_CLIENTID +SPE_CONTAINER_TYPE_ID=YOUR_CONTAINERTYPE_ID +``` + +Install packages and start the development server. + +```console +npm install +npm run dev +``` + +After Webpack completes, open `https://localhost:8080`, sign in with tenant credentials, and grant admin consent for the app when prompted. Open the same URL in another browser tab or send it to another user in the same tenant. Changes to the item counter synchronize across connected clients. + +![Item Counter sample app running in the browser, showing a shared counter that synchronizes across connected clients.](../images/itemcount.png) + +## Decide what belongs in Fluid + +Use Fluid for collaborative application state that benefits from low-latency synchronization. Store durable documents and files in SharePoint Embedded containers. Persist final business output to your own durable model or to SharePoint Embedded files when your scenario needs audit, retention, search, or reporting. + +Treat Fluid shared objects as user-visible collaboration state. Don't place secrets, access tokens, SAS URLs, or privileged Graph responses in shared data structures. + +## Handle identity and access + +Your app still needs the SharePoint Embedded client ID and container type ID to acquire the correct tokens and access containers. Test the sample with one tab, two tabs for the same user, and two different users from the tenant. Verify behavior for users who can view the container but shouldn't edit the collaborative state. + +## Move from sample to app design + +Use the item counter sample to prove tenant setup, consent, and client connectivity. In your own app, plan reconnect behavior, token refresh, offline transitions, container switching, and cleanup for collaborative sessions that users abandon. + +## Next steps + +- [Set up SharePoint Embedded as a Foundry knowledge source](sharepoint-embedded-knowledge-source.md) diff --git a/docs/embedded/build/manage-files.md b/docs/embedded/build/manage-files.md new file mode 100644 index 0000000000..ea2d056a06 --- /dev/null +++ b/docs/embedded/build/manage-files.md @@ -0,0 +1,195 @@ +--- +title: Upload, Download, and Manage Files +description: Use Microsoft Graph DriveItem APIs to upload, download, organize, update, delete, and restore SharePoint Embedded files. +ms.date: 07/13/2026 +ms.reviewer: cindylay +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Upload, download, and manage files + +**Applies to:** Developer + + + +Use Microsoft Graph file and DriveItem APIs to manage files inside SharePoint Embedded containers. + +Complete [Create and manage containers](create-manage-containers.md) first so you have a container ID. + +## Understand file storage + +A SharePoint Embedded container is the storage boundary for your application content. + +Each container exposes file content through Microsoft Graph file storage and DriveItem APIs. + +Use your application data model to decide which business object owns each container, which folders your app creates, which users or services can read and write, and which file IDs your app stores. + +For architecture, see [SharePoint Embedded app architecture](../plan/app-tenant-architecture.md). + +## Use Microsoft Graph file storage APIs + +Start with these Microsoft Graph references: + +- [fileStorageContainer resource type](/graph/api/resources/filestoragecontainer) +- [DriveItem resource type](/graph/api/resources/driveitem) +- [Microsoft Graph file storage overview](/graph/api/resources/onedrive) + +> [!IMPORTANT] +> Use documented Microsoft Graph DriveItem and file storage APIs. Don't invent SharePoint Embedded-specific file API names. + +## Prerequisites + +Before managing files, make sure: + +- Your app can acquire Microsoft Graph tokens. +- The app has `FileStorageContainer.Selected` consent. +- The app has container type permissions for intended operations. +- The target container exists. +- For delegated calls, the user is a member of the container. +- Your app stores the container ID and DriveItem IDs it needs. + +## Map container IDs to drives + +The preview source notes that the Graph preview endpoint uses a `driveId`, and for SharePoint Embedded the drive ID is the container ID that starts with `b!`. + +In your app: + +1. Store the container ID returned when the container is created. +1. Use the container ID when calling DriveItem APIs that require a drive identifier. +1. Store item IDs returned by upload or folder creation operations. + +1. Avoid reconstructing IDs from URLs. + +## Upload files + +Use Microsoft Graph upload patterns for DriveItems. + +For small files (up to 250 MB), use the simple upload API documented for DriveItems with a single `PUT` to the item's content. + +For larger files (over 250 MB), use an upload session as documented by Microsoft Graph and send the file in byte-range chunks (for example, 320 KB multiples) until the upload completes. + +In your upload flow: + +1. Validate write access. +1. Choose a destination folder in the container. +1. Create folders first if the path doesn't exist. +1. Upload file bytes with the appropriate Graph method. +1. Store the returned DriveItem ID. +1. Display file name, size, and status. + +> [!TIP] +> Keep business metadata in your application database, and keep file content in SharePoint Embedded. + +## Download files + +Use Microsoft Graph DriveItem download capabilities for file content. + +In your download flow: + +1. Validate read access. +1. Resolve the container ID and DriveItem ID. +1. Request the file content or download URL using DriveItem APIs. +1. Stream the content to the user or service. +1. Handle expiration for short-lived download URLs. +1. Log according to your audit requirements. + +## Create folders + +Use DriveItem folder creation APIs to organize content. + +Create folders for predictable content structure, workflow stages, related uploads, and stable parent items for Office launch URLs. + +When creating folders: + +1. Check whether the folder exists. +1. Create only the missing path segment. +1. Store the folder DriveItem ID if needed. +1. Apply naming rules consistently. + +## Update file content + +Use Microsoft Graph DriveItem update or upload session patterns to replace content. + +Before replacing content: + +- Confirm write permission. +- Read current metadata if concurrency checks are needed. +- Preserve the DriveItem ID where supported. +- Update your app metadata after Graph succeeds. + +Office files stored in SharePoint Embedded have versioning enabled automatically for Word, Excel, and PowerPoint files. + +See [Open Office files from your app](open-office-files.md) for Office behavior. + +## Rename or move items + +Use documented DriveItem update and move operations where supported. + +A safe flow should read the current DriveItem, confirm the destination folder, apply the operation, refresh stored path or display name, and keep the DriveItem ID as the durable reference when possible. + +## Delete files + +Use delete operations when a file should no longer appear in the active content experience. + +Before deleting: + +- Confirm user intent. +- Confirm write or delete permission. +- Decide whether your app needs soft delete. +- Update app state only after Graph returns success. + +## Restore files + +Use Microsoft Graph and SharePoint file restore capabilities documented for DriveItems and the service experience. + +A restore flow should identify the deleted item or version, confirm permission, perform the restore, refresh the item list, and communicate the restored location. + +> [!NOTE] +> [recycleBinItem: restore](/graph/api/filestoragecontainer-restore-recyclebinitem) supports `driveItemId` as an alternate key (October 2025). If you know the ID of the original **driveItem**, you can restore the corresponding **recycleBinItem** directly without first enumerating the recycle bin. +> [!NOTE] +> For exact file operation request and response details, use Microsoft Graph DriveItem documentation. + +## Connect to Office and preview experiences + +After upload, add richer experiences: + +- [Open Office files from your app](open-office-files.md) for Word, Excel, and PowerPoint launch behavior. +- [Preview files in your app](preview-files.md) for browser previews. +- [Search containers and files](../build/search-containers-files.md) for discovery. + +## Validate file operations + +Create a smoke test: + +1. Create a test container. +1. Create a folder. +1. Upload a file. +1. Read returned DriveItem metadata. +1. Download the file. +1. Replace the content. +1. Rename the file. +1. Delete the file. +1. Restore it if supported. +1. Clean up the test container. + +## Troubleshoot file operations + +| Symptom | Check | +|---|---| +| Upload fails | `WriteContent` permission and user Writer role. | +| Download fails | `ReadContent` permission and user Reader role. | +| Folder create fails | Parent folder ID and write permissions. | +| Preview fails | File type support and preview URL generation. | +| Office launch opens wrong mode | Launch URL `action` parameter or Office URI scheme. | +| Access differs by user | Delegated access intersects app permissions with membership. | + +## Next steps + +Enable Office launch experiences in [Open Office files from your app](open-office-files.md). diff --git a/docs/embedded/build/migrate-azure-blob-storage.md b/docs/embedded/build/migrate-azure-blob-storage.md new file mode 100644 index 0000000000..7ac1eeb23c --- /dev/null +++ b/docs/embedded/build/migrate-azure-blob-storage.md @@ -0,0 +1,146 @@ +--- +title: Migrate from Azure Blob Storage +description: Move files from Azure Blob Storage into SharePoint Embedded containers with Microsoft Graph. +ms.date: 07/10/2026 +ms.reviewer: stpuceli +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Migrate from Azure Blob Storage + +**Applies to:** Developer + + + +Use this guide when you move content from Azure Blob Storage to SharePoint Embedded. A C# migration app reads blobs with the Azure Storage SDK and uploads them to a SharePoint Embedded container with Microsoft Graph. + +> [!TIP] +> For migrating from SharePoint or OneDrive sources, SharePoint Embedded also provides dedicated [migration APIs](/graph/api/resources/sharepointmigration-api-overview) that are generally available on the **v1.0** Microsoft Graph endpoint (November 2025) and support migrating **file version history** (February 2026). The manual sample in this article is best when copying from Azure Blob Storage specifically. + +## Prepare authentication + +For Azure Blob Storage, the sample uses a container-level SAS URL with `Read` and `List` permissions. + +```csharp +_containerClient = new BlobContainerClient(new Uri(_containerLevelSASUrl)); +``` + +For SharePoint Embedded, the sample uses delegated Microsoft Graph scopes `User.Read` and `FileStorageContainer.Selected` with `InteractiveBrowserCredential`. + +```csharp +string[] scopes = { "User.Read", "FileStorageContainer.Selected" }; +InteractiveBrowserCredentialOptions options = new InteractiveBrowserCredentialOptions() +{ + ClientId = clientId, + RedirectUri = new Uri("http://localhost"), +}; +InteractiveBrowserCredential credential = new InteractiveBrowserCredential(options); +_graphClient = new GraphServiceClient(credential, scopes, null); +``` + +Because the sample uses `InteractiveBrowserCredential` with a `http://localhost` redirect URI, the Microsoft Entra ID app registration must include a **Mobile and desktop applications** platform that lists `http://localhost` as a redirect URI. Add this platform in the [Microsoft Entra admin center](https://entra.microsoft.com) under the app registration's **Authentication** page before you run the sample. + +![Screenshot of the Authentication page for a Microsoft Entra ID app registration. A Mobile and desktop applications platform is configured with http://localhost listed as a redirect URI.](../images/app-registration-console-platform.png) + +*Figure 1: Add a Mobile and desktop applications platform with the `http://localhost` redirect URI so the interactive sign-in flow can return the token to the migration app.* + +The consuming tenant must have the application and container type registered. The sample also requires a SharePoint Embedded container ID for the destination. + +## Enumerate source blobs + +List blob names from the Azure Blob Storage container before queuing migration work. + +```csharp +var blobs = new List(); +await foreach (var blobItem in _containerClient.GetBlobsAsync()) +{ + blobs.Add(blobItem.Name); +} +return blobs; +``` + +Azure Blob Storage uses a flat namespace. If blob names include `/`, parse those segments into SharePoint Embedded folders or decide to upload all files to the container root. + +## Create destination folders + +The sample creates a top-level folder named after the Azure Blob Storage container, then creates nested folders as it traverses each blob name. Check for an existing item before creating a folder. + +```csharp +var item = await _graphClient.Drives[_containerId].Items[parentFolderId].ItemWithPath(itemPath).GetAsync(); +``` + +Create a folder under the destination parent with conflict behavior set to `fail`. + +```csharp +var folder = new DriveItem +{ + Name = folderName, + Folder = new Folder(), + AdditionalData = new Dictionary() + { + { "@microsoft.graph.conflictBehavior", "fail" } + } +}; +var createdFolder = await _graphClient.Drives[_containerId].Items[parentFolderId].Children.PostAsync(folder); +``` + +## Upload files with Graph sessions + +Download each blob to a stream, reset the stream position, create an upload session, and upload with `LargeFileUploadTask`. + +```csharp +BlobClient blobClient = _containerClient.GetBlobClient(blobName); +MemoryStream memoryStream = new MemoryStream(); +await blobClient.DownloadToAsync(memoryStream); +memoryStream.Position = 0; +``` + +```csharp +int maxChunkSize = 320 * 1024; +var uploadSessionRequestBody = new CreateUploadSessionPostRequestBody() +{ + AdditionalData = new Dictionary + { + { "@microsoft.graph.conflictBehavior", "fail" } + } +}; + +var uploadSession = await _graphClient.Drives[_containerId] + .Items[parentFolderId] + .ItemWithPath(fileName) + .CreateUploadSession + .PostAsync(uploadSessionRequestBody); + +var fileUploadTask = new LargeFileUploadTask(uploadSession, memoryStream, maxChunkSize, _graphClient.RequestAdapter); +IProgress progress = new Progress(prog => Console.WriteLine($"Uploaded {fileName} {prog} bytes")); +var uploadResult = await fileUploadTask.UploadAsync(progress); +``` + +Use `fail` when duplicate files shouldn't be overwritten. Change the conflict behavior only after you define replacement, rename, and audit rules. + +## Run the sample + +The sample uses Microsoft Graph SDK 5.56.0, Azure.Identity 1.12.0, Azure.Storage.Blobs 12.21.0, CommandLineParser 2.9.1, and Newtonsoft.Json 13.0.3. + +```console +dotnet run Program.cs -- --sasurl "" --tenantid "" --clientid "" --containerid "" [ --blobfile "" --outputfile "" ] +``` + +Use the optional blob list file for controlled batches and the optional output file to capture failed blobs for reruns. + +## Validate migrated content + +Compare source blob counts with destination drive item counts. Check folder paths, file sizes, upload failures, duplicate handling, and required metadata. Open representative files through your SharePoint Embedded app, then validate search and metadata queries after indexing has had time to complete. + +Don't delete source blobs until business owners approve the migration result and retention requirements are satisfied. + +## Next steps + +- [Prepare your app for customer installation](../publish/prepare-customer-installation.md) diff --git a/docs/embedded/build/open-office-files.md b/docs/embedded/build/open-office-files.md new file mode 100644 index 0000000000..5b4c5072a5 --- /dev/null +++ b/docs/embedded/build/open-office-files.md @@ -0,0 +1,248 @@ +--- +title: Open Office Files From Your App +description: Launch Word, Excel, and PowerPoint files from SharePoint Embedded in Office web or desktop clients. +ms.date: 07/13/2026 +ms.reviewer: cindylay +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Open Office files from your app + +**Applies to:** Developer + + + +Open Office files from your SharePoint Embedded app by using Microsoft Graph DriveItem metadata and Office launch patterns supported by Microsoft 365. + +Complete [Upload, download, and manage files](manage-files.md) first so your app has files to launch. + +## Understand Office experiences + +SharePoint Embedded Office file experiences work similarly to Microsoft 365 file experiences. +Supported experiences include: + +- Opening Office documents in Office for the web. +- Opening Office documents in Office desktop clients. +- Viewing and editing files. +- AutoSave for Word, Excel, and PowerPoint files. +- Version history for Office documents. +- Coauthoring. +- Sharing and shareable links. +- Comments and mentions, with documented limitations. +- Breadcrumbs in Office clients that associate a file with your app. + +> [!NOTE] +> Documents stored in an archived container can't be viewed or accessed. Your app must handle the archived state by showing an appropriate error and guiding users on next steps, such as reactivating the container. + +## Prerequisites + +Before launching Office files, make sure: + +- The file is stored in a SharePoint Embedded container. +- The app can read DriveItem metadata for the file. +- The user has permission to view or edit the file. +- The file type is supported by the target Office client. +- Your app handles browser redirects or new-window behavior. + +## Get the DriveItem web URL + +When your app retrieves a DriveItem from Microsoft Graph, the response can include `webUrl`. + +For supported Office file types, `webUrl` points to a URL that opens the document in Office for the web. + +A supported Office web URL has this shape: + +```http +https://host/:w:r/contentstorage/sitecollection/_layouts/15/doc2.aspx?sourcedoc=guid&file=filename.docx&action=default&mobileredirect=true +``` + +For request details, see [Get a DriveItem resource](/graph/api/driveitem-get). + +## Launch Office for the web + +Use the DriveItem `webUrl` when your app should open Office in the browser. + +1. Read the DriveItem for the selected file. +1. Confirm the response includes `webUrl`. +1. Open the URL in a browser tab, window, or app-controlled navigation surface. +1. Preserve app context so users can return after editing. +1. Handle access denied errors by checking file permissions and container membership. + +> [!NOTE] +> Office files use AutoSave when users edit Word, Excel, and PowerPoint files stored in SharePoint Embedded. + +## Configure the default launch experience + +By default, the Office URL includes `action=default`. + +To force a mode, update the query parameter with this pattern: + +```csharp +System.UriBuilder builder = new System.UriBuilder(webUrl); +System.Collections.Specialized.NameValueCollection queryDictionary = System.Web.HttpUtility.ParseQueryString(builder.Query); +queryDictionary["action"] = "view"; +builder.Query = queryDictionary.ToString(); +string modifiedWebUrl = builder.ToString(); +``` + +Use: + +- `action=view` for read-only viewing. +- `action=edit` for editing when the user has edit permission. +- `action=default` when Office should choose the default behavior. + +For supported `action` values, see [Web Application Open Platform Interface actions](/microsoft-365/cloud-storage-partner-program/online/discovery#wopi-actions). + +## Open files in Office desktop clients + +Use Office URI schemes when your app should open desktop clients directly. + +The format is: + +```text +:|| +``` + +Common values include: + +| Segment | Value | +|---|---| +| Scheme name | `ms-word`, `ms-excel`, or `ms-powerpoint` | +| Open File View command | `ofv` | +| Open File Edit command | `ofe` | +| URL descriptor | `u` | + +Examples: + +```text +ms-word:ofv|u|https://contoso.com/document.docx +ms-powerpoint:ofe|u|https://contoso.com/presentation.pptx +``` + +> [!NOTE] +> The URI must be opened in a blank window or new tab. + +## Build a desktop client URL + +Because `webUrl` points to Office Online for Office documents, build the desktop URI in two steps: + +1. Get the `webUrl` of the parent folder. +1. Append the file name. + +Example pattern: + +```text +ms-word:ofe|u|{folder.WebUrl}/{item.Name} +``` + +Resulting shape: + +```text +ms-word:ofe|u|https://contoso.sharepoint.com/contentstorage/CSP_1234765465/Document%20Library/MyDocument.docx +``` + +For scheme details, see [Office URI Schemes](/office/client-developer/office-uri-schemes). + +## Configure redirect behavior + +Use redirect settings to route users back to your app when Microsoft 365 can't open a file in a supported viewer. + +`ApplicationRedirectUrl` configures the application redirect URL on the container type. Use it for the app route that handles file-return scenarios for your workload. + +The `urlTemplate` setting controls where Microsoft 365 sends users for files without a supported viewer. Supported Office web viewer files, such as Word, Excel, and PowerPoint, open in the Office web viewer. PDF files open in the embedded viewer. Other file types redirect through `urlTemplate` when it's configured. If `urlTemplate` isn't configured, Microsoft 365 sends users to a Microsoft help page. + +Set `settings.urlTemplate` with the Microsoft Graph `PATCH /storage/fileStorage/containerTypes/{containerTypeId}` API. Use a valid absolute `https://` URL that doesn't resolve to a loopback address. + +```http +PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId} +Content-Type: application/json + +{ + "settings": { + "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}" + } +} +``` + +Microsoft 365 resolves supported tokens, URL-encodes their values, and substitutes them into the template. Common tokens include `{tenant-id}`, `{drive-id}`, `{folder-id}`, `{item-id}`, `{site-domain}`, `{list-id}`, and `{site-url}`. + +When your app receives a `urlTemplate` redirect, authenticate the user, parse the token values, and use Microsoft Graph to retrieve the file. If you need the canonical file URL, use the DriveItem `webDavUrl` property instead of `webUrl`. + +When you design redirects: + +- Use a stable production URL for your app. +- Use development URLs only for local or trial work. +- Keep Microsoft Entra ID redirect URIs aligned with app routes. +- Validate that users return to the right in-app context after Office actions. +- Avoid URL rewriting that removes required Office query parameters. +- Verify `urlTemplate` after updates because invalid values are stored as `null`. + +## Support sharing and coauthoring + +Office experiences include collaboration features. + +Users can share documents, create shareable links, coauthor in real time, see presence indicators, use comments, and use mentions where supported. + +When a user creates a sharing link, they choose who it grants access to: + +| Sharing scope | Who can use the link | +|---|---| +| **Anyone** | Anyone who receives the link, including people outside your organization, whether you send it directly or it's forwarded. | +| **People in your organization** | Anyone in your organization who has the link, whether sent directly or forwarded. | +| **Specific people** | Only the people you specify. If the invitation is forwarded, only people who already have access can use the link. | +| **People with existing access** | People who already have access to the file or folder. This scope doesn't change existing permissions. | + +> [!NOTE] +> Mentions require target users to have a Microsoft 365 license assigned. Mentions are restricted to people inside the consuming tenant's organization and exclude guests and users from other tenants in multitenant settings. + +## Use version history + +Versioning is automatically enabled for Word, Excel, and PowerPoint files stored in SharePoint Embedded apps. + +Users can see changes, compare versions, restore previous versions, recover from mistakes, and review changes from coauthoring sessions. + +## Use breadcrumb properties + +Office clients can display breadcrumb-style elements that associate Office files with your application. + +Breadcrumb patterns are constructed from container properties configured for your app. + +Use Current Channel to get breadcrumb patterns and future Office app enhancements. + +For Office update channel information, see [Overview of update channels for Microsoft 365 Apps](/deployoffice/updates/overview-update-channels). + +## Validate Office launch + +Test each launch path: + +1. Upload a Word document to a container. +1. Read the DriveItem and capture `webUrl`. +1. Open `webUrl` with `action=default`. +1. Modify the query string to `action=view`. +1. Modify the query string to `action=edit`. +1. Build an Office URI scheme for desktop launch. +1. Confirm permissions block edit when appropriate. +1. Confirm AutoSave and version history behavior. +1. Confirm the user can return to your app. + +## Troubleshoot Office launch + +| Symptom | Check | +|---|---| +| URL opens in view instead of edit | `action` parameter and user edit permission. | +| Desktop client doesn't open | Office URI scheme, browser policy, and new-tab behavior. | +| User can't coauthor | File type, permissions, and Office client support. | +| Mentions don't find a user | Microsoft 365 license and tenant membership limitations. | +| Breadcrumb doesn't look right | Container properties and Office update channel. | +| Redirect returns to wrong route | `ApplicationRedirectUrl` and app route handling. | + +## Next steps + +Add embedded previews in [Preview files in your app](preview-files.md). diff --git a/docs/embedded/build/preview-files.md b/docs/embedded/build/preview-files.md new file mode 100644 index 0000000000..989674ddc4 --- /dev/null +++ b/docs/embedded/build/preview-files.md @@ -0,0 +1,257 @@ +--- +title: Preview Files in Your App +description: Create Microsoft Graph preview links and embed supported SharePoint Embedded file previews in your app. +ms.date: 07/13/2026 +ms.reviewer: cindylay +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Preview files in your app + +**Applies to:** Developer + + + +Add file preview UX so users can inspect SharePoint Embedded content without downloading files or opening a full Office editing experience. + +Complete [Open Office files from your app](open-office-files.md) when you need Office editing. Use this article for lightweight previews. + +## Understand preview flow + +The preview flow has two steps: + +1. Call the Microsoft Graph DriveItem preview endpoint. +1. Use the returned URL in an iframe or new browser page. + +The Graph endpoint is: + +```http +POST https://graph.microsoft.com/{version}/drives/{driveId}/items/{itemId}/preview +``` + +Where: + +- `{version}` is the Microsoft Graph version, such as `v1.0`. +- `{driveId}` is the container ID that starts with `b!`. +- `{itemId}` is the DriveItem ID. + +For the canonical API reference, see [Preview a DriveItem](/graph/api/driveitem-preview). + +## Know supported file types + +Microsoft 365 supports previews for many file types, including common document, image, video, and PDF formats. + +Examples include: + +- PDF files. +- JPG and other image files. +- MP4 and other supported media files. +- Office files supported by Microsoft 365 preview experiences. + +For the current list, see [File types supported for previewing files in OneDrive, SharePoint, and Teams](https://support.microsoft.com/office/file-types-supported-for-previewing-files-in-onedrive-sharepoint-and-teams-e054cd0f-8ef2-4ccb-937e-26e37419c5e4). + +> [!NOTE] +> File type support can vary by service capability, tenant policy, and client experience. Always handle preview failures gracefully. + +## Native PDF viewing + +The SharePoint Embedded native PDF viewing experience supports **searching within the file**, **viewing comments and sticky notes** embedded on the file, and **printing** (added March 2026). These capabilities are available through the [driveItem: preview](/graph/api/driveitem-preview) API in **both the beta and v1.0** Microsoft Graph endpoints. + +### Enhance the PDF previewer with query parameters + +Enhance the SharePoint Embedded PDF previewer by appending query parameters to the driveItem's `webUrl` property. To get `webUrl`, call the [driveItem GET API](/graph/api/driveitem-get), for example `GET /drives/{drive-id}/items/{item-id}?$select=webUrl`. + +Pass parameters as a JSON-encoded `embed` query string. You can include one or more parameters in the same object. + +```text +?&embed={"":,"":} +``` + +| Parameter | Effect | +|---|---| +| `mpp` | Enables the print icon and Ctrl+P printing. For example, `?&embed={"mpp":true}`. | +| `mpsn` | Shows sticky note content when the PDF contains sticky notes. For example, `?&embed={"mpsn":true}`. | + +## Prerequisites + +Before creating previews, make sure: + +- The file is stored in a SharePoint Embedded container. +- Your app knows the container ID and DriveItem ID. +- Your app can acquire a Microsoft Graph token. +- The caller has permission to read the file. +- The file type is supported for preview. +- Your UI can host an iframe or open a new page. + +## Create a preview link + +Call the preview endpoint from your service layer. + +Use this C# SDK pattern: + +```csharp +ItemPreviewInfo preview = await graphServiceClient.Drives[driveId].Items[itemId] + .Preview() + .Request() + .PostAsync(); +``` + +The response includes preview URL information: + +```json +{ + "getUrl": "https://www.onedrive.com/embed?foo=bar&bar=baz", + "postParameters": "param1=value¶m2=another%20value", + "postUrl": "https://www.onedrive.com/embed_by_post" +} +``` + +Use `getUrl` when available. + +> [!CAUTION] +> `getUrl` currently contains an encrypted token that can only be used with your application. This behavior may change. + +## Remove the preview banner + +Add `nb=true` to the obtained URL to remove the banner at the top. + +Example: + +```http +https://contoso.sharepoint.com/restOfUrl/embed.aspx?param1=value&nb=true +``` + +Use this only when it fits your user experience and compliance requirements. + +## Embed the preview in an iframe + +Create an app page that hosts the preview URL. + +Example shape: + +```html + + + +

Preview

+

Preview of {file name}:

+ + + +``` + +In production, also provide: + +- A descriptive iframe title. +- Responsive sizing. +- Loading states. +- Error states. + +- A fallback download or open action. + +## Load previews dynamically + +Don't call Microsoft Graph directly from a browser script if that creates CORS issues or exposes tokens. + +Use a server-side endpoint that: + +1. Authenticates the user. +1. Validates access to the requested file. +1. Acquires a Graph token. +1. Calls the DriveItem preview endpoint. +1. Returns the preview URL to the client. + +Use this server-side pattern: + +```csharp +[HttpGet] +[AuthorizeForScopes(Scopes = new string[] { "Files.Read.All" })] +public async Task> GetPreviewUrl(string driveId, string itemId) +{ + return url + "&nb=true"; +} +``` + +Then the client can request the URL and set the iframe source. + +```javascript +async function preview(driveId, itemId) { + const url = `/GetPreviewUrl?driveId=${driveId}&itemId=${itemId}`; + const response = await fetch(url, { + credentials: 'include', + }).then(response => response.text()); + document.getElementById('preview').src = response + "&nb=true"; +} +``` + +## Design preview UX + +A good preview UX should: + +- Show the file name. +- Show a loading indicator. +- Reserve enough space for the iframe. +- Provide an open-in-Office action for Office files. +- Provide a download action when preview isn't available. +- Preserve keyboard accessibility. +- Avoid trapping focus inside the preview frame. +- Explain errors in user-friendly language. + +## Handle preview errors + +| Failure | Handling | +|---|---| +| Unsupported file type | Show a download or open action instead. | +| Missing permission | Ask the user to request access or sign in again. | +| Expired URL | Request a fresh preview URL. | +| CORS error | Move the Graph call to your server-side endpoint. | +| File deleted | Refresh the file list and remove stale selections. | +| Service error | Retry once, then show a stable fallback. | + +> [!IMPORTANT] +> Don't cache preview URLs as durable identifiers. Store the container ID and DriveItem ID, then create a fresh preview URL when needed. + +## Secure preview requests + +Treat preview as a read operation on protected content. + +Your service should: + +1. Validate the signed-in user or service context. +1. Confirm the caller can read the container content. +1. Confirm the requested item belongs to the expected container. +1. Avoid exposing Graph tokens to the browser. +1. Avoid logging preview URLs that include sensitive tokens. +1. Expire app-side preview sessions when the user signs out. + +## Validate the preview experience + +Test with multiple file types and users: + +1. Upload a PDF file. +1. Upload an image file. +1. Upload an Office file. +1. Create a preview URL for each file. +1. Render each preview in an iframe. +1. Test a user with read access. +1. Test a user without access. +1. Delete a file and confirm the error is handled. +1. Refresh an expired preview URL. +1. Confirm the fallback action works. + +## Connect to the next build task + +After preview is working, add discovery experiences so users can find content across containers and files. + +Continue to [Search containers and files](../build/search-containers-files.md). + +## Next steps + +- [Search containers and files](search-containers-files.md) diff --git a/docs/embedded/build/quickstart-vscode.md b/docs/embedded/build/quickstart-vscode.md new file mode 100644 index 0000000000..759b0ea7ee --- /dev/null +++ b/docs/embedded/build/quickstart-vscode.md @@ -0,0 +1,195 @@ +--- +title: "Quickstart: Build your first app with VS Code" +description: Create a standard SharePoint Embedded container type in Visual Studio Code and run the sample application locally. +ms.date: 07/13/2026 +ms.reviewer: mawin +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Quickstart: build your first app with VS Code + +**Applies to:** Developer + + + +Use the [SharePoint Embedded Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=SharepointEmbedded.ms-sharepoint-embedded-vscode-extension) to create a standard container type for your first app. The extension also configures the owning app, attaches Azure billing, and registers the container type. Then you create a container and run a local sample app. + +This article starts the build journey. For more billing guidance, see [Create and configure a container type](create-container-type.md). + +## Prerequisites + +Before you start, make sure you have: + +- [Visual Studio Code](https://code.visualstudio.com/) installed. +- Administrative access to a Microsoft 365 tenant. +- A tenant with SharePoint available. +- An Azure subscription and resource group that your account can access. +- Owner or Contributor permissions on the Azure subscription. +- Node.js and npm installed for the sample app. +- Permission to grant admin consent in Microsoft Entra ID. + +> [!IMPORTANT] + +> You need administrative access to a Microsoft 365 tenant. If you don't have a tenant, use the Microsoft 365 Developer Program, Microsoft Customer Digital Experience, or a Microsoft 365 E3 trial. + +## Install the extension + +1. Open Visual Studio Code. +1. Open **Extensions** from the activity bar. +1. Search for **SharePoint Embedded**. +1. Select **Install**. +1. If the extension is already installed, update it. +1. Select the SharePoint Embedded icon in the activity bar. + +## Sign in + +1. In the SharePoint Embedded view, select the sign-in action. +1. Use a Microsoft 365 administrator account. +1. Complete authentication in the browser. +1. Review the requested permissions. +1. Select **Accept** to grant admin consent. +1. Return to Visual Studio Code when redirected. + +> [!IMPORTANT] +> Review the consent prompt carefully. The extension needs tenant permissions to configure development resources. + +![Screenshot of the SharePoint Embedded sign-in view in Visual Studio Code.](../images/vsx-images/n2vsx-signin.png) + +After you sign in, the extension shows the SharePoint Embedded home view. + +![Screenshot of the SharePoint Embedded home view in Visual Studio Code after sign-in. The view lists actions to create a container type and load a sample app.](../images/vsx-images/n4vsx-home-screen.png) + +## Create a standard container type + +A container type defines the relationship, access privileges, billing accountability, and selected behaviors for a set of SharePoint Embedded containers. + +1. Select **Create Container Type**. +1. For the billing method, select **standard**. +1. Enter a container type name. +1. Follow the prompts until creation completes. + +![Screenshot of the Visual Studio Code input box prompting for a container type name during the Create Container Type flow.](../images/vsx-images/n5a-name-ct.png) + +Use a standard container type when the organization that owns the app pays for SharePoint Embedded usage. +For evaluation, choose **trial**. For customer-tenant billing, choose the pass-through option, which uses the `directToCustomer` billing classification. + +## Create or select the owning app + +Every container type has one owning Microsoft Entra ID application. + +1. Create a new Microsoft Entra ID application or select an existing application ID. +1. If you create a new application, enter its name. +1. Let the extension configure development settings. + +![Screenshot of the Visual Studio Code input box prompting for a Microsoft Entra ID application name while creating the owning app for the container type.](../images/vsx-images/n6aname-app.png) + +> [!CAUTION] +> If you select an existing application, the extension updates that app's configuration. Don't use a production app for this quickstart. +For the model, see [SharePoint Embedded app architecture](../plan/app-tenant-architecture.md). + +## Configure standard billing + +Standard container types require Azure billing. The extension attaches billing by using an Azure subscription and resource group that your account can access. + +1. Select an Azure subscription. +1. Select a resource group. +1. Wait for the extension to register the **Microsoft.Syntex** resource provider and attach billing. + +If you skip billing setup or don't have the required Azure permissions, the tree shows **Billing not set up**. To finish setup later, right-click the container type. Then select **Attach billing**. + +## Register the container type locally + +You must register the container type in the consuming tenant before your app can create containers or access content. + +1. After creation, follow the prompt to register the container type in the local tenant. +1. If the prompt isn't visible, right-click the container type and select **Register**. +1. Review the permissions. +1. Grant admin consent in the browser. +1. Return to Visual Studio Code. +Registration configures the permissions the owning app can use against containers of the container type. + +![Screenshot of the SharePoint Embedded extension prompting to register the container type on the local tenant, with the registration action highlighted.](../images/vsx-images/n7aregister-ct.png) + +## Create your first container + +1. In the SharePoint Embedded tree, expand your container type. +1. Right-click **Containers**. +1. Select **Create container**. +1. Enter a container name. +1. Confirm the container appears in the tree. + +A container is the basic storage unit and security boundary in SharePoint Embedded. + +![Screenshot of the SharePoint Embedded tree in Visual Studio Code. A container type is expanded, the Containers node is right-clicked, and the Create container command is selected.](../images/vsx-images/n10acreate-container.png) + +![Screenshot of the Visual Studio Code input box prompting for a container name.](../images/vsx-images/n11aname-first-cont.png) + +## Load a sample app + +1. In the SharePoint Embedded view, select **Load Sample App**. +1. Choose a SharePoint Embedded sample. + +![Screenshot of the SharePoint Embedded extension home view with the Load Sample App action selected to scaffold a sample application.](../images/vsx-images/n15vsxsa-c.png) + +1. Review the warning about local plain text secrets. +1. If prompted to create a client secret, select **OK** for local development. + +1. Let the extension populate the runtime configuration file. + +> [!IMPORTANT] +> The sample configuration is for development only. It stores authentication secrets in plain text on your local machine. + +## Run the sample app + +Open a terminal and run the sample app from the generated sample directory. + +```console +cd [your-path]\SharePoint-Embedded-Samples\Custom Apps\boilerplate-typescript-react +npm run start +``` + +The sample starts: + +- A React client application. +- An Azure Functions application server. + +Wait for both console outputs to appear. + +Then: + +1. Open `http://localhost:8080`. +1. Sign in with the same Microsoft 365 administrator account. +1. Select **Containers** on the home page. +1. Create containers and upload files from the sample UI. + +> [!NOTE] +> Initial startup can take several minutes while dependencies install and both applications build. + +## Troubleshoot startup + +| Symptom | Check | +|---|---| +| Port conflict | The app tries the next available port when port 8080 is in use. | +| Dependencies fail | Run `npm install`, then run `npm run start` again. | +| Authentication error | Confirm the Microsoft Entra ID app has the expected redirect URIs. | +| Access denied | Confirm registration and admin consent succeeded. | +| Billing not set up | Confirm you have Owner or Contributor permissions on the selected Azure subscription, then use **Attach billing**. | + +## Clean up + +When you're finished testing: + +1. Remove test containers that you no longer need. +1. Review Azure billing resources that you created for this quickstart. +1. Remove local sample secrets that are no longer needed. + +## Next steps + +Learn more about container type options in [Create and configure a container type](create-container-type.md). diff --git a/docs/embedded/build/register-application-permissions.md b/docs/embedded/build/register-application-permissions.md new file mode 100644 index 0000000000..49730e7442 --- /dev/null +++ b/docs/embedded/build/register-application-permissions.md @@ -0,0 +1,201 @@ +--- +title: Register Application Permissions +description: Register SharePoint Embedded container type application permissions in a consuming tenant. +ms.date: 07/13/2026 +ms.reviewer: stpuceli +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Register application permissions + +**Applies to:** Developer + + + +Register container type application permissions before your SharePoint Embedded app creates containers or accesses content in a consuming tenant. + +Complete [Create and configure a container type](create-container-type.md) first so you have a container type ID and owning application. + +## Why registration is required + +A SharePoint Embedded application can't interact with containers in a consuming tenant until the container type is registered in that tenant. + +Registration controls: + +- Which application IDs can access the container type. +- Which delegated permissions each application has. +- Which app-only permissions each application has. +- Whether guest applications can interact with the owning application's containers. + +If registration is missing or incomplete, later calls can fail with access denied errors. + +## Understand who can register + +Only the owning application of the container type can invoke the registration API in the consuming tenant. + +The owning application must have: + +- A service principal installed on the consuming tenant. +- Admin consent to perform registration in the consuming tenant. +- The `FileStorageContainerTypeReg.Selected` Microsoft Graph permission (user-delegated or app-only). +- A valid token for the Microsoft Graph resource. + +> [!NOTE] +> The container type registration API is available in Microsoft Graph v1.0. +When the owning application calls the registration API on behalf of a user (delegated), that user must be assigned the [SharePoint Embedded Administrator](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) or [Global Administrator](/entra/identity/role-based-access-control/permissions-reference#global-administrator) role. When it calls without a user context (app-only), it uses the client credentials grant flow. + +## Grant admin consent + +Ask a consuming tenant administrator to grant admin consent to the owning application. + +Use the Microsoft identity platform admin consent endpoint: + +```http +https://login.microsoftonline.com/{consuming-tenant-id}/v2.0/adminconsent?client_id={owning-app-clientid}&scope=https://graph.microsoft.com/.default&redirect_uri={spe-app-redirect-uri} +``` + +Configure success and error handling for your onboarding flow. + +For national cloud endpoints, see [Microsoft identity platform endpoints on national clouds](/entra/identity-platform/authentication-national-cloud#microsoft-entra-authentication-endpoints). + +## Acquire a token for registration + +Use either delegated or app-only authentication for registration. + +Registration requires: + +- The `FileStorageContainerTypeReg.Selected` Microsoft Graph permission. +- For app-only calls, the [client credentials grant flow](/entra/identity-platform/v2-oauth2-client-creds-grant-flow). +- For delegated calls, a signed-in user with the SharePoint Embedded Administrator or Global Administrator role. + +## Register container type permissions + +Call the registration endpoint in the consuming tenant. + +```http +PUT https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypeRegistrations/{containerTypeId} +``` + +`{containerTypeId}` is the container type ID created in the owning tenant. + +In the request body, provide the application permission grants for the container type. + +## Grant permissions to the owning app + +A common first registration grants the owning app full permissions for delegated and app-only calls. + +```json +{ + "applicationPermissionGrants": [ + { + "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", + "delegatedPermissions": ["full"], + "applicationPermissions": ["full"] + } + ] +} +``` + +Replace the sample app ID with your owning application ID. + +> [!CAUTION] +> Use least privilege for production. Grant `full` only when the application needs full container type access. + +## Grant permissions to a guest app + +The owning app can also register permissions for another application. + +Use this pattern when a guest app needs a defined workload, such as backup or processing. + +```json +{ + "applicationPermissionGrants": [ + { + "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", + "delegatedPermissions": ["full"], + "applicationPermissions": ["full"] + }, + { + "appId": "89ea5c94-7736-4e25-95ad-3fa95f62b6", + "delegatedPermissions": ["read", "write"], + "applicationPermissions": ["none"] + } + ] +} +``` + +Replace both app IDs with your applications. + +## Permission values + +| Permission | Use | +|---|---| +| `None` | Grant no permissions. | +| `ReadContent` | Read content in containers of this type. | +| `WriteContent` | Write content in containers of this type. | +| `Create` | Create containers of this type. | +| `Delete` | Delete containers of this type. | +| `Read` | Read container metadata. | +| `Write` | Update container metadata. | +| `EnumeratePermissions` | Enumerate container members and roles. | +| `AddPermissions` | Add container members. | +| `UpdatePermissions` | Update existing memberships. | +| `DeletePermissions` | Delete other members. | +| `DeleteOwnPermission` | Remove the caller's own membership. | +| `ManagePermissions` | Manage container role assignments. | +| `ManageContent` | Manage the content of containers of this type. | +| `Full` | Grant all permissions. | + +> [!NOTE] + +> `WriteContent` can't be granted without `ReadContent`. + +## Validate registration + +A successful registration returns `201 Created` and the configured permissions in the response body. + +After registration succeeds: + +1. Confirm the response includes expected app IDs. +1. Confirm delegated and app-only arrays match your intended grants. +1. Acquire a Microsoft Graph token with SharePoint Embedded permissions. +1. Try a low-risk operation that matches the registered permission. +1. Continue to [Configure authentication and authorization](configure-authentication-authorization.md). + +## Troubleshoot consent issues + +| Symptom | Likely cause | Action | +|---|---|---| +| `401 Unauthorized` | Missing or invalid token | Request a valid app-only token. | +| `403 Forbidden` | App lacks permission or isn't owning app | Confirm `FileStorageContainerTypeReg.Selected`, consent, and app ID. | +| `404 Not Found` | Container type doesn't exist | Verify ID and tenant. | +| Access denied on Graph calls | Registration missing or insufficient | Re-register with needed permissions. | +| Admin can't find hidden permission | Portal doesn't expose it | Use an admin consent URL. | + +## Re-register safely + +There's no restriction on how many times the registration API can be invoked. + +The last successful registration call determines the settings used in the consuming tenant. + +Use a safe update process: + +1. Build a complete registration payload. +1. Include all apps that should retain access. +1. Submit the registration call. +1. Validate the response. +1. Run smoke tests for each app role. + +> [!IMPORTANT] +> Don't send a partial payload unless you intend the resulting registration to contain only that set of applications and permissions. + +## Next steps + +Configure tokens and authorization flows in [Configure authentication and authorization](configure-authentication-authorization.md). diff --git a/docs/embedded/build/respond-to-changes-webhooks.md b/docs/embedded/build/respond-to-changes-webhooks.md new file mode 100644 index 0000000000..4ba02f20ce --- /dev/null +++ b/docs/embedded/build/respond-to-changes-webhooks.md @@ -0,0 +1,118 @@ +--- +title: Respond to file and container changes with webhooks +description: Subscribe to SharePoint Embedded drive changes and handle Microsoft Graph webhook notifications. +ms.date: 07/10/2026 +ms.reviewer: jaeccles +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Respond to file and container changes with webhooks + +**Applies to:** Developer + + + +Use Microsoft Graph webhooks when your app must react to file changes in a SharePoint Embedded container. A subscription tells Microsoft Graph to call your HTTPS endpoint when the subscribed resource changes. + +![Diagram of the SharePoint Embedded webhook flow: the app creates a Microsoft Graph subscription for a container drive, and Microsoft Graph sends change notifications to the app's HTTPS endpoint.](../images/Using-Webhooks.png) + +## Create a notification endpoint + +Expose an HTTPS endpoint that accepts `POST` requests. During local development, use ngrok to tunnel requests to a local server. + +```console +ngrok http 3001 +``` + +![ngrok terminal output showing the public HTTPS forwarding URL that tunnels to the local server.](../images/ngrok-registration.png) + +When Microsoft Graph creates a subscription, it validates the endpoint by sending a `validationToken` query parameter. Return that token as plain text with HTTP 200. + +```typescript +export const onReceiptAdded = async (req: Request, res: Response) => { + const validationToken = req.query['validationToken']; + if (validationToken) { + res.send(200, validationToken, { "Content-Type": "text/plain" }); + return; + } + + const driveId = req.query['driveId']; + if (!driveId) { + res.send(200, "Notification received without driveId, ignoring", { "Content-Type": "text/plain" }); + return; + } + + console.log(`Received driveId: ${driveId}`); + res.send(200, ""); +} +``` + +Register the route in your API server and enable request body and query parsing before the route handles notifications. + +```typescript +server.use(restify.plugins.bodyParser(), restify.plugins.queryParser()); +server.post('/api/onReceiptAdded', async (req, res, next) => { + try { + const response = await onReceiptAdded(req, res); + res.send(200, response); + } catch (error: any) { + res.send(500, { message: `Error in API server: ${error.message}` }); + } + next(); +}); +``` + +## Subscribe to a container drive + +Create the subscription with Microsoft Graph. In this pattern, the SharePoint Embedded container ID is the drive ID. + +```http +POST https://graph.microsoft.com/v1.0/subscriptions +Content-Type: application/json +``` + +```json +{ + "changeType": "updated", + "notificationUrl": "https://contoso.example/api/onReceiptAdded?driveId={container-id}", + "resource": "drives/{container-id}/root", + "expirationDateTime": "2026-06-25T03:58:34.088Z", + "clientState": "" +} +``` + +Subscribe to changes under `drives/{container-id}/root` and append `driveId={container-id}` to the notification URL so the handler can identify the container. + +## Calculate expiration + +Drive item subscriptions have a maximum lifetime of 4,230 minutes. Use a pre-request script or backend scheduler to set the expiration time before creating the subscription. + +```javascript +var now = new Date(); +var duration = 1000 * 60 * 4230; +var expiry = new Date(now.getTime() + duration); +pm.environment.set("ContainerSubscriptionExpiry", expiry.toISOString()); +``` + +Store the subscription ID, resource, container ID, and expiration time. Renew each subscription before it expires. + +## Process notifications safely + +Return quickly from the webhook request. Queue background work, fetch the current file or container state with Microsoft Graph, and make processing idempotent because notifications can be duplicated or delayed. + +Use webhooks for actions such as document processing, index refresh, user notifications, or workflow triggers. Keep a periodic reconciliation job for missed notifications or expired subscriptions. + +## Verify the flow + +Create a subscription, upload or update a file in the container, and confirm your endpoint logs the expected drive ID. If validation fails, check the public HTTPS URL, the `validationToken` response content type, and whether your server parses query parameters before route execution. + +## Next steps + +- [Archive and restore containers](archive-restore-containers.md) diff --git a/docs/embedded/build/search-containers-files.md b/docs/embedded/build/search-containers-files.md new file mode 100644 index 0000000000..59982e1d20 --- /dev/null +++ b/docs/embedded/build/search-containers-files.md @@ -0,0 +1,142 @@ +--- +title: Search Containers and Files +description: Search SharePoint Embedded containers and files with Microsoft Search in Microsoft Graph. +ms.date: 07/13/2026 +ms.reviewer: cindylay +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Search containers and files + +**Applies to:** Developer + + + +Use Microsoft Search in Microsoft Graph when your app needs keyword search across SharePoint Embedded containers or content. The search API ranks matching results and returns `drive` resources for containers or `driveItem` resources for files and folders. + +> [!NOTE] +> SharePoint Embedded search is in preview and is available only on the Microsoft Graph **`/beta`** endpoint — there's no `v1.0` search API for containers. Search supports delegated permissions only and follows the [exceptional access pattern](configure-authentication-authorization.md#handle-operations-not-exposed-through-graph). + +## Choose the search scope + +Scope every request to the container type or container that belongs to your app. Search runs in the context of the signed-in user, so the service trims results to content the user can access. Your app must also have access to the corresponding container type before it can open returned containers or files. + +Use these managed properties in the `queryString`: + +| Scope | Entity type | Query pattern | +| --- | --- | --- | +| All containers of a type | `drive` | `ContainerTypeId:{containerTypeId}` | +| One container by title | `drive` | `Title:'contoso' AND ContainerTypeId:{containerTypeId}` | +| One container by description | `drive` | `Description:'Everything' AND ContainerTypeId:{containerTypeId}` | +| Files in one container | `driveItem` | `Title:'contoso' AND ContainerId:{containerId}` | +| Files across a container type | `driveItem` | `'contoso' AND ContainerTypeId:{containerTypeId}` | + +If your application opted out of Microsoft 365 content discoverability, set `sharePointOneDriveOptions.includeHiddenContent` to `true` in the request body. + +## Search containers + +Send a `POST` request to Microsoft Graph search and request `drive` resources. + +```http +POST https://graph.microsoft.com/beta/search/query +Content-Type: application/json +``` + +```json +{ + "requests": [ + { + "entityTypes": ["drive"], + "query": { + "queryString": "ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae" + }, + "sharePointOneDriveOptions": { + "includeHiddenContent": true + }, + "from": 0, + "size": 25 + } + ] +} +``` + +The response includes `hitsContainers`. Each hit contains a `hitId`, `rank`, `summary`, and a `resource` whose `@odata.type` is `#microsoft.graph.drive`. + +## Search files and folders + +Request `driveItem` resources when the user searches file names or file content. Scope to a specific container with `ContainerId` when the user is already inside a workspace. + +```json +{ + "requests": [ + { + "entityTypes": ["driveItem"], + "query": { + "queryString": "Title:'contoso' AND ContainerId:b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0" + }, + "sharePointOneDriveOptions": { + "includeHiddenContent": true + }, + "from": 0, + "size": 25 + } + ] +} +``` + +A `driveItem` result can include file metadata such as `id`, `name`, `size`, `createdDateTime`, `lastModifiedDateTime`, `parentReference`, `createdBy`, `lastModifiedBy`, and `webUrl`. + +## Return selected fields and sort results + +Use the `fields` collection to request specific managed properties in the response. Use `sortProperties` only with sortable properties. + +```json +{ + "requests": [ + { + "entityTypes": ["driveItem"], + "query": { "queryString": "Everything about contoso" }, + "sharePointOneDriveOptions": { "includeHiddenContent": true }, + "fields": ["SampleOWSText", "id", "name", "parentReference", "webUrl", "createdDateTime", "lastModifiedDateTime", "size"], + "sortProperties": [ + { "name": "Created", "isDescending": false } + ] + } + ] +} +``` + +Use `from` and `size` to page through ranked results. Read `hitsContainers[].total` and `hitsContainers[].moreResultsAvailable` to decide whether to request another page. + +## Search custom properties + +For container custom properties, append `OWSTEXT` to the custom property name in the query string. + +```text +customPropertyNametOWSTEXT:customPropertyValue AND ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae +``` + +Use full-text **search** (the `/beta/search/query` endpoint above) when users type free-text terms and you want relevance ranking across containers. Use direct enumeration instead of search when your app must filter on known metadata values without relevance ranking. For example, query drive items with `$filter`, `$expand`, and `$orderby`: + +```http +GET https://graph.microsoft.com/v1.0/drives/{container-id}/items?$filter=startswith(listitem/fields/{column}, '{value}')&$expand=listitem($expand=fields) +``` + +When a container has more than 5,000 items and you enumerate with `$orderby`, include the `Prefer: HonorNonIndexedQueriesWarningMayFailRandomly` header required for large ordered enumerations. + +## Known limitations + +Search enforces the signed-in user's access, not your app's authorization. Results include every container and item the user can access that matches the query — even containers whose container type your app isn't authorized to use. Always include `ContainerTypeId` in the `queryString` to scope results to your app. + +To open a container or file returned by search, your app must have access permissions to the corresponding container type. + +## Next steps + +- [Store and query container metadata](container-metadata.md) diff --git a/docs/embedded/build/share-files-manage-permissions.md b/docs/embedded/build/share-files-manage-permissions.md new file mode 100644 index 0000000000..362b886f5e --- /dev/null +++ b/docs/embedded/build/share-files-manage-permissions.md @@ -0,0 +1,97 @@ +--- +title: Share files and manage permissions +description: Grant targeted SharePoint Embedded file access with additive permissions and role-based sharing. +ms.date: 07/10/2026 +ms.reviewer: cindylay +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Share files and manage permissions + +**Applies to:** Developer + + + +SharePoint Embedded content inherits permissions from its container hierarchy. You can't break inheritance on arbitrary files or folders. Use additive permissions to extend access to a specific drive item without changing the baseline container membership. + +## Understand container roles + +Container roles provide the inherited baseline access for a container. These roles are defined in [container permissions](configure-authentication-authorization.md#understand-container-permissions): + +| Role | Access summary | +| --- | --- | +| `Reader` | Reads container properties and contents. | +| `Writer` | Has Reader access, plus permission to create, update, and delete content and update applicable container properties. | +| `Manager` | Has Writer access, plus permission to manage container membership. | +| `Owner` | Has Manager access, plus permission to delete containers. | + +A user with inherited `Reader` access can receive additive edit access on one document. Removing that added permission doesn't remove the user's inherited container role. + +## Grant additive access + +Grant additive access with Microsoft Graph drive item invite. Set `sendInvitation` to `false`. App-only permissions aren't supported for this operation. + +```http +POST https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{item-id}/invite +Content-Type: application/json +``` + +```json +{ + "recipients": [ + { "email": "user@contoso.com" } + ], + "message": "", + "requireSignIn": true, + "sendInvitation": false, + "roles": ["write"] +} +``` + +Use `roles: ["read"]` for view access and `roles: ["write"]` for edit access. Don't grant additive permissions to the root folder of a container; add the user to an appropriate container role instead. + +## Retrieve and delete permissions + +List permissions when you need to show direct sharing state on a file or folder. + +```http +GET https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{item-id}/permissions +GET https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{item-id}/permissions/{perm-id} +``` + +Delete only the additive permission on the drive item where it was originally added. + +```http +DELETE https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{item-id}/permissions/{perm-id} +``` + +If the user still has access after deletion, inspect inherited container roles, Microsoft Entra groups, and any other additive permission on parent folders. + +## Configure who can share + +SharePoint Embedded supports a role-based sharing model on the container type. The restrictive model allows only `Owner` and `Manager` members to add new permissions to files. The open model allows container members and guests with edit permissions to add new file permissions. By default, a container type uses the open model. + +Application owner developers control this container type setting. Design your UI so the share action is disabled or hidden when the current user's role can't add permissions. For administrative configuration, see [Create apps with PowerShell](../admin/create-apps-powershell.md). + +## Respect tenant sharing policy + +By default, SharePoint Embedded application sharing follows the consuming tenant's sharing configuration. If the tenant disables guest sharing, your app can't add guests to container roles or grant guest additive permissions. + +A consuming tenant SharePoint Embedded Administrator can configure application-level sharing in administrative tools. + +Report policy failures in user-facing language. Distinguish inherited container access from direct item access in permission panels so users understand why a person can still open a file. + +## Manage membership from the consuming tenant + +Consuming-tenant administrators can manage container membership directly in administrative tools. These tools complement the app-driven Microsoft Graph permission APIs and are useful for administrative or break-glass membership changes. + +## Next steps + +- [Respond to file and container changes with webhooks](respond-to-changes-webhooks.md) diff --git a/docs/embedded/build/sharepoint-embedded-knowledge-source.md b/docs/embedded/build/sharepoint-embedded-knowledge-source.md new file mode 100644 index 0000000000..8ac9593aac --- /dev/null +++ b/docs/embedded/build/sharepoint-embedded-knowledge-source.md @@ -0,0 +1,87 @@ +--- +title: Set up SharePoint Embedded as a Foundry knowledge source +description: Configure Microsoft Foundry Agent Service to use SharePoint Embedded content as a SharePoint knowledge source. +ms.date: 07/13/2026 +ms.reviewer: dilucesr +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Set up SharePoint Embedded as a Foundry knowledge source + +**Applies to:** Developer + + + +Use Microsoft Foundry Agent Service with a SharePoint knowledge source when your app needs a grounded agent experience over files stored in SharePoint Embedded containers. + +> [!NOTE] +> SharePoint knowledge sources for SharePoint Embedded are in preview. + +## Prerequisites + +Before you start, make sure you have: + +- A SharePoint Embedded app with at least one container. +- The container type ID for the SharePoint Embedded app. +- A Microsoft Foundry Agent Service project. +- At least one Microsoft 365 Copilot license in the tenant during preview. +- Permission to update the container type registration in each consuming tenant where the agent must access content. + +During preview, the Copilot license is required. After preview, this feature is expected to move to metered billing. + +## Configure the SharePoint knowledge source + +Configure the Foundry SharePoint knowledge source with `remoteSharePointParameters.containerTypeId` set to your SharePoint Embedded container type ID. + +For source-specific configuration details, see [SharePoint knowledge source properties](/azure/search/agentic-knowledge-source-how-to-sharepoint-remote#source-specific-properties). + +## Grant Foundry access to the container type + +Grant Microsoft Foundry read access to your container type in each consuming tenant. The Foundry application ID is `880da380-985e-4198-81b9-e05b1cc53158`. + +The container type's owning application must call the registration API in the consuming tenant. + +```http +PUT /storage/fileStorage/containerTypeRegistrations/{fileStorageContainerTypeId}/applicationPermissionGrants/880da380-985e-4198-81b9-e05b1cc53158 +Content-Type: application/json +``` + +```json +{ + "delegatedPermissions": ["readContent"], + "applicationPermissions": ["none"] +} +``` + +Replace `{fileStorageContainerTypeId}` with your container type ID. + +You can also grant this permission during initial container type registration by using the [Create container type registration](/graph/api/filestorage-post-containertyperegistrations) endpoint. + +## Validate retrieval + +1. Upload supported files to a SharePoint Embedded container. +1. Wait for indexing to complete. +1. Sign in as a user who has access to the container content. +1. Ask the agent a question that the uploaded files can answer. +1. Confirm that the answer is grounded in the expected SharePoint Embedded content. + +If the answer omits expected files, check: + +- Container type registration in the consuming tenant. +- Foundry application permission grants. +- User access to the container and files. +- Supported file formats. +- Content discoverability settings. +- Indexing delay. + +## Next steps + +- [Add Microsoft 365 Copilot and agent experiences](agent-experiences.md) +- [Register application permissions](register-application-permissions.md) diff --git a/docs/embedded/getting-started/sharepoint-embedded-mcp-server.md b/docs/embedded/build/sharepoint-embedded-mcp-server.md similarity index 84% rename from docs/embedded/getting-started/sharepoint-embedded-mcp-server.md rename to docs/embedded/build/sharepoint-embedded-mcp-server.md index a442d3a373..831e130c71 100644 --- a/docs/embedded/getting-started/sharepoint-embedded-mcp-server.md +++ b/docs/embedded/build/sharepoint-embedded-mcp-server.md @@ -1,14 +1,15 @@ --- -title: SharePoint Embedded Model Context Protocol (MCP) server -description: Use the open-source SharePoint Embedded MCP server to provision and manage SharePoint Embedded from any MCP-compatible AI client through natural language. +title: Use the MCP server to build apps with a coding agent +description: Use the open-source SharePoint Embedded MCP server with a coding agent to provision, configure, scaffold, and manage SharePoint Embedded applications through natural language. ms.date: 07/10/2026 ms.localizationpriority: high ms.author: grjoseph +ai-usage: ai-assisted --- -# SharePoint Embedded Model Context Protocol (MCP) server +# Use the MCP server to build apps with a coding agent -The SharePoint Embedded MCP server is an open-source [Model Context Protocol](https://modelcontextprotocol.io/) server that lets any MCP-compatible AI client—such as GitHub Copilot in Visual Studio Code, Claude Desktop, Cursor, or Azure AI Foundry—set up and manage SharePoint Embedded through natural language. It's distributed as the [`@microsoft/spe-mcp`](https://github.com/microsoft/SharePoint-Embedded-MCP-Server) npm package and runs locally on your machine as a developer tool. +The SharePoint Embedded MCP server is an open-source [Model Context Protocol](https://modelcontextprotocol.io/) server that lets any MCP-compatible AI client—such as GitHub Copilot in Visual Studio Code or CLI, Claude Desktop, Cursor, or Azure AI Foundry—set up and manage SharePoint Embedded applications through natural language. It's distributed as the [`@microsoft/spe-mcp`](https://github.com/microsoft/SharePoint-Embedded-MCP-Server) npm package and runs locally on your machine as a developer tool. Instead of clicking through portals and stitching together Microsoft Graph and Azure CLI commands by hand, you describe what you want—"create a trial container type for my app"—and the AI client calls the server's tools to do it. @@ -24,7 +25,7 @@ Instead of clicking through portals and stitching together Microsoft Graph and A The server exposes tools that an AI client can call on your behalf, grouped by task: -- **Provisioning and status**: Check your signed-in identity and provisioning readiness, create the owning Microsoft Entra ID application, and create, register, list, update, or delete [container types](containertypes.md) and containers. A single `project_provision` tool can run the whole sequence—app → container type → billing → registration → container—in one call. +- **Provisioning and status**: Check your signed-in identity and provisioning readiness, create the owning Microsoft Entra ID application, and create, register, list, update, or delete [container types](../plan/container-types-containers.md) and containers. A single `project_provision` tool can run the whole sequence—app → container type → billing → registration → container—in one call. - **Billing**: Pick an Azure subscription and resource group, register the `Microsoft.Syntex` resource provider, link a container type to [standard billing](../administration/billing/billing.md), and inspect billing classification or trial expiry. - **Scaffold, run, and deploy**: Generate a runnable reference application (a React single-page app with Azure Functions, or a C# web app), write its runtime configuration from your provisioning state, seed sample content, run it locally, and deploy it to Azure. - **Content operations (opt-in)**: After a separate, explicit consent, upload files, create folders, search, preview, manage sharing and permissions, and archive or restore containers. @@ -34,9 +35,9 @@ For the complete, versioned list of tools, CLI flags, and environment variables, ## Prerequisites -- **Node.js** version 18 or later. +- **Node.js** version 22 or later. - **[Azure CLI](/cli/azure/install-azure-cli)**, signed in with `az login --allow-no-subscriptions`. The `--allow-no-subscriptions` flag is required for Microsoft 365–only tenants that have no Azure subscription. -- A Microsoft 365 tenant with **SharePoint Embedded** enabled and tenant-admin access (Global Administrator or Application Administrator). +- A Microsoft 365 tenant and tenant-admin access (Global Administrator or Application Administrator). - An **MCP-compatible client**, such as [Visual Studio Code](https://code.visualstudio.com/) with GitHub Copilot, Claude Desktop, or Cursor. ## Install and configure @@ -90,7 +91,7 @@ The server supports two running modes. az login --allow-no-subscriptions ``` -- **Pre-provisioned-app mode**: Pass an existing public-client Microsoft Entra ID application that already has admin-consented delegated permissions for `FileStorageContainer.Selected`, `FileStorageContainerType.Manage.All`, and `FileStorageContainerTypeReg.Manage.All`. Provide the app and tenant IDs through the `SPE_CLIENT_ID` and `SPE_TENANT_ID` environment variables (or the `--client-id` and `--tenant-id` flags): +- **Pre-provisioned-app mode**: Pass an existing public-client Microsoft Entra ID application that already has admin-consented delegated permissions for `FileStorageContainer.Selected`, `FileStorageContainerType.Manage.All`, and `FileStorageContainerTypeReg.Manage.All`. Provide the app ID and tenant ID through the `SPE_CLIENT_ID` and `SPE_TENANT_ID` environment variables (or the `--client-id` and `--tenant-id` flags): ```json { @@ -132,8 +133,8 @@ The **content operations** tools are also gated behind a separate, explicit cons ## Related content - [SharePoint Embedded MCP server on GitHub](https://github.com/microsoft/SharePoint-Embedded-MCP-Server) – source code, full tool reference, and issues. -- [SharePoint Embedded for Visual Studio Code](spembedded-for-vscode.md) – a guided extension for getting started for free. -- [SharePoint Embedded container types](containertypes.md) +- [Quickstart: Build your first app with VS Code](quickstart-vscode.md) – a guided extension for getting started for free. +- [SharePoint Embedded container types](../plan/container-types-containers.md) - [SharePoint Embedded app architecture](../development/app-architecture.md) - [Authentication and authorization](../development/auth.md) - [Model Context Protocol](https://modelcontextprotocol.io/) diff --git a/docs/embedded/compliance/audit-events.md b/docs/embedded/compliance/audit-events.md deleted file mode 100644 index 0c72d6857f..0000000000 --- a/docs/embedded/compliance/audit-events.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: SharePoint Embedded audit log events -description: Learn about audit log events for SharePoint Embedded container type and container type registration operations in the Microsoft Purview unified audit log. -ms.date: 04/24/2026 -ms.localizationpriority: medium ---- - -# SharePoint Embedded audit log events - -SharePoint Embedded container type and container type registration operations are captured in the Microsoft 365 unified audit log through [Microsoft Purview](/purview/audit-solutions-overview). These events let compliance administrators and developers track changes to container type definitions and their tenant registrations. - -For general information about searching the audit log, see [Search the audit log](/purview/audit-search). For a broader overview of all compliance capabilities available for content stored in SharePoint Embedded, see [Security and Compliance](security-and-compliance.md). - -## Container type activities - -The following events are logged when a container type is created, updated, or deleted. For more information, see [SharePoint Embedded container types](../getting-started/containertypes.md). - -These events use **Workload** value **SharePoint** in the unified audit log. - -| Friendly name | Operation | Description | -| :-- | :-- | :-- | -| Created container type | ContainerTypeCreated | A new SharePoint Embedded container type definition was created. | -| Deleted container type | ContainerTypeDeleted | A SharePoint Embedded container type owned by the tenant was deleted. | -| Updated container type | ContainerTypeUpdated | Properties of a SharePoint Embedded container type, such as name or configuration, were changed. | -| Updated container type owners | ContainerTypeOwnersUpdated | Owners were added to or removed from a SharePoint Embedded container type. | - -These events appear in the Microsoft Purview audit log under the **SharePoint Embedded Container Type activities** category. For the full reference of all audit activities, see [Audit log activities](/purview/audit-log-activities#sharepoint-embedded-container-type-activities). - -## Container type registration activities - -The following events are logged when a container type registration is created, updated, or deleted in a consuming tenant. Container type registrations are required for a SharePoint Embedded application to operate in a given tenant. For more information, see [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md). - -These events use **Workload** value **SharePoint** in the unified audit log. - -| Friendly name | Operation | Description | -|:-- | :-- | :-- | -| Created container type registration | ContainerTypeRegistrationCreated | A SharePoint Embedded container type registration was created in a tenant. | -| Deleted container type registration | ContainerTypeRegistrationDeleted | A SharePoint Embedded container type registration was deleted from a tenant. | -| Updated container type registration | ContainerTypeRegistrationUpdated | A SharePoint Embedded container type registration was updated in a tenant. | - -These events appear in the Microsoft Purview audit log under the **SharePoint Embedded Container Type Registration activities** category. For the full reference of all audit activities, see [Audit log activities](/purview/audit-log-activities#sharepoint-embedded-container-type-registration-activities). - -## Searching for SharePoint Embedded audit events - -To search for these events, use the [Microsoft Purview audit log search](/purview/audit-search). When searching, set the activity category filter to **SharePoint Embedded Container Type activities** or **SharePoint Embedded Container Type Registration activities** to find the relevant events. - -You can also search using PowerShell: - -```powershell -Search-UnifiedAuditLog -Operations ContainerTypeCreated,ContainerTypeDeleted,ContainerTypeUpdated,ContainerTypeOwnersUpdated,ContainerTypeRegistrationCreated,ContainerTypeRegistrationDeleted,ContainerTypeRegistrationUpdated -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) -``` - -Container type audit events include the `ContainerTypeId` property to identify the relevant container type. Unlike container-level file events, container type events don't include `ContainerInstanceId` because they apply at the type level, not to individual container instances. - -## Schema reference - -Container type and container type registration audit events use the SharePoint base schema. For the full schema definition and enum values, see the [Office 365 Management Activity API schema](/office/office-365-management-api/office-365-management-activity-api-schema#sharepoint-base-schema). - -## Related content - -- [SharePoint Embedded container types](../getting-started/containertypes.md) -- [Security and Compliance](security-and-compliance.md) -- [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) -- [Audit log activities](/purview/audit-log-activities#sharepoint-embedded-container-type-activities) -- [Office 365 Management Activity API schema](/office/office-365-management-api/office-365-management-activity-api-schema) diff --git a/docs/embedded/compliance/security-and-compliance.md b/docs/embedded/compliance/security-and-compliance.md deleted file mode 100644 index d002720fcc..0000000000 --- a/docs/embedded/compliance/security-and-compliance.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Security and Compliance -description: Details Security and Compliance methods provided by SharePoint Embedded -ms.date: 11/21/2023 -ms.localizationpriority: high ---- - -# Security and Compliance - -Microsoft's SharePoint Embedded provides a faster way to create secure and compliant documents stored in various applications. SharePoint Embedded uses Microsoft’s comprehensive compliance and data governance solutions to help organizations manage risks, protect, and govern sensitive data, and respond to regulatory requirements. Security and compliance solutions work similarly in the SharePoint Embedded platform as they do today on the Microsoft 365 (Microsoft 365) platform so that data is stored in a secure, protected way that meets customers’ business and compliance policies while making it easy for Compliance and SharePoint Administrators to enforce critical security and compliance policies on the content. - -In this article, we describe the security and compliance policies that are supported today on content that resides in the SharePoint Embedded platform, and their capabilities and limitations. - -Since SharePoint Embedded by design doesn’t have any user interface, some Compliance scenarios necessitating user interaction aren't natively supported. The owning application that governs the container can choose to support these scenarios and provide the optimal experience to end users by using the Microsoft Graph. - -## Compliance Policies using Microsoft Purview - -Currently, SharePoint Embedded supports the following Compliance features under Microsoft Purview. You can follow the following steps to retrieve the details of a container that the policy needs to be applied to. - -1. View a list of registered SharePoint Embedded applications registered in the specified tenant: - - ```powershell - Get-SPOApplication - ``` - -1. Retrieve a list of containers in a SharePoint Embedded application by providing the ApplicationID returned in Step #1: - - ```powershell - Get-SPOContainer -OwningApplicationId - ``` - -1. Retrieve the details of a container including the ContainerSiteURL by providing the ContainerID returned in Step #2: - - ```powershell - Get-SPOContainer -OwningApplicationId -Identity - ``` - -For information on how to retrieve the `ContainerSiteURL` to set the various compliance policies described in this article at a container level, see [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer). - -### Audit - -The Audit capabilities provided by SharePoint Embedded mirror the existing Audit functionalities currently supported within SharePoint. All user and admin operations performed in various applications hosted in SharePoint Embedded are captured, recorded, and retained in your organization's unified audit log. For more information on Audit, see [Auditing solutions in Microsoft Purview](/purview/audit-solutions-overview). - -For a detailed list of container type and container type registration audit events, see [SharePoint Embedded audit log events](audit-events.md). - -In addition to existing file properties, Audit events related to SharePoint Embedded are logged with the following more data to help filter the Audit search results to isolate the relevant SharePoint Embedded content: - -- `ContainerInstanceId` -- `ContainerTypeId` - -![Audit events](../images/sc1.png) - - -### eDiscovery - -Compliance Admins can use eDiscovery tools in Microsoft Purview to search/hold/export content hosted in the SharePoint Embedded platform. For more information on eDiscovery, see [Microsoft Purview eDiscovery solutions](/purview/ediscovery). - -To perform an eDiscovery Search on all SharePoint Embedded content, Admins should select **All** SharePoint Sites when configuring the eDiscovery Search in Microsoft Purview. This enables the Search for content stored in all SharePoint Sites and all SharePoint Embedded containers. - -![eDiscovery search](../images/sc2.png) - -To limit the eDiscovery Search to one/few SharePoint Embedded containers, Admins can **Choose sites** under the **SharePoint sites** workload and provide the desired container URL. - -![choose sites in eDiscovery search](../images/sc3.png) - -### Data Lifecycle Management (DLM) - -SharePoint Embedded supports retention and holds policies on content stored in its applications using the Microsoft Purview compliance portal. For more information on DLM, see [Learn about Microsoft Purview Data Lifecycle Management](/purview/data-lifecycle-management). - -The existing retention policy is applied to all SharePoint Embedded containers if the policy is configured for **All sites**. Similarly, creating a new retention/hold policy on *all* SharePoint Sites workload automatically enforces the policy on all SharePoint Sites and all containers within SharePoint Embedded. - -![retention policy](../images/sc4.png) - -To selectively enforce the policy on one or more SharePoint Embedded containers, copy the container URL and configure the policy to be selectively enforced only on those containers. - -![enforce retention policy](../images/sc5.png) - -Since SharePoint Embedded doesn't have a built-in user interface, DLM scenarios requiring user interaction aren't natively supported. For instance, if an end user attempts to apply a retention label on a container using a SharePoint Embedded application (app), the app governing the access to the container must furnish that functionality. In such cases, Graph APIs for DLM functionalities can be used. - -### Data Loss Protection (DLP) - -Using Microsoft Purview, Admins can identify, monitor, and automatically protect sensitive items stored in applications using SharePoint Embedded. For more information on DLP, see  [Learn about data loss prevention](/purview/dlp-learn-about-dlp). - -Like retention policies, DLP policies can be enforced on all SharePoint Sites and SharePoint Embedded containers by choosing to configure the policy on ‘All sites’. - -![DLP Policy](../images/sc6.png) - -Admins can also restrict the enforcement of a DLP policy to specific SharePoint Embedded containers by specifying the relevant container URLs during policy configuration. - -![Configure DLP Policy](../images/sc7.png) - -Several scenarios supported by DLP today need user interaction that isn’t natively supported by SharePoint Embedded. For instance, based on its configuration, a DLP policy that prevents external sharing might allow end users to provide a business justification to override the policy. The client app that renders this DLP-flagged file item needs to support such user interactions. - -Policy tips are shown today for files hosted in SharePoint so that users are kept informed about DLP-flagged file items and corresponding restrictions. Similarly, for policy tips to be displayed for files hosted in SharePoint Embedded, the client app can choose to provide more support by utilizing the Microsoft Graph for this purpose. - -## Security features - -### Sensitivity labels on containers - -Global Administrators and SharePoint Administrators can set and remove sensitivity labels on a SharePoint Embedded container by using the newly created SharePoint PowerShell cmdlet: - -```powershell -Set-SPOContainer -Identity -SensitivityLabel -``` - -To learn more about setting sensitivity labels, see [Learn about sensitivity labels](/purview/sensitivity-labels). - -### Block Download policy - -Block Download policy allows SharePoint Administrator or Global Administrator to block the download of files from SharePoint Embedded containers using the following SharePoint PowerShell cmdlet. - -```powershell -Set-SPOSite -Identity -BlockDownloadPolicy $true -``` - -A SharePoint Advanced Management (SAM) license is needed to enforce this policy. Read the full documentation for advanced capabilities at [Block download policy for SharePoint sites and OneDrive](/sharepoint/block-download-from-sites). - -### Conditional Access policy - -SharePoint Embedded supports basic Conditional Access policy configurations such as: - -- `AllowFullAccess`: Allows full access from desktop apps, mobile apps, and the web -- `AllowLimitedAccess`: Allows limited, web-only access -- `BlockAccess`: Blocks Access - -These settings are available with the following PowerShell cmdlet. The `AuthorizationContext` will also be supported soon. - -```powershell -Set-SPOContainer -Identity -ConditionalAccessPolicy -``` - -To learn more about conditional access policies, see [Control access from unmanaged devices](/sharepoint/control-access-from-unmanaged-devices). diff --git a/docs/embedded/development/app-architecture.md b/docs/embedded/development/app-architecture.md deleted file mode 100644 index d3eb1d73cb..0000000000 --- a/docs/embedded/development/app-architecture.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: App Architecture -description: Anatomy of a SharePoint Embedded application -ms.date: 05/21/2024 -ms.localizationpriority: high ---- - -# SharePoint Embedded app architecture - -All files and documents in SharePoint Embedded are stored in containers, with all containers and container content created and stored within a Microsoft 365 Tenant. All containers and container content are created, managed, and interacted via the SharePoint Embedded application using Microsoft Graph. - -![SharePoint Embedded Architecture](../images/SPEArch.png) - -## SharePoint Embedded application - -A Microsoft Entra ID application registration. As an owning or guest application to a container type, it has access to containers of that container type. - -## Owning tenant and consuming tenant - -SharePoint Embedded introduces the concepts of owning tenant and consuming tenant. Owning tenant is a Microsoft Entra ID tenant where a container type is created. This is often also the tenant where your SharePoint Embedded application is registered. Consuming tenant is a Microsoft Entra ID tenant where a container type is used. Only a consuming tenant may have containers of such container type. All container and content created via the application is stored within the consuming tenant's Microsoft 365 tenant boundary. - -The same Microsoft Entra ID tenant can be both owning and consuming tenant of a given container type in the SharePoint Embedded ecosystem. - -## Container, container type, and owning application - -A container is the basic storage unit in SharePoint Embedded. Also, a container defines a security and compliance boundary. - -A container type is a SharePoint Embedded resource that defines the relationship, access privileges, and billing accountability between an application and a set of containers. Also, the container type defines behaviors on the set of containers. Learn more about [container types](../getting-started/containertypes.md). - -The container type is represented on each container as an immutable property and is used across the entire SharePoint Embedded ecosystem. Each container type is strongly coupled with one SharePoint Embedded application, which is referred to as the owning application. The owning application developer (the owning tenant) is responsible for creating and managing their container types. SharePoint Embedded mandates a 1:1 relationship between owning application and container type. - -## Access Model - -An application's access to containers and container content is determined by a set of permissions configured between the application and the container type it attempts to access. This set of permission is determined at container Type creation time for owning application. The SharePoint Embedded ecosystem allows applications to access containers of container types it doesn't own. - -In this illustration, multiple applications are deployed in the tenancy, including two apps developed by ISVs (App 1 and 2) and a LOB app (App 3). Each application can access only to the stack of containers of the container type they own. - -![SPE multi app architecture](../images/SPECTDedicated.png) - -In this illustration, both App 1 and App 2 in the tenancy have access to the same container type. Both apps can access the stack of the containers of that type. - -![SPE multi app architecture sharing Container Types](../images/SPECTShared.png) - -#### Example - -Contoso is an ISV and built a human resource management application on SharePoint Embedded. The application is registered and deployed in Fabrikam, an auditing firm. Fabrikam also developed an LOB auditing application on SharePoint Embedded that is used internally. - -In this scenario, both the human resource management application developed by Contoso and the auditing application developed by Fabrikam have their own container type. Contoso is the owning tenant of the human resource management application; and the application is the owning app for its container Type. Likewise, Fabrikam is the owning tenant the auditing application; and the application is the owning app for its container type. In addition, Fabrikam is the consuming tenant for both applications. - -![Example](../images/apparchexample.png) diff --git a/docs/embedded/development/auth.md b/docs/embedded/development/auth.md deleted file mode 100644 index fdf13bc278..0000000000 --- a/docs/embedded/development/auth.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -title: SharePoint Embedded Authentication and Authorization -description: This article describes the authentication and authorization model for SharePoint Embedded applications. -ms.date: 11/21/2023 -ms.localizationpriority: high ---- - -# SharePoint Embedded authentication and authorization - -To use SharePoint Embedded, your application must utilize Microsoft Graph. Learn more about [Microsoft Graph authentication and authorization](/graph/auth/auth-concepts). Learn more about the [SharePoint Embedded architecture](./app-architecture.md). - -## Overview - -Here are some key principles of SharePoint Embedded authentication and authorization: - -- Applications interact with SharePoint Embedded via Microsoft Graph. -- Applications need container type application permissions to access containers of that container type. -- Applications can only access content that the user has access to when using access on behalf of a user. -- Applications can access all containers enabled by their container type application permissions when using access without a user. -- Applications use access on behalf of users whenever possible to enhance security and accountability. - -## Prerequisites - -- A Microsoft Entra ID application registration. See [register an application](/graph/auth-register-app-v2). -- Your Microsoft Entra ID tenant has a Microsoft 365 subscription. - -## Authorization - -SharePoint Embedded operations are exposed via Microsoft Graph. SharePoint Embedded supports [access on behalf of a user](/graph/auth-v2-user) and also [access without a user](/graph/auth-v2-service). - -> [!IMPORTANT] -> Microsoft Graph permissions granted to your application allow it to call SharePoint Embedded endpoints. However, your application must be granted [permission to a container type](#container-type-application-permissions) before it gets access to containers of that type. - -### Application permissions - -SharePoint Embedded applications need to request the following Microsoft Graph permissions in their application manifest to work with SharePoint Embedded: - -- **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** to allow an application to create and manage container types on the owning tenant. This permission is only needed on the owning tenant where the container type is created. -- **[FileStorageContainerTypeReg.Selected](/graph/permissions-reference#filestoragecontainertyperegselected)** to allow an application to register the container type on consuming tenants. -- **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** to allow an application to access containers of the given container type on consuming tenants. - -#### Access on behalf of a user - -SharePoint Embedded operations [on behalf of a user](/graph/auth-v2-user) support two Microsoft Graph permissions: - -- **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** to allow an application to access containers on behalf of the signed-in user. - - In addition to your application receiving consent for the permission on a consuming tenant, the user that it's acting on behalf of is required to have [user permissions](#user-permissions). The effective permissions that the application has are the intersection of the application permissions and the user permissions when acting on behalf of a user. -- **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** to allow an application to utilize administration capabilities on all containers of all governable container types within the consuming tenant on behalf of an administrator user. The administration capabilities include the ability to enumerate, delete, restore, purge, and update containers, and manage their permissions. - -> [!IMPORTANT] -> -> - Using SharePoint Embedded on behalf of a user is the recommended approach. This type of access enhances the security of your application. It also improves the auditability of actions performed by your application. -> - Using a confidential client application is the recommended approach to ensure your application remains in control of actions taken on behalf of a user. A public client application may expose user tokens to the end user, which may lead to actions being taken outside of your application's control. See [Public client and confidential client applications](/entra/identity-platform/msal-client-applications) to learn more. - -#### Access without a user - -SharePoint Embedded operations [without a user](/graph/auth-v2-service) require applications to receive consent for Microsoft Graph **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** application permission. This permission requires admin consent on the consuming tenant. - -> [!NOTE] -> An administrator on the consuming tenant must consent to your application's request for permissions. To learn more, see [Grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal). - -### Container type application permissions - -SharePoint Embedded applications need to be granted container type application permissions by the owning application before they can access containers of the given container type. Container type application permissions are granted to applications via [container type registration](../getting-started/register-api-documentation.md) in a consuming tenant. - -| Permission | Description | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------ | -| **None** | Has no permissions to any containers or content of this container type. | -| **ReadContent** | Can read the content of containers of this container type. | -| **WriteContent** | Can write content to containers for this container type. This can't be granted without the ReadContent permission. | -| **Create** | Can create containers of this container type. | -| **Delete** | Can delete containers of this container type. | -| **Read** | Can read the metadata of containers of this container type. | -| **Write** | Can update the metadata of containers of this container type. | -| **EnumeratePermissions** | Can enumerate the members of a container and their roles for containers of this container type. | -| **AddPermissions** | Can add members to the container for containers of this container type. | -| **UpdatePermissions** | Can update (change roles of) existing memberships in the container for containers of this container type. | -| **DeletePermissions** | Can delete other members (but not self) from the container for containers of this container type. | -| **DeleteOwnPermission** | Can remove own membership from the container for containers of this container type. | -| **ManagePermissions** | Can add, remove (including self), or update members in the container roles for containers of this container type. | -| **ManageContent** | Can manage the content of the container (WriteContent plus discard checkout permission in app-only mode). | -| **Full** | Has all permissions for containers of this container type. | - -> [!NOTE] -> The combination of Microsoft Graph permissions and container type application permissions encompasses the client authorization for applications. - -### User permissions - -Users are granted different access levels to SharePoint Embedded based on the scenario: - -- [Accessing content in containers](#accessing-content-in-containers) -- [Managing SharePoint Embedded applications installed in the consuming tenant](#managing-sharepoint-embedded-applications-installed-in-the-consuming-tenant) -- [Managing SharePoint Embedded applications created in the owning tenant](#managing-sharepoint-embedded-applications-created-in-the-owning-tenant) - -#### Accessing content in containers - -There are two ways in which users can gain access to content in containers: - -- [Container permissions](#container-permissions) -- [Access to specific items in a container](#access-to-specific-items-in-a-container) - -##### Container permissions - -Users can be assigned container permissions in two ways: - -- Direct membership. A user is directly added as a member of a container with specific permissions. -- Transitive membership. A user is a member of a [Microsoft 365 group](/microsoft-365/admin/create-groups/office-365-groups) that is itself a member of a container with specific permissions. - -Membership to a container [grants users container permissions](/graph/api/filestoragecontainer-post-permissions). These permissions define the access level that users have on a given container. Container permissions only apply to access on behalf of a user and not to access without a user. A SharePoint Embedded application accessing containers without a user gets the full access defined in its [container type application permissions](#container-type-application-permissions) instead. - -> [!IMPORTANT] -> The calling user creating a new container via delegated calls is automatically assigned the Owner role. - -| Permission | Description | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Reader** | This role allows the user to read the properties and the contents of the container. | -| **Writer** | This role has all the permissions a Reader has, plus the permission to create, update, and delete content inside the container, and to update applicable container properties. | -| **Manager** | This role has all the permissions a Writer has, plus the permission to manage membership of the container. | -| **Owner** | This role has all the permissions a Manager has, plus the permission to delete containers and restore deleted containers. | - -##### Access to specific items in a container - -Specific items in a container can be shared with users via the [driveItem invite](/graph/api/driveitem-invite) or the [permission create](/graph/api/driveitem-post-permissions) endpoints. Sharing grants users access to the specific items, but it doesn't grant them access to the container itself or any other item in the container. For information on the access levels supported, see [permission roles](/graph/api/resources/permission#roles-property-values). - -> [!NOTE] -> For more information about sharing, see [Sharing and permissions in SharePoint Embedded](./sharing-and-perm.md). - -#### Managing SharePoint Embedded applications installed in the consuming tenant - -[SharePoint Embedded Administrators](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) can manage all SharePoint Embedded applications installed in the **consuming** tenant. To learn more about managing installed applications in the consuming tenant, see [Manage SharePoint Embedded applications installed in the consuming tenant](../administration/consuming-tenant-admin/cta.md). - -> [!NOTE] -> [Global Administrators](/entra/identity/role-based-access-control/permissions-reference#global-administrator) have all the permissions that SharePoint Embedded Administrators have and more, so they can also manage SharePoint Embedded applications installed in the consuming tenant. However, you should assign the least privileged role necessary to perform administrative tasks, so using the SharePoint Embedded Administrator role is recommended for managing SharePoint Embedded applications. - -#### Managing SharePoint Embedded applications created in the owning tenant - -[SharePoint Embedded Administrators](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) can manage all SharePoint Embedded applications created in the **owning** tenant. Additionally, any Microsoft Entra user that isn't an external identity can be assigned as an owner of a [container type](/graph/api/resources/filestoragecontainertype). Container type owners can manage that specific container type. To learn more about managing applications created in the owning tenant, see [SharePoint Embedded developer administrator](../administration/developer-admin/dev-admin.md). - -#### Container type owner capabilities - -Container type owners are managed through the [permissions](/graph/api/filestoragecontainertype-post-permissions) navigation property on the [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) resource. Each permission entry has a role of `owner` and identifies the user via `grantedToV2`. Owners can be managed in the following ways: - -- **Automatic assignment**: The user who [creates a container type](/graph/api/filestorage-post-containertypes) is automatically assigned as an owner. -- **Add owners**: Use [`POST /containerTypes/{id}/permissions`](/graph/api/filestoragecontainertype-post-permissions) to add up to three owners per container type. -- **Remove owners**: Use [`DELETE /containerTypes/{id}/permissions/{id}`](/graph/api/filestoragecontainertype-delete-permissions) to remove an owner. -- **Read owners**: Use [`GET /containerTypes/{id}?$expand=permissions`](/graph/api/filestoragecontainertype-get) or [`GET /containerTypes/{id}/permissions`](/graph/api/filestoragecontainertype-list-permissions) to retrieve the container type owners. - -Container type owners can do the following operations on the **owning tenant** when using an application with **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** in delegated mode: - -- **Create, read, update, and delete** the container type they own. Non-admin owners can manage only container types on which they have a permission, and the calling app must match the owning application. -- **Add and remove** other owners on the container type they own (via the permissions endpoint). -- **Create containers** of the container type they own, as long as the call is delegated (not app-only). - -> [!NOTE] -> The user who creates a container type is automatically assigned as an owner. External identities (guest users) can't be assigned as container type owners and can't perform owner operations. - -> [!IMPORTANT] -> Container type owners exist only in the owning tenant. When a container type is registered in a consuming tenant, the owner information is **not** propagated to that tenant. For example, if Contoso creates a container type with owners and registers it in Fabrikam, those Contoso users don't exist in Fabrikam's tenant and have no owner capabilities there. - -> [!IMPORTANT] -> Container type owner capabilities are user permissions. The effective access is the intersection of the application permissions (Microsoft Graph permissions) and the user permissions (owner role). The application must have sufficient Graph permissions for the intersection to grant the desired access. - -### Exceptional access patterns - -Currently, there are three types of operations with exceptional access patterns: - -- [Operations involving searching SharePoint Embedded content](#operations-involving-searching-sharepoint-embedded-content) -- [Operations that require a user license](#operations-that-require-a-user-license) -- [Operations that involve administrative actions on containers](#operations-that-involve-administrative-actions-on-containers) - -> [!IMPORTANT] -> Consider the repercussions of these exceptional access patterns on how your application and other applications can access SharePoint Embedded content in your container type. - -#### Operations involving searching SharePoint Embedded content - -This section refers only to the search scenarios in [Search Content](./content-experiences/search-content.md), and not the enumeration scenarios. - -To use [Microsoft Search](/microsoftsearch/overview-microsoft-search) on SharePoint Embedded content, you must request the Delegated **[Files.Read.All](/graph/permissions-reference#filesreadall)** Microsoft Graph permission on top of **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)**, normally used for SharePoint Embedded access. During the Preview stage of this feature, the **[Files.Read.All](/graph/permissions-reference#filesreadall)** application permission grants applications access to search capabilities on all SharePoint Embedded content. - -> [!NOTE] -> Microsoft Search support for SharePoint Embedded content is in Preview and is subject to change. The access requirements for Microsoft Search on SharePoint Embedded content will align with the SharePoint Embedded authorization model in the future. Stay tuned. - -#### Operations that require a user license - -SharePoint Embedded is designed to work without the need for end users to have any kind of Microsoft 365 product licenses assigned to them. However, there are certain operations that don't abide by this principle yet. - -##### List containers - -The [List containers](/graph/api/filestorage-list-containers?tabs=http) operation returns a **403 Forbidden** response code if called on behalf of a user who doesn't have a OneDrive. There are plans to remove this dependency soon. This dependency doesn't apply to the List containers operation when called without a user context (app-only mode). - -##### Mention users in Office documents - -The common [Office experience](./content-experiences/office-experience.md) includes reviewing documents and adding comments to those documents. For users to show up in the @mentions people picker, they need to have a Microsoft 365 license assigned to them. - -#### Operations that involve administrative actions on containers - -The **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** permission requires the signed-in user to be a SharePoint Embedded Administrator or Global Administrator. - -If the user isn't an administrator, **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** doesn't grant the application any permissions: -- If only **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** is granted, the application will get an access denied error when trying to access the container on behalf of the non-admin user. -- If both **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** and **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** are granted, **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** will be ignored. - -## What's next - -Here are some actions you can take next: - -1. Configure your SharePoint Embedded [application manifest](/entra/identity-platform/reference-app-manifest#requiredresourceaccess-attribute) (you can use [Microsoft Entra PowerShell](/powershell/entra-powershell/manage-apps#assign-permissions-to-an-app) or the [Azure CLI](/cli/azure/ad/app/permission#az-ad-app-permission-add)) to request the required permissions on your _owning_ tenant: - - - Add the Microsoft Graph permission **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** to create container types on the _owning_ tenant: - - **resourceAppId**: `00000003-0000-0000-c000-000000000000` - - **type**: `Scope` - - **ID**: `8e6ec84c-5fcd-4cc7-ac8a-2296efc0ed9b` - - > [!NOTE] - > **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** is a delegated permission and doesn't require admin consent. Any non-guest user in the owning tenant can consent to it and use it to create a container type; that user is then automatically added as an [owner of the container type](#container-type-owner-capabilities). - -1. [Create a new container type](../getting-started/containertypes.md) on the _owning_ tenant. -1. Reconfigure your SharePoint Embedded [application manifest](/entra/identity-platform/reference-app-manifest#requiredresourceaccess-attribute) to request only the required permissions on consuming tenants: - - - Remove the Microsoft Graph permission **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** as this is only needed to create the container type on the _owning_ tenant: - - **resourceAppId**: `00000003-0000-0000-c000-000000000000` - - **type**: `Scope` - - **ID**: `8e6ec84c-5fcd-4cc7-ac8a-2296efc0ed9b` - - > [!NOTE] - > After creating the container type on the _owning_ tenant, you should remove the **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** permission from your application's manifest. - > Your application DOES NOT need this on _consuming_ tenants, only on the _owning_ tenant to create the container type. Failure to remove this permission from the application's manifest will lead to your customers being concerned about the excessive permissions requested by your application. - - - Add the Microsoft Graph permission **[FileStorageContainerTypeReg.Selected](/graph/permissions-reference#filestoragecontainertyperegselected)** to register the container type on _consuming_ tenants: - - **resourceAppId**: `00000003-0000-0000-c000-000000000000` - - **type**: `Role` - - **ID**: `2dcc6599-bd30-442b-8f11-90f88ad441dc` - - Add the Microsoft Graph permission **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** to access containers on _consuming_ tenants on behalf of users: - - **resourceAppId**: `00000003-0000-0000-c000-000000000000` - - **type**: `Scope` - - **ID**: `085ca537-6565-41c2-aca7-db852babc212` - - Optionally add the Microsoft Graph permission **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** to access the container on _consuming_ tenants without a user: - - **resourceAppId**: `00000003-0000-0000-c000-000000000000` - - **type**: `Role` - - **ID**: `40dc41bc-0f7e-42ff-89bd-d9516947e474` - -1. [Grant admin consent](/entra/identity-platform/v2-admin-consent) to your application on a _consuming_ tenant (which can be the same as the owning tenant). -1. [Register the container type](../getting-started/register-api-documentation.md) on the _consuming_ tenant. -1. [Create a container](/graph/api/filestoragecontainer-post) on the _consuming_ tenant diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md deleted file mode 100644 index 6f0be236b4..0000000000 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: Configuring redirect behavior -description: Configure the urlTemplate property on a SharePoint Embedded container type to control how Microsoft 365 routes users to container content from Microsoft 365 search results and from the driveItem.webUrl property returned by Microsoft Graph. -ms.date: 07/09/2026 -ms.localizationpriority: high ---- - -# Configuring redirect behavior - -The `urlTemplate` property on a SharePoint Embedded [container type](../../getting-started/containertypes.md) governs where Microsoft 365 sends users when they open files in your containers. It controls the destination on two surfaces: - -- Microsoft 365 search results. -- The `driveItem.webUrl` property is used to open an item in a browser. - -For files without a supported viewer (the Office web viewer or the embedded viewer), both surfaces use `urlTemplate` to route users to your application. This article explains how Microsoft 365 chooses a destination and how to configure `urlTemplate`. - -## Prerequisites - -Before you configure `urlTemplate`, ensure you have: - -- A SharePoint Embedded [container type](../../getting-started/containertypes.md) that you own. -- The delegated Microsoft Graph permission scope(s) listed in the **Permissions** section of [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update). Application permissions aren't supported. - -> [!NOTE] -> Discoverability is separate from redirect behavior: you don't need to enable it to configure or use `urlTemplate`. The [`isDiscoverabilityEnabled`](/graph/api/resources/filestoragecontainertypesettings) setting is **disabled by default** and controls only whether your content is surfaced in the broader Microsoft 365 experience, such as **My Activity**, office.com, OneDrive.com, other intelligent file discovery features, and Copilot grounding. Leaving it disabled doesn't prevent search: applications can still query content in non-discoverable containers with the [Microsoft Search API](search-content) by setting `sharePointOneDriveOptions.includeHiddenContent` to `true`. To learn how discoverability affects Microsoft 365 surfaces, see [Content discovery in Microsoft 365](user-experiences-overview.md#content-discovery-in-microsoft-365). - -## How Microsoft 365 chooses a destination - -Microsoft 365 chooses a destination based on the file type. `urlTemplate` applies only to files without a supported viewer (the Office web viewer or the embedded viewer). This file-type scope is the same today and after the `webUrl` rollout described in [driveItem.webUrl behavior](#driveitemweburl-behavior). - -If `urlTemplate` isn't configured, Microsoft 365 sends users who open files without a supported viewer to a generic [Microsoft help page](https://aka.ms/spe-openfilelocation). The help page explains that the file is stored in a third-party application and directs the user to open it there. - -### How file types are handled - -The destination for a file depends on the file type and whether `urlTemplate` is set: - -| File type | `urlTemplate` set? | Behavior when opened | -| --- | --- | --- | -| Files with a supported Office web viewer (Word, Excel, PowerPoint, Visio, OneNote, and others) | Either | Opens in the corresponding Office web viewer | -| PDF | Either | Opens in the embedded viewer | -| All other types | Yes | Redirected to your application through `urlTemplate` | -| All other types | No | Redirected to a [Microsoft help page](https://aka.ms/spe-openfilelocation) | - -### `driveItem.webUrl` behavior - -For SharePoint Embedded items, the `driveItem.webUrl` property returned by Microsoft Graph reflects the same redirect behavior described above: - -- For files without a supported viewer, when `urlTemplate` is set: `webUrl` returns the resolved `urlTemplate` redirect URL. -- For files without a supported viewer, when `urlTemplate` isn't set: `webUrl` returns the `aka.ms` help link. -- For files with a supported viewer: `webUrl` returns the viewer URL. - -> [!IMPORTANT] -> `driveItem.webUrl` will soon reflect the redirect behavior described above. If your application currently relies on `webUrl` returning the file's canonical URL, switch to the [`webDavUrl`](/graph/api/resources/driveitem) property, which returns the canonical URL today and continues to do so after the rollout. - -## Configure `urlTemplate` - -Set `urlTemplate` on your container type by calling the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API (`PATCH /storage/fileStorage/containerTypes/{id}`) and setting `settings.urlTemplate`. The value applies to every tenant that registers the container type. This API requires the delegated permission scope(s) listed in its **Permissions** section; application permissions aren't supported. - -The value is a URL with placeholder tokens that Microsoft 365 resolves to actual item identifiers when a user opens an item. - -The SharePoint Embedded PowerShell cmdlet exposes the same setting as a "redirect URI" parameter. The PowerShell "redirect URI" is the `urlTemplate` value and is unrelated to the app-registration redirect URI used for authentication. - -### Requirements - -The `urlTemplate` value must: - -- Be a valid absolute URL that uses the `https://` scheme. HTTP URLs aren't accepted. -- Not resolve to a loopback address, such as `localhost` or `127.0.0.1`. - -> [!IMPORTANT] -> If the URL fails validation, `urlTemplate` is silently set to `null` without returning an error. To confirm your configuration, see [Verify your configuration](#verify-your-configuration). - -### URL template syntax - -```text -https://app.contoso.com/open?tenant={tenant-id}&drive={drive-id}&item={item-id} -``` - -Each placeholder token uses curly braces. When a user opens an item, Microsoft 365 resolves each token to a value that corresponds to the item, URL-encodes the value, and substitutes it in the template. - -If Microsoft 365 can't resolve a token, it drops the entire query parameter that contains that token from the resolved URL (for example, `&folder={folder-id}` is dropped entirely rather than emitted as `&folder=`). The exceptions are `{tenant-id}` and `{drive-id}`: when Microsoft 365 can't resolve them, their query parameters remain in the URL with the token left as literal text (for example, `&tenant={tenant-id}`). - -### Supported tokens - -| Token | Value your application receives | -| --- | --- | -| `{tenant-id}` | GUID of the consuming tenant. Used to make tenant-scoped Microsoft Graph API calls. | -| `{drive-id}` | Drive ID of the container. Use it with Microsoft Graph APIs to reference the container. | -| `{folder-id}` | Item ID of the file's immediate parent folder. Item IDs aren't GUIDs. If the file is at the root of the container, Microsoft 365 drops the entire query parameter that contains `{folder-id}` from the redirect URL rather than passing it with an empty value. | -| `{item-id}` | Item ID of the driveItem. Item IDs aren't GUIDs. | -| `{site-domain}` | The hostname of the container's site (for example, contoso.sharepoint.com). | -| `{list-id}` | The GUID identifier of the document library that backs the container. | -| `{site-url}` | The container site's full web URL without the scheme (authority + path + query + fragment). For example: `contoso.sharepoint.com/contentstorage/CSP_6fa4ae51-5276-4437-b4f5-9b42388a9e1c` | - -#### Advanced tokens - -The following tokens cover specialized scenarios. Most applications can rely on the [supported tokens](#supported-tokens) above. - -| Token | Value your application receives | -| --- | --- | -| `{ownershipType}` | The container's ownership type: TenantOwned, UserOwned, GroupOwned, or ApplicationOwned. | -| `{itemname-guid}` | The GUID parsed from the item's filename, if the file is named `.extension`. Empty if the filename isn't a GUID. | -| `{folderpath-guids}` | Comma-separated GUIDs found in the folder path segments leading to the item. Path segments split on / or _ are each checked for a valid GUID. | - -### Example - -If your container type has `urlTemplate` set to: - -```text -https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id} -``` - -When a user opens a `.txt` file, Microsoft 365 redirects the user to a URL like the following: - -```text -https://app.contoso.com/open?t=72f988bf-86f1-41af-91ab-2d7cd011db47&d=b%21abc123def456ghi789jkl0&i=01ABC23DEF45GHI67JKL890 -``` - -Your application receives the tenant ID, drive ID, and item ID as the values of whatever query-parameter names you defined in the template. The parameter names (`t`, `d`, and `i` in this example) are arbitrary and developer-defined; Microsoft 365 doesn't require any specific names. Use the parsed values to retrieve and open the file through the Microsoft Graph API. - -### Update `urlTemplate` with Microsoft Graph - -Use the PATCH endpoint [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) to update `urlTemplate`: - -```http -PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId} -Content-Type: application/json - -{ - "settings": { - "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}" - } -} -``` - -To clear `urlTemplate`, set the property to `null` in the PATCH request body. - -### Verify your configuration - -Because validation failures are silent, confirm your update by reading the value back. Call [Get fileStorageContainerType](/graph/api/filestoragecontainertype-get) with the `$select` query option to retrieve the current `urlTemplate` value: - -```http -GET https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}?$select=settings -``` - -If the response shows `urlTemplate` as `null`, the URL you submitted didn't meet the [requirements](#requirements). Update the value and try again. - -## What your application does when called - -When Microsoft 365 routes a user to your application, your application must: - -1. Authenticate the user. The user might not have an active session in your app. Microsoft 365 doesn't pass authentication context in the redirect URL. -1. Parse the token values from the redirect URL query string. -1. Call Microsoft Graph with the drive ID and item ID values from the query string to retrieve the [driveItem](/graph/api/resources/driveitem) and open the file in your application's UI. - -For information about calling Microsoft Graph against a consuming tenant's containers, see [Authentication and authorization](../auth.md). - -## Troubleshooting - -| Symptom | Possible cause | -| --- | --- | -| Your files don't appear in Microsoft 365 search results. | The container type's `isDiscoverabilityEnabled` setting is `false`. Search indexing can also take time after enablement. | -| Users land on the Microsoft help page instead of your application. | `urlTemplate` is `null` (likely because the URL failed validation), or the file type opens in a supported viewer (the Office web viewer or the embedded viewer) instead of redirecting. | -| A token appears as literal text (such as `{tenant-id}`) in the redirect URL. | Microsoft 365 couldn't resolve the token for the current item. Verify the token name matches a [supported token](#supported-tokens) or a [custom property](/graph/api/filestoragecontainer-post-customproperty). | -| Updates to `urlTemplate` don't appear in search results. | Search index updates aren't instantaneous. See [Limitations](#limitations). | - -## Limitations - -### Updates to `urlTemplate` aren't instantaneous - -Microsoft 365 stores the destination URL for each file in the search index. If you configure or update `urlTemplate` after files are indexed, search results continue to use the previous destination until Microsoft 365 updates the index. Updates to a container type's settings can take up to 24 hours to reach existing container type registrations. - -### Search results for already-indexed content require a recrawl - -Setting or updating `urlTemplate` takes effect immediately for Microsoft Graph API responses. However, search results for content that's already indexed continue to use the previously indexed destination until Microsoft 365 recrawls and reindexes that content. Today, there's no self-serve mechanism to trigger a recrawl. - -### `urlTemplate` is scoped to the container type - -The template applies to all container instances of the corresponding container type across all consuming tenants. Use the `{tenant-id}` token to route users to the correct tenant within your application. - -## Related content - -- [Container types](../../getting-started/containertypes.md) -- [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) -- [fileStorageContainerTypeSettings](/graph/api/resources/filestoragecontainertypesettings) -- [Add custom properties to a fileStorageContainer](/graph/api/filestoragecontainer-post-customproperty) -- [Authentication and authorization](../auth.md) diff --git a/docs/embedded/development/content-experiences/office-experience.md b/docs/embedded/development/content-experiences/office-experience.md deleted file mode 100644 index 03f75af649..0000000000 --- a/docs/embedded/development/content-experiences/office-experience.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Office Experiences -description: Overview of Office experiences with SharePoint Embedded content -ms.date: 06/18/2025 -ms.localizationpriority: high ---- - -# Office file experiences for SharePoint Embedded - -Office file experiences for SharePoint Embedded platform will work in a similar manner to Microsoft 365 platform. - -## Opening Office documents from SharePoint Embedded - -Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. AutoSave feature saves your files automatically as your user's work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. - -Documents stored in an archived container can’t be viewed or accessed. Applications must handle the archived state of the container by displaying an appropriate error message and guiding end users on the next steps to regain access, such as reactivating the container. - -## View or restore a previous version of an Office document from SharePoint Embedded - -Versioning is automatically enabled on each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Apps, that helps your users to see what changes have been made in a file, compare different versions, or restore the version you want. This is incredibly important to your users if a mistake was made, a previous version is preferred, or in multi-user coauthoring scenarios when your users are collaborating with others and someone makes changes your users didn't want in a file. - -## Collaborating on Office documents from SharePoint Embedded - -It's simple for your users to collaborate on your SharePoint Embedded Application's Office documents – they can **Share documents** with specific peers or with people outside your organization by Creating a shareable link to use wherever needed, Send an email invitation or @mention in comments to tag someone for feedback and, **Collaborate in real time** by co-authoring in Office with SharePoint Embedded Applications. - -> [!NOTE] -> Mentions require target users to [have an Microsoft 365 license assigned to them](../auth.md#mention-users-in-office-documents). -> -> Mentions are restricted to people inside the consuming tenant's organization. Mentions exclude guests and users from other tenants in a multitenant setting. - -### Share your documents - -#### Send an email invite - -Share your SharePoint Embedded documents by sending an email invitation to specific people: - -- Select Share, start typing the email addresses or contact names of people you want to share with. When you begin to enter info in the box, you can also choose a contact from the list that appears. -- Include a message if you want and hit Send. - -#### Create a shareable link - -Creating a shareable link makes it simple to share your SharePoint Embedded document in an email, document, or IM. - -- Select Share, Copy Link, and Paste the link wherever you want -- Change any permissions of the link if needed - -#### Co-Author - -If you want others to edit with you, you can easily share files and collaborate with trusted peers for a fresh perspective. When you need help with a presentation, you can invite trusted peers to help you get it into shape. This means that when you work on a file, they can as well. You’ll see their changes and they’ll see yours—as you make them! Use @mentions in comments to get someone's attention. - -- See who else is in the document and where they're working. -- A presence indicator shows where someone is making changes. See any changes right as they're being made. -- See changes made by others and see what's happened while you were away. - -#### Levels of sharing access - -There are different options for sharing SharePoint Embedded Application Office Documents from: - -| If you want to … | Sharing Setting to Set | -| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Allow Anyone who receives the link access to SharePoint Embedded Application File | **Anyone**  gives access to anyone who receives this link, whether they receive it directly from you or are forwarded from someone else. This might include people outside of your organization. | -| Allow anyone in your organization to access to your SharePoint Embedded Application File | **People in \** gives anyone in your organization who has the link access to the file, whether they receive it directly from you or forwarded from someone else. | -| Secure your SharePoint Embedded Application docs only to specific people. | When you need to prevent recipients from forwarding a shared link, use the **Specific People**  permission. **Specific people**  gives access only to the people you specify, although other people might already have access. If people forward the sharing invitation, only people who already have access to the item will be able to use the link. | -| Reshare the link with specific people | **People with existing access**  can be used by people who already have access to the document or folder. It doesn't change the permissions on the item. Use this if you just want to send a link to somebody who already has access. | - -## Breadcrumb properties on Office documents from SharePoint Embedded - -Breadcrumb properties are used by Office clients to display breadcrumb-style elements within Office client UI that aid your users in associating Office files with your Application. - -> [!NOTE] -> We recommend specifying 'Current Channel' to take advantage of Breadcrumb patterns and future enhancements to Office Apps. Learn more about [specifying update channels for Office Apps](/deployoffice/updates/overview-update-channels). - -Breadcrumb patterns for SharePoint Embedded Application Apps are constructed from container properties configured for your Apps. The following diagram maps the container properties to breadcrumb presentation in Office clients: - -![Screenshot of breadcrumb pattern in SharePoint Embedded Applications](../../images/office2.png) - -Here are few examples of SharePoint Embedded Application breadcrumb display within Office client experiences. - -![Screenshot of breadcrumb options in SharePoint Embedded Applications.](../../images/office1.png) diff --git a/docs/embedded/development/content-experiences/search-content.md b/docs/embedded/development/content-experiences/search-content.md deleted file mode 100644 index 98afb1bd1a..0000000000 --- a/docs/embedded/development/content-experiences/search-content.md +++ /dev/null @@ -1,832 +0,0 @@ ---- -title: Search SharePoint Embedded containers and content -description: Overview on how to search SharePoint Embedded containers and content -ms.date: 03/28/2025 -ms.localizationpriority: high ---- - -# Search SharePoint Embedded content - -Use the [Microsoft Search](/microsoftsearch/overview-microsoft-search) API in Microsoft Graph to search SharePoint Embedded containers and content. The Search API lets you scope the container type and file type for your queries by specifying the corresponding parameter in the request body. This article describes some examples. - -> [!NOTE] -> -> 1. Searching SharePoint Embedded content is in Preview stage and is subject to change. Please refer to the [exceptional access pattern](../auth.md#operations-involving-searching-sharepoint-embedded-content) that describes its current permission requirements. -> 1. Search API only supports Delegated permissions. -> 1. Your search requests must specify and set the `includeHiddenContent` parameter if your application has opted out of content discoverability in Microsoft 365. Learn more about [SharePoint Embedded content discoverability](./user-experiences-overview.md). - -## Example 1: Search containers by container type - -This example queries all containers by the specified container type with the SharePoint Embedded application opted out from content discoverability on Microsoft 365. The response includes all container instances (`drive`) of the specified container type in the tenant: - -### Request - -```HTTP -POST /search/query -Content-Type: application/json - -{ - "requests": [ - { - "entityTypes": [ - "drive" - ], - "query": { - "queryString": "ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae" - }, - "sharePointOneDriveOptions": { - "includeHiddenContent": true - } - } - ] -} -``` - -### Response - -```HTTP -HTTP/1.1 200 OK -Content-type: application/json - -{ - "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.searchResponse)", - "value": [ - { - "searchTerms": [], - "hitsContainers": [ - { - "hits": [ - { - "hitId": "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0", - "rank": 1, - "summary": "Everything about Contoso", - "resource": { - "@odata.type": "#microsoft.graph.drive", - "id": "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0", - "createdBy": { - "user": { - "displayName": "Dylan Williams" - } - }, - "lastModifiedDateTime": "2024-01-18T19:45:25Z", - "name": "AllItems.aspx", - "parentReference": { - "sharepointIds": { - "listId": "26d6a67d-bd07-4646-9c5b-85b0e519d6f4" - }, - "siteId": "contoso.sharepoint.com,05031a50-e9c7-474c-889e-7cf44659a5b2,e00b849e-3cec-4ade-8f7b-96d1f0f598fa" - }, - "webUrl": "https://contoso.sharepoint.com/contentstorage/CSP_05031a50-e9c7-474c-889e-7cf44659a5b2/Document Library/Forms/AllItems.aspx" - } - } - ], - "total": 1, - "moreResultsAvailable": false - } - ] - } - ] -} -``` - -## Example 2: Search containers by title - -This example queries all containers by a specified container display name and the SharePoint Embedded application didn't opt out from content discoverability on Microsoft 365. The response includes all container instances in the tenant that match the criteria: - -### Request - -```HTTP -POST /search/query -Content-Type: application/json - -{ - "requests": [ - { - "entityTypes": [ - "drive" - ], - "query": { - "queryString": "Title:'contoso' AND ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae" - } - } - ] -} -``` - -### Response - -```HTTP -HTTP/1.1 200 OK -Content-type: application/json - -{ - "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.searchResponse)", - "value": [ - { - "searchTerms": [ - "contoso" - ], - "hitsContainers": [ - { - "hits": [ - { - "hitId": "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0", - "rank": 1, - "summary": "Everything about Contoso", - "resource": { - "@odata.type": "#microsoft.graph.drive", - "id": "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0", - "createdBy": { - "user": { - "displayName": "Dylan Williams" - } - }, - "lastModifiedDateTime": "2024-01-18T19:45:25Z", - "name": "AllItems.aspx", - "parentReference": { - "sharepointIds": { - "listId": "26d6a67d-bd07-4646-9c5b-85b0e519d6f4" - }, - "siteId": "contoso.sharepoint.com,05031a50-e9c7-474c-889e-7cf44659a5b2,e00b849e-3cec-4ade-8f7b-96d1f0f598fa" - }, - "webUrl": "https://contoso.sharepoint.com/contentstorage/CSP_05031a50-e9c7-474c-889e-7cf44659a5b2/Document Library/Forms/AllItems.aspx" - } - } - ], - "total": 1, - "moreResultsAvailable": false - } - ] - } - ] -} -``` - -## Example 3: Search containers by container description - -This example queries all containers by the specified container type and container description, with the SharePoint Embedded application opted out from content discoverability on Microsoft 365. The response includes all container instances in the tenant that match the criteria: - -### Request - -```HTTP -POST /search/query -Content-Type: application/json - -{ - "requests": [ - { - "entityTypes": [ - "drive" - ], - "query": { - "queryString": "Description:'Everything' AND ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae" - }, - "sharePointOneDriveOptions": { - "includeHiddenContent": true - } - } - ] -} -``` - -### Response - -```HTTP -HTTP/1.1 200 OK -Content-type: application/json - -{ - "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.searchResponse)", - "value": [ - { - "searchTerms": [], - "hitsContainers": [ - { - "hits": [ - { - "hitId": "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0", - "rank": 1, - "summary": "Everything about Contoso", - "resource": { - "@odata.type": "#microsoft.graph.drive", - "id": "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0", - "createdBy": { - "user": { - "displayName": "Dylan Williams" - } - }, - "lastModifiedDateTime": "2024-01-18T19:45:25Z", - "name": "AllItems.aspx", - "parentReference": { - "sharepointIds": { - "listId": "26d6a67d-bd07-4646-9c5b-85b0e519d6f4" - }, - "siteId": "contoso.sharepoint.com,05031a50-e9c7-474c-889e-7cf44659a5b2,e00b849e-3cec-4ade-8f7b-96d1f0f598fa" - }, - "webUrl": "https://contoso.sharepoint.com/contentstorage/CSP_05031a50-e9c7-474c-889e-7cf44659a5b2/Document Library/Forms/AllItems.aspx" - } - } - ], - "total": 1, - "moreResultsAvailable": false - } - ] - } - ] -} -``` - -## Example 4: Search for content by title in a specific container - -This example queries all the content by a specific title in a specific container instance, with the SharePoint Embedded application opted out from content discoverability on Microsoft 365. The response includes all `driveItems` in the specific container instance that match the criteria: - -### Request - -```HTTP -POST /search/query -Content-Type: application/json - -{ - "requests": [ - { - "entityTypes": [ - "driveItem" - ], - "query": { - "queryString": "Title:'contoso' AND ContainerId:b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0" - }, - "sharePointOneDriveOptions": { - "includeHiddenContent": true - } - } - ] -} -``` - -### Response - -```HTTP -HTTP/1.1 200 OK -Content-type: application/json - -{ - "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.searchResponse)", - "value": [ - { - "searchTerms": [ - "contoso", - "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0" - ], - "hitsContainers": [ - { - "hits": [ - { - "hitId": "01SHAK4OWIBDXV4NG2JVFLSGUXVKZ5VF5E", - "rank": 1, - "summary": "Contoso Detailed Design Contoso Product Specification", - "resource": { - "@odata.type": "#microsoft.graph.driveItem", - "size": 56, - "fileSystemInfo": { - "createdDateTime": "2024-01-18T19:46:48Z", - "lastModifiedDateTime": "2024-01-18T19:46:48Z" - }, - "listItem": { - "@odata.type": "#microsoft.graph.listItem", - "fields": {}, - "id": "5eef08c8-da34-4a4d-b91a-97aab3da97a4" - }, - "id": "01SHAK4OWIBDXV4NG2JVFLSGUXVKZ5VF5E", - "createdBy": { - "user": { - "displayName": "Dylan Williams", - "email": "dywilliams@contoso.onmicrosoft.com" - } - }, - "createdDateTime": "2024-01-18T19:46:48Z", - "lastModifiedBy": { - "user": { - "displayName": "Dylan Williams", - "email": "dywilliams@contoso.onmicrosoft.com" - } - }, - "lastModifiedDateTime": "2024-01-18T19:46:48Z", - "name": "contoso.txt", - "parentReference": { - "driveId": "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0", - "id": "01SHAK4OVPJ5Q5P6YD6VCZHPV7PKILUJ65", - "sharepointIds": { - "listId": "26d6a67d-bd07-4646-9c5b-85b0e519d6f4", - "listItemId": "1", - "listItemUniqueId": "5eef08c8-da34-4a4d-b91a-97aab3da97a4" - }, - "siteId": "contoso.sharepoint.com,05031a50-e9c7-474c-889e-7cf44659a5b2,e00b849e-3cec-4ade-8f7b-96d1f0f598fa" - }, - "webUrl": "https://contoso.sharepoint.com/contentstorage/CSP_05031a50-e9c7-474c-889e-7cf44659a5b2/Document Library/contoso.txt" - } - } - ], - "total": 1, - "moreResultsAvailable": false - } - ] - } - ] -} -``` - -## Example 5: Search by content - -This example queries all the content by the specified words across all containers of a specific container type, with the SharePoint Embedded application opted out from content discoverability on Microsoft 365. The response includes all `driveItems` that match the criteria: - -### Request - -```HTTP -POST /search/query -Content-Type: application/json - -{ - "requests": [ - { - "entityTypes": [ - "driveItem" - ], - "query": { - "queryString": "'contoso' AND ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae" - }, - "sharePointOneDriveOptions": { - "includeHiddenContent": true - } - } - ] -} -``` - -### Response - -```HTTP -HTTP/1.1 200 OK -Content-type: application/json - -{ - "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.searchResponse)" - "value": [ - { - "searchTerms": [ - "contoso" - ], - "hitsContainers": [ - { - "hits": [ - { - "hitId": "01SHAK4OWIBDXV4NG2JVFLSGUXVKZ5VF5E", - "rank": 1, - "summary": "Contoso Detailed Design Contoso Product Specification", - "resource": { - "@odata.type": "#microsoft.graph.driveItem", - "size": 56, - "fileSystemInfo": { - "createdDateTime": "2024-01-18T19:46:48Z", - "lastModifiedDateTime": "2024-01-18T19:46:48Z" - }, - "listItem": { - "@odata.type": "#microsoft.graph.listItem", - "fields": {}, - "id": "5eef08c8-da34-4a4d-b91a-97aab3da97a4" - }, - "id": "01SHAK4OWIBDXV4NG2JVFLSGUXVKZ5VF5E", - "createdBy": { - "user": { - "displayName": "Dylan Williams", - "email": "dywilliams@contoso.onmicrosoft.com" - } - }, - "createdDateTime": "2024-01-18T19:46:48Z", - "lastModifiedBy": { - "user": { - "displayName": "Dylan Williams", - "email": "dywilliams@contoso.onmicrosoft.com" - } - }, - "lastModifiedDateTime": "2024-01-18T19:46:48Z", - "name": "contoso.txt", - "parentReference": { - "driveId": "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0", - "id": "01SHAK4OVPJ5Q5P6YD6VCZHPV7PKILUJ65", - "sharepointIds": { - "listId": "26d6a67d-bd07-4646-9c5b-85b0e519d6f4", - "listItemId": "1", - "listItemUniqueId": "5eef08c8-da34-4a4d-b91a-97aab3da97a4" - }, - "siteId": "contoso.sharepoint.com,05031a50-e9c7-474c-889e-7cf44659a5b2,e00b849e-3cec-4ade-8f7b-96d1f0f598fa" - }, - "webUrl": "https://contoso.sharepoint.com/contentstorage/CSP_05031a50-e9c7-474c-889e-7cf44659a5b2/Document Library/contoso.txt" - } - } - ], - "total": 1, - "moreResultsAvailable": false - } - ] - } - ] -} -``` -## Example 6: Search containers by container custom property - -This example queries all containers by the specified custom property key:value pair, with the SharePoint Embedded application that has opted out from content discoverability on Microsoft 365. The response includes all containers that match the criteria: - -> [!NOTE] -> The custom property name must be appended with the text "OWSTEXT" in the query string. - -### Request - -```HTTP -POST /search/query -Content-Type: application/json - -{ - "requests": [ - { - "entityTypes": [ - "drive" - ], - "query": { - "queryString": "customPropertyNametOWSTEXT:customPropertyValue AND ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae" - }, - "sharePointOneDriveOptions": { - "includeHiddenContent": true - } - } - ] -} -``` - -### Response - -```HTTP -HTTP/1.1 200 OK -Content-type: application/json - -{ - "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.searchResponse)", - "value": [ - { - "searchTerms": [], - "hitsContainers": [ - { - "hits": [ - { - "hitId": "b!C4Psl-ZZZkaZINVay8RKt2fqu3agJbVNlIUjNuIzqlPhOJMrr7ThS4aR8L8XdZu4", - "rank": 1, - "summary": "Everything about Contoso", - "resource": { - "@odata.type": "#microsoft.graph.drive", - "id": "b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0", - "createdBy": { - "user": { - "displayName": "Dylan Williams" - } - }, - "lastModifiedDateTime": "2024-08-02T17:31:06Z", - "name": "AllItems.aspx", - "parentReference": { - "sharepointIds": { - "listId": "2b9338e1-b4af-4be1-8691-f0bf17759bb8" - }, - "siteId": "contoso.sharepoint.com,97ec830b-59e6-4666-9920-d55acbc44ab7,76bbea67-25a0-4db5-9485-2336e233aa53" - }, - "webUrl": "https://contoso.sharepoint.com/contentstorage/CSP_97ec830b-59e6-4666-9920-d55acbc44ab7/Document Library/Forms/AllItems.aspx" - } - } - ], - "total": 1, - "moreResultsAvailable": false - } - ] - } - ] -} -``` -## Example 7: Search for content with specific content properties in the response body and sort the results - -This example queries container content by specific words and requires the response to include all specified attributes on the content. Properties that are [sortable](/sharepoint/technical-reference/crawled-and-managed-properties-overview) can be used to sort the results. - -### Request - -```HTTP -POST /search/query -Content-Type: application/json - -{ - "requests": [ - { - "entityTypes": [ - "driveItem" - ], - "query": { - "queryString": "Everything about contoso" - }, - "sharePointOneDriveOptions": { - "includeHiddenContent": true - }, - "fields": [ - "SampleOWSText", - "id", - "name", - "parentReference", - "file", - "folder", - "webUrl", - "createdDateTime", - "lastModifiedDateTime", - "size", - "fileSystemInfo", - "createdBy", - "lastModifiedBy", - "fileSystemInfo", - "fileSystemInfo" - ], - "sortProperties": [ - { - "name": "Created", - "isDescending": false - } - ] - } - ] -} -``` - -### Response - -```HTTP -HTTP/1.1 200 OK -Content-type: application/json - -{ - "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.searchResponse)", - "value": [ - { - "searchTerms": [ - "everything", - "about", - "contoso" - ], - "hitsContainers": [ - { - "hits": [ - { - "hitId": "017JL52SWZQ2M5MULUKFBIL7SZ56EB4V2Z", - "rank": 1, - "summary": "Everything about Contoso", - "resource": { - "@odata.type": "#microsoft.graph.driveItem", - "size": 17363, - "fileSystemInfo": { - "createdDateTime": "2024-06-20T21:49:03Z", - "lastModifiedDateTime": "2024-04-01T16:57:00Z" - }, - "listItem": { - "@odata.type": "#microsoft.graph.listItem", - "id": "d69986d9-7451-4251-85fe-59ef881e5759", - "fields": { - "sampleOWSText": "Sample Value", - "id": "AAAAAH_MwHAjYctMtjgTN1cWJnYHAApvY20ubJFGtzLui9sETKcAAAAAASsAAApvY20ubJFGtzLui9sETKcAAAAAJqsAAA2", - "size": 17363, - "createdBy": "Dylan Williams" - } - }, - "id": "017JL52SWZQ2M5MULUKFBIL7SZ56EB4V2Z", - "createdBy": { - "user": { - "displayName": "Dylan Williams", - "email": "dywilliams@contoso.onmicrosoft.com" - } - }, - "createdDateTime": "2024-06-20T21:49:03Z", - "lastModifiedBy": { - "user": { - "displayName": "Dylan Williams", - "email": "dywilliams@contoso.onmicrosoft.com" - } - }, - "lastModifiedDateTime": "2024-04-01T16:57:00Z", - "name": "Constoso Details.docx", - "parentReference": { - "driveId": "b!rWzsZXXFWEOeeP31bSE5BTjn_6qC3dFNloUBMv62EMilewHuRwQrQau-zcJu2BT0", - "id": "017JL52SXQSKBKPB7VKZCJE5ZSWUN4LZDZ", - "sharepointIds": { - "listId": "ee017ba5-0447-412b-abbe-cdc26ed814f4", - "listItemId": "1", - "listItemUniqueId": "d69986d9-7451-4251-85fe-59ef881e5759" - }, - "siteId": "contoso.sharepoint.com,65ec6cad-c575-4358-9e78-fdf56d213905,aaffe738-dd82-4dd1-9685-0132feb610c8" - }, - "webUrl": "https://contoso.sharepointt.com/contentstorage/CSP_65ec6cad-c575-4358-9e78-fdf56d213905/Document Library/Constoso Details.docx" - } - } - ], - "total": 1, - "moreResultsAvailable": false - } - ] - } - ] -} -``` - -## Known Limitations - -- Search requests run in the context of the signed-in user. Search results are only scoped to enforce any access control applied to the items by the user. For example, search results will include all container or container content matching the search criteria and accessible by the user regardless of whether the SharePoint Embedded application is authorized to access. You should specify the desired container type by including the ContainerTypeId as part of your **queryString** when searching for containers or container content to ensure search results are properly scoped. -- For your application to access the containers or container content in search results, it must have access permissions to the corresponding container types. - -## Enumerate (filter) SharePoint Embedded content - -Content can also be enumerated using URL parameters to return specific content in SharePoint Embedded containers. This does not use the search API to retrieve items. See the [enumerate query parameter](/graph/filter-query-parameter?tabs=http) for reference. - -## Example 1: enumerate content by a specific column property and view the results - -This example enumerates the specified container content by the column property that is on the item: - -### Request - -```HTTP -GET https://graph.microsoft.com/v1.0/drives/{{ContainerID}}/items?$filter=startswith(listitem/fields/{{ColumnProperty}}, '{{Value}}')&$expand=listitem($expand=fields) -``` - -### Response - -```HTTP -HTTP/1.1 200 OK -Content-type: application/json -{ - "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#drives('b%21CORq-a8orUGIrd3_z9t1_vjCBSeqM3JKhDglEU3DIDvEl-Hms0qoQ7QCWYNQfGOF')/items(listItem(fields()))", - "value": [ - { - "@odata.etag": "\"{B8051D89-836E-4B8E-BD2B-7634BAC92825},21\"", - "@microsoft.graph.downloadUrl": "https://.sharepoint.com/contentstorage/CSP_f96ae408-28af-41ad-88ad-ddffcfdb75fe/_layouts/15/download.aspx?UniqueId=b8051d89-836e-4b8e-bd2b-7634bac92825&Translate=false&tempauth=v1.eyJzaXRlaWQiOiJmOTZhZTQwOC0yOGFmLTQxYWQtODhhZC1kZGZmY2ZkYjc1ZmUiLCJhcHBfZGlzcGxheW5hbWUiOiJTUEUtQmFzZWJhbGwiLCJhcHBpZCI6ImZiN2NmNTIwLWNiMzMtNDViZi1hMjM4LWFlNTFkMzE2NjY1ZiIsImF1ZCI6IjAwMDAwMDAzLTAwMDAtMGZmMS1jZTAwLTAwMDAwMDAwMDAwMC9wdWNlbGlrZW50ZXJwcmlzZS5zaGFyZXBvaW50LmNvbUAxNTNhNmViZS1mZjYyLTRiY2UtYjFiYy1hMWVkYTNiYzY2NDUiLCJleHAiOiIxNzMxNjE3MDE3In0.CgoKBHNuaWQSAjY5EgsIzpKzp9W7wj0QBRoNMjAuMTkwLjEzNS40MioscW54cjFGalBneHh2N1lGTkp1dUpxTFZWdFFIS1hOQ2RlQ3EvUUk2aHhlcz0wuAE4AUIQoWPmC1YwAABF4iHcgCWrfkoQaGFzaGVkcHJvb2Z0b2tlbnIpMGguZnxtZW1iZXJzaGlwfDEwMDM3ZmZlOWE5NDg5ZGRAbGl2ZS5jb216ATKCARIJvm46FWL_zksRsbyh7aO8ZkWSAQVTdGV2ZZoBB1B1Y2VsaWuiASdzdGV2ZUBwdWNlbGlrZW50ZXJwcmlzZS5vbm1pY3Jvc29mdC5jb22qARAxMDAzN0ZGRTlBOTQ4OUREsgFyY29udGFpbmVyLnNlbGVjdGVkIGFsbGZpbGVzLnJlYWQgYWxsZmlsZXMud3JpdGUgY29udGFpbmVyLnNlbGVjdGVkIGFsbHNpdGVzLnJlYWQgYWxscHJvZmlsZXMucmVhZCBhbGxwcm9maWxlcy5yZWFkyAEB.tfaYgtjhQxMctJeHUWb9RU7CChHXqFHT0FaM9Dt7J9I&ApiVersion=2.1", - "createdDateTime": "2024-09-20T16:46:00Z", - "eTag": "\"{B8051D89-836E-4B8E-BD2B-7634BAC92825},21\"", - "id": "01UELPCREJDUC3Q3UDRZF32K3WGS5MSKBF", - "lastModifiedDateTime": "2024-11-01T08:14:28Z", - "name": "ClaimExample-1.docx", - "size": 2299607, - "webUrl": "https://.sharepoint.com/contentstorage/CSP_f96ae408-28af-41ad-88ad-ddffcfdb75fe/_layouts/15/Doc.aspx?sourcedoc=%7BB8051D89-836E-4B8E-BD2B-7634BAC92825%7D&file=ClaimExample-1.docx&action=default&mobileredirect=true", - "cTag": "\"c:{B8051D89-836E-4B8E-BD2B-7634BAC92825},5\"", - "commentSettings": { - "commentingDisabled": { - "isDisabled": false - } - }, - "createdBy": { - "application": { - "displayName": "SPEContainerType", - "id": "fb7cf520-cb33-45bf-a238-ae51d316665f" - }, - "user": { - "displayName": "SharePoint App" - } - }, - "lastModifiedBy": { - "application": { - "displayName": "SPEContainerType", - "id": "fb7cf520-cb33-45bf-a238-ae51d316665f" - }, - "user": { - "displayName": "Steve Pucelik", - "email": "Steve@.onmicrosoft.com" - } - }, - "parentReference": { - "driveId": "b!CORq-a8orUGIrd3_z9t1_vjCBSeqM3JKhDglEU3DIDvEl-Hms0qoQ7QCWYNQfGOF", - "driveType": "other", - "id": "01UELPCRF6Y2GOVW7725BZO354PWSELRRZ", - "path": "/drives/b!CORq-a8orUGIrd3_z9t1_vjCBSeqM3JKhDglEU3DIDvEl-Hms0qoQ7QCWYNQfGOF/root:", - "sharepointIds": { - "listId": "e6e197c4-4ab3-43a8-b402-5983507c6385", - "listItemUniqueId": "c4782251-bdd3-4766-a747-b2a2f51c3a00", - "siteId": "f96ae408-28af-41ad-88ad-ddffcfdb75fe", - "siteUrl": "https://.sharepoint.com/contentstorage/CSP_f96ae408-28af-41ad-88ad-ddffcfdb75fe", - "tenantId": "153a6ebe-ff62-4bce-b1bc-a1eda3bc6645", - "webId": "2705c2f8-33aa-4a72-8438-25114dc3203b" - } - }, - "file": { - "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", - "hashes": { - "quickXorHash": "DMzi0kCsuukcHlMXiPX9tmTCXtA=" - } - }, - "fileSystemInfo": { - "createdDateTime": "2024-09-20T16:46:00Z", - "lastModifiedDateTime": "2024-11-01T08:14:28Z" - }, - "shared": { - "scope": "unknown" - }, - "listItem@odata.context": "https://graph.microsoft.com/v1.0/$metadata#drives('b%21CORq-a8orUGIrd3_z9t1_vjCBSeqM3JKhDglEU3DIDvEl-Hms0qoQ7QCWYNQfGOF')/items('01UELPCREJDUC3Q3UDRZF32K3WGS5MSKBF')/listItem(fields())/$entity", - "listItem": { - "@odata.etag": "\"{B8051D89-836E-4B8E-BD2B-7634BAC92825},21\"", - "createdDateTime": "2024-09-20T16:46:00Z", - "eTag": "\"{B8051D89-836E-4B8E-BD2B-7634BAC92825},21\"", - "id": "23", - "lastModifiedDateTime": "2024-11-01T08:14:28Z", - "webUrl": "https://.sharepoint.com/contentstorage/CSP_f96ae408-28af-41ad-88ad-ddffcfdb75fe/_layouts/15/Doc.aspx?sourcedoc=%7BB8051D89-836E-4B8E-BD2B-7634BAC92825%7D&file=ClaimExample-1.docx&action=default&mobileredirect=true", - "createdBy": { - "application": { - "displayName": "SPEContainerType", - "id": "fb7cf520-cb33-45bf-a238-ae51d316665f" - }, - "user": { - "displayName": "SharePoint App" - } - }, - "lastModifiedBy": { - "application": { - "displayName": "SPEContainerType", - "id": "fb7cf520-cb33-45bf-a238-ae51d316665f" - }, - "user": { - "displayName": "Steve Pucelik", - "email": "Steve@M.onmicrosoft.com" - } - }, - "parentReference": { - "id": "0", - "path": "Document Library", - "siteId": "f96ae408-28af-41ad-88ad-ddffcfdb75fe" - }, - "contentType": { - "id": "0x0101004368E78BC3115C4CAD94FEA35E0F9D90", - "name": "Document" - }, - "fields@odata.context": "https://graph.microsoft.com/v1.0/$metadata#drives('b%21CORq-a8orUGIrd3_z9t1_vjCBSeqM3JKhDglEU3DIDvEl-Hms0qoQ7QCWYNQfGOF')/items('01UELPCREJDUC3Q3UDRZF32K3WGS5MSKBF')/listItem/fields/$entity", - "fields": { - "@odata.etag": "\"{B8051D89-836E-4B8E-BD2B-7634BAC92825},21\"", - "id": "23", - "FileLeafRef": "ClaimExample-1.docx", - "": "", - "ContentType": "Document", - "Created": "2024-09-20T16:46:00Z", - "AuthorLookupId": "1073741822", - "Modified": "2024-11-01T08:14:28Z", - "EditorLookupId": "7", - "_CheckinComment": "", - "LinkFilenameNoMenu": "ClaimExample-1.docx", - "LinkFilename": "ClaimExample-1.docx", - "DocIcon": "docx", - "FileSizeDisplay": "2299607", - "ItemChildCount": "0", - "FolderChildCount": "0", - "_ComplianceFlags": "", - "_ComplianceTag": "", - "_ComplianceTagWrittenTime": "", - "_ComplianceTagUserId": "", - "_CommentCount": "", - "_LikeCount": "", - "_DisplayName": "Confidential \\ Internal only", - "AppAuthorLookupId": "1", - "AppEditorLookupId": "1", - "Edit": "0", - "_UIVersionString": "19.0", - "MediaServiceImageTags@odata.type": "#Collection(microsoft.graph.Json)", - "MediaServiceImageTags": [] - } - } - } - ] -} -``` - -## Example 2: Enumerate content by a specific column property and Order the results - -This example enumerates the specified container content by the column property that is on the item and will order the results by the column specified: - -### Request - -```HTTP -GET https://graph.microsoft.com/v1.0/drives/{{ContainerID}}/items?$filter=listitem/fields/{{ColumnProperty}} eq '{{Value}}'&$select=id,name,lastModifiedDateTime,size&$expand=listitem($expand=fields)&$orderby=createdDateTime desc -Headers: -Content-Type: application/json -Prefer: HonorNonIndexedQueriesWarningMayFailRandomly -``` - -> [!NOTE] -> -> When a container has more than 5,000 items and you are using the enumerate method with the OrderBy clause, you must include the following in the header of your request. -> -> `Content-Type: application/json` -> `Prefer: HonorNonIndexedQueriesWarningMayFailRandomly` -## Example 3: Enumerate content by mulitple column properties and Order the results - -This example enumerates the specified container content by the column property you specify and the name of the document (listitem/fields/FileLeafRef) that is on the item and will order the results by the column specified: - -### Request - -```HTTP -GET https://graph.microsoft.com/v1.0/drives/{{ContainerID}}/items?$filter=listitem/fields/{{ColumnProperty1}} eq '{{Value}}' AND listitem/fields/FileLeafRef eq '{{Value}}' &$select=id,name,lastModifiedDateTime,size&$expand=listitem($expand=fields)&$orderby=createdDateTime desc -Headers: -Content-Type: application/json -Prefer: HonorNonIndexedQueriesWarningMayFailRandomly -``` \ No newline at end of file diff --git a/docs/embedded/development/content-experiences/user-experiences-overview.md b/docs/embedded/development/content-experiences/user-experiences-overview.md deleted file mode 100644 index b54e0205ff..0000000000 --- a/docs/embedded/development/content-experiences/user-experiences-overview.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Content Experiences Overview -description: Experiences with SharePoint Embedded content -ms.date: 07/30/2024 -ms.localizationpriority: high ---- - -# User experiences overview - -SharePoint Embedded provides a comprehensive set of user experience features like open and editing Office files, file preview, or in-app search that you can use to build the right user experiences for your applications. - -## Open & edit using Office - -Office documents from SharePoint Embedded applications can be opened for viewing, editing, and collaborating using either the web or Office applications for a richer viewing and editing experience. Learn more about [Office experiences available on SharePoint Embedded](./office-experience.md). - -You can set up your applications to launch Office when a user selects an Office document within your application. This includes options to directly launch an Office application or to open it in a specific mode, such as view (for read-only content) or edit (for editing mode). Learn how to [configure the right Office Experience for your Office Documents](../tutorials/launch-experience.md) - -## Preview content - -Integrate your application with SharePoint Embedded player plugin to offer file preview experiences on a wide range of supported file types. You can embed the file preview experiences either in an iFrame or open a new page. Learn how to [offer File Preview experiences for content on your applications](../tutorials/using-file-preview.md) - -## Download - -You can use [Microsoft Graph's Download DriveItem API](/graph/api/driveitem-get-content) to offer download file user experiences for your applications. This will generate a short-lived, pre-authenticated URL that allows users to download files from your applications. - -> [!NOTE] -> A direct link to the file lacks the appropriate authorization from your application. If used directly in a browser, this would yield an access denied. - -## Content discovery in Microsoft 365 - -You can control how your content appears in the Microsoft 365 experience. The default behavior is SharePoint Embedded application content will be hidden in Microsoft 365 environments including office.com, oneDrive.com, or other Microsoft intelligent file discovery features. The default behavior also excludes Copilot for Microsoft 365 from grounding with your SharePoint Embedded application content. - -If you want to opt into the Microsoft 365 experience, during container type creation, you can change the default settings using cmdlet [Set-SPOContainerTypeConfiguration](../../administration/developer-admin/dev-admin.md#container-type-configuration-properties) as per this example: - -```powershell -Set-SPOContainerTypeConfiguration - -ContainerTypeID - -discoverabilityDisabled $False -``` - -In this way, your files will be integrated into the Microsoft 365 environment, participating in intelligent file discovery. - -> [!NOTE] -> -> 1. If you modify the settings after creating some content, it may take up to 30 days for these changes to achieve full consistency across all consuming tenants. -> 1. To enable the sharing user experience for your content in Office.com, additional application permissions **must** be added at the time of the container type registration process. To add more permission to enable sharing dialog, refer to the following code: - -```http -PUT /storageContainerTypes/{containerTypeId}/applicationPermissions -Content-Type: application/json - -{ - "appId": "4765445b-32c6-49b0-83e6-1d93765276ca", - "delegated": ["readContent","writeContent"], - "appOnly": ["none"] -} -``` - -## Archived containers - -You can use Microsoft Graph to archive containers, which moves the container’s data to the cold storage tier and helps reduce storage costs. - -While a container is archived, it can’t be accessed by any user or application. To access the container again, it must be reactivated. If the data is no longer required, archived containers can be deleted without first reactivating them. - -## Recycle bin - -You can use Microsoft Graph to either delete or permanently delete items in containers. Deleted items are moved to the container’s recycle bin and retained for 93 days. During this period, the items can be restored or permanently deleted using Microsoft Graph. An item in the recycle bin is permanently deleted when it exceeds the 93-day retention period. Permanently deleted items can't be restored. diff --git a/docs/embedded/development/declarative-agent/sharepoint-embedded-knowledge-source.md b/docs/embedded/development/declarative-agent/sharepoint-embedded-knowledge-source.md deleted file mode 100644 index 52e2f34c4e..0000000000 --- a/docs/embedded/development/declarative-agent/sharepoint-embedded-knowledge-source.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Set up SharePoint Embedded as a knowledge source in Microsoft Foundry -description: Instructions to configure SPE in Azure's knowledge retrieval -ms.date: 11/12/2025 -ms.localizationpriority: high ---- - -# Set up SharePoint Embedded as a knowledge source in Microsoft Foundry (Preview) - -> [!NOTE] -> -> This functionality is currently in preview. - -This article helps you configure [Microsoft Foundry Agent Service](/azure/foundry/agents/overview) with a [SharePoint knowledge source (Preview)](/azure/search/agentic-knowledge-source-how-to-sharepoint-remote) configured for SharePoint Embedded (SPE). - -## Prerequisites - -- You have set up an SPE app with at least one container. To get started, learn more at [SharePoint Embedded Overview](../../overview.md). -- You have at least one Copilot license on your tenant. This requirement is for the preview period only. We will switch to metered billing once we transition out of preview. - -## Set up the SharePoint knowledge source for SharePoint Embedded - -The SharePoint knowledge source must be configured with the `remoteSharePointParameters.containerTypeId` pointing to your application's container type. For more information, see the [SharePoint knowledge source properties](/azure/search/agentic-knowledge-source-how-to-sharepoint-remote#source-specific-properties). - -## Grant Foundry access to a container type - -You also need to grant Microsoft Foundry the necessary application permission to access your container type. You can do this by updating the container type registration in your consuming tenants as shown below. Replace `{fileStorageContainerTypeId}` with your container type ID. The container type's owning application must call this API on consuming tenants. - -```http -PUT /storage/fileStorage/containerTypeRegistrations/{fileStorageContainerTypeId}/applicationPermissionGrants/880da380-985e-4198-81b9-e05b1cc53158 -Content-Type: application/json - -{ - "delegatedPermissions": ["readContent"], - "applicationPermissions": ["none"] -} -``` - -> [!TIP] -> This may also be done during initial container type registration using the [Create container type registration](/graph/api/filestorage-post-containertyperegistrations) endpoint. diff --git a/docs/embedded/development/declarative-agent/spe-da-adv.md b/docs/embedded/development/declarative-agent/spe-da-adv.md deleted file mode 100644 index b6c0d00da7..0000000000 --- a/docs/embedded/development/declarative-agent/spe-da-adv.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -title: SharePoint Embedded agent Advanced Topics -description: Learn how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses in SharePoint Embedded agent. -ms.date: 03/06/2025 -ms.localizationpriority: high ---- - -# SharePoint Embedded agent Advanced Topics Overview - -> [!CAUTION] -> SharePoint Embedded agent has been deprecated in its current form and replaced with [Microsoft Foundry Agent Service](/azure/foundry/agents/overview) with a [SharePoint knowledge source (Preview)](/azure/search/agentic-knowledge-source-how-to-sharepoint-remote) configured for SharePoint Embedded. Learn how to [set up SharePoint Embedded as a knowledge source in Microsoft Foundry](sharepoint-embedded-knowledge-source.md). - -This article will remain in place for a limited time for historical reference. - -This advanced guide covers how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses. We explore how these concepts work together to ensure your agent retrieves relevant information from your data and returns grounded answers. - -## Caveats - -### Configuration - -#### Required Container Type Configuration - -##### DiscoverabilityDisabled - -The [`discoverabilityDisabled`](../../administration/developer-admin/dev-admin.md#container-type-configuration-properties) property controls whether Microsoft 365 can discover [drive items](/graph/api/resources/driveitem) within a specific container type. - -If you’re updating an existing container type to set this property to `false`, allow up to **24 hours** for the configuration change to fully propagate before: - -- Creating new containers, -- Uploading files to containers, or -- Using SPE agent to interact with folders or files. - -This ensures the agent can correctly access and surface the content. - -Here's an example of how to set `discoverabilityDisabled` to `false` with [Set-SPOContainerTypeConfiguration](/powershell/module/SharePoint-online/set-spocontainertypeconfiguration#examples) - -```powershell -Set-SPOContainerTypeConfiguration -ContainerTypeId 4f0af585-8dcc-0000-223d-661eb2c604e4 -DiscoverabilityDisabled $false -``` - -Discoverability can also be disabled using the Visual Studio Code SharePoint Embedded extension - -![Using the VS Code extension for SPE to set DiscoverabilityDisabled to false](../../images/speco-vscodeextensiondisablediscovery.png) - -##### CSP Policies - -The Content-Security-Policy (CSP) for embedded chat hosts ensures that only specified hosts can load the chat component. Specifically, the `CopilotEmbeddedChatHosts` setting is used in a [Content-Security-Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) header as a `frame-ancestors` value. This helps in securing the application by restricting which domains can embed the chat component. - -The SPE Administrator on the owning tenant can set this setting by using the `Set-SPOContainerTypeConfiguration` cmdlet: - -```powershell -# Note this MUST be run in Windows PowerShell. It will not work in PowerShell. -Import-Module -Name "Microsoft.Online.SharePoint.PowerShell" -Connect-SPOService "https://-admin.sharepoint.com" -# Login with your admin account. -# ... - -Set-SPOContainerTypeConfiguration -ContainerTypeId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -CopilotEmbeddedChatHosts @("http://localhost:3000", "https://contoso.sharepoint.com", "https://fabrikam.com") - -# This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly. -# Replication of this configuration on consuming tenants can take up to 24 hours -# ... - -# Confirm setting value -Get-SPOContainerTypeConfiguration -ContainerTypeId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX - -# On a consuming tenant, you may confirm the setting value as follows -Get-SPOApplication -OwningApplicationId | Select-Object CopilotEmbeddedChatHosts - -OwningApplicationId : -OwningApplicationName : SharePoint Embedded App -Applications : {} -CopilotEmbeddedChatHosts : {http://localhost:3000, https://contoso.sharepoint.com, https://fabrikam.com} -``` - -> [!NOTE] -> -> If this configuration isn't set, the [Content-Security-Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) is by default set to -> [frame-ancestors](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors): "none", which means no one can embed the agent. - -A SharePoint Embedded Administrator on a consuming tenant may override the values specified by the owning application, by using the consuming tenant cmdlets: - -- [Set-SPOApplication](/powershell/module/SharePoint-online/set-spoapplication) to set the `CopilotEmbeddedChatHosts` property. -- [Get-SPOApplication](/powershell/module/SharePoint-online/get-spoapplication) to get the `CopilotEmbeddedChatHosts` property. - -> [!NOTE] -> -> A consuming tenant override must be a subset of what the owning tenant configured for `CopilotEmbeddedChatHosts`. An administrator -> in a consuming tenant can't set values that the application owner hasn't specified for the container type. The override capability is intended for consuming tenant administrators to enable the agent in only a subset of hosts that the owning application has defined. - -Here's an example of how a consuming tenant can override the setting: - -```powershell -# Note this MUST be run in Windows PowerShell. It will not work in PowerShell. -Import-Module -Name "Microsoft.Online.SharePoint.PowerShell" -Connect-SPOService "https://-admin.sharepoint.com" -# Login with your admin account. -# ... - -Set-SPOApplication -OwningApplicationId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -CopilotEmbeddedChatHosts @("https://contoso.sharepoint.com", "https://fabrikam.com") - -# This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly -# Note that @("https://contoso.sharepoint.com", "https://fabrikam.com") is a subset of what we defined in the owning tenant -# Those values were @("http://localhost:3000", "https://contoso.sharepoint.com", "https://fabrikam.com") - -# Confirm the configuration - -Get-SPOApplication -OwningApplicationId | Select-Object CopilotEmbeddedChatHosts - -OwningApplicationId : -OwningApplicationName : SharePoint Embedded App -Applications : {} -CopilotEmbeddedChatHosts : {https://contoso.sharepoint.com, https://fabrikam.com} -``` - -#### Optional Configuration - -##### Authentication and Third-Party Cookies - -The `iframe` used by SharePoint Embedded agent authenticates users using third-party cookies. If third-party cookies are disabled in the user's browser, the iframe can't authenticate automatically. In this case, a popup prompts the user to sign in manually, ensuring that authentication can still be completed. - -## Advanced Topics - -### Application Scoping - -Application scoping in SharePoint Embedded agent (SPE agent) involves defining the boundaries and context within which the tool operates, ensuring its features and capabilities are tailored to meet the specific needs of different applications. This process helps customize the agent's functionality, making it more effective and relevant for various use cases. - -When SPE agent users query the LLM, it will only have access to files that the **User+Application** have access to. The effective permissions for the agent session will be the intersection of your SharePoint Embedded application's permissions and the user's permissions. - -![Venn Diagram with SPE application access on left, SPE agent in middle and consuming tenant user on right, overlapped area is what agent can access](../../images/speco-appscopingvenn.png) - -### Information Architecture - -Files in SharePoint Embedded are naturally [semantic indexed](spe-da-adv.md#semantic-index). This semantic index underpins retrieval augmented generation [(RAG)](spe-da-adv.md#retrieval-augmented-generation-rag) workflows by providing relevant context from your stored content at query time. In essence, it [grounds](spe-da-adv.md#grounding) the AI responses, ensuring they directly reference accurate information in your containers rather than relying on general knowledge alone. - -![How RAG works in SPE](../../images/speco-ragm365.png) - -With SharePoint Embedded agent, you can further ground the large language models (LLM) response on [specific files or drive items.](spe-da-adv.md#scoping-your-agent-to-specific-content). - -### Semantic index - -[Learn more about semantic index for Microsoft 365 Copilot here](/microsoftsearch/semantic-index-for-copilot) - -The semantic index allows for quick and accurate searches based on data similarity. This means it can find the most relevant information not just by exact matches, but also by understanding the context and meaning. - -### Retrieval-Augmented Generation (RAG) - -RAG enables you to reference relevant source materials stored in a repository at runtime. The data is retrieved from the index and is used to augment the prompt sent to the large language model (LLM). Some benefits of RAG​: - -- Treat data sources as knowledge without having to train your model​ -- Uses search (retrieval) results as additional context in your prompt​ -- Generates the output using the prompt and the supplied context - -The LLM uses the data to inform and construct the response. - -​![The flow of a RAG query](../../images/speco-ragquery.png) - -### Grounding - -Grounding in the context of SPE agent refers to the process of providing input sources to the large language model (LLM) related to the user's prompt. This helps improve the specificity of the prompt and ensures that the responses are relevant and actionable to the user's specific task. The data the agent is grounded on will be the contents of the container type in the agent application. Behind the scenes, SPE agent uses Microsoft 365 Copilot. [Learn more about Microsoft 365 Copilot architecture](/copilot/microsoft-365/microsoft-365-copilot-architecture). - -### Scoping your agent to specific content - -SharePoint Embedded (SPE) agent has the ability to restrict the data sources it has access to. The sample code below shows the available data source types. [This example](https://github.com/microsoft/SharePoint-Embedded-Samples/blob/main/Custom%20Apps/boilerplate-typescript-react/react-client/src/providers/ChatController.ts#L15) shows how to configure the SDK. - -```typescript -export type IDataSourcesProps = - | IFileDataSource - | IFolderDataSource - | IDocumentLibraryDataSource - | ISiteDataSource - | IWorkingSetDataSource - | IMeetingDataSource; - -export enum DataSourceType { - File = 'File', - Folder = 'Folder', - DocumentLibrary = 'DocumentLibrary', - Site = 'Site', - WorkingSet = 'WorkingSet', - Meeting = 'Meeting' -} -``` - -#### Supported document types for scoping - -[Reference - File Formats Support By copilot](https://support.microsoft.com/topic/file-formats-supported-by-copilot-1afb9a70-2232-4753-85c2-602c422af3a8) - -**Documents**: PDF, DOCX, XLSX, PPTX - -**Text-based Files**: RTF, TXT, CSV, LOG, INI, CONFIG - -**Audio**: WAV - -**Programming Languages**: PY, JS, JSX, JAVA, PHP, CS, C, CPP, CXX, H, HPP, M, COFFEE, DART, LUA, PL, PM, RB, RS, SWIFT, GO, KT, KTS, R, SCALA, T, TS, TSX - -**Shell Scripts**: BASH, SH, ZSH - -**Markup and Documentation**: HTML, CSS, MD, RMD, TEX, LATEX - -**Database Languages**: SQL - -**Data Serialization Formats**: IPYNB, JSON, TOML, YAML, YML - -##### Language/Locale - -The agent `iframe` dynamically loads localization settings to ensure that the chat interface is displayed in the appropriate language. These settings are derived from SharePoint, which provides a comprehensive set of localization options. - -When the agent iframe is initialized, it retrieves the current localization settings from SharePoint. These settings dictate the language and regional preferences for the chat interface, ensuring that all UI elements, messages, and interactions are presented in the user's preferred language. - -You can have this localized by setting your language options in the SharePoint account settings: [Change your personal language and region settings - Microsoft Support](https://support.microsoft.com/office/change-your-personal-language-and-region-settings-caa1fccc-bcdb-42f3-9e5b-45957647ffd7). - -> [!NOTE] -> -> If your Microsoft 365 language setting is different from your SharePoint account language setting, your Microsoft 365 language setting takes precedence. You can change your Microsoft 365 language setting here: [Change your display language in Microsoft 365](https://support.microsoft.com/topic/change-your-display-language-and-time-zone-in-microsoft-365-for-business-6f238bff-5252-441e-b32b-655d5d85d15b). - -An additional locale option can be passed in through the `ChatLaunchConfig` to further set the language the agent responds in: - -```typescript - const [chatConfig] = React.useState({ - header: ChatController.instance.header, - theme: ChatController.instance.theme, - zeroQueryPrompts: ChatController.instance.zeroQueryPrompts, - suggestedPrompts: ChatController.instance.suggestedPrompts, - instruction: ChatController.instance.pirateMetaPrompt, - locale: "en", - }); -``` - -###### Locale Options - -Here are some examples of locale options you can use: - -| Locale Code | Common Name | -|--------------|------------------------------------------| -| af | Afrikaans | -| en-gb | English (UK) | -| he | Hebrew | -| kok | Konkani | -| nn-no | Norwegian (Nynorsk) | -| sr-latn-rs | Serbian (Latin, Serbia) | -| am-et | Amharic | -| es | Spanish | -| hi | Hindi | -| lb-lu | Luxembourgish | -| or-in | Odia (India) | -| sv | Swedish | -| ar | Arabic | -| es-mx | Spanish (Mexico) | -| hr | Croatian | -| lo | Lao | -| pa | Punjabi | -| ta | Tamil | -| as-in | Assamese | -| et | Estonian | -| hu | Hungarian | -| lt | Lithuanian | -| pl | Polish | -| te | Telugu | -| az-latn-az | Azerbaijani (Latin, Azerbaijan) | -| eu | Basque | -| hy | Armenian | -| lv | Latvian | -| pt-br | Portuguese (Brazil) | -| th | Thai | -| bg | Bulgarian | -| fa | Persian | -| id | Indonesian | -| mi-nz | Maori (New Zealand) | -| pt-pt | Portuguese (Portugal) | -| tr | Turkish | -| bs-latn-ba | Bosnian (Latin, Bosnia and Herzegovina) | -| fi | Finnish | -| is | Icelandic | -| mk | Macedonian | -| quz-pe | Quechua (Peru) | -| tt | Tatar | -| ca-es-valencia | Catalan (Valencian) | -| fil-ph | Filipino (Philippines) | -| it | Italian | -| ml | Malayalam | -| ro | Romanian | -| ug | Uyghur | -| ca | Catalan | -| fr-ca | French (Canada) | -| ja | Japanese | -| mr | Marathi | -| ru | Russian | -| uk | Ukrainian | -| cs | Czech | -| fr | French | -| ka | Georgian | -| ms | Malay | -| sk | Slovak | -| ur | Urdu | -| cy-gb | Welsh (UK) | -| ga-ie | Irish (Ireland) | -| kk | Kazakh | -| mt-mt | Maltese (Malta) | -| sl | Slovenian | -| uz-latn-uz | Uzbek (Latin, Uzbekistan) | -| da | Danish | -| gd | Scottish Gaelic | -| km-kh | Khmer (Cambodia) | -| nb-no | Norwegian (Bokmål) | -| sq | Albanian | -| vi | Vietnamese | -| de | German | -| gl | Galician | -| kn | Kannada | -| ne-np | Nepali (Nepal) | -| sr-cyrl-ba | Serbian (Cyrillic, Bosnia and Herzegovina)| -| zh-cn | Chinese (Simplified) | -| el | Greek | -| gu | Gujarati | -| ko | Korean | -| nl | Dutch | -| sr-cyrl-rs | Serbian (Cyrillic, Serbia) | -| zh-tw | Chinese (Traditional) | diff --git a/docs/embedded/development/declarative-agent/spe-da.md b/docs/embedded/development/declarative-agent/spe-da.md deleted file mode 100644 index 76047def79..0000000000 --- a/docs/embedded/development/declarative-agent/spe-da.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: SharePoint Embedded agent (Deprecated) -description: Details usage and billing for SharePoint Embedded agents -ms.date: 03/17/2026 -ms.localizationpriority: high ---- - -# Overview - -> [!CAUTION] -> SharePoint Embedded agent has been deprecated in its current form and replaced with [Microsoft Foundry Agent Service](/azure/foundry/agents/overview) with a [SharePoint knowledge source (Preview)](/azure/search/agentic-knowledge-source-how-to-sharepoint-remote) configured for SharePoint Embedded. Learn how to [set up SharePoint Embedded as a knowledge source in Microsoft Foundry](sharepoint-embedded-knowledge-source.md). - -This article will remain in place for a limited time for historical reference. - -> [!NOTE] -> -> The SharePoint Embedded agent SDK is not suitable for production use cases. -> -> SPE agent consumption-based model will be available in May 2025! Starting May 1st, standard billing model will be available to all private preview customers and this rollout is expected to complete by May 15th. This means that starting May 15th, to use SPE agent within an SPE application, you will need to use standard Container Type. SPE Agent interactions, including those from Microsoft 365 Copilot license users, will be billed to the Azure subscription associated with your Container Type. Learn more about [SharePoint Embedded billing management](/sharepoint/dev/embedded/administration/billing/billingmanagement). - -SharePoint Embedded agent enables you to quickly demo AI capabilities into your application through a simple SDK, though it is not intended for production use. This chat control offers the following features: - -- Reason over documents in SharePoint Embedded containers using RAG. -- Developers can configure the application code to limit the search scope to files, folders, and containers. -- Developers can customize and configure chat control including starter prompts, suggested prompts, colors and more. - -Watch this demo to learn more about how to configure this functionality. - -> [!VIDEO https://www.youtube.com/embed/30i7q09EtQo?si=MwLtbrGKnzv7a6My] - -## Why use SharePoint Embedded agent - -SharePoint Embedded agent harness a semantic index to power Retrieval-Augmented Generation (RAG), securely referencing your data within the Microsoft 365 boundary at query time. This ensures accurate, grounded AI responses while reducing reliance on broad knowledge models. A pay-as-you-go billing model is on the horizon, aligning costs with actual usage. - -![Diagram illustrating SPE agent is AI ready](../../images/speco-apparch.png) - -## How to use SharePoint Embedded agent - -### How to build your agent - -Currently, you can use the React SDK library written in TypeScript to build your application. Plans to support additional frameworks and environments will be announced. The SDK is configured with the containerId instance of your containerType, as well as the authorization and authentication token logic you provide through a callback. It will embed itself as an iFrame into your host application. By default, the iFrame is given a `frame-ancestors` property that prevents it from being embedded by any host until configured. Details are provided below. - -#### SPE TypeScript React Application - -Follow the [quick start guide](../tutorials/spe-da-vscode.md) to get started with a prebuilt sample application. - -### API Documentation - -The SharePoint Embedded React TypeScript NPM Package, available at [here](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/feature/copilot-react-sdk/sharepointembedded-chatembedded-react/docs/index.md), provides the SDK for integrating SharePoint Embedded agent into your client applications. - -## Frequently Asked Questions - -### Is consumption-based billing available for SPE agent? - -Yes, starting May 15th you will need to use standard Container Type to use SPE agent within an SPE application. SharePoint Embedded agent interactions, including those from Microsoft 365 Copilot license users, will be billed to the Azure subscription associated with your Container Type. Learn more about [SharePoint Embedded billing management](/sharepoint/dev/embedded/administration/billing/billingmanagement) - -***Trial Container Types expire after 30 days, for this reason we recommend starting off with Standard Container types. There is no upgrade path from Trial to Standard container types.*** - -### Should I use a standard or trial Container Type? - -Once consumption-based billing is enabled, we will be disabling the use of this feature with Trial Container Types and it will only be enabled on Standard Container Types going forward. Please follow this [guide](../../getting-started/containertypes.md) to get started on creating your Standard Container Type. - -## SharePoint Embedded agent Support - -### Chat Control Feedback Dialog - -If you encounter any issues with the chat control, please use the thumbs up or down feedback buttons to report the problem. This method is preferred for sending feedback because it provides us with telemetry data that helps us diagnose and troubleshoot the issue more effectively. - -When you click the thumbs down button, a feedback dialog will appear. Please include any relevant information in this dialog. - -![SPE agent Feedback Modal preview](../../images/speco-feedbackcombined.png) - -## Advanced Topics Overview - -The [advanced topics](spe-da-adv.md) delve into how SharePoint Embedded agent use a semantic index to facilitate Retrieval-Augmented Generation (RAG), ensuring responses are accurately grounded in your stored content. You’ll also learn how to scope your agent to specific data sources, set up various file formats, and configure locale options to tailor the agent experience. By exploring concepts like grounding, semantic indexing, and RAG workflows, you can optimize your agent’s effectiveness and maintain security within the Microsoft 365 boundary. diff --git a/docs/embedded/development/fluid.md b/docs/embedded/development/fluid.md deleted file mode 100644 index 84d879d7fd..0000000000 --- a/docs/embedded/development/fluid.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Fluid Framework in SharePoint Embedded Applications -description: Details Fluid Integration with SharePoint Embedded Applications -ms.date: 05/21/2024 -ms.localizationpriority: high ---- - -# Fluid Framework in SharePoint Embedded Applications - -Integrate Fluid Framework and [SharePoint Embedded](../overview.md) to seamlessly and efficiently incorporate document collaboration into your applications. - -## Background - -[Fluid Framework](https://fluidframework.com/) is a collection of client libraries for distributing, synchronizing, and saving shared data. These libraries allow multiple clients to simultaneously create and operate on shared data structures in real-time. Fluid Framework allows developers to use the same practices with shared data as with local data--for example, a Fluid object works in the same way as a local TypeScript object. - -## Quickstart - -Start [building](https://github.com/microsoft/FluidExamples/) in the Fluid [Sample Apps Directory](https://github.com/microsoft/FluidExamples/tree/main/item-counter-spe). You need to [create](#get-started-with-sharepoint-embedded) a SharePoint Embedded application first. - -### Get started with SharePoint Embedded - -Try SharePoint Embedded for free by creating a container type for [trial purposes](../getting-started/containertypes.md). - -1. Set up a free trial [Microsoft 365 tenant](https://www.microsoft.com/microsoft-365/enterprise/microsoft365-plans-and-pricing). Alternatively, you can use an existing tenant if you have admin credentials. -1. Sign into the [SharePoint Embedded Visual Studio Code Extension](../getting-started/spembedded-for-vscode.md) and follow the steps to create an application and container type for trial purposes. - -## Prerequisites - -To get started building with Fluid Framework, you need: - -1. **Admin Credentials**: You need administrative credentials for a [Microsoft 365](https://www.microsoft.com/microsoft-365/enterprise/microsoft365-plans-and-pricing) tenant. -1. **SharePoint Embedded Application**: Ensure that you register your application in [Microsoft Entra ID](https://entra.microsoft.com/). If you don't have a SharePoint Embedded application, refer to the [earlier section](#get-started-with-sharepoint-embedded). -1. **Application (Client) ID**: Obtain the `ClientID` for your SharePoint Embedded Application. -1. **Container Type Information**: - - Identify the `ContainerTypeId` associated with your app’s container type. -1. **Containers**: - - Make sure you have *at least* one container created of the same container type linked to your SharePoint Embedded Application. - -## Get started with Fluid - -### Access App information - -You need the `ClientID` from your application and the `ContainerTypeId` associated with the containers created on that application. - -The `ClientID` is essential for acquiring the correct access tokens when working with Fluid Framework and documents. The `ContainerTypeId` is necessary for accessing containers associated with your SharePoint Embedded application. - -If you used the [Visual Studio Code Extension](../getting-started/spembedded-for-vscode.md), you can [export](/sharepoint/dev/embedded/getting-started/spembedded-for-vscode#export-postman-environment) your Postman Environment to easily view your both your `ContainerTypeId` and `ClientID`. - -Otherwise, you can access your `ContainerTypeId` by using the [`Get-SPOContainerType`](/sharepoint/dev/embedded/concepts/admin-exp/dev-admin#viewing-of-container-types) PowerShell cmdlet. Your `ClientID` is available in [Microsoft Entra ID](https://entra.microsoft.com/) by navigating to **Identity** > **App Registrations** > **Applications** > **All applications** to view your application overview. - -## Run Fluid Sample App: Item Counter - -Now you can test out and start building with the [Fluid Sample App](https://github.com/microsoft/FluidExamples/tree/main/item-counter-spe) Item Counter. - -**Steps:** - -1. Gather your `ClientID` and `ContainerTypeId` of your SharePoint Embedded Application and tenant admin credentials -1. Change to the directory where you'd like to clone the [Fluid Examples repo](https://github.com/microsoft/FluidExamples) -1. Clone the repository by executing the command: `git clone https://github.com/microsoft/FluidExamples.git` -1. Navigate to the **Item Counter** directory `cd .\FluidExamples\item-counter-spe\` -1. Create an empty **.env** file and input your `ClientID` and `ContainerTypeId` with no spaces like so: - - ```text - SPE_CLIENT_ID=YOUR_CLIENTID - - SPE_CONTAINER_TYPE_ID=YOUR_CONTAINERTYPE_ID - ``` - -1. `npm install` -1. `npm run dev` -1. Once Webpack is completed, go to `https://localhost:8080` -1. Sign in with the Admin credentials for your tenant -1. Grant admin consent for your app in the pop-up window -1. Copy the full URL to another browser tab or send it to someone who has credentials to the same tenant. These can be user credentials as long as they are on the same tenant. The live changes to the Item Counter on both browsers show that the data is synced between clients. -1. Congrats on getting your first Fluid App to run! More details can be found in the Item Counter [README](https://github.com/microsoft/FluidExamples/tree/main/item-counter-spe). - - ![Item Counter Sample App](../images/itemcount.png) diff --git a/docs/embedded/development/limits-calling.md b/docs/embedded/development/limits-calling.md deleted file mode 100644 index 111227fd76..0000000000 --- a/docs/embedded/development/limits-calling.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Limits and Calling Patterns -description: This article explains the limits of SharePoint Embedded. -ms.date: 01/16/2026 -ms.localizationpriority: high ---- - -# Limits and Calling Patterns - -This document explains the limits of SharePoint Embedded during public preview. - -> [!NOTE] -> These are preview limits that are subject to change. - -## Size limits - -The following table defines the size limits of containers: - -| Resource | Limit | -| --------------------------------------------------------- | ------------------------------------------------------ | -| Container types that a partner tenant can create | 25* | -| Container types that an app can own | 1 | -| Containers of a container type per consuming tenant | 100k* | -| Storage per container type per consuming tenant | 100 TB* | -| Files and folders per container | 30M | -| Storage per container | 25 TB | -| Files and folders with additive permissions per container | 5k | -| File size | 250 GB | -| Version count per file | 500 (Automatic Version History Limits Default Setting) | -| Number of users shared per folder or file | 5k | - -> [!NOTE] -> Limit can be increased per request. - -## Throttling - -### Patterns and best practices - -When applications hit service limits, you receive an HTTP status code 429 ("Too many requests"). You might also receive an HTTP status code 503 ("Server Too Busy"). - -In general, the following are the best practices to handle throttling: - -- Reduce the number of concurrent requests. -- Avoid request spikes. -- Honor the `Retry-After` HTTP header. - -In both cases, a `Retry-After` header is included in the response, indicating how long the calling application should wait before retrying or making a new request. Throttled requests count towards usage limits, so failure to honor `Retry-After` might result in more throttling. - -## API rate limits - -SharePoint Embedded provides various APIs. Different APIs have different costs depending on the functionality and complexity of the API. The cost of APIs is normalized and expressed by resource units. API rate limits are also defined using resource units. - -| Resource units per request | Operations | -| -------------------------- | -------------------------------------------------------------------------- | -| 1 | Single item query, such as get item | -| 2 | Multi-item query, such as list children, create, update, delete, and upload | -| 5 | All permission resource operations, including $expand=permissions | - -> [!NOTE] -> We reserve the right to change the API resource unit cost. - -The following table lists the API rate limits for applications and containers. - -| Resource | Limits | -| --------------------------- | --------------------------- | -| Requests per container | 3k resource units per min | -| Requests per app per tenant | 12k resource units per min* | -| Requests per user | 600 resource units per min | - -> [!NOTE] -> \* Limit can be increased per request. - -Application limits are defined in resource units, and the actual request rate, such as requests per minute, varies based on the chosen API and its corresponding resource unit cost. As a general rule, you can estimate the request rate by averaging about two resource units per request and dividing application resource unit limits by 2. Reducing the usage of permission operations can notably improve the call rate since these operations have the most significant impact on overall resource consumption. - -### Container creation rate limiting - -Per consuming tenant, and during the tenant's peak hours, container creation is limited to 5 new containers per second. Requests beyond this limit will be rate limited. Outside of peak hours, containers may be created at a faster rate. diff --git a/docs/embedded/development/sharing-and-perm.md b/docs/embedded/development/sharing-and-perm.md deleted file mode 100644 index 4c63f48430..0000000000 --- a/docs/embedded/development/sharing-and-perm.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Sharing and Permissions -description: Outlines Permission Model for SharePoint Embedded -ms.date: 03/03/2025 -ms.localizationpriority: high ---- - -# Sharing and permissions in SharePoint Embedded - -## Additive permissions - -In SharePoint Embedded, content always inherits permissions from its parent hierarchy. While you can't alter this inherited permission structure, you can extend access within a container by applying "additive permissions" to specific files and folders. For instance, if _UserA_ belongs to the Reader role, you can grant the user edit permission to a particular document in that container using Microsoft Graph: - -| Scenario | Microsoft Graph API(s) | Notes | -| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Grant an additive permission | [POST /drives/{drive-id}/items/{item-id}/invite](/graph/api/driveitem-invite) | The sendInvitation property must always be false. You can't grant additive permissions to the root folder in a container as this is essentially the same as adding a User to a role. You can't use AppOnly permissions. | -| Retrieve permissions | [GET /drives/{drive-id}/items/{item-id}/permissions](/graph/api/permission-get) & [GET /drives/{drive-id}/items/{item-id}/permissions/{perm-id}](/graph/api/permission-get), | | -| Delete additive permissions | [DELETE /drives/{drive-id}/items/{item-id}/permissions/{perm-id}](/graph/api/permission-delete) | You can only delete the additive permission on the drive item where it was originally added. | - -## Role-based sharing setting - -SharePoint Embedded offers a role-based sharing model that allows developers to configure file-sharing permissions based on container permission roles, offering a choice between restrictive and open sharing models. By default, the sharing setting is configured to the open model, permitting unrestricted content sharing by all users. This sharing setting is part of [container type configuration](../getting-started/containertypes.md#configuring-container-types). This configuration can only be set by the application owner's developers. To learn more about container permission roles, refer to [Authentication and Authorization with SharePoint Embedded](auth.md#container-permissions). - -### Restrictive sharing model - -Only container members who are either the Owner or Manager roles are permitted to add new permissions to files. - -### Open sharing model - -Any container members and guests with edit permissions can add new permissions to this file. - -This can be configured using the PowerShell cmdlet [Set-SPOcontainerTypeConfiguration](../administration/developer-admin/dev-admin.md#container-type-configuration-properties) as per this example: - -```powershell -Set-SPOcontainerTypeConfiguration - -containerTypeID - -sharingRestricted $false -``` - -## Sharing configuration setting - -By default, SharePoint Embedded application sharing configuration is the same as the consuming tenant-sharing configuration. For example, if the consuming tenant is configured to disable sharing for guests, then the SharePoint Embedded application is unable to add guests to container roles or grant them additive permissions. - -### Application external sharing override - -For SharePoint Embedded applications, sharing configurations can be adjusted at the application level. Consuming tenant admin can configure permissions that are different than tenant-level sharing settings. For example, if a tenant's sharing setting prohibits sharing with guests, SharePoint Embedded applications can be configured to allow guest sharing. So, all containers within that SharePoint Embedded application would have the ability to include guests or extend another permission, while other SharePoint Embedded applications and SharePoint maintain restricted sharing permissions. - -This setting can only be set by consuming tenant SharePoint Embedded admin, and can be configured using the latest PowerShell cmdlet [Set-SPOApplication](../administration/consuming-tenant-admin/ctapowershell.md#set-sharing-capability-of-applications) as shown in this example: - -```powershell -Set-SPOApplication - -OwningApplicationID - -OverrideTenantSharingCapability $true - -SharingCapability -``` diff --git a/docs/embedded/development/support-archival-of-containers.md b/docs/embedded/development/support-archival-of-containers.md deleted file mode 100644 index 5cf997fb9c..0000000000 --- a/docs/embedded/development/support-archival-of-containers.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Support archival of SharePoint Embedded containers -description: This article explains how archival functionality can be supported for a container type. -ms.date: 03/20/2026 -ms.localizationpriority: high ---- - -# Onboard your application to support archival functionality - -Archival of containers helps customers in reducing the cost of storing infrequently used data. Support archival in your application by enabling the `-IsArchiveEnabled` flag using the following PowerShell cmdlet. This cmdlet is supported only by the SharePoint Embedded administrator of your organization. - -Use the following command on already existing container type: - -```powershell -Set-SPOContainerTypeConfiguration -ContainerTypeId -IsArchiveEnabled $true -``` - -Use the following command while creating a new container type: - -```powershell -New-SPOContainerType -ContainerTypeName -OwningApplicationId -IsArchiveEnabled $true -``` - -APIs for supporting the archive and reactivate actions on the containers: - -| Action | API Documentation link | Example | -| ------------------------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -| Archive an active container | [Archive](/graph/api/filestoragecontainer-archive) | `POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{ContainerId}/archive` | -| Reactivate an archived container | [Unarchive](/graph/api/filestoragecontainer-unarchive) | `POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{containerId}/unarchive` | -| Retrieve an archived container using ID | [Get](/graph/api/filestoragecontainer-get) | `GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{containerId}` | -| Retrieve all archived container collection | [Get](/graph/api/filestoragecontainer-get) | `GET https://graph.microsoft.com/beta/storage/fileStorage/containers?$filter=containerTypeId eq {containerTypeId} and archivalDetails ne null` | diff --git a/docs/embedded/development/tutorials/doc-processing-acs.md b/docs/embedded/development/tutorials/doc-processing-acs.md deleted file mode 100644 index 2d450bf9e9..0000000000 --- a/docs/embedded/development/tutorials/doc-processing-acs.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Document Processing with Azure Cognitive Services -description: Enabling document processing with Azure Cognitive Services. -ms.date: 03/03/2025 -ms.localizationpriority: high ---- - -# Enabling Document Processing with Azure Cognitive Services - -## Utilizing Azure Cognitive Services - -Azure Cognitive Services is a set of cloud-based APIs that you can use in AI applications and data flows. It provides pre-trained models that are ready to use in your applications, requiring no data and no model training on your part. They can be easily integrated into applications via HTTP REST interfaces. - -You have already learned how to use webhooks with [the application](/training/modules/sharepoint-embedded-create-app/) to get a notification whenever an existing file is updated, or a new file is uploaded in the [Using Webhooks tutorial](./using-webhooks.md). This tutorial will cover connecting it with Azure Cognitive Services to extract data from invoices. - -To set up automatic AI processing with your current SharePoint application upon a change in your container, you need to follow [Using Webhooks](./using-webhooks.md) and then: - -1. Get the delta changes of the container. You're currently able to get the notification whenever there's any change in our container and will now get the files that are added or updated. -1. Call Azure Cognitive Services’s Document Intelligence service API. You'll need to create an Azure AI resource to use the API to extract the fields from an image and get the extracted files. You might store them as shown in this tutorial or you might process them as you like. -![document processing schema](../../images/Document-Processing.png) - -> [!TIP] -> To learn more about the Microsoft Graph APIs used in this tutorial, see [Track changes for a Drive](/graph/api/driveitem-delta), [Get a DriveItem resource](/graph/api/driveitem-get), and [Upload or replace the contents of a DriveItem](/graph/api/driveitem-put-content). - -## Get the delta changes of a container - -Open **GraphProvider.ts** and implement the method `getDriveChanges` to get the list of changed items: - -```typescript -public static async getDriveChanges(driveId: string): Promise { - let changedItems: any[] = []; - const driveDeltaBasePath: string = `/drives/${driveId}/items/root/delta`; - let driveDeltaTokenParams: string = ""; - let hasMoreChanges: boolean = true; - try{ - do { - if (this.changeTokens.has(driveId)) { - driveDeltaTokenParams = `?token=${this.changeTokens.get(driveId)}` - } - const response = await this.graphClient.api(driveDeltaBasePath + driveDeltaTokenParams).get(); - changedItems.push(...response.value); - if (response['@odata.nextLink']) { - const token = new URL(response['@odata.nextLink']).searchParams.get('token'); - this.changeTokens.set(driveId, token); - } else { - hasMoreChanges = false; - const token = new URL(response['@odata.deltaLink']).searchParams.get('token'); - this.changeTokens.set(driveId, token); - } - console.log(this.changeTokens.get(driveId)); - } while (hasMoreChanges); - } - catch(err){ - console.log(err); - } - return changedItems; -} -``` - -Implement the method `getDriveItem` to fetch a file from a container: - -```typescript -public static async getDriveItem(driveId: string, itemId: string): Promise { - return await this.graphClient.api(`/drives/${driveId}/items/${itemId}`).get(); -} -``` - -Create a new file **ReceiptProcessor.ts** and implement a method `processDrive`: - -```typescript -export abstract class ReceiptProcessor { - - public static async processDrive(driveId: string): Promise { - const changedItems = await GraphProvider.getDriveChanges(driveId); - for (const changedItem of changedItems) { - try { - const item = await GraphProvider.getDriveItem(driveId, changedItem.id); - const extension = this.getFileExtension(item.name); - if (this.SUPPORTED_FILE_EXTENSIONS.includes(extension.toLowerCase())) { - console.log(item.name); - const url = item["@microsoft.graph.downloadUrl"]; - const receipt = await this.analyzeReceiptStream(await this.getDriveItemStream(url)); - const receiptString = JSON.stringify(receipt, null, 2) - const fileName = this.getFileDisplayName(item.name) + "-extracted-fields.json"; - const parentId = item.parentReference.id; - await GraphProvider.addDriveItem(driveId, parentId, fileName, receiptString); - } - } catch (error) { - console.log(error); - } - } - } -} -``` - -At this point if you restart the app along with tunneling and subscription, you should see the recently added/updated files listed in the console. - -## Call Azure Cognitive Services' Document Intelligence service API - -To use the Azure Cognitive Services Document Intelligence APIs, you need to create a Multi-Service or Document Intelligence resource for Azure AI Service. Refer to the following tutorials to create the resource: - -- [Quickstart: Create a multi-service resource for Azure AI services](/azure/ai-services/multi-service-resource?tabs=windows&pivots=azportal) -- [Get started with Document Intelligence](/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api?view=doc-intel-3.1.0&viewFallbackFrom=form-recog-3.0.0&preserve-view=true&pivots=programming-language-javascript) - -After this step, you should have an endpoint and a key ready to use. - -Now open **ReceiptProcessor.ts** to create method `dac` to store the Azure Cognitive Services credentials: - -```typescript -private static dac = new DocumentAnalysisClient( - `${process.env["DAC_RESOURCE_ENDPOINT"]}`, - new AzureKeyCredential(`${process.env["DAC_RESOURCE_KEY"]}`) -); -``` - -Create method `getDriveItemStream`. - -```typescript -private static async getDriveItemStream(url: string): Promise { - const token = GraphProvider.graphAccessToken; - const config: AxiosRequestConfig = { - method: "get", - url: url, - headers: { - "Authorization": `Bearer ${token}` - }, - responseType: 'stream' - }; - const response = await axios.get(url, config); - return response.data; -} -``` - -Create method `analyzeReceiptStream` to get the OCR fields through Azure Cognitive Services processing. Here we're taking the `prebuilt-invoice` model, but other models can be chosen: - -```typescript -private static async analyzeReceiptStream(stream: Readable): Promise { - const poller = await this.dac.beginAnalyzeDocument("prebuilt-invoice", stream, { - onProgress: ({ status }) => { - console.log(`status: ${status}`); - }, - }); - - const { - documents: [result] = [], - } = await poller.pollUntilDone(); - - const fields = result?.fields; - this.removeUnwantedFields(fields); - return fields; -} -``` - -Create a method `removeUnwantedFields` to remove the undesirable fields in Azure Cognitive Services’s response: - -```typescript -private static removeUnwantedFields(fields: any) { - for (const prop in fields) { - if (prop === 'boundingRegions' || prop === 'content' || prop === 'spans') { - delete fields[prop]; - } - if (typeof fields[prop] === 'object') { - this.removeUnwantedFields(fields[prop]); - } - } -} -``` - -Finally, open **GraphProvider.ts** to add the `addDriveItem` method at the end of the `GraphProvider` class. - -```typescript -public static async addDriveItem(driveId: string, parentId: any, fileName: string, receiptString: string) { - await this.graphClient.api(`/drives/${driveId}/items/${parentId}:/${fileName}:/content`).put(receiptString); -} -``` - -Now, restart the demo app and set up the tunneling using ngrok and delta change subscription on the container again. - -If you add/update any file (supported formats: JPEG, JPG, PNG, BMP, TIFF, PDF) in this container, you should see a new JSON file created and containing the fields extracted from the file. diff --git a/docs/embedded/development/tutorials/launch-experience.md b/docs/embedded/development/tutorials/launch-experience.md deleted file mode 100644 index e0b92344db..0000000000 --- a/docs/embedded/development/tutorials/launch-experience.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Configure Default Launch Experience for your Office Files -description: Configure Default Launch Experience for your Office Files -ms.date: 05/21/2024 -ms.localizationpriority: high ---- - -# Configure Default Launch Experience for your Office Files - -## Configure the Launch mode of Office Clients - -When retrieving a `DriveItem` from the Microsoft Graph API with: - -```http -/graph/api/driveitem-get?view=graph-rest-1.0 -``` - -The `webUrl` property in the response can be a link to Web Application Open Platform Interface (WOPI) for rendering supported office file types. The URL will look like: - -```http -https://host/:w:r/contentstorage/sitecollection/_layouts/15/doc2.aspx?sourcedoc=guid&file=filename.docx&action=default&mobileredirect=true -``` - -This `webUrl` will open WOPI in the default mode (`action=default`). If you wish to override the default mode to force a specific mode (for example, View for read-only and Edit for editor), you can augment the `webUrl` like this: - -```csharp -string webUrl = https://host/:w:r/contentstorage/sitecollection/_layouts/15/doc2.aspx?sourcedoc=guid&file=filename.docx&action=default&mobileredirect=true; - -System.UriBuilder builder = new System.UriBuilder(webUrl); -System.Collections.Specialized.NameValueCollection queryDictionary = System.Web.HttpUtility.ParseQueryString(builder.Query); -queryDictionary["action"] = "view"; -//queryDictionary["action"] = "edit"; -builder.Query = queryDictionary.ToString(); -string modifiedWebUrl = builder.ToString(); -``` - -> [!TIP] -> To learn more about WOPI Actions, see: [WOPI Discovery - WOPI Actions](/microsoft-365/cloud-storage-partner-program/online/discovery#wopi-actions). - -### Open Office files directly in Desktop clients - -To open your files directly in the Office desktop clients, you need to create an Office URI scheme. The format is as follows: - -```xml -:"|""|" -``` - -Use the following table to replace the preceding segments: - -- **scheme-name**: the name of the application, for example: *ms-excel* -- **command-name**: - - `ofv` for Open File View - - `ofe` for Open File Edit - - `nft` for New From Template -- **command-argument-descriptor** and **command-argument**: - - `|u|{file url}` - - `|s|{save location}` - - *only for New From Template* - -> [!NOTE] -> The **New From Template** may not work as you would expect for save location since the permissions schema is different from SharePoint Sites. - -The following contains an example usage of the Office URI scheme: - -```text -ms-word:ofv|u|https://contoso.com/document.docx -ms-powerpoint:ofe|u|https://contoso.com/presentation.pptx -``` - -Because the `webUrl` property points to Office Online for Office documents, you must get the actual link in two steps: - -1. Getting the WebUrl of the parent folder -1. Appending the name of the file - -For example, the following scheme: - -```text -ms-word:ofe|u|{folder.WebUrl]/{item.Name} -``` - -... will result in the following scheme: - -```text -ms-word:ofe|u|https://contoso.sharepoint.com/contentstorage/CSP_1234765465/Document%20Library/MyDocument.docx -``` - -To learn more about Office URI schemes, see [Office URI Schemes](/office/client-developer/office-uri-schemes). - -> [!NOTE] -> The Uri must be opened in a blank window or new tab. diff --git a/docs/embedded/development/tutorials/metadata.md b/docs/embedded/development/tutorials/metadata.md deleted file mode 100644 index 1973c22b9e..0000000000 --- a/docs/embedded/development/tutorials/metadata.md +++ /dev/null @@ -1,474 +0,0 @@ ---- -title: SharePoint Embedded Container Metadata -description: Add metadata in Containers and Files. -ms.date: 3/22/2024 -ms.localizationpriority: high ---- - -# Using Metadata with SharePoint Embedded Containers - -In SharePoint Embedded, columns can be added to [Containers](../../getting-started/containertypes.md) to address scenarios requiring custom metadata via Microsoft Graph APIs. Content in the container can then set desired values for corresponding metadata. Metadata is schematized and can be queried. Note the APIs to create and manage columns are on the container instances level – an application is responsible for defining and managing the columns across its containers. - -## Authorization and Authentication - -App+User (Delegated) or App-only (Application) Bearer {token} is required in the Authorization header. - -> [!NOTE] -> Container owners can Create, Update, and Delete Container columns -> All Container members can Read and List Container columns - -### `microsoft.graph.fileStorageContainer` properties - -| Property | Type | Description | Key | Required | ReadOnly | -| -------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------- | --- | -------- | -------- | -| `id` | `Edm.String` | unique stable identifier of the storage container instance | Yes | Yes | Yes | -| `displayName` | `Edm.String` | display name of the container | No | Yes | No | -| `description` | `Edm.String` | description of the container | No | No | No | -| `containerTypeId` | `Edm.Guid` | container type ID | No | Yes | Yes | -| `containerTypeDisplayName` | `Edm.String` | display name of the container type | No | No | Yes | -| `externalGroupId` | `Edm.Guid` | external group ID | No | No | No | -| `permissions` | `Collection` | permissions of users / groups in the container | No | No | No | -| `customProperties` | `microsoft.graph.fileStorageContainerCustomPropertyDictionary` | custom properties | No | No | No | -| `viewpoint` | `microsoft.graph.fileStorageContainerViewpoint` | data that is specific to the current user | No | No | No | -| `drive` | `microsoft.graph.drive` | storage container's drive resource | No | No | Yes | -| `recycleBin` | `microsoft.graph.recycleBin` | storage container's recycleBin resource | No | No | Yes | -| `status` | `microsoft.graph.fileStorageContainerStatus` | an enum value representing the status of the container | No | No | Yes | -| `createdDateTime` | `microsoft.graph.dateTimeOffset` | createdDateTime | No | No | Yes | -| `storageUsedInBytes` | `Edm.Int64` | storage used in bytes | No | No | Yes | -| `assignedSensitivityLabel` | `microsoft.graph.assignedLabel` | the sensitivity label assigned to the container | No | No | No | -| `owners` | `Collection` | The list of users who own the container | No | No | Yes | -| `columns` | `Collection` | the collection of custom metadata fields in the container | No | No | No | - - - -## Limitations - -The following are the properties that SharePoint Embedded Metadata supports: - -| Property name | Type | -| ---------------------- | ------------------------- | -| boolean | booleanColumn | -| choice | choiceColumn | -| currency | currencyColumn | -| dateTime | dateTimeColumn | -| hyperlinkOrPicture | hyperlinkOrPictureColumn | -| isDeletable | Boolean | -| ID | string | -| indexed | Boolean | -| isSealed | Boolean | -| name | string | -| number | numberColumn | -| personOrGroup | personOrGroupColumn | -| readOnly | Boolean | -| text | textColumn | -| type | columnTypes | - -> [!NOTE] -> Please name columns according to the appropriate column naming convention - -### Column Naming Conventions - -Column Names must adhere to the following rules: -- Can't contain "!". -- Can't start with a digit, period, minus sign, or question mark. -- Can't contain any space or any nonalphanumeric characters except "_" or "\". -- Can't look like either type of cell reference. - - A1 mode cell reference with 1 to 3 characters followed by 1 to 5 digits (for example, A3 F02563, ZZZ12). - - R1C1 mode cell references that look like r, or c, or r[#], c[#] or r[#]c[#]. -- Can't be any localized word for "true" or "false". -- Can't be specific names, including "Author", "Created", "Description", etc. - - - -## Create a column in a fileStorageContainer - -This API lets callers create a new column instance in a fileStorageContainer. - -##### Required permissions (at least one of) - -| ScopeName | Type | -| ----------------------------- | ----------- | -| FileStorageContainer.Selected | Application | -| FileStorageContainer.Selected | Delegated | - -#### REST Operation example: create a column in a fileStorageContainer - -##### Request - -```http -POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns -Content-Type: application/json - -{ - "description": "test", - "displayName": "Title", - "enforceUniqueValues": false, - "hidden": false, - "indexed": false, - "name": "Title", - "text": { - "allowMultipleLines": false, - "appendChangesToExistingText": false, - "linesForEditing": 0, - "maxLength": 255 - } -} -``` - -> [!NOTE] -> Note Type is not supported. `maxLength` should =< 255. - -##### Response - -```http -HTTP/1.1 201 Created -Content-type: application/json - -{ - "description": "test", - "displayName": "Title", - "enforceUniqueValues": false, - "hidden": false, - "id": "99ddcf45-e2f7-4f17-82b0-6fba34445103", - "indexed": false, - "name": "Title", - "text": { - "allowMultipleLines": false, - "appendChangesToExistingText": false, - "linesForEditing": 0, - "maxLength": 255 - } -} -``` - -## Get a column in a fileStorageContainer by ID - -This API lets callers get a fileStorageContainer column instance by ID. - -##### Required permissions (at least one of) - -| ScopeName | Type | -| ----------------------------- | ----------- | -| FileStorageContainer.Selected | Application | -| FileStorageContainer.Selected | Delegated | - -#### REST Operation example: get a column in a fileStorageContainer by ID - -##### Request - -```http -GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id} -``` - -##### Response - -```http -HTTP/1.1 200 OK -Content-type: application/json - -{ - "description": "test", - "displayName": "Title", - "enforceUniqueValues": false, - "hidden": false, - "id": "99ddcf45-e2f7-4f17-82b0-6fba34445103", - "indexed": false, - "name": "Title", - "text": { - "allowMultipleLines": false, - "appendChangesToExistingText": false, - "linesForEditing": 0, - "maxLength": 255 - } -} -``` - -## Update a column in a fileStorageContainer by ID - -This API lets callers update a fileStorageContainer column instance by ID. -You can update any property of the column other than the **id** property. - -##### Required permissions (at least one of) - -| ScopeName | Type | -| ----------------------------- | ----------- | -| FileStorageContainer.Selected | Application | -| FileStorageContainer.Selected | Delegated | - -#### REST Operation example: update a column in a fileStorageContainer by ID - -##### Request - -```http -PATCH https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id} -Content-Type: application/json - -{ - "required": true, - "hidden": false, - "description": "This is my new column description" -} -``` - -##### Response - -```http -HTTP/1.1 200 OK -Content-type: application/json - -{ - "description": "", - "displayName": "Custom Column", - "enforceUniqueValues": false, - "hidden": false, - "id": "11dfef35-e2f7-4f17-82b0-6fba34445103", - "indexed": false, - "name": "Custom Column", - "readOnly": false, - "required": true, - "text": { - "allowMultipleLines": false, - "appendChangesToExistingText": false, - "linesForEditing": 0, - "maxLength": 255 - } -} -``` - -## Delete a column from a fileStorageContainer - -This API lets callers delete a fileStorageContainer column instance by ID. - -##### Required permissions (at least one of) - -| ScopeName | Type | -| ----------------------------- | ----------- | -| FileStorageContainer.Selected | Application | -| FileStorageContainer.Selected | Delegated | - -#### REST Operation example: delete a column from a fileStorageContainer - -##### Request - -```http -DELETE https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id} -``` - -##### Response - -```http -HTTP/1.1 204 No Content -``` - -## List columns in a fileStorageContainer - -This API lets callers enumerate the columns in a fileStorageContainer. - -##### Required permissions (at least one of) - -| ScopeName | Type | -| ----------------------------- | ----------- | -| FileStorageContainer.Selected | Application | -| FileStorageContainer.Selected | Delegated | - -#### REST Operation example: List columns in a fileStorageContainer - -##### Request - -```http -GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns -``` - -##### Response - -```http -HTTP/1.1 200 OK -Content-type: application/json - -{ - "value": [ - { - "description": "", - "displayName": "Title", - "hidden": false, - "id": "99ddcf45-e2f7-4f17-82b0-6fba34445103", - "indexed": false, - "name": "Title", - "readOnly": false, - "required": false, - "text": { - "allowMultipleLines": false, - "appendChangesToExistingText": false, - "linesForEditing": 0, - "maxLength": 255 - } - }, - { - "description": "", - "displayName": "Address", - "id": "11dfef35-e2f7-4f17-82b0-6fba34445103", - "indexed": false, - "name": "Address", - "readOnly": false, - "required": false, - "text": { - "allowMultipleLines": false, - "appendChangesToExistingText": false, - "linesForEditing": 0, - "maxLength": 255 - } - } - ] -} -``` - -## Get column values of an item in a fileStorageContainer's drive - -This is an existing API used to showcase our new feature of getting the column values of an item in a fileStorageContainer's drive. -This API supports OData $select features for `column`. - - -##### Required permissions (at least one of) - -| ScopeName | Type | -| ----------------------------- | ----------- | -| FileStorageContainer.Selected | Application | -| FileStorageContainer.Selected | Delegated | - -#### REST Operation example: Get column values of an item in a fileStorageContainer's drive - -##### Request - -```http -GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields -``` - -##### Response - -```http -HTTP/1.1 200 OK -Content-type: application/json - -{ - "Name": "Widget", - "Color": "Blue", - "Quantity": 2357 -} -``` - -##### Request - -```http -GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields?$select=Name,Color -``` - -##### Response - -```http -HTTP/1.1 200 OK -Content-type: application/json - -{ - "Name": "Widget", - "Color": "Blue" -} -``` - -## Patch column values of an item in a fileStorageContainer's drive - -This is an existing API used to showcase our new feature of updating and deleting the column values of an item in a fileStorageContainer's drive. - -##### Required permissions (at least one of) - -| ScopeName | Type | -| ----------------------------- | ----------- | -| FileStorageContainer.Selected | Application | -| FileStorageContainer.Selected | Delegated | - -#### REST Operation example: update column values of an item in a fileStorageContainer's drive - -##### Request - -```http -PATCH https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields - -Content-Type: application/json - -{ - "Color": "Fuchsia", - "Quantity": 934 -} -``` - -##### Response - -```http -HTTP/1.1 200 OK -Content-type: application/json - -{ - "Name": "Widget", - "Color": "Fuchsia", - "Quantity": 934 -} -``` - -#### REST Operation example: delete column values of an item in a fileStorageContainer's drive - -##### Request - -```http -PATCH https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields - -Content-Type: application/json - -{ - "Color": null -} -``` - -##### Response - -```http -HTTP/1.1 200 OK -Content-type: application/json - -{ - "Name": "Widget", - "Quantity": 934 -} -``` - -## Query a fileStorageContainer's driveitems with Odata query options on custom columns - -This API lets users query drive items in a fileStorageContainer with `$expand`, `$filter`, and `$orderby` Odata query options on their custom columns. - -##### Required permissions (at least one of) - -| ScopeName | Type | -| ----------------------------- | ----------- | -| FileStorageContainer.Selected | Application | -| FileStorageContainer.Selected | Delegated | - -#### REST Operation example: filter fileStorageContainer's driveitems by their custom columns 'TestField' and order the results by 'TestField' - -##### Request - -```http -GET https://graph.microsoft.com/beta/drives/{drive-id}/items?$orderby=listitem/fields/TestField asc&$filter=startswith(listitem/fields/TestField, '3')&$expand=listitem($expand=fields) -``` - -##### Response - -```http -HTTP/1.1 200 OK -Content-type: application/json - -{ - "value": [ - {"name": "a.jpg", "size": 2048, "listitem/fields/TestField": "31" }, - {"name": "b.xlsx", "size": 197, "listitem/fields/TestField": "32" }, - {"name": "c.docx", "size": 391, "listitem/fields/TestField": "33" } - ] -} -``` \ No newline at end of file diff --git a/docs/embedded/development/tutorials/migrate-abs-to-spe.md b/docs/embedded/development/tutorials/migrate-abs-to-spe.md deleted file mode 100644 index 8ae025bb82..0000000000 --- a/docs/embedded/development/tutorials/migrate-abs-to-spe.md +++ /dev/null @@ -1,382 +0,0 @@ ---- -title: Tutorial to Migrate from Azure Blob Storage container to SharePoint Embedded container -description: Tutorial in how to migrate from Azure Blob Storage container to SharePoint Embedded container Using C# -ms.date: 08/02/2024 -ms.localizationpriority: high ---- - -# Tutorial For Migrating Content From Azure Blob Storage Container To SharePoint Embedded Container - -## Purpose - -This tutorial will guide you through migrating content from Azure Blob Storage (ABS) to SharePoint Embedded (SPE) using C#. This is useful for customers who have 500 docs in the blob storage container. - -### Prerequisites - -1. A Microsoft Entra ID application registration. See [register an application](/graph/auth-register-app-v2). -1. Your Microsoft Entra ID tenant has a [Microsoft 365 subscription](/training/m365/). -1. A Microsoft Entra ID tenant. If you don't have a tenant, create a [free Azure account to get a free subscription](https://azure.microsoft.com/free/). -1. An account with at least the Global Administrator or SharePoint Embedded Administrator role. -1. .NET Core SDK [version 8.0.303](https://dotnet.microsoft.com/download/dotnet/8.0) -1. Dotnet environment to run the sample app - - - It can be run on Windows, Linux and macOS - -1. SharePoint Embedded container - - - For more information on how to set up a [SPE container](https://aka.ms/start-spe) - -1. Azure Blob Storage container - - - For more information on how to set up an [ABS container](/azure/storage/blobs/storage-blobs-introduction) - -## Authentication - -### Azure Blob Storage - -1. Credentials - Container-level Shared Access Signature (SAS) URL. -1. Permission - Read and List - -### SharePoint Embedded - -1. An [Azure account](https://portal.azure.com) -1. A SharePoint Tenant where you'll create your containers and its Tenant ID -1. An onboarded application ID (sometimes called client ID) and its corresponding ContainerTypeId -1. Create a new App Registration in [Microsoft Entra ID portal](https://entra.microsoft.com). -1. In the App Registration, add a new Mobile & Console application platform in [Microsoft Entra ID App Registration Authenticate portal](https://entra.microsoft.com) - - ![Screenshot of Microsoft Entra ID application configuration](../../images/app-registration-console-platform.png) - -1. A ContainerType -1. A Container -1. Having the application registered in the consuming tenant (even if the owner of the application is the same as the consuming) -1. Having the containerType registered in the consuming tenant (even if the owner of the CT is the same as the consuming) -1. Consuming tenant user name and password credentials - will be required to authenticate the Microsoft Graph client -1. Permission - "User.Read", "FileStorageContainer.Selected" - -## Migrating Data from Azure Blob Storage container to SharePoint Embedded container - -### Description - -This section provides code snippets on how to accomplish the migration. All the validation has been removed for readability. - -### Connecting to Azure Blob Storage Container - -```c# -_containerClient = new BlobContainerClient(new Uri(_containerLevelSASUrl)); -``` - -### Connecting to SharePoint Embedded - -```c# -string[] _scopes = { "User.Read", "FileStorageContainer.Selected" }; -InteractiveBrowserCredentialOptions interactiveBrowserCredentialOptions = new InteractiveBrowserCredentialOptions() - { - ClientId = clientId, - RedirectUri = new Uri("http://localhost"), - }; -InteractiveBrowserCredential interactiveBrowserCredential = new InteractiveBrowserCredential(interactiveBrowserCredentialOptions); - -_graphClient = new GraphServiceClient(interactiveBrowserCredential, scopes, null); - -// Will open up a browser to provide your consuming tenant admin credentials -var user = await _graphClient.Me.GetAsync(); -``` - -### Getting the blob list - -```c# -var blobs = new List(); -await foreach (var blobItem in _containerClient.GetBlobsAsync()) -{ - blobs.Add(blobItem.Name); -} -return blobs; -``` - -### Thread pooling - -```c# -private CountdownEvent _countdown; - -// This is how the thread pool knows how many files are being migrated -_countdown = new CountdownEvent(blobs.Count); -``` - -### FileStructure - -```c# -public class FileStructure -{ - public string blobName { get; set; } - public string parentFolderId { get; set; } -} -``` - -### Traverse blob list - -```c# -// It creates a new folder in the destination. The name of the folder is the blob's container name. -// root means it is the root of the document library. -// If you want to copy it to another drive item, you can put the drive item ID here. -containerFolder = await _graphClient.CreateFolder(_containerName, "root"); - -// Traverse the blob list -foreach (var blobName in fileList) -{ - FileStructure fs = new FileStructure() { blobName = blobName }; - - // This function parses the flat file into the folder hierarchy and creates the folder structure in the destination. It will retrieve the parentFolderId that the file should be copied to. - // If you are going to copy it to root you can comment this line out. The parentFolderId will be containerFolder.Id - fs.parentFolderId = TraverseBlobName(fs, containerFolder.Id) - - // This is where the thread pool happens. - // It takes in a callback function and an Object parameter. - ThreadPool.QueueUserWorkItem(MigrateFile, fs); -} - -// Call so the program doesn't end, it waits for all the files to be processed -_countdown.Wait(); -``` - -### Traverse blob name - -```c# -// Parse for folder path not including the file name and put it in an array -var pathSegments = filePath.Split(new char[] { '/' }, StringSplitOptions.RemoveEmptyEntries); -string[] directoriesParts = pathSegments.Take(pathSegments.Length - 1).ToArray(); - -// Traverse the folder listing and create 1 folder at a time -string relativePath = _containerName; -string newFolderId = parentFolderId; -foreach (string folderName in directoriesParts) -{ - string newPath = relativePath + _separator + folderName; - ... - - DriveItem subFolder = await _graphClient.CheckIfItemExists(folderName, newFolderId); - if (subFolder == null) - { - subFolder = await _graphClient.CreateFolder(folderName, newFolderId); - ... - } - newFolderId = subFolder.Id; - - relativePath = newPath; -} - -return newFolderId; -``` - -### Check if the item exists - -```c# -var item = await _graphClient.Drives[_containerId].Items[parentFolderId].ItemWithPath(itemPath).GetAsync(); -``` - -### Create folder - -```c# -var folder = new DriveItem -{ - Name = folderName, - Folder = new Folder(), - AdditionalData = new Dictionary() - { - { "@microsoft.graph.conflictBehavior", "fail" } - } -}; -var createdFolder = await _graphClient.Drives[_containerId].Items[parentFolderId].Children.PostAsync(folder); -``` - -### Migrate File - -```c# -// The parameter must be of type Object. -internal async void MigrateFile(Object stateInfo) -{ - var fileStructure = (FileStructure)stateInfo; - - // Check if the file exists in the destination. If it exists - // - don't upload - // - check if the file is newer in the source than the destination - then upload - ... - - // Migrate the file - // This is where you download the blob as a stream from abs (code below) - ... - - // Then upload the stream to SPE (code below) - ... - - // Signal the countdown event that a file has been migrated - _countdown.Signal(); - - return; -} -``` - -### Downloading From The Blob From ABS As A Stream - -```c# -BlobClient blobClient = _containerClient.GetBlobClient(blobName); - -MemoryStream memoryStream = new MemoryStream(); -await blobClient.DownloadToAsync(memoryStream); -memoryStream.Position = 0; // Reset the stream position to the beginning -``` - -### Uploading The Stream To SPE - -```c# -int _maxChunkSize = 320 * 1024; - -var uploadSessionRequestBody = new CreateUploadSessionPostRequestBody() -{ - AdditionalData = new Dictionary - { - // Fail is set here, so it doesn't get upload again if it already exist - { "@microsoft.graph.conflictBehavior", "fail" } - } -}; - -var uploadSession = await _graphClient.Drives[_containerId] - .Items[parentFolderId] - .ItemWithPath(fileName) - .CreateUploadSession - .PostAsync(uploadSessionRequestBody); - -// The stream is the same stream from the downloading the blob -var fileUploadTask = new LargeFileUploadTask(uploadSession, memoryStream, _maxChunkSize, _graphClient.RequestAdapter); -IProgress progress = new Progress(prog => Console.WriteLine($"Uploaded {fileName} {prog} bytes")); - -// Check uploadResult.UploadSucceeded to see if it is successful -var uploadResult = await fileUploadTask.UploadAsync(progress); -``` - -## Overview Of The Sample App - -### Description - -A sample app called **MigrateABStoSPE** that is designed to migrate files from an Azure Blob Storage (ABS) container to a SharePoint Embedded (SPE) container. The code snippets provided in the **Migrating Data from Azure Blob Storage container to SharePoint Embedded container** are from the sample app. - -It uses Azure.Storage.Blobs and Newtonsoft.Json libraries for working with ABS and JSON data respectively. The app authenticates with both ABS and SPE using client credentials and performs the migration of files. - -### Packages - -1. Microsoft Graph SDK (version 5.56.0) -1. Azure.Identity (version 1.12.0) -1. Azure.Storage.Blobs (version 12.21.0) -1. CommandLineParser (version 2.9.1) -1. Newtonsoft.Json (13.0.3) - -### Out Of Scope - -1. How to deal with files that already exist in the destination - it fails, it doesn't overwrite or rename -1. How to deal with ABS version newer than the destination - it fails because the file already exists in the destination - -### Running The Sample App - -1. Open a terminal or command prompt. -1. Navigate to the directory where the **Program.cs** file is located. -1. Make sure you have the .NET Core SDK installed on your machine. You can check this by running the command **dotnet --version** in the terminal. If the command isn't recognized, you can download and install the .NET Core SDK from the official Microsoft website. -1. Once you have confirmed that the .NET Core SDK is installed, you can build the application by running the command **dotnet build**. This will compile the code and generate the necessary binaries. -1. After the build process is complete, you can run the application by executing the command **dotnet run** followed by the required arguments. The required arguments are: - - - The container-level SAS URL: This is an Azure Blob container level SAS URL. It provides access to the container and its blobs. - - The SPE tenant ID: This is the tenant you're authenticating against in the SPE. - - The SPE client ID: This is the client you're authenticating against in the SPE. - - The SPE container ID: This is the container you're migrating content to in the SPE. For more information on how to get the [container ID](/graph/api/filestorage-list-containers) - - (optional) File name with full path that contains the blob list. - - (optional) File name with full path where to output failed blobs. - -For example, the command to run the application with the required arguments would look like this: - -```console -# line breaks added for readability -dotnet run Program.cs -- \ - --sasurl "" \ - --tenantid "" \ - --clientid "" \ - --containerid "" \ - [ --blobfile "" --outputfile "" ] -``` - -### Blob and SPE Item Structure - -ABS container doesn't adhere to a folder structure, all the blobs are stored in a flat listing structure. When migrating to SPE, the sample app parses the blob name and creates the folder structure in the container ID provided, with the container name as the top folder. If you're migrating to the root folder, you can ignore this section. - -**Source** - -- Container Name: Container1 - - Blob name: FolderA/blob1.txt - - Blob name: FolderA/FolderB/blob2.txt - - Blob name: FolderA/FolderB/FolderC/blob3.txt - -**Destination** - -- Drive Item folder - - Container1 - - FolderA - - blob1.txt - - FolderB - - blob2.txt - - FolderC - - blob3.txt - -## Handling Errors and Exceptions - -### Common Issues - -1. File already exists in the destination - - - This app checks to see if the file name exists in the destination before it uploads. If a file with the exact same name exists, it will not do the upload again. It will print to stdout a message that the file already exists. To fix it, you can either delete the file from the destination or change the `conflictBehavior` to replace and not call `CheckIfItemExists` on upload. - -1. The file for the list of blobs isn't found -1. The format for the list of blobs - one blob per line, without quotes around the blob name -1. Not giving enough permission to access the ABS container - - - The minimum permissions are **Read** and **List** - -1. Not giving enough permissions to the SPE container - - - The required scope is **User.Read** and **FileStorageContainer.Selected** - - Remember to grant admin consent - - Remember to create the mobile & console platform app - -## Testing the Migration - -### Verification - -1. When the file is queued, it will print to stdout -1. It will print the stats of the total blobs that were processed: total, success, exists in destination, and failed. -1. If there are errors, it will send the failed blob list to a file. The file name will be printed to stdout. It will also, print a command for an incremental re-run. - -## Conclusion - -### Summary - -In this tutorial, we explored how to migrate content from ABS container to SPE container. By following the steps outlined, writing your own app to migrate content should be easy. - -To recap, we: - -1. Authenticated with ABS and Graph -1. How to use a thread pool to queue migration of blob -1. Check if the item exists in destination -1. Retrieved the blob list from ABS container -1. Uploaded the blob to the SPE container - -Understanding these steps is crucial for migrating content from ABS container to SPE container. Now, try implementing these steps in your own projects and see the difference it makes! - -Happy coding! - -### Next Steps - -- For more information about Blob Storage, see [Blob Storage documentation](/azure/storage/blobs/storage-blobs-introduction). -- For more information about SPE, see [SharePoint Embedded documentation](https://aka.ms/start-spe). - -## Appendix - -### Code Repository - -The sample app can be found in the [SharePoint Embedded Samples repository](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/main/Tools/migrate-from-blob-storage). diff --git a/docs/embedded/development/tutorials/spe-da-vscode.md b/docs/embedded/development/tutorials/spe-da-vscode.md deleted file mode 100644 index 43e579d018..0000000000 --- a/docs/embedded/development/tutorials/spe-da-vscode.md +++ /dev/null @@ -1,355 +0,0 @@ ---- -title: SharePoint Embedded agent Tutorial -description: SharePoint Embedded agent tutorial with the SDK and the VS Code SharePoint Embedded Extension -ms.date: 03/06/2025 -ms.localizationpriority: high ---- - -# Tutorial for getting started with SharePoint Embedded agent - -## Prerequisites - -> [!NOTE] -> -> 1. You'll need to create a SharePoint Embedded application. If you don't have one, you can easily build a sample application using the instructions [here](#getting-started-using-the-sharepoint-embedded-visual-studio-code-extension). -> 1. You must specify a standard container type at creation time. Depending on the purpose, you may or may not need to provide your Azure Subscription ID. A container type set for trial purposes can't be converted for production, or vice versa. -> 1. You must use the latest version of SharePoint PowerShell to configure a container type. For permissions and the most current information about Windows PowerShell for SharePoint Embedded, see the documentation at [Intro to SharePoint Embedded Management Shell](/powershell/SharePoint/SharePoint-online/introduction-SharePoint-online-management-shell). -> -> - Set the **CopilotChatEmbeddedHosts** property of your container type configuration to `http://localhost:8080` to be able to work through the following quick start, refer to [the preceding CSP section for more information](../declarative-agent/spe-da-adv.md#csp-policies). -> - Set the **DiscoverabilityDisabled** property of your container type configuration to `false` so that the agent can find the files in your created container. Refer to the [Discoverability Disabled section above for more information](../declarative-agent/spe-da-adv.md#discoverabilitydisabled). -> - Ensure that Copilot for Microsoft 365 is available for your organization. You have two ways to get a developer environment for Copilot: -> - A sandbox Microsoft 365 tenant with Microsoft 365 Copilot (available in limited preview through [TAP membership](https://developer.microsoft.com/microsoft-365/tap)). -> - An [eligible Microsoft 365 or Office 365 production environment](/microsoft-365-copilot/extensibility/prerequisites#customers-with-existing-microsoft-365-and-copilot-licenses) with a Microsoft 365 Copilot license. - -## Getting started using the SharePoint Embedded SDK - -### 1. Install the SDK into your React repo - -```console -# Install the SDK with npm - -npm install "https://download.microsoft.com/download/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz" -``` - -#### If you want to verify checksums - -In MacOS/Linux - -```console -version="1.0.9"; - -url="https://download.microsoft.com/download/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz"; - -expected_checksum="3bdf19830ffc098b253cc809f969f50fba236ad95fe85123e7b15c7cf58ecf6b"; - -package_path="microsoft-sharepointembedded-copilotchat-react-$version.tgz"; - -curl -o $package_path $url && [ "$(sha256sum $package_path | awk '{ print $1 }')" == "$expected_checksum" ] && npm install $package_path || { echo "Checksum does not match. Aborting installation."; rm $package_path; } -``` - -In Windows: - -```powershell -$version = "1.0.9" -$url = "https://download.microsoft.com/download/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz" -$expected_checksum = "3BDF19830FFC098B253CC809F969F50FBA236AD95FE85123E7B15C7CF58ECF6B" -$package_path = "microsoft-sharepointembedded-copilotchat-react-$version.tgz" - -Invoke-WebRequest -Uri $url -OutFile $package_path - -$calculated_checksum = Get-FileHash -Path $package_path -Algorithm SHA256 | Select-Object -ExpandProperty Hash - -if ($calculated_checksum -eq $expected_checksum) { - Write-Output "Checksum matches. Installing the package..." - npm install $package_path -} else { - Write-Output "Checksum does not match. Aborting installation." -} -Remove-Item $package_path -``` - -### 2. Create an `authProvider` object - -This is an object that matches this interface: - -```typescript -export interface IChatEmbeddedApiAuthProvider { - // The hostname for your tenant. Example: https://m365x10735106.sharepoint.com - hostname: string; - // This function will be called when an SPO token is required - // Scope needed: ${hostname}/Container.Selected - getToken(): Promise; -} -``` - -Example usage in app: - -```typescript -// In your app: -import { IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react'; - -const authProvider: IChatEmbeddedApiAuthProvider = { - hostname: 'https://m365x10735106.sharepoint.com', - getToken: requestSPOAccessToken, -}; -``` - -Example implementation of `getToken` (you need to customize it): - -```typescript -// -async function requestSPOAccessToken() { - // Use your app's actual msalConfig - const msalConfig = { - auth: { - clientId: "{Your Entra client ID}", // this can likely point to process.env.REACT_APP_CLIENT_ID if you have set it in your .env file - }, - cache: { - // https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/caching.md - /* - Cache Location | Cleared on | Shared between windows/tabs | Redirect flow supported - ----------------- ---------- ------------------------- ------------------------ - sessionStorage | window/tab close | No | Yes - localStorage | browser close | Yes | Yes - memoryStorage | page | refresh/navigation | No | No - */ - cacheLocation: 'localStorage', - storeAuthStateInCookie: false, - }, - }; - - const containerScopes = { - scopes: [`${authProvider.hostname}/Container.Selected`], - redirectUri: '/' - }; - - const pca = new msal.PublicClientApplication(msalConfig); - let containerTokenResponse; - - // Consent FileStorageContainer.Selected scope - try { - // attempt silent acquisition first - containerTokenResponse = await pca.acquireTokenSilent(containerScopes); - return containerTokenResponse.accessToken; - } catch (error) { - if (error instanceof InteractionRequiredAuthError) { - // fallback to interaction when silent call fails - containerTokenResponse = await pca.acquireTokenPopup(containerScopes); - return containerTokenResponse.accessToken; - } - else { - console.log(error); - } - } -} -``` - -### 3. Create a React state to store your `chatApi` in - -```typescript -const [chatApi, setChatApi] = React.useState(null); -``` - -Example: - -```typescript -import React from 'react'; -import { ChatEmbedded, ChatEmbeddedAPI, IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react'; - -//... -async function requestSPOAccessToken() { - //... -} - -const authProvider: IChatEmbeddedApiAuthProvider = { - hostname: 'https://m365x10735106.sharepoint.com', - getToken: requestSPOAccessToken, -}; - -function App() { - const [chatApi, setChatApi] = React.useState(null); - - return ( - //... - ); -} -``` - -### 4. Add the `ChatEmbedded` component into your react app - -```typescript -import React from 'react'; -import { ChatEmbedded, ChatEmbeddedAPI, IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react'; - -//... -async function requestSPOAccessToken() { - //... -} - -const authProvider: IChatEmbeddedApiAuthProvider = { - hostname: 'https://m365x10735106.sharepoint.com', - getToken: requestSPOAccessToken, -}; - -function App() { - const [chatApi, setChatApi] = React.useState(null); - - return ( - //... - - //... - ); -} -``` - -### 5. Use the `chatApi` object in your state to open the chat and run it - -In the preceding example, call it this way to open the chat. - -```typescript -await chatApi.openChat(); -``` - -You may choose to pass in launch configurations - -```typescript -import { IconName, IconStyle } from './sdk/types'; - -//... -const zeroQueryPrompts = { - headerText: "This is my Starter Prompt", - promptSuggestionList: [{ - suggestionText: 'Hello', - iconRegular: { name: IconName.ChatBubblesQuestion, style: IconStyle.Regular }, - iconHover: { name: IconName.ChatBubblesQuestion, style: IconStyle.Filled }, - }] -}; - -const launchConfig: ChatLaunchConfig = { - header: 'My Awesome Chat', - zeroQueryPrompts, - suggestedPrompts: ["What are my files?",], - instruction: "Response must be in the tone of a pirate", - locale: "en", -}; - -await chatApi.openChat(launchConfig); -``` - -Full example: - -```typescript -import React from 'react'; -import { ChatEmbedded, ChatEmbeddedAPI, IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react'; - -//... -async function requestSPOAccessToken() { - //... -} - -const authProvider: IChatEmbeddedApiAuthProvider = { - hostname: 'https://m365x10735106.sharepoint.com', - getToken: requestSPOAccessToken, -}; - -function App() { - const [chatApi, setChatApi] = React.useState(null); - - React.useEffect(() => { - const openChat = async () => { - if (!chatApi) { - return; - } - - await chatApi.openChat(); - }; - - openChat(); - }, [chatApi]); - - - return ( - //... - setChatApi(api)} - authProvider={authProvider} - containerId={container.id} - style={{ width: 'calc(100% - 4px)', height: 'calc(100vh - 8px)' }} - /> - //... - ); -} -``` - -### 6. Your AI chat should be loaded successfully - -## Getting started using the SharePoint Embedded Visual Studio Code Extension - -### Quick Start - -> [!NOTE] -> When using standard container types with the VS Code extension, [DisableDiscoverability](../declarative-agent/spe-da-adv.md#discoverabilitydisabled) and [Grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal) features are currently not supported. This will need to be done using the [SPO Admin PowerShell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online). - -1. Follow this guide up to the [Load Sample App section](../../getting-started/spembedded-for-vscode.md#load-sample-app) with the Visual Studio Code Extension -1. Within the extension, right select on the owning application, and select `Run sample apps -> Typescript + React + Azure Functions` - - ![Using the SPE VS Code extension to create a TypeScript React Azure Functions project](../../images/speco-runsampleapp.png) - -1. Allow for the extension to copy and create client secrets - - > [!CAUTION] - > Caution for production environments, storing secrets in plain text poses a security risk. - - ![SPE VS Code notification alerting it will copy app secrets in plain text on local machine](../../images/speco-createappsecret.png) - - If the application doesn't already have a client secret, the extension will ask to create one for you. - - ![SPE VS Code notification prompting user to allow it to create a secret for the application if it does not exist.](../../images/speco-createclientsecret.png) - -1. Select a folder to host the application, this will clone the following [repository for SharePoint Embedded Samples](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/main/Custom%20Apps/boilerplate-typescript-react) into the folder - - ![windows File Explorer folder to save project on local machine](../../images/speco-cloneproject.png) - - Next, when prompted, open the folder - - ![VS Code extension with the SPE React Typescript + Azure Functions sample application cloned on local machine and open in VS Code](../../images/speco-vscodeclonedproject.png) - -1. Navigate to `react-client\src\components\ChatSideBar.tsx` and uncomment this section - - ![VS Code file explorer with ChatSideBar.tsx in open window with relevant code to uncomment highlighted](../../images/speco-uncommentchatsidebar.png) - -1. Navigate to `react-client\src\routes\App.tsx` and set the React state of the `showSidebar` variable to `true` - - ![VS Code file explorer with App.tsx open with line of showSidebar variable useState function input changed from false to true to enable showing chat side bar](../../images/speco-setshowsidebartrue.png) - -1. You can follow the instructions of the `README.md` file in the root of the project for further npm commands. Run `npm run start` in the root of the project to start your application with the SPE agent functionality enabled. - - > [!NOTE] - > `npm run start` Should be done in the root folder of the sample project. `\SharePoint-Embedded-Samples\Custom Apps\boilerplate-typescript-react` - - ![VS Code terminal in root folder of SPE Typescript project cloned earlier and npm run start command typed in](../../images/speco-runnpmrunstart.png) - -1. Sign in with a user who has a Microsoft 365 Copilot license enabled. - - ![SPE Typescript App running in Edge with sign in buttons](../../images/speco-reacttypescripthomepage.png) - -1. Navigate to the `containers` page, create one if you don't have any yet - - ![SPE Typescript App running in edge in /containers sub page with modal of user c reatign a container called ContosoCompanyContainer](../../images/speco-createcontosocontainer2.png) - - After it has been created, you'll see it here: - - ![SPE Typescript App running in edge with a created container from above ContosoCompanyContainer](../../images/speco-createdcontainer.png) - -1. Select the container and upload your files. Once a container has been created and you have navigated inside it, your agent chat experience will become enabled. - - ![SPE Typescript App running in edge inside a created container page of ContosoCompanyContainer](../../images/speco-spechatenabled.png) - -### Examples - -The [SharePoint Embedded Samples](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/main/Custom%20Apps/boilerplate-typescript-react) repository has examples for how to use SharePoint Embedded in your custom applications. diff --git a/docs/embedded/development/tutorials/using-file-preview.md b/docs/embedded/development/tutorials/using-file-preview.md deleted file mode 100644 index 3c17ada733..0000000000 --- a/docs/embedded/development/tutorials/using-file-preview.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: File Previews -description: Preview SharePoint Embedded content -ms.date: 03/05/2025 -ms.localizationpriority: high ---- - -# Using File Previews - -## Embedding a file preview in an iFrame - -It's possible to preview a [wide range](https://support.microsoft.com/office/file-types-supported-for-previewing-files-in-onedrive-sharepoint-and-teams-e054cd0f-8ef2-4ccb-937e-26e37419c5e4) of files in your browser without using a special application. Among the files supported, you can view PDF, JPG, MP4, etc. - -In order to preview a file in an `iframe`, you need to - -1. Call Graph's driveItem preview endpoint and obtain the GetUrl -1. Use the URL in an iFrame (or even open it in a new page) - -## Get the preview url using Graph - -Microsoft Graph offers the following endpoint to [preview a file](/graph/api/driveitem-preview): - -```javascript -POST https://graph.microsoft.com/{version}/drives/{driveId}/items/{itemId}/preview -``` - -- `Version` is Graph's version. For example "v1.0" -- The `driveId` is Container ID (starts with "b!") -- The `itemId`, which is the drive item ID. - -If you're using the Microsoft Graph C# SDK, the code would be similar to the following: - -```csharp -ItemPreviewInfo preview = await graphServiceClient - .Drives[driveId] - .Items[itemId] - .Preview() - .Request() - .PostAsync(); -``` - -The JSON response includes the preview URLs for each document. Use the one obtained in `getUrl`: - -```javascript -{ - "getUrl": "https://www.onedrive.com/embed?foo=bar&bar=baz", - "postParameters": "param1=value¶m2=another%20value", - "postUrl": "https://www.onedrive.com/embed_by_post" -} -``` - -> [!TIP] -> It's possible to remove the banner at the top by adding the parameter `nb=true` to the obtained URL. E.g., -> `https://contoso.sharepoint.com/restOfUrl/embed.aspx?param1=value&nb=true` - -> [!CAUTION] -> Currently **getUrl** contains a parameter with an encrypted token that can only be used with your application. However, this may change soon and you may be asked to add an auth header as you do with other requests. - -## Use the URL in an `iframe` - -The next step is simply to use the URL obtained in the previous step in a new page. You could have an endpoint in your application that serves a new page as similar to this one: - -```html - - - -

Preview

-

Preview of {file name}:

- - - - -``` - -## Load the document preview dynamically - -If you intend to dynamically load the preview in the same page without leaving it, you might get a CORS error if you attempt to access the Microsoft Graph endpoint directly from a script from your page. - -One way to solve this problem is to create an endpoint in your application that makes the request and returns the url. - -For example, your server-side code should first obtain the document's preview url: - -```csharp -[HttpGet] -[AuthorizeForScopes(Scopes = new string[] { "Files.Read.All" })] -public async Task> GetPreviewUrl(string driveId, string itemId) -{ - // Obtain tokens for the the request - // Use the function created in the first step - return url + "&nb=true"; //Use nb=true to suppress banner -} -``` - -The client-side application can then use the browser's `fetch` API to request and inject the url into the `iframe`: - -```javascript -async function preview(driveId, itemId) { - const url = `/GetPreviewUrl?driveId=${driveId}&itemId=${itemId}`; - const response = await fetch(url, { - credentials: 'include', - }).then(response => response.text()); - - document.getElementById('preview').src = response + "&nb=true"; //Use nb=true to suppress banner -} -``` - -## PDF Preview - -SharePoint Embedded includes a PDF previewer that you can enhance with query parameters appended to the driveItem's `webUrl` property. To get `webUrl`, call the [driveItem GET API](/graph/api/driveitem-get), for example `GET /drives/{drive-id}/items/{item-id}?$select=webUrl`, and retrieve the `webUrl` field. - -The parameters are passed as a JSON-encoded `embed` query string: - -```text -?&embed={"":,"":} -``` - -You can include one or more parameters in the same object. - -> [!NOTE] -> Additional query parameters will be added to this section as the PDF previewer expands. - -### Print (`mpp`) - -Enables the print icon and Ctrl+P functionality. - -```text -?&embed={"mpp":true} -``` - -### Sticky Notes (`mpsn`) - -Shows sticky note content if sticky notes are present in the PDF. - -```text -?&embed={"mpsn":true} -``` diff --git a/docs/embedded/development/tutorials/using-webhooks.md b/docs/embedded/development/tutorials/using-webhooks.md deleted file mode 100644 index 88fb8ca114..0000000000 --- a/docs/embedded/development/tutorials/using-webhooks.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Using Webhooks -description: Use webhooks with SharePoint Embedded. -ms.date: 03/03/2025 -ms.localizationpriority: high ---- - -# Using Webhooks - -## Set Up Webhooks with SharePoint Embedded - -Webhooks are automated messages that are transmitted by an application when a trigger is activated. They can be used in SPE to enable the automation of workflows, the integration of systems, and to respond to events in real-time. - -You'll use webhooks to invoke the Azure Cognitive Services APIs from the application whenever an existing file is updated, or a new file is uploaded. - -To set up webhooks with your [current SharePoint Embedded application](/training/modules/sharepoint-embedded-create-app/), you need to: - -1. Create and register a webhook endpoint to get notifications whenever there's a change in your container. This will be done using REST APIs. -1. Connect to Graph and subscribe to changes. You can expose your application to the internet by either running it locally or deploying it on the cloud. For this tutorial, you'll be employing the former by utilizing ngrok and then subscribing to the changes by making a POST call. -1. Perform any desired action by handling the webhook data. One such use case is covered in [Enabling document processing with Azure Cognitive Services tutorial](./doc-processing-acs.md). - -![using webhooks schema](../../images/Using-Webhooks.png) - -> [!TIP] -> To learn more about the Microsoft Graph APIs used in this tutorial, see [Create subscription](/graph/api/subscription-post-subscriptions). - -## Create and register a webhook - -Open the **index.ts** file and add an endpoint `onReceiptAdded`: - -```typescript -server.post('/api/onReceiptAdded', async (req, res, next) => { - try { - const response = await onReceiptAdded(req, res); - res.send(200, response) - } catch (error: any) { - res.send(500, { message: `Error in API server: ${error.message}` }); - } - next(); -}); -``` - -You also need to add the query parser plugin at the top of this file so that it runs at server startup: - -```typescript -server.use(restify.plugins.bodyParser(), restify.plugins.queryParser()); -``` - -Create **onReceiptAdded.ts** and implement the method `onReceiptAdded` to read `validationToken` and `driveId`. `validationToken` is required when Microsoft Graph makes a one-time call to verify the endpoint upon creation of the webhook subscription. `driveId` is the container-id for which the subscription is created. - -```typescript -require('isomorphic-fetch'); - -export const onReceiptAdded = async (req: Request, res: Response) => { - - const validationToken = req.query['validationToken']; - if (validationToken) { - res.send(200, validationToken, {"Content-Type":"text/plain"}); - return; - } - - const driveId = req.query['driveId']; - if (!driveId) { - res.send(200, "Notification received without driveId, ignoring", {"Content-Type":"text/plain"}); - return; - } - - console.log(`Received driveId: ${driveId}`); - - res.send(200, ""); - return; -} -``` - -## Connect to Graph and subscribe to changes - -Follow the [documentation](https://ngrok.com/docs/getting-started/) to create a tunnel for your backend server using ngrok. - -After starting the app, run the following command in a terminal: - -```console -ngrok http 3001 -``` - -On successful completion, you should get the following output. The public-facing endpoint for the app is highlighted in the red rectangle: - -![ngrok registration](../../images/ngrok-registration.png) - -Once the tunneling is active, you can subscribe to delta changes in the container by adding the webhook URL. To do that, open Postman and make the following `POST` request with the appropriate graph access token and `notificationUrl` with the `driveId` appended as a query parameter to ensure that you get notifications for changes only in the desired container. - -```json -POST https://graph.microsoft.com/v1.0/subscriptions -{ - "changeType": "updated", - "notificationUrl":"https://5ac2-2404-f801-8028-3-691a-87b2-d309-545b.ngrok-free.app/api/onReceiptAdded?driveId={{ContainerId}}", - "resource": "drives/{{ContainerId}}/root", - "expirationDateTime": "2024-01-20T03:58:34.088Z", - "clientState": "" -} -``` - -You can use the following code snippet for setting the max possible expiration time of 4230 minutes from the current time by adding this to the "Pre-request Script" section. It will set an environment variable that can be used in the request body. - -```javascript -var now = new Date() -var duration = 1000 * 60 * 4230; // max lifespan of driveItem subscription is 4230 minutes -var expiry = new Date(now.getTime() + duration); -var expiryDateTime = expiry.toISOString(); - -pm.environment.set("ContainerSubscriptionExpiry", expiryDateTime); -``` - -At this point, if you add/update any file in the container, you'll get a notification at the previously added endpoint (`/api/onReceiptAdded`) and a log message at the console: `Received driveId: ` diff --git a/docs/embedded/development/tutorials/vendor-install-app-customer.md b/docs/embedded/development/tutorials/vendor-install-app-customer.md deleted file mode 100644 index 949fdfd8ad..0000000000 --- a/docs/embedded/development/tutorials/vendor-install-app-customer.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Install your SharePoint Embedded application for customers. -description: Seamlessly install your SharePoint Embedded application on your customers' tenant. -ms.date: 10/08/2025 -ms.localizationpriority: medium ---- - -# Install your SharePoint Embedded application for customers - -This guide provides instructions for developers looking to get their SharePoint Embedded (SPE) app installed on a Microsoft 365 consuming tenant. - -## Prerequisites - -This guide assumes that you created a SharePoint Embedded container type and developed your application. Learn more about [container types](../../getting-started/containertypes.md). - -The consuming tenant can be any Microsoft 365 tenant (including your own), but it must have at least one SharePoint license. - -## Overview - -Developers looking to get their SharePoint Embedded app installed on a tenant have a few tasks to complete: - -- Get the required admin permission grants for your app on the consuming tenant -- Register your app's container type on the consuming tenant -- Ensure your customer’s tenant completed [SharePoint Embedded pay-as-you-go billing setup](../../administration/consuming-tenant-admin/cta.md#set-up-billing-for-passthrough-container-type) if your container type is [configured for pass-through billing](../../administration/billing/billing.md#passthrough-billing) - -### Application permissions to request - -Your app needs a minimum set of Microsoft Graph permissions to be installed on a consuming tenant. For more information, see [SharePoint Embedded authentication and authorization](../auth.md). - -1. [`FileStorageContainerTypeReg.Selected`](/graph/permissions-reference#filestoragecontainertyperegselected) delegated or application permission to register the SPE container type in the consuming tenant. When your app uses the delegated permission, the user performing the container type registration must be a [SharePoint Embedded Admin](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) or [Global Admin](/entra/identity/role-based-access-control/permissions-reference#global-administrator). The application permission requires admin consent, but the delegate permission doesn't require admin consent. -1. [`FileStorageContainer.Selected`](/graph/permissions-reference#filestoragecontainerselected) delegated or application permission to interact with SharePoint Embedded content for the container type in the consuming tenant. This permission requires admin consent. - -> [!IMPORTANT] -> Using SharePoint Embedded on behalf of a user is the recommended approach. This type of access enhances the security of your application. It also improves the auditability of actions performed by your application. - -### Request admin consent - -Single-tenant apps (when the app is registered and is used in the same tenant) can benefit from getting admin consent from the Microsoft Entra directory administrator in a simplified manner. [Construct the admin consent URL](/entra/identity-platform/v2-admin-consent#request-the-permissions-from-a-directory-admin) and provide it to your Microsoft Entra directory administrator for them to grant admin consent. For example: - -```http -https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id={client_id}&redirect_uri={redirect_uri} -``` - -> [!NOTE] -> Make sure your app's [redirect URI](/entra/identity-platform/reply-url) can [handle admin consent flows](/entra/identity-platform/v2-admin-consent#successful-response). - -## In-app installation experience (recommended) - -You can facilitate the installation of your SharePoint Embedded app within your own app experience. We recommended that you use the [Microsoft Authentication Library (MSAL)](/entra/identity-platform/msal-overview) to handle all authorization steps. Here's the high-level process: - -1. Provide a [sign-in experience in your app](/entra/identity-platform/quickstart-web-app-sign-in) and obtain an [ID token](/entra/identity-platform/id-tokens) for the user -1. Inspect and [validate the token](/entra/identity-platform/claims-validation) to extract the tenant ID and roles assigned to the user -1. Determine if your app is already installed on the tenant - 1. Request a Microsoft Graph access token with `FileStorageContainerTypeReg.Selected` application permission - 1. Try to [get the registration for your container type](/graph/api/filestoragecontainertyperegistration-get). If your container type is already registered in the consuming tenant, you're done! -1. Determine if the user has either the [Privileged Role Administrator](/entra/identity/role-based-access-control/permissions-reference#privileged-role-administrator) or [Global Administrator](/entra/identity/role-based-access-control/permissions-reference#global-administrator) roles by validating the `wids` claim in the ID token. - 1. If the user isn't a Privileged Role Admin or Global Admin, it's unlikely that they can provide admin consent in the following steps. -1. [Request admin consent](#request-admin-consent) for your app by navigating the user to the admin consent URL. - 1. Ensure your app's redirect URI can handle this redirection appropriately so you can proceed with the next steps within the app experience. -1. Once admin consent is granted, request a Microsoft Graph access token with `FileStorageContainerTypeReg.Selected` application permission -1. [Create your container type registration](/graph/api/filestorage-post-containertyperegistrations) on the consuming tenant -1. If your container type is [configured for pass-through billing](../../administration/billing/billing.md#passthrough-billing), you should make a billable API call to confirm that billing is set up. For example, [create a container](/graph/api/filestoragecontainer-post). - 1. If the call fails with a billing error, point the user to [set up SharePoint Embedded pay-as-you-go billing](../../administration/consuming-tenant-admin/cta.md#set-up-billing-for-passthrough-container-type). diff --git a/docs/embedded/getting-started/containertypes.md b/docs/embedded/getting-started/containertypes.md deleted file mode 100644 index c87544cd4c..0000000000 --- a/docs/embedded/getting-started/containertypes.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: Create new SharePoint Embedded container types -description: This article explains how container types work and the steps to create new container types. -ms.date: 11/27/2023 -ms.localizationpriority: high ---- - -# SharePoint Embedded container types - -A container type is a SharePoint Embedded resource that defines the relationship, access privileges, and billing accountability between a SharePoint Embedded application and a set of containers. Also, the container type defines behaviors on the set of containers. - -Each container type is strongly coupled with one SharePoint Embedded application, which is referred to as the owning application. The owning application developer is responsible for creating and managing their container types. SharePoint Embedded mandates a 1:1 relationship between the owning application and a container type. - -A container type is represented on each container instance as an immutable property (ContainerTypeID) and is used across the entire SharePoint Embedded ecosystem, including: - -- **Access authorization**: A SharePoint Embedded application must be associated with a container type to get access to container instances of that type. Once associated, the application has access to all container instances of that type. The actual access privilege is determined by the application-ContainerTypeID permission setting. The owning application by default has full access privilege to all container instances of the container type it's strongly coupled with. Learn more about [SharePoint Embedded Authorization](../development/auth.md). -- **Easy exploration**: Container types can be created for trial purposes, allowing developers to explore SharePoint Embedded application development and assess its features for free. -- **Billing**: Container types for nontrial purposes are billable and must be created with an Azure Subscription. The usage of containers is metered and charged. Learn more about [metering](../administration/billing/meters.md) and the [SharePoint Embedded billing experience](../administration/billing/billingmanagement.md). -- **Configurable behaviors**: Container type defines selected behaviors for all container instances of that type. Learn more about setting [Container type configuration](../getting-started/containertypes.md#configuring-container-types). - -> [!NOTE] -> -> 1. You must specify the purpose of the container type you're creating at creation time. A container type set for trial purposes can't be converted for production; or vice versa. -> 1. Standard and passthrough container types can't be converted once created. If you want to convert a standard container type to passthrough billing or vice versa, you must delete and re-create the container type. - -## Tenant requirements - -- An active instance of SharePoint is required in your Microsoft 365 tenant. -- Users who authenticate into SharePoint Embedded container types and containers must be in Microsoft Entra ID (Members and Guests) -- A Microsoft Entra ID app registration needs to be configured for container type management. For more information, see [SharePoint Embedded authentication and authorization](../development/auth.md). - -> [!NOTE] -> An Office license isn't required to collaborate on Microsoft Office documents stored in a container. - -## Creating container types - -SharePoint Embedded has two different container types you can create. - -1. [Trial container type](#trial-container-type). Uses the `trial` billing classification. -1. [Standard container type](#standard-container-types-nontrial). Uses the `standard` or `directToCustomer` billing classification. - -To create a container type, your Microsoft Entra ID application needs the [`FileStorageContainerType.Manage.All`](/graph/permissions-reference#filestoragecontainertypemanageall) **delegated** Microsoft Graph permission. Application-only access isn't supported for this endpoint. The calling user must be a non-guest member of the owning tenant. Administrator roles aren't required. The calling user is automatically assigned as an owner of the new container type. For details on owner capabilities and how to manage owners, see [Container type owner capabilities](../development/auth.md#container-type-owner-capabilities). - -Call the [Create fileStorageContainerType](/graph/api/filestorage-post-containertypes) endpoint: - -```http -POST https://graph.microsoft.com/beta/storage/fileStorage/containerTypes -Content-Type: application/json - -{ - "name": "{ContainerTypeName}", - "owningAppId": "{ApplicationId}", - "billingClassification": "{BillingClassification}", - "settings": { - ... - } -} -``` - -> [!NOTE] -> Replace: -> -> - `{ContainerTypeName}` with a user-friendly name for your SharePoint Embedded application. -> - `{ApplicationId}` with the ID of your properly configured application. -> - `{BillingClassification}` with `trial`, `standard`, or `directToCustomer`. Keep reading to understand what each means. -> -> You can also [configure your container type](#configuring-container-types) during creation by setting the `settings` field. - -## Trial container type - -A container type can be created for trial/development purposes and isn't linked to any Azure billing profile. Trial container types enable developers to explore SharePoint Embedded application development and assess its features for free. For trial container types, the developer tenant is the same as the consuming tenant. -Each developer can have only one container type with `trial` billing classification in their tenant at a time. The trial container type is valid for up to 30 days but can be removed at any time within this period. - -You can easily set up a trial container type using the [SharePoint Embedded Visual Studio Code extension](../getting-started/spembedded-for-vscode.md). - -The following restrictions are applied to trial container types: - -- The tenant can have up to five containers of the container type. This includes active containers and those in the recycle bin. -- Each container has up to 1 GB of storage space. -- The container type expires after 30 days and access to any existing containers of that container type is then removed. -- The developer must permanently delete all containers of an existing container type in trial status to create a new container type for trial. This includes containers in the deleted container collection. -- The container type is restricted to work in the developer tenant. It can't be deployed in other consuming tenants. - -## Standard container types (nontrial) - -A standard container type can be used in production environments. Each tenant can have 25 container types at a time. Standard container types don't have the same restrictions as trial container types, but they still have limits. For more information, see [SharePoint Embedded Limits](../development/limits-calling.md). - -To learn more about the supported pay-as-you-go meters, refer to the [SharePoint Embedded meters](../administration/billing/meters.md) article. - -### Billing profile - -SharePoint Embedded is a consumption-based, pay-as-you-go (PAYG) offering meaning you pay only for what you use. SharePoint Embedded provides two billing models that the tenant developing the SharePoint Embedded application can select for respective container types, tailoring it to their unique business requirements. The two billing models are Standard and Passthrough billing. - -### Standard container type - with billing profile - -With the standard billing profile, all consumption-based charges are directly billed to the tenant who owns or develops the application. The admin in the developer tenant must establish a valid billing profile when creating a standard container type. - -![Standard](../images/1bill521.png) - -There are limits around the number of container types that each tenant can have. For more information, see [SharePoint Embedded Limits](../development/limits-calling.md). - -### Roles and Permissions - -- The admin who sets up the billing relationship for SharePoint Embedded needs to have owner or contributor permissions on the Azure subscription. -- The admin needs to have a SharePoint Embedded Administrator or Global Administrator role to operate billing cmdlets. - -### Azure Subscription - -For the standard billing container type, the Global Administrator needs to: - -- [Create an Azure subscription in your tenancy](/azure/cloud-adoption-framework/ready/azure-best-practices/initial-subscriptions) -- [Create a resource group](/azure/azure-resource-manager/management/manage-resource-groups-portal) attached to the Azure subscription - -After [creating the container type](#creating-container-types) with `standard` billing classification, you need to attach a billing profile to the container type. - -### Set the billing profile - -The billing profile for your container type is created using **SharePoint Online Management Shell**: - -1. Download and install the [latest version of SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588) -1. Open SharePoint Online Management Shell from **Start** screen, type **sharepoint**, and then select **SharePoint Online Management Shell**. -1. Connect to SPO service using `Connect-SPOService` cmdlet by providing admin credentials associated with tenancy. For information, see [how to use Connect-SPOService](/powershell/module/sharepoint-online/connect-sposervice). -To create the standard billing profile for your container type, use the following cmdlet: - -```powershell -Add-SPOContainerTypeBilling –ContainerTypeId -AzureSubscriptionId -ResourceGroup -Region -``` - -> [!NOTE] -> The admin who sets up a billing relationship for SharePoint Embedded must have owner or contributor permissions on the Azure subscription, and be assigned the SharePoint Embedded Administrator or Global Administrator role. -> -> Every container type must have an owning application. -> -> A single-owning app can only own one container type at a time. -> -> An Azure subscription can be attached to any number of container types. -> -> If the preceding cmdlet fails with a SubscriptionNotRegistered error, it is because **Microsoft.Syntex** isn't registered as a resource provider in the subscription. The cmdlet sends a resource provider registration request on your behalf but it takes a few minutes to be completed. Wait 5-10 minutes and try again until the cmdlet succeeds. - -To update the billing profile for a standard container type, use the following cmdlet: - -```powershell -Set-SPOContainerType -ContainerTypeId [-AzureSubscriptionId ] [-ResourceGroup ] -``` - -> [!NOTE] -> Billing setup for standard container types is done via the SharePoint Online Management Shell. In the future, this operation will be available as a Microsoft Graph operation. - -### Standard container type - passthrough billing - -With passthrough billing, consumption-based charges are billed directly to the tenant registered to use the SharePoint Embedded application (consuming tenant). Admins in the developer tenant don't need to set up an Azure billing profile when creating a passthrough SharePoint Embedded container type. - -![Pass Through](../images/2bill521.png) - -For container types intended to be directly billed to a customer use the `directToCustomer` billing classification during [container type creation](#creating-container-types). For the passthrough billing container types, there's no need to attach a billing profile. - -Once the container type is [registered](../getting-started/register-api-documentation.md) in the consuming tenant, the consuming tenant admin (SharePoint Administrator or Global Administrator) needs to set up the billing profile in the consuming tenant to use the SharePoint Embedded application. - -#### Set up billing profile in consuming tenant - -1. In [Microsoft 365 admin center](https://admin.microsoft.com/), select **Setup**, and the view the **Billing and licenses** section. Select **Activate pay-as-you-go services.** - - ![Microsoft 365 admin center Files and Content](../images/SyntexActivatePAYGSetup.png) - -1. Select **Go to Pay as you go services**. -1. Select **Apps** under **Syntex services for**, then select **SharePoint Embedded** in the Apps panel - - ![Microsoft 365 admin center SharePoint Embedded Billing setting](../images/SyntexPAYGActivateSPE.png) - - > [!NOTE] - > The subscription configured in the Syntex services will reflect the consuming charges in the Azure billing portal. - -## Configuring container types - -The Developer Admin may apply configuration when calling the [Create fileStorageContainerType](/graph/api/filestorage-post-containertypes) endpoint. Alternatively, they may call the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) endpoint to reconfigure an existing container type. - -> [!IMPORTANT] -> Updating settings on a container type may take up to **24 hours** for the new values to be replicated on all consuming tenants. If a consuming tenant applied overrides on container type settings, the new values aren't applied and the overrides remain in place. Some settings only apply to new content and not to existing content for the container type (for example, storage size, discoverability enabled, and others). - -For information on all the settings supported by container types, see [fileStorageContainerTypeSettings resource type](/graph/api/resources/filestoragecontainertypesettings). - -## Viewing container types - -You can list container types in your tenant by calling the [List fileStorageContainerType](/graph/api/filestorage-list-containertypes) endpoint. Results are filtered by ownership: non-administrator users see only the container types they have a permission on. [SharePoint Embedded Administrators](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) and [Global Administrators](/entra/identity/role-based-access-control/permissions-reference#global-administrator) see every container type in the tenant. - -## Registering container types - -To create and interact with containers, you must [register](../getting-started/register-api-documentation.md) the container type within the Consuming Tenant. The owning application defines the permissions for the container type by invoking the [Create fileStorageContainerTypeRegistration](/graph/api/filestorage-post-containertyperegistrations) endpoint. - -## Deleting container types - -You can only delete trial container types. Deletion of standard container types isn't yet supported. Before you delete a container type, you need to remove every container of that type, including from the deleted container collection. To remove containers, see [Delete fileStorageContainer](/graph/api/filestorage-delete-containers). - -Once every container is deleted, call the [Delete fileStorageContainerType](/graph/api/filestorage-delete-containertypes) endpoint. Non-administrator users can delete only container types they have a permission on. [SharePoint Embedded Administrators](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) and [Global Administrators](/entra/identity/role-based-access-control/permissions-reference#global-administrator) can delete any trial container type. diff --git a/docs/embedded/getting-started/microsoft-365-archive-support-for-containers.md b/docs/embedded/getting-started/microsoft-365-archive-support-for-containers.md deleted file mode 100644 index 88bf99a0a7..0000000000 --- a/docs/embedded/getting-started/microsoft-365-archive-support-for-containers.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Microsoft 365 Archive support for SharePoint Embedded containers -description: This article provides an overview of Microsoft 365 Archive support for archival of SharePoint Embedded containers. -ms.date: 03/20/2026 -ms.localizationpriority: high ---- - -# Microsoft 365 Archive for SharePoint Embedded Containers (Preview) - -Microsoft 365 Archive provides a cost-effective storage option for inactive or aging content stored in SharePoint Embedded containers. - -Your organization and consuming tenants might need to retain data for extended periods to meet legal, compliance, or regulatory requirements. You might prefer to store the data in SharePoint to simplify searchability, security, compliance, and data lifecycle management. - -Microsoft 365 Archive enables you to retain inactive SharePoint Embedded container data by moving it to a cold storage tier (archive) within SharePoint. Archived data continues to benefit from the same Microsoft 365 security, compliance, and search standards, while significantly reducing storage costs. - -Once a container is archived, it becomes inaccessible. To access it again, the container must be reactivated. Reactivation is instantaneous if performed within the first seven days after archival. If reactivated after seven days, the process can take up to 24 hours to complete. - -Archival and reactivation actions are supported for users with the Owner or Principal Owner roles on the container. Global Administrators and SharePoint Embedded Administrators can perform these actions on all containers. In addition, the application must have write permission on the container. - -Microsoft 365 Archive is available for SharePoint sites. For more information, see: [Microsoft 365 Archive Overview](/microsoft-365/archive/archive-overview) - -## SharePoint Embedded container archival guide - -- Developer tenant guide: [Support archival of containers](../development/support-archival-of-containers.md) -- Consuming tenant guide: [Manage Archival of containers using SharePoint Admin Center](../administration/consuming-tenant-admin/ctaUX.md) diff --git a/docs/embedded/getting-started/register-api-documentation.md b/docs/embedded/getting-started/register-api-documentation.md deleted file mode 100644 index 1888e20789..0000000000 --- a/docs/embedded/getting-started/register-api-documentation.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: Register file storage container type application permissions -description: Register the container type. -ms.date: 08/11/2025 -ms.localizationpriority: high ---- - -# Register file storage container type application permissions - -In order for a SharePoint Embedded application to interact with containers in a consuming tenant, the container type must first be registered in the consuming tenant. Container type registration happens when the owning application invokes the registration API to specify how applications can access its container type. The registration API also grants access to other Guest Apps to interact with the owning application's containers. For example, a SharePoint Embedded application can grant permissions to another application--a Guest App so that the Guest App can perform backup operations against its containers. - -Since the [container type registration API](/graph/api/filestorage-post-containertyperegistrations) controls the access to a container type in the consuming tenant, it's the first endpoint invoked by a SharePoint Embedded application on a consuming tenant. Failure to do so results in access denied errors when invoking other APIs against containers and/or content in the containers. - -There are no restrictions on how many times the registration API can be invoked. How often the registration API is invoked and when it's invoked is dependent on the SharePoint Embedded application. However, the last successful call to the registration API determines the settings used in the consuming tenant. - -## Authentication and authorization requirements - -For the container type's owning application to act on a consuming tenant, some prerequisites must be completed: - -- the owning app must have a [service principal](/entra/identity-platform/app-objects-and-service-principals) installed on the consuming tenant -- the owning app must be granted admin consent to perform container type registration in the consuming tenant. - -You can satisfy these requirements by having the consuming tenant's Global Administrator [grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal) to the container type's owning application. - -The [container type registration API](/graph/api/filestorage-post-containertyperegistrations) requires the `FileStorageContainerTypeReg.Selected` user-delegated or app-only permission. When the owning application calls the container type registration API on behalf of a user, the user must be assigned the [SharePoint Embedded Administrator](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) or the [Global Administrator](/entra/identity/role-based-access-control/permissions-reference#global-administrator) roles. When the owning application calls the container type registration API without a user context, it needs to request a token using the [client credentials grant flow](/entra/identity-platform/v2-oauth2-client-creds-grant-flow). - -> [!NOTE] -> The container type registration API is currently in preview and subject to change. - -To request admin consent from a tenant administrator in the consuming tenant, you may direct them to the [admin consent endpoint](/entra/identity-platform/v2-admin-consent). For the right endpoints on national clouds, see [Microsoft identity platform endpoints on national clouds](/entra/identity-platform/authentication-national-cloud#microsoft-entra-authentication-endpoints): - -```http -https://login.microsoftonline.com/{ConsumingTenantId}/v2.0/adminconsent?client_id={OwningAppId}&scope=https://graph.microsoft.com/.default -``` - -You may configure the admin consent endpoint to fit your needs, including handling errors and successful grants. For more information, see [Admin consent URI](/entra/identity-platform/v2-admin-consent). - -## Container type Permissions - -The registration API determines what permissions a SharePoint Embedded application can perform against containers and content in containers for the specified container type. - -| Permission | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------ | -| None | Has no permissions to any containers or content of this container type. | -| ReadContent | Can read the content of containers of this container type. | -| WriteContent | Can write content to containers for this container type. This can't be granted without the ReadContent permission. | -| Create | Can create containers of this container type. | -| Delete | Can delete containers of this container type. | -| Read | Can read the metadata of containers of this container type. | -| Write | Can update the metadata of containers of this container type. | -| EnumeratePermissions | Can enumerate the members of a container and their roles for containers of this container type. | -| AddPermissions | Can add members to the container for containers of this container type. | -| UpdatePermissions | Can update (change roles of) existing memberships in the container for containers of this container type. | -| DeletePermissions | Can delete other members (but not self) from the container for containers of this container type. | -| DeleteOwnPermissions | Can remove own membership from the container for containers of this container type. | -| ManagePermissions | Can add, remove (including self), or update members in the container roles for containers of this container type. | -| ManageContent | Can manage the content of the container | -| Full | Has all permissions for containers of this container type. | - -## Examples - -### Register the container type in a consuming tenant with permissions only for the Owning App - -Register the container type `de988700-d700-020e-0a00-0831f3042f00` in the consuming tenant and grant `full` permissions to the owning application `71392b2f-1765-406e-86af-5907d9bdb2ab` for delegated and app-only calls. - -#### Request - -```http -PUT https://graph.microsoft.com/beta/storage/fileStorage/containerTypeRegistrations/de988700-d700-020e-0a00-0831f3042f00 -Content-Type: application/json - -{ - "applicationPermissionGrants": [ - { - "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "delegatedPermissions": ["full"], - "applicationPermissions": ["full"] - } - ] -} -``` - -#### Response - -```json -HTTP/1.1 201 Created -Content-Type: application/json - -{ - "@odata.type": "#microsoft.graph.fileStorageContainerTypeRegistration", - "id": "de988700-d700-020e-0a00-0831f3042f00", - "name": "Test Container Type", - "owningAppId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "billingClassification": "trial", - "billingStatus": "valid", - "registeredDateTime": "08/11/2025", - "expirationDateTime": "08/11/2025", - "etag": "RVRhZw==", - "settings": { - "@odata.type": "microsoft.graph.fileStorageContainerTypeRegistrationSettings", - "sharingCapability": "disabled", - "urlTemplate": "https://app.contoso.com/redirect?tenant={tenant-id}&drive={drive-id}&folder={folder-id}&item={item-id}", - "isDiscoverabilityEnabled": true, - "isSearchEnabled": true, - "isItemVersioningEnabled": true, - "itemMajorVersionLimit": 50, - "maxStoragePerContainerInBytes": 104857600, - "isSharingRestricted": false - }, - "applicationPermissionGrants": [ - { - "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "delegatedPermissions": ["full"], - "applicationPermissions": ["full"] - } - ] -} -``` - -### Register the container type in a consuming tenant with permissions for a Guest App - -Register the container type `de988700-d700-020e-0a00-0831f3042f00` in the consuming tenant and grant full permissions to the owning application `71392b2f-1765-406e-86af-5907d9bdb2ab` for delegated and app-only calls. In addition, grant a guest app `89ea5c94-7736-4e25-95ad-3fa95f62b6` both `read` and `write` permissions only for delegated calls. - -#### Request - -```http -PUT https://graph.microsoft.com/beta/storage/fileStorage/containerTypeRegistrations/de988700-d700-020e-0a00-0831f3042f00 -Content-Type: application/json - -{ - "applicationPermissionGrants": [ - { - "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "delegatedPermissions": ["full"], - "applicationPermissions": ["full"] - }, - { - "appId": "89ea5c94-7736-4e25-95ad-3fa95f62b6", - "delegated": ["read", "write"], - "appOnly": ["none"] - } - ] -} -``` - -#### Response - -```json -HTTP/1.1 201 Created -Content-Type: application/json - -{ - "@odata.type": "#microsoft.graph.fileStorageContainerTypeRegistration", - "id": "de988700-d700-020e-0a00-0831f3042f00", - "name": "Test Container Type", - "owningAppId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "billingClassification": "trial", - "billingStatus": "valid", - "registeredDateTime": "08/11/2025", - "expirationDateTime": "08/11/2025", - "etag": "RVRhZw==", - "settings": { - "@odata.type": "microsoft.graph.fileStorageContainerTypeRegistrationSettings", - "sharingCapability": "disabled", - "urlTemplate": "https://app.contoso.com/redirect?tenant={tenant-id}&drive={drive-id}&folder={folder-id}&item={item-id}", - "isDiscoverabilityEnabled": true, - "isSearchEnabled": true, - "isItemVersioningEnabled": true, - "itemMajorVersionLimit": 50, - "maxStoragePerContainerInBytes": 104857600, - "isSharingRestricted": false - }, - "applicationPermissionGrants": [ - { - "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "delegatedPermissions": ["full"], - "applicationPermissions": ["full"] - }, - { - "appId": "89ea5c94-7736-4e25-95ad-3fa95f62b6", - "delegated": ["read", "write"], - "appOnly": ["none"] - } - ] -} -``` diff --git a/docs/embedded/getting-started/spembedded-for-vscode.md b/docs/embedded/getting-started/spembedded-for-vscode.md deleted file mode 100644 index 2452191c5c..0000000000 --- a/docs/embedded/getting-started/spembedded-for-vscode.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: SharePoint Embedded for Visual Studio Code -description: Installation and getting started with SharePoint Embedded for Visual Studio Code -ms.date: 01/30/2024 -ms.localizationpriority: high ---- - -# SharePoint Embedded for Visual Studio Code - -The SharePoint Embedded Visual Studio Code extension helps developers get started for free with SharePoint Embedded application development. - -> [!IMPORTANT] -> To start building with SharePoint Embedded, you'll need administrative access to a Microsoft 365 tenant. -> If you don't already have a tenant, you can get your own tenant with the [Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program), [Microsoft Customer Digital Experience](https://cdx.transform.microsoft.com/), or create a free trial of a [Microsoft 365 E3 license](https://www.microsoft.com/microsoft-365/enterprise/microsoft365-plans-and-pricing). - -## Install SharePoint Embedded for Visual Studio Code - -1. Open a new window in [Visual Studio Code](https://code.visualstudio.com/) and navigate to "**Extensions**" on the activity bar. -1. Search "SharePoint Embedded" in the Extensions view. You can also view the extension in [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=SharepointEmbedded.ms-sharepoint-embedded-vscode-extension). -1. Select **"Install"** and the SharePoint Embedded icon will appear on the activity bar. -1. If already installed, update to the latest version if one is available. -1. Select the icon to open the SharePoint Embedded view and create a container type with trial configuration. - -![SharePoint Embedded VS Extensions](../images/vsx-images/n1downloadvsx.png) - -### Sign in with admin credentials - -To use the extension, you must sign in to a Microsoft 365 tenant with an administrator account. - -![Install](../images/vsx-images/n2vsx-signin.png) - -- Authentication opens a new tab in an external browser to grant permissions - - ![authorize and authenticate the extension to your M365 Entra tenant](../images/vsx-images/auth-allow-extension-uri.png) - -- Review the requested permissions carefully, then select **Accept** on the pop-up window prompting admin consent - - ![review before consenting to the permissions the extension is asking for](../images/vsx-images/n3vsx-grant-admin-consent.png) - -After successful authorization, select open on the dialog to be redirected to VS Code: - -![authorization completed in browser now redirecting to visual studio code](../images/vsx-images/auth-redirect.png) - -## Create a container type with a trial configuration - -Once signed in, you're prompted to create a [container type with trial configuration](./containertypes.md#trial-container-type). A container type lets you get started calling SharePoint Embedded APIs and building a proof-of-concept application using SharePoint Embedded. Learn more about [container types](containertypes.md). - -![home screen](../images/vsx-images/n4vsx-home-screen.png) - -- Select **Create Trial Container Type** -- Follow the prompts to name your container type. You can change your container type name later on. - -![create container type](../images/vsx-images/n5a-name-ct.png) - -> [!NOTE] -> SharePoint Embedded for Visual Studio Code only supports container types with trial configuration at this time. Other container types with standard or passthrough billing configurations must be created using the SharePoint Online PowerShell Module. - -## Create a Microsoft Entra ID App - -Every container type is owned by a Microsoft Entra ID application. The first step when creating a free trial container type is to create a new or select an existing Microsoft Entra ID application as the owning application. You can either specify the name of your new application or pick one of your existing applications. Learn more about SharePoint Embedded [app architecture](../development/app-architecture.md) - -- Follow the prompts to name your new Entra application or select an existing application ID: - - ![Create App](../images/vsx-images/n6aname-app.png) - -> [!NOTE] -> If you choose an existing application, the extension will update that app's configuration settings for it to work with both SharePoint Embedded and this extension. Doing this is NOT recommended on production applications. - -After your container type is created and your application is configured, you'll be able to view your local tenant registration as a tree in the left nav-bar. - -## Register your container type - -After creating your container type, you'll need to register that container type on your local tenant. Learn more about container type [registration](./register-api-documentation.md). - -- Follow the prompts and select **Register on local tenant** on the lower right corner of the VS Code window - - ![local tenant registration popup](../images/vsx-images/local-tenant-registration-popup.png) - -- If you don't see the prompt, you can right-click on your `` and select **Register** from the menu - - ![register](../images/vsx-images/n7aregister-ct.png) - -### Grant permissions - -Review permissions and follow the prompt to grant admin consent - -![grant admin consent popup](../images/vsx-images/auth-grant-admin-consent-popup.png) - -An external browser window will pop open for you to sign-in and grant admin consent - -![login permissions](../images/vsx-images/n9alogin-grant-permissions.png) - -## Create your first container - -With your container type registered, you can now create your first container. Only five containers of container type can be created to upload and manage content. - -- Right-click on the **Containers** drop-down from the tree in the left nav-bar and select **Create container** -- Enter a name for the container you would like to create - -![create container](../images/vsx-images/n10acreate-container.png) -![name container](../images/vsx-images/n11aname-first-cont.png) - -## Recycling Containers - -You can also recycle and recover containers within the extension. - -![recycle containers](../images/vsx-images/n12arecycle-cont.png) - -![final home page](../images/vsx-images/n13a-final-home-page.png) - -## Load Sample App - -With your free trial container type created, you can use the extension to load one of the SharePoint Embedded sample apps and automatically populate the runtime configuration file with the details of your Microsoft Entra ID app and container type. - -![Load Sample App](../images/vsx-images/n15vsxsa-c.png) - -When loading the sample application, you'll be notified that it will create plain text secrets to authenticate on your local machine. - -![sample app plain text secrets notice](../images/vsx-images/sample-app-app-secrets-notice.png) - -If no client secret is found on your application, it will ask if you would like to create one. Press OK to proceed. - -![sample app creating client secret](../images/vsx-images/sample-app-create-client-secret.png) - -> [!IMPORTANT] -> This isn't intended for production environments. [Find out more on how to setup Application Registration for production environments here.](/entra/identity-platform/quickstart-register-app) - -## Using Sample App - -In your terminal, run the following command, this will start the sample application, which consists of two parts: - -1. **React Client Application** - The frontend user interface running on port 8080 -1. **Azure Function Application Server** - The backend API server that handles SharePoint Embedded operations - -```console -# Navigate to your sample application directory -cd [your-path]\SharePoint-Embedded-Samples\Custom Apps\boilerplate-typescript-react - -# Install dependencies and start the application -npm run start -``` - -> [!NOTE] -> The initial startup may take a few minutes as dependencies are installed and both applications are built. Wait for both console outputs to appear before navigating to the application. - -This will install the dependencies and run the server and client application, once running, you'll see the following in the terminal, after which you can navigate to `http://localhost:8080` to access the application. - -![function api console logs](../images/vsx-images/fn-api-logs.png) - -![client app console logs](../images/vsx-images/client-app-logs.png) - -Once both applications are running successfully: - -1. Open your web browser and navigate to `http://localhost:8080` -1. Sign in using your Microsoft 365 administrator account (the same account used in the VS Code extension) -1. On the home page, select **Containers** to begin creating containers and uploading files -1. Follow the on-screen prompts to interact with your SharePoint Embedded containers - -![home-page-for-spe-sample-app](../images/vsx-images/spe-sample-app-home.png) - -> [!IMPORTANT] -> This sample application stores authentication secrets in plain text for development purposes only. Never use this configuration in a production environment. - -### Troubleshooting - -If you encounter issues: - -- **Port already in use**: If port 8080 is already in use, the application will automatically try the next available port -- **Dependencies not installing**: Try running `npm install` manually before `npm run start` -- **Authentication errors**: Ensure your Microsoft Entra ID app is properly configured with the correct redirect URIs - -## Export Postman Environment - -The [SharePoint Embedded Postman Collection](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/main/Tools/api-clients) allows you to explore and call the SharePoint Embedded APIs. The Collection requires an environment file with variables used for authentication and various identifiers. This extension automates the generation of this populated environment file so you can import it into Postman and immediately call the SharePoint Embedded APIs. - -![Export Postman Environment](../images/vsx-images/n14postman-c.png) diff --git a/docs/embedded/images/create-app-panel-1.png b/docs/embedded/images/create-app-panel-1.png new file mode 100644 index 0000000000..835a8279da Binary files /dev/null and b/docs/embedded/images/create-app-panel-1.png differ diff --git a/docs/embedded/images/create-app-panel-2.png b/docs/embedded/images/create-app-panel-2.png new file mode 100644 index 0000000000..a851389d87 Binary files /dev/null and b/docs/embedded/images/create-app-panel-2.png differ diff --git a/docs/embedded/images/installed-app-details-panel.png b/docs/embedded/images/installed-app-details-panel.png new file mode 100644 index 0000000000..337d393516 Binary files /dev/null and b/docs/embedded/images/installed-app-details-panel.png differ diff --git a/docs/embedded/images/installed-apps-page.png b/docs/embedded/images/installed-apps-page.png new file mode 100644 index 0000000000..1e1225009c Binary files /dev/null and b/docs/embedded/images/installed-apps-page.png differ diff --git a/docs/embedded/images/owned-apps-page.png b/docs/embedded/images/owned-apps-page.png new file mode 100644 index 0000000000..fa6523219c Binary files /dev/null and b/docs/embedded/images/owned-apps-page.png differ diff --git a/docs/embedded/llms.txt b/docs/embedded/llms.txt new file mode 100644 index 0000000000..4040d0fad5 --- /dev/null +++ b/docs/embedded/llms.txt @@ -0,0 +1,68 @@ +# SharePoint Embedded + +> SharePoint Embedded (SPE) is a cloud-based, API-only file and document management platform built on Microsoft 365. Developers embed Office collaboration, Microsoft Purview compliance, and Copilot capabilities into their own apps while content stays inside each customer's Microsoft 365 tenant. This index is organized by task. Each link points to the single best page for that task. + +## Overview +- [What is SharePoint Embedded?](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/overview): Definition, key concepts (tenant partition, containers), and routing to the right task area. +- [Scenarios and use cases](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/scenarios-and-use-cases): When to use SPE; enterprise and ISV examples. +- [What's new](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/whats-new): Recent releases, preview features, and breaking changes. + +## Plan a solution (architect, IT decision maker) +- [Understand app and tenant architecture](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/app-tenant-architecture): Developer vs consuming tenant, app ownership, container types, where files live. +- [Choose an app model: single-tenant or multitenant](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/choose-app-model): Enterprise LOB vs ISV; who owns, installs, and pays. +- [Understand container types and containers](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/container-types-and-containers): The container type/container model and ownership. +- [Choose a billing model](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/choose-billing-model): Standard vs pass-through (consuming-tenant) billing. +- [Plan authentication and permissions](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/authentication-permissions): Permission models, admin consent, app-only vs delegated. +- [Plan security, compliance, and governance](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/security-compliance-governance): Purview, DLP, retention, sensitivity labels, conditional access. +- [Understand limits and calling patterns](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/limits-calling-patterns): Service limits, throttling, batching, retry guidance. + +## Build an app (developer) +- [Quickstart: Build your first app with VS Code](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/quickstart-vscode): Install the extension, create a trial container type, run the sample app. +- [Create and configure a container type](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/create-container-type): Create trial/production container types and the owning Entra app. +- [Register application permissions](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/register-application-permissions): Register container type permissions and grant consent. +- [Configure authentication and authorization](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/configure-authentication-authorization): Entra app, tokens, app-only and delegated flows. +- [Create and manage containers](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/create-manage-containers): Create, list, update, delete, recycle, and restore containers. +- [Upload, download, and manage files](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/manage-files): File and folder operations via Microsoft Graph. +- [Open Office files from your app](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/open-office-files): Office web/desktop experiences and launch behavior. +- [Preview files in your app](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/preview-files): File preview UX and preview links. +- [Search containers and files](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/search-containers-files): Query content with security trimming and paging. +- [Store and query container metadata](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/container-metadata): Define, set, and filter custom metadata. +- [Share files and manage permissions](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/share-files-manage-permissions): Grant/revoke access and permission inheritance. +- [Respond to file and container changes with webhooks](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/respond-to-changes-webhooks): Subscribe to and process change notifications. +- [Archive and restore containers](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/archive-restore-containers): Container archival lifecycle and cost. +- [Add real-time collaboration with Fluid Framework](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/fluid-framework): Live collaborative experiences over SharePoint Embedded. +- [Add Microsoft 365 Copilot and agent experiences](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/agent-experiences): Agent patterns and knowledge source overview. +- [Set up SharePoint Embedded as a Foundry knowledge source](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/sharepoint-embedded-knowledge-source): Configure Microsoft Foundry Agent Service to retrieve SharePoint Embedded content. +- [Migrate from Azure Blob Storage](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/migrate-azure-blob-storage): Move blobs into containers with metadata. + +## Publish and onboard customers (ISV, developer) +- [Prepare your app for customer installation](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/publish/prepare-customer-installation): Package and configure a multitenant app for customers. +- [Choose a billing model for your app](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/publish/choose-app-billing-model): Billing choice and its effect on onboarding. +- [Guide customers through tenant setup](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/publish/customer-tenant-setup-guide): Customer prerequisites, consent, and billing setup. +- [Validate customer app installation](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/publish/validate-customer-installation): Confirm registration, permissions, and billing. + +## Install and manage apps (administrator) +- [Admin overview](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/admin-overview): Admin roles and where to manage SharePoint Embedded. +- [Create apps in SharePoint admin center](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/create-apps-sharepoint-admin-center): Create SharePoint Embedded apps from the admin center. +- [Create apps with PowerShell](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/create-apps-powershell): Create SharePoint Embedded apps with SharePoint PowerShell. +- [Install a SharePoint Embedded app](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/install-sharepoint-embedded-app): Register/install an app in your tenant. +- [Grant admin consent and permissions](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/grant-admin-consent-permissions): Review and grant requested permissions. +- [Set up billing in Microsoft 365 admin center](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/setup-billing-m365-admin-center): Configure billing for a consuming tenant. +- [Manage containers in SharePoint admin center](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/manage-containers-sharepoint-admin-center): View and manage containers in the UI. +- [Manage containers with PowerShell](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/manage-containers-powershell): Script container management. +- [Monitor usage, billing, and cost](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/monitor-usage-billing-cost): Track usage and cost drivers. +- [Review audit events](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/review-audit-events): Find and interpret SharePoint Embedded audit events. +- [Apply security and compliance controls](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/apply-security-compliance-controls): Apply Purview retention, DLP, labels, and eDiscovery. + +## Reference +- [Billing meters](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/billing-meters): Storage, transaction, egress, and agent meters. +- [Audit events](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/audit-events): SharePoint Embedded audit event names and properties. +- [PowerShell reference](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/powershell): SharePoint Embedded admin cmdlets. +- [Microsoft Graph API reference links](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/graph-api-links): Graph fileStorageContainer and related APIs. +- [Troubleshooting](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/troubleshooting): Common setup, auth, billing, and runtime issues. +- [Glossary](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/glossary): SPE terms and definitions. + +## Optional +- [Microsoft Graph file storage container API](https://learn.microsoft.com/en-us/graph/api/resources/filestoragecontainer): Underlying Graph API surface for SharePoint Embedded. +- [Learning module: SharePoint Embedded overview and configuration](https://learn.microsoft.com/en-us/training/modules/sharepoint-embedded-setup): Guided training. +- [Learning module: Build SharePoint Embedded applications](https://learn.microsoft.com/en-us/training/modules/sharepoint-embedded-create-app): Guided training. diff --git a/docs/embedded/overview.md b/docs/embedded/overview.md index 9a4741024e..defb1b4a9e 100644 --- a/docs/embedded/overview.md +++ b/docs/embedded/overview.md @@ -1,72 +1,84 @@ --- title: SharePoint Embedded Overview -description: Microsoft SharePoint Embedded is a cloud-based file and document management system suitable for use in any application. SharePoint Embedded is a new API-only solution that enables app developers to harness the power of the Microsoft 365 file and document storage platform for any app, and is suitable for enterprises building line-of-business applications and ISVs building multitenant applications. -ms.date: 08/17/2024 +description: Microsoft SharePoint Embedded is an API-only file and document management platform built on Microsoft 365. Start here and route to the right task. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan ms.localizationpriority: high +ai-usage: ai-assisted --- -# Overview of SharePoint Embedded +# What is SharePoint Embedded? -Microsoft SharePoint Embedded is a cloud-based file and document management system suitable for use in any application. SharePoint Embedded is a new API-only solution that enables app developers to harness the power of the Microsoft 365 file and document storage platform for any app, and is suitable for enterprises building line-of-business applications and ISVs building multitenant applications. +**Applies to:** All -SharePoint Embedded allows you to integrate advanced Microsoft 365 features into your apps including full-featured collaborative functions from Office, Purview's security and compliance tools, and Copilot capabilities. +Microsoft SharePoint Embedded is a cloud-based, API-only file and document management system you can use in any application. It lets app developers harness the Microsoft 365 file and document storage platform, and is suitable for enterprises building line-of-business applications and ISVs building multitenant applications. -> [!IMPORTANT] -> Help us shape the future of SharePoint Embedded! -> Take our [quick survey](https://forms.microsoft.com/r/1YpGd2pAUS) and share your experience! - -## App documents stay in their Microsoft 365 tenant +SharePoint Embedded has no standalone end-user UI and no no-code option. You access it programmatically through Microsoft Graph, so using SharePoint Embedded always involves building or deploying an application. -When a consumer uses a SharePoint Embedded application in their Microsoft 365 tenant, SharePoint Embedded creates another partition within their tenant. This storage partition doesn't have a user experience and the documents in the partition are only accessible via APIs. This means that all documents will be accessible to the developer’s application, but the documents will only reside in the consumer’s Microsoft 365 tenant. Within this new storage partition inside of a Microsoft 365 tenant, a SharePoint Embedded application can create many "File Storage Containers" for storing content. +SharePoint Embedded brings advanced Microsoft 365 capabilities into your app, including Office collaboration, Microsoft Purview security and compliance, and Copilot. -## Introducing File Storage Containers +> [!IMPORTANT] +> Help us shape the future of SharePoint Embedded! Take our [quick survey](https://forms.microsoft.com/r/1YpGd2pAUS) and share your thoughts. -SharePoint Embedded applications use Microsoft Graph APIs to store files and documents in a new entity called a "File Storage Container” or Container for short.  If you’re an ISV, your app will create these containers in your customer’s Microsoft 365 tenant, and if you’re an enterprise, your app will create these containers in your own tenant. Each container provides a place to store files - you can think of them as similar to an API-only Document Library in SharePoint, but with some slight differences. Your app can create many of these containers inside each tenant that uses your app, and each container can be granted permissions separately storing many files with multiple terabytes of content. + -SharePoint Embedded containers are dedicated to and accessible by just your app, so the files and documents your app depends on are isolated and secure within that tenant boundary. +## Choose your path -## App-managed content experiences +This page is a router. Pick the row that matches what you're trying to do. -By default, the content stored within a Microsoft 365 tenant by a SharePoint Embedded application is only accessible through that owning application. Applications using SharePoint Embedded also provide the user experience layer for accessing and managing content, using some of the rich content capabilities that Microsoft 365 offers such as: +> [!TIP] +> **Not sure which path?** Ask one question: *do you write code, or manage a tenant?* +> **Developers** write and deploy applications that call SharePoint Embedded APIs — start with **Build an app**. +> **Administrators** install, consent to, and manage SharePoint Embedded apps inside a Microsoft 365 tenant — start with **Install or manage apps**. -- Core content management features like support for any file type and folder structure, searching, sharing, automatic versioning, recycle-bin, and more -- Collaboration features like view, edit, and co-authoring Office Word, Excel, and PowerPoint documents in Office Web and Desktop +| I want to… | Start here | +|---|---| +| **Understand SharePoint Embedded and decide if it fits** | [Scenarios and use cases](scenarios-and-use-cases.md) · keep reading below | +| **Plan a solution** (architect, IT decision maker) | [Plan a SharePoint Embedded solution](plan/app-tenant-architecture.md) | +| **Build an app** (developer) | [Quickstart: build your first app with VS Code](build/quickstart-vscode.md) | +| **Ship my app to customers** (ISV / developer) | [Publish and onboard customers](publish/prepare-customer-installation.md) | +| **Install or manage apps in my tenant** (admin) | [Install and manage apps](admin/admin-overview.md) | +| **Govern and secure content** (compliance admin) | [Apply security and compliance controls](admin/apply-security-compliance-controls.md) | +| **Look something up** | [Reference](reference/glossary.md) · [Graph API](/graph/api/resources/filestoragecontainer) | -SharePoint Embedded is used by several types of applications: +## Key concepts in 60 seconds -- Certain Microsoft products use SharePoint Embedded to manage customer content, such as Loop and Designer. -- ISVs can use SharePoint Embedded in their apps to manage content within their customer’s Microsoft 365 tenant -- Enterprises can use SharePoint Embedded to manage and store content within their own Microsoft 365 tenant, but outside of regular Microsoft 365 entitlements +### App documents stay in the customer's Microsoft 365 tenant -## Consumer Microsoft 365 settings apply to app documents +When a customer uses a SharePoint Embedded application, SharePoint Embedded creates a dedicated storage partition inside that customer's Microsoft 365 tenant. The partition has no user experience of its own — its documents are reachable only through Microsoft Graph APIs. Content is accessible to the developer's application, but it physically resides in the customer's tenant. -All documents stored in the SharePoint partition created by the SharePoint Embedded app are in the consumer’s Microsoft 365 tenant and therefore are subject to the consumer’s Microsoft 365 tenant settings. +### File Storage Containers -This includes settings from Microsoft Purview compliance, risk, and security settings, documents can be opened from Office clients, and customers can use the Office web clients to view and collaborate on the documents. Choosing applications that are built on SharePoint Embedded provides the app consumer Microsoft Purview security and compliance capabilities on that app content, such as: +SharePoint Embedded apps store files in an entity called a **File Storage Container** (or *container*). Think of a container as an API-only document library. Your app can create many containers in each tenant that uses it, and each container can be permissioned separately and hold terabytes of content. Containers are dedicated to — and accessible only by — your app, keeping your data isolated within the tenant boundary. -- eDiscovery -- Auditing -- Data loss prevention (DLP) -- Retention policies, sensitivity labels, conditional access +To learn how containers and container types relate, see [Understand container types and containers](plan/container-types-containers.md). -## Understanding the costs and billing for SharePoint Embedded content +### App-managed content experiences -Microsoft 365 customers have different entitlements related to storage, usage, and features depending on the licenses the customer has purchased. +By default, content stored by a SharePoint Embedded app is accessible only through that owning app, which also provides the user experience for it. You can light up rich Microsoft 365 capabilities, including: -The partition created in the consumer’s Microsoft 365 tenant by a SharePoint Embedded app doesn’t count towards other Microsoft 365 entitlements including the total amount of Microsoft SharePoint storage that can be used by your organization. Instead, the partition in the consumer’s Microsoft 365 tenant by the SharePoint Embedded app are billed separately through an Azure subscription on a pay-as-you-go metered consumption model that’s based on total storage in active and archived state and the number of API calls. +- Core content management — any file type, folders, search, sharing, versioning, recycle bin. +- Office collaboration — view, edit, and co-author Word, Excel, and PowerPoint on the web and desktop. +- Low-code integration — the [SharePoint Embedded connector](/connectors/sharepointembedded/) for [Power Platform](/power-platform/) (generally available February 2026). -> [!NOTE] -> Learn more about billing for SharePoint Embedded, see [Billing Meters](./administration/billing/meters.md). +SharePoint Embedded is used by Microsoft products (such as Loop and Designer), by ISVs embedding content management in their apps, and by enterprises storing content outside their regular Microsoft 365 entitlements. -## Get Started with SharePoint Embedded +### Compliance and billing follow the tenant -[Review the prerequisites](./administration/billing/billing.md) +Because content lives in the customer's Microsoft 365 tenant, it's subject to that tenant's settings — including Microsoft Purview compliance (eDiscovery, auditing, DLP, retention, sensitivity labels, conditional access). The SharePoint Embedded partition doesn't count against Microsoft 365 storage entitlements; it's billed separately through an Azure subscription on a pay-as-you-go, metered model based on storage and API usage. See [Choose a billing model](plan/choose-billing-model.md) and [Billing meters](reference/billing-meters.md). -Create a "File Storage Container" in 15 minutes or less: +### Availability -- [Free trial: SharePoint Embedded for Visual Studio Code](./getting-started/spembedded-for-vscode.md) +SharePoint Embedded is available in the Microsoft 365 commercial cloud, in [Microsoft 365 GCC](/office365/servicedescriptions/office-365-platform-service-description/office-365-us-government/gcc) (November 2025, not yet GCC High or DoD), and in [Microsoft 365 operated by 21Vianet](/office365/servicedescriptions/office-365-platform-service-description/microsoft-365-operated-by-21vianet) for customers in China (February 2026). See [Microsoft Graph national cloud deployments](/graph/deployments). -Follow manual set-up on SharePoint Embedded from the following Microsoft Learning modules: +## Next steps -- [Microsoft Learning: SharePoint Embedded - overview & configuration](/training/modules/sharepoint-embedded-setup) -- [Microsoft Learning: SharePoint Embedded - building applications](/training/modules/sharepoint-embedded-create-app) +- New to SharePoint Embedded? Read [Scenarios and use cases](scenarios-and-use-cases.md), then [Plan a solution](plan/app-tenant-architecture.md). +- Ready to build? Jump to the [VS Code quickstart](build/quickstart-vscode.md). +- Administering a tenant? Start at the [Admin overview](admin/admin-overview.md). +- See [What's new](whats-new.md) for the latest releases. diff --git a/docs/embedded/plan/app-tenant-architecture.md b/docs/embedded/plan/app-tenant-architecture.md new file mode 100644 index 0000000000..79857149b5 --- /dev/null +++ b/docs/embedded/plan/app-tenant-architecture.md @@ -0,0 +1,224 @@ +--- +title: Understand App and Tenant Architecture +description: Plan how SharePoint Embedded apps, tenants, container types, and containers relate across owning and consuming tenants. +ms.date: 07/13/2026 +ms.reviewer: dilucesr +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Understand app and tenant architecture + +**Applies to:** Architect + + + +Use this article to map the core SharePoint Embedded architecture before you choose an app model or create a container type. + +SharePoint Embedded is API-only storage built on Microsoft 365. Your application provides the user experience. Files and documents are stored in containers and accessed through Microsoft Graph. + +## Architecture at a glance + +SharePoint Embedded separates three concepts: + +- The application that calls Microsoft Graph. +- The container type that defines application access, behavior, and billing accountability. +- The containers and files that live inside a Microsoft 365 tenant boundary. + +All files and documents in SharePoint Embedded are stored in containers. + +All containers and container content are created and stored within a Microsoft 365 tenant. + +Applications create, manage, and interact with containers and container content through Microsoft Graph. + +![Diagram of the SharePoint Embedded architecture. A SharePoint Embedded application calls Microsoft Graph, which connects to storage inside a Microsoft 365 tenant. Inside the tenant, a container type groups a stack of containers, and each container holds files and documents.](../images/SPEArch.png) + +*Figure 1: The application calls Microsoft Graph, and Graph reads and writes files in containers that live inside the Microsoft 365 tenant boundary.* + +## Developer tenant and consuming tenant + +SharePoint Embedded uses two tenant roles. + +| Tenant role | Meaning | Typical responsibility | +| --- | --- | --- | +| Owning tenant | The Microsoft Entra ID tenant where a container type is created. | Own the Microsoft Entra ID app registration and manage the container type. | +| Consuming tenant | The Microsoft Entra ID tenant where a container type is used. | Host containers and content for users of the application. | + +The same Microsoft Entra ID tenant can be both the owning tenant and the consuming tenant for a given container type. + +For example, an enterprise line-of-business (LOB) app can be owned by the enterprise tenant and used in that same tenant. + +An independent software vendor (ISV) app can be owned by the ISV tenant and used in many different customer tenants. + +> [!IMPORTANT] +> Containers and content are stored in the consuming tenant. They don't move into the developer or ISV tenant just because the app is owned there. + +## App ownership + +A SharePoint Embedded application is a Microsoft Entra ID application registration. + +As an owning or guest application to a container type, the app has access to containers of that container type. + +SharePoint Embedded requires a 1:1 relationship between an owning application and a container type. + +This means: + +- One owning app owns only one container type. +- A container type is owned by exactly one app. +- The owning app developer is responsible for creating and managing that container type. +- The owning app defines the access controls for guest apps to containers of that type. + +> [!NOTE] +> Other applications can be granted access to the same container type, but the container type still has only one owning application. + +## Container types + +A container type is a SharePoint Embedded resource. + +It defines the relationship, access privileges, and billing accountability between an application and a set of containers. + +It also defines selected behaviors for all containers of that type. + +The container type is represented on each container as an immutable property. + +Use a container type to answer these architecture questions: + +- Which app owns this family of containers? +- Which tenant is accountable for billing? +- Which behavior settings apply to all containers of this type? + +For more detail, see [Understand container types and containers](../plan/container-types-containers.md). + +## Container type registration resource + +A container type registration is also a SharePoint Embedded resource. + +It represents the installation of a container type in a specific consuming tenant. It also defines selected behaviors for all containers of that type in that specific consuming tenant. + +Use a container type registration to answer these architecture questions: + +- Which apps can access containers of this type in a consuming tenant? +- Which tenant can create containers of this type? +- Which behavior settings apply to all containers of this type in a consuming tenant? + +For more detail, see [Understand container types and containers](../plan/container-types-containers.md). + +## Containers + +A container is the basic storage unit in SharePoint Embedded. + +A container also defines a security and compliance boundary. + +Applications can create many containers for a container type inside each consuming tenant. + +Each container provides a place to store files. You can think of it as similar to an API-only document library in SharePoint Online, with differences specific to SharePoint Embedded. + +Containers can store many files and multiple terabytes of content, subject to SharePoint Embedded limits. + +For current limits, see [Understand limits and calling patterns](../plan/limits-calling-patterns.md). + +## Where files live + +When a consuming tenant uses a SharePoint Embedded app, SharePoint Embedded creates a storage partition in that Microsoft 365 tenant. + +The partition doesn't have a SharePoint Online user experience. + +Documents in the partition are accessible through APIs and through app-provided content experiences. + +Files remain inside the consumer's Microsoft 365 tenant boundary. + +The consuming tenant's Microsoft 365 settings apply to app documents, including supported Microsoft Purview security and compliance policies. + +For governance planning, see [Plan security, compliance, and governance](../plan/security-compliance-governance.md). + +## Container type registrations + +An owning app can't interact with containers in a consuming tenant until the container type is registered in that consuming tenant. + +Container type registration is performed by the owning application. + +The registration specifies the permissions that the owning app and guest apps have on containers of that container type in the consuming tenant. + +For full registration requirements, see [Register file storage container type application permissions](../build/register-application-permissions.md). + +## Access relationships + +An application's access to containers and content is determined by permissions configured during container type registration. + +The owning application receives permissions for its container type when the container type is created. However, it may only interact with containers of its container type after registration in a consuming tenant. + +The following diagram shows the dedicated pattern. Three applications are deployed in one tenant: two independent software vendor (ISV) apps (App 1 and App 2) and one line-of-business (LOB) app (App 3). Each app owns a separate container type and can access only the stack of containers for the container type it owns. + +![Diagram of the dedicated access pattern. Three applications (App 1, App 2, and App 3) each own a separate container type, and each app can access only its own stack of containers. No app can reach another app's containers.](../images/SPECTDedicated.png) + +*Figure 2: Dedicated access. Each application owns one container type and reaches only its own containers.* + +SharePoint Embedded also allows applications to access containers of container types they don't own when those permissions are granted in the container type registration. + +The next diagram shows the shared pattern. App 1 and App 2 both have access to the same container type, so both apps can access the same stack of containers. + +![Diagram of the shared access pattern. App 1 and App 2 both connect to a single container type and its stack of containers. App 1 owns the container type, and App 2 is granted guest access to the same container type.](../images/SPECTShared.png) + +*Figure 3: Shared access. One app owns the container type, and another app is granted access to the same containers.* + +Plan the access model with both application permissions and user container permissions. + +For full details, see [Plan authentication and permissions](../plan/authentication-permissions.md). + +## Common architecture patterns + +### Enterprise LOB app + +In an enterprise LOB app: + +- The enterprise tenant usually owns the app registration. +- The enterprise tenant creates the container type. +- The same enterprise tenant consumes the app. +- Containers and files are stored in the enterprise tenant. +- Enterprise admins manage billing, compliance, and tenant settings. + +Use this model when the app is built for internal use in one organization. + +### ISV multitenant app + +In an ISV app: + +- The ISV tenant owns the app registration. +- The ISV tenant creates the container type. +- Customer tenants consume the app. +- Containers and files are stored in each customer tenant. +- Customer tenant settings apply to that customer's content. + +Use this model when one app is used by multiple customer tenants. + +The following diagram shows a worked example. Contoso is an ISV that built a human-resources app on SharePoint Embedded and deployed it into Fabrikam, an auditing firm. Fabrikam also built its own LOB auditing app. Each app has its own container type: Contoso owns the HR app and its container type, and Fabrikam owns the auditing app and its container type. Fabrikam is the consuming tenant for both apps, so both stacks of containers are stored in Fabrikam's Microsoft 365 tenant. Fabrikam owns all the data stored in its Microsoft 365 tenant, including the HR App data. + +![Diagram of a worked ISV example. Contoso's HR application and its container type sit in the Contoso owning tenant. Both Contoso's HR app and Fabrikam's LOB auditing app operate in the Fabrikam consuming tenant, where each app's container stack is stored separately.](../images/apparchexample.png) + +*Figure 4: An ISV app (Contoso) and an LOB app (Fabrikam) each own a container type, and both store their containers in the same consuming tenant (Fabrikam).* + +For model selection, see [Choose an app model: single-tenant or multitenant](../plan/choose-app-model.md). + +## Planning checklist + +- Identify the owning tenant. +- Identify each consuming tenant. +- Confirm where the Microsoft Entra ID app registration lives. +- Confirm which app registration owns the container type. +- Decide whether other guest apps need access. +- Decide where containers are created. +- Confirm that content must remain in the consuming tenant. +- Plan container type registration for each consuming tenant. +- Plan billing for the container type. +- Plan authentication and admin consent. +- Plan security and compliance responsibilities. + +## Next steps + +Choose the app model that matches your tenant and customer relationship: [Choose an app model: single-tenant or multitenant](../plan/choose-app-model.md). diff --git a/docs/embedded/plan/authentication-permissions.md b/docs/embedded/plan/authentication-permissions.md new file mode 100644 index 0000000000..3ea81c49e0 --- /dev/null +++ b/docs/embedded/plan/authentication-permissions.md @@ -0,0 +1,230 @@ +--- +title: Plan Authentication and Permissions +description: Plan SharePoint Embedded authentication, admin consent, delegated access, app-only access, and container permissions. +ms.date: 07/13/2026 +ms.reviewer: mawin +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Plan authentication and permissions + +**Applies to:** Developer + + + +Use this article to plan authentication and authorization for a SharePoint Embedded application. + +SharePoint Embedded applications use Microsoft Graph to access containers and content. + +For the full authentication reference, see [SharePoint Embedded authentication and authorization](../build/configure-authentication-authorization.md). + +## Core principles + +SharePoint Embedded authentication and authorization follow these principles: + +- Applications interact with SharePoint Embedded through Microsoft Graph. +- Applications need container type application permissions to access containers of that container type. +- Applications can only access containers that the user is a member of when using access on behalf of a user. +- Applications can access all containers enabled by their container type application permissions when using access without a user. +- Applications should use access on behalf of users whenever possible to enhance security and accountability. + +## Prerequisites + +Plan for: + +- A Microsoft Entra ID application registration. +- A Microsoft 365 subscription in the Microsoft Entra ID tenant. +- Microsoft Graph permissions for SharePoint Embedded operations. +- Container type application permissions granted through container type registration. +- Admin consent in the consuming tenant. + +## Permission layers + +SharePoint Embedded access has multiple layers. + +| Layer | Purpose | +| --- | --- | +| Microsoft Graph permission | Allows the app to call SharePoint Embedded endpoints. | +| Container type application permission | Allows the app to access containers of a specific container type. | +| Container permission | Determines what a user can do in a specific container for delegated access. | + +> [!IMPORTANT] +> Microsoft Graph permissions alone don't grant access to containers. The application must also be granted permission to a container type. + +## Delegated access + +Delegated access means the application acts on behalf of a user. + +SharePoint Embedded operations on behalf of a user require Microsoft Graph `FileStorageContainer.Selected` delegated permission. + +This delegated permission does not require admin consent on the consuming tenant. + +The user must also have container permissions. + +The application's effective permissions are the intersection of: + +- The application permissions granted for the container type. +- The user's permissions on the container. + +Use delegated access whenever possible. + +Delegated access improves auditability because actions can be associated with the user. + +## App-only access + +App-only access means the application acts without a user. + +SharePoint Embedded operations without a user require Microsoft Graph `FileStorageContainer.Selected` application permission. + +This permission requires admin consent on the consuming tenant. + +With app-only access, the app can access all containers enabled by its container type application permissions. + +Use app-only access for background operations that can't be performed on behalf of a user. + +Apply least privilege when granting container type application permissions. + +## Admin consent + +An administrator on the consuming tenant must consent to the application's permission request. + +Admin consent is required for the application `FileStorageContainer.Selected` permission. Delegated `FileStorageContainer.Selected` does not require admin consent. + +Container type registration also requires consent for the owning application to act in the consuming tenant. + +For container type registration, see [Register file storage container type application permissions](../build/register-application-permissions.md). + +## Container type permissions (Microsoft Graph) + +Container type creation, management, and registration are now Microsoft Graph operations. Plan for these permissions: + +| Permission | Purpose | Tenant | +| --- | --- | --- | +| `FileStorageContainerType.Manage.All` | Create and manage container types on the owning tenant. | Owning only | +| `FileStorageContainerTypeReg.Selected` | Register the container type on consuming tenants. | Consuming | +| `FileStorageContainer.Selected` | Access containers of the container type on consuming tenants. | Consuming | + +`FileStorageContainerType.Manage.All` is a **delegated** permission and **doesn't require admin consent**. Any non-guest user in the owning tenant can consent to it, use it to create a container type, and is then automatically assigned as an [owner of that container type](#container-type-owners). (Before June 2026 this required the SharePoint Embedded Administrator or Global Administrator role.) + +> [!IMPORTANT] +> `FileStorageContainerType.Manage.All` is only needed on the **owning** tenant to create the container type. Remove it from your application manifest before distributing to consuming tenants so customers aren't asked for excessive permissions. On consuming tenants request only `FileStorageContainerTypeReg.Selected` and `FileStorageContainer.Selected`. + +## Container type application permissions + +Container type application permissions are granted by the owner application through container type registration. + +These permissions define what an application can do against containers of the container type. + +Container type application permissions include: + +- `None` +- `ReadContent` +- `WriteContent` +- `Create` +- `Delete` +- `Read` +- `Write` +- `EnumeratePermissions` +- `AddPermissions` +- `UpdatePermissions` +- `DeletePermissions` +- `DeleteOwnPermission` +- `ManagePermissions` +- `ManageContent` +- `Full` + +Grant only the permissions the application needs. + +For example, don't grant `Full` to a background guest app if it only needs read access for backup or analysis. + +## Container permissions + +Container permissions apply to users. + +They apply only to access on behalf of a user. + +Any user accessing a container must be a member of the container. + +Container membership grants user permissions for that container. + +SharePoint Embedded supports these container roles: + +| Role | Summary | +| --- | --- | +| Reader | Read properties and contents of the container. | +| Writer | Reader permissions plus create, update, and delete content and update applicable container properties. | +| Manager | Writer permissions plus manage membership of the container. | +| Owner | Manager permissions plus delete containers. | + +When a user creates a new container through delegated calls, that user is automatically assigned the Owner role. + +## Container type owners + +Container type owners are distinct from container owners. They govern the container type itself, in the **owning** tenant. + +- **Automatic assignment**: The user who creates a container type is automatically assigned as an owner. +- **Add or remove owners**: Use the container type `permissions` relationship (`POST`/`DELETE /storage/fileStorage/containerTypes/{id}/permissions`, beta) to manage up to **three** owners per container type. +- **Capabilities**: With `FileStorageContainerType.Manage.All` in delegated mode, owners can create, read, update, and delete the container type they own, manage its owners, and create containers of that type (delegated calls only). +- **Restrictions**: External identities (guest users) can't be container type owners. Owner information exists **only** in the owning tenant and isn't propagated to consuming tenants on registration. +- **Effective access**: Owner capabilities are user permissions; effective access is the intersection of the app's Graph permissions and the owner role. + +## Container type registration implications + +For the owning application to act on a consuming tenant: + +- The owning app must have a service principal installed on the consuming tenant. +- The owning app must be granted admin consent to perform container type registration. +- Only the owning application of the container type can invoke the registration API in the consuming tenant. + +The registration API specifies permissions for the owning app and any guest apps. + +The last successful registration API call determines the settings used in the consuming tenant. + +## Exceptional access patterns + +Plan for operations that don't follow the normal Microsoft Graph authorization pattern. + +Exceptional access patterns include: + +- Container type management on owning tenants through Microsoft Graph. +- Container type registration on consuming tenants through Microsoft Graph (`FileStorageContainerTypeReg.Selected`). +- Administrative container operations that require `FileStorageContainer.Manage.All` and a SharePoint Embedded Administrator or Global Administrator signed-in user. +- Microsoft Search scenarios that require additional permissions during preview. +- Operations that currently require a user license. + +Review these before designing privileged or search-heavy features. + +## Security considerations + +- Prefer delegated access for user-driven operations. +- Use app-only access only when needed for service operations. +- Grant least privilege at the container type level. +- Grant least privilege at the container membership level. +- Require admin consent in the correct tenant. +- Treat registration as part of customer onboarding. +- Avoid broad guest app access unless the scenario requires it. +- Review audit and compliance implications with your tenant admins. + +## Planning checklist + +- Register the Microsoft Entra ID application. +- Decide which operations use delegated access. +- Decide which operations use app-only access. +- Request Microsoft Graph `FileStorageContainer.Selected` permissions. +- Request Microsoft Graph `FileStorageContainerType.Manage.All` (owning tenant) and `FileStorageContainerTypeReg.Selected` (consuming tenants) for container type creation and registration. +- Plan admin consent in each consuming tenant. +- Define container type application permissions. +- Define user container roles. +- Identify any guest apps and their permissions. +- Review exceptional access patterns. + +## Next steps + +Review scale and performance constraints: [Understand limits and calling patterns](../plan/limits-calling-patterns.md). diff --git a/docs/embedded/plan/choose-app-model.md b/docs/embedded/plan/choose-app-model.md new file mode 100644 index 0000000000..ab60809b8d --- /dev/null +++ b/docs/embedded/plan/choose-app-model.md @@ -0,0 +1,196 @@ +--- +title: "Choose an App Model: Single-Tenant or Multitenant" +description: Compare single-tenant and multitenant SharePoint Embedded app models before you create container types and containers. +ms.date: 07/13/2026 +ms.reviewer: mawin +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Choose an app model: single-tenant or multitenant + +**Applies to:** Architect + + + +Use this article to choose between an enterprise line-of-business (LOB) model and an ISV multitenant model for SharePoint Embedded. + +The app model determines who owns the app, who installs it, where containers are created, who pays, and which admins must consent or configure billing. + +For architecture details, see [Understand app and tenant architecture](../plan/app-tenant-architecture.md). + +## Decision summary + +| Requirement | Choose single-tenant LOB | Choose multitenant ISV | +| --- | --- | --- | +| App is built for one organization | Yes | No | +| App is sold or provided to multiple customer tenants | No | Yes | +| Owning tenant and consuming tenant are usually the same | Yes | No | +| Customer tenants host their own containers and files | Not usually | Yes | +| App owner pays for all usage by default | Often | Depends on billing model | +| Customer tenant admin must onboard the app | Sometimes | Yes | + +Both models use the same SharePoint Embedded primitives: + +- Microsoft Entra ID application registration. +- Container type. +- Container type registration. +- Containers. +- Microsoft Graph access. +- Pay-as-you-go billing meters. + +## Enterprise LOB model + +Use the enterprise LOB model when an organization builds an app for internal users. + +In this model: + +- The enterprise owns or develops the app. +- The app registration is in the enterprise tenant. +- The enterprise tenant creates the container type. +- The enterprise tenant is also the consuming tenant. +- Containers are created in the enterprise Microsoft 365 tenant. +- Files remain in the enterprise tenant boundary. +- Enterprise tenant settings apply to the content. + +This model is usually single-tenant because the same tenant owns and consumes the application. + +> [!NOTE] +> The same Microsoft Entra ID tenant can be both the owning tenant and the consuming tenant for a container type. + +## Multitenant ISV model + +Use the multitenant ISV model when an ISV builds one app for multiple customer tenants. + +In this model: + +- The ISV owns or develops the app. +- The ISV tenant usually owns the app registration. +- The ISV tenant creates the container type. +- Each customer is a consuming tenant. +- Containers are created in each customer Microsoft 365 tenant. +- Files remain in the customer tenant boundary. +- Customer Microsoft 365 settings apply to that customer's content. + +The ISV app provides the user experience and calls Microsoft Graph. Customer content stays with the consuming tenant. + +## Who owns the app + +App ownership is tied to the Microsoft Entra ID application registration and the container type. + +Every container type has one owning application. + +SharePoint Embedded requires a 1:1 relationship between an owning app and a container type. + +For an LOB app, the enterprise owns both. + +For an ISV app, the ISV owns both. + +## Who installs or onboards the app + +In a single-tenant LOB model, admins in the same tenant can create the container type, grant consent, and configure billing. + +In a multitenant ISV model, customer tenant admins must onboard the app for their tenant. + +The owning app must have a service principal in the consuming tenant and must receive admin consent to perform container type registration. + +For the registration flow, see [Register file storage container type application permissions](../build/register-application-permissions.md). + +## Where containers are created + +Containers are created in the consuming tenant. + +For an enterprise LOB app, that's usually the enterprise tenant. + +For an ISV app, each customer tenant has its own containers. + +This separation keeps customer files in the customer's Microsoft 365 tenant boundary. + +> [!IMPORTANT] +> Don't design an ISV architecture that stores all customer files in the ISV tenant. SharePoint Embedded stores app documents in the consuming tenant. + +## Who pays + +SharePoint Embedded is pay-as-you-go. + +Billing is based on meters such as storage, API transactions, and egress. + +The billing model is selected for the container type. + +SharePoint Embedded supports two billing models: + +- Standard billing. +- Pass-through billing. + +For details, see [Choose a billing model](../plan/choose-billing-model.md). + +## Standard billing + +With standard billing, consumption-based charges are billed to the tenant that owns or develops the application. + +An Azure subscription from the developer tenant is used when creating a standard container type. + +Use standard billing when the app owner wants to absorb or centrally manage SharePoint Embedded usage charges. + +## Pass-through billing + +With pass-through billing, charges are billed directly to the tenant registered to use the SharePoint Embedded application. + +The developer tenant admin doesn't set up a billing profile when creating the pass-through container type. + +After the container type is registered in the consuming tenant, the consuming tenant admin sets up the billing profile. + +Use pass-through billing when each customer tenant should pay for its own usage. + +## Consent and admin responsibilities + +Plan these responsibilities before implementation. + +| Responsibility | LOB single-tenant | ISV multitenant | +| --- | --- | --- | +| Create app registration | Enterprise tenant | ISV tenant | +| Create container type | Enterprise tenant | ISV tenant | +| Register container type | Same tenant | Each customer consuming tenant | +| Grant Microsoft Graph consent | Enterprise admin | Customer tenant admin for consuming tenant access | +| Configure standard billing | Enterprise/developer | ISV/developer | +| Configure pass-through billing | Consuming tenant admin | Customer tenant admin | +| Govern content | Enterprise compliance admin | Customer compliance admin | + +## Which setup path to follow next + +If you're building an internal enterprise app: + +1. Plan authentication with [Plan authentication and permissions](../plan/authentication-permissions.md). +1. Understand container type design with [Understand container types and containers](../plan/container-types-containers.md). +1. Create the container type by using the guidance in [SharePoint Embedded container types](../build/create-container-type.md). +1. Configure billing by using [PAYG billing for SharePoint Embedded](../admin/setup-billing-microsoft-365-admin-center.md). + +If you're building an ISV app: + +1. Plan tenant relationships with [Understand app and tenant architecture](../plan/app-tenant-architecture.md). +1. Choose standard or pass-through billing with [Choose a billing model](../plan/choose-billing-model.md). +1. Create the container type in the owning tenant. +1. Register the container type in each consuming tenant by using [Register file storage container type application permissions](../build/register-application-permissions.md). + +## Planning checklist + +- Identify whether the app is internal or customer-facing. +- Identify the owning tenant. +- Identify all consuming tenants. +- Confirm who owns the Microsoft Entra ID application registration. +- Confirm where the container type is created. +- Confirm where containers are created. +- Choose standard or pass-through billing. +- Identify who grants admin consent. +- Identify who configures billing. +- Identify who manages compliance policies. + +## Next steps + +Review the storage model: [Understand container types and containers](../plan/container-types-containers.md). diff --git a/docs/embedded/plan/choose-billing-model.md b/docs/embedded/plan/choose-billing-model.md new file mode 100644 index 0000000000..9d3131a080 --- /dev/null +++ b/docs/embedded/plan/choose-billing-model.md @@ -0,0 +1,199 @@ +--- +title: Choose a Billing Model +description: Compare standard and pass-through SharePoint Embedded billing models before you create production container types. +ms.date: 07/13/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Choose a billing model + +**Applies to:** Architect + + + +Use this article to choose a billing model for production SharePoint Embedded container types. SharePoint Embedded is a consumption-based, pay-as-you-go offering, and you select billing at the container type level. + +For the full billing setup procedure, see [PAYG billing for SharePoint Embedded](../admin/setup-billing-microsoft-365-admin-center.md). + +## Billing models + +SharePoint Embedded provides two billing models: + +- Standard billing. +- Pass-through billing. + +Both models use the same billing meters. + +The model determines which tenant is billed and which admin configures the billing profile. + +> [!IMPORTANT] +> Once a container type is created, its billing model can't be changed. To switch models, you must delete and re-create the container type with the desired billing model. + +| Billing model | Who is billed | Who configures billing | +| --- | --- | --- | +| Standard | Tenant that owns or develops the application. | Admin in the developer tenant. | +| Pass-through | Tenant registered to use the SharePoint Embedded application. | Admin in the consuming tenant. | + +## Standard billing + +With standard billing, all consumption-based charges are directly billed to the tenant that owns or develops the application. + +The admin in the developer tenant must establish a valid billing profile when creating a standard container type. + +Use standard billing when: + +- The application owner wants to centralize usage charges. +- The app is an internal enterprise LOB app. +- The ISV or developer tenant plans to absorb or separately recover usage costs. +- Customer tenants shouldn't configure their own SharePoint Embedded billing profile. + +The billing setup requires: + +- An existing SharePoint tenancy. +- An Azure subscription in the tenancy. +- A resource group attached to the Azure subscription. +- A SharePoint Embedded Administrator or Global Administrator to operate billing cmdlets. +- Owner or contributor permissions on the Azure subscription for the admin who sets up billing. + +The standard billing pattern creates the container type and then attaches an Azure billing profile (see [Create and configure a container type](../build/create-container-type.md)): + +```powershell +New-SPOContainerType -ContainerTypeName -OwningApplicationId -ApplicationRedirectUrl +``` + +Attach the Azure billing profile: + +```powershell +Add-SPOContainerTypeBilling -ContainerTypeId -AzureSubscriptionId -ResourceGroup -Region +``` + +> [!IMPORTANT] +> Every container type must have an owning application. A single owning app can only own one container type at a time. + +## Pass-through billing + +With pass-through billing, consumption-based charges are billed directly to the tenant registered to use the SharePoint Embedded application. + +Admins in the developer tenant don't need to set up a billing profile when creating a pass-through container type. + +After the container type is registered in the consuming tenant, the consuming tenant admin sets up the billing profile in that tenant. + +Use pass-through billing when: + +- Each customer tenant should pay for its own SharePoint Embedded usage. +- The app is an ISV multitenant application. +- The customer tenant controls the Azure subscription used for pay-as-you-go charges. +- The consuming tenant admin is expected to complete billing onboarding. + +Use this pass-through creation pattern: + +```powershell +New-SPOContainerType -ContainerTypeName -OwningApplicationId -IsPassThroughBilling +``` + +> [!NOTE] +> Use the `-IsPassThroughBilling` switch with `New-SPOContainerType` when the consuming tenant pays for usage. + +## Billing meters + +SharePoint Embedded billing is determined by usage. The supported meters are described in [SharePoint Embedded billing meters](../reference/billing-meters.md). + +The current meters include: + +- Storage. +- Archived storage. +- API transactions. +- Egress. + +Both standard billing container types and pass-through billing container types use the same meters. + +## Storage meter + +Storage consumption includes files and documents with their metadata and versions, in both active and archived states. + +Storage consumption also includes content in the recycle bin and deleted container collection within SharePoint Embedded. + +Plan lifecycle and deletion policies with storage cost in mind. + +## Archived storage meter + +The archived storage meter measures storage consumed by archived containers. Archiving a container moves its data to the cold storage tier, which offers lower storage costs than active storage. + +## API transactions meter + +Each Microsoft Graph call made explicitly by the SharePoint Embedded application is counted as one transaction. + +Customers are billed based on transaction count. + +Calls made by internal services to containers aren't charged when the application has no control over those calls. + +Nonchargeable transactions include: + +- eDiscovery queries that search through container content for compliance or legal purposes. +- Admin actions taken through SharePoint Admin Center or SharePoint PowerShell. + +## Egress meter + +Egress is data that exits the SharePoint Embedded platform, such as a document downloaded to a customer client device or data transferred to a server operated by the customer. Charges are based on the total volume of data transferred out (GB). + +Downloads from the SharePoint Embedded application server to Office desktop clients or Web Application Companion are exempt from egress charges. + +Review pricing and cost management in Azure Cost Management as part of your operations plan. + +## Admin responsibilities + +Plan these responsibilities by billing model. + +| Responsibility | Standard billing | Pass-through billing | +| --- | --- | --- | +| Create container type | Developer tenant admin | Developer tenant admin | +| Attach billing profile at creation | Developer tenant admin | Not in developer tenant | +| Register container type | Owning app in consuming tenant | Owning app in consuming tenant | +| Set up consuming tenant billing | Not required for app usage billing | Consuming tenant admin | +| Monitor Azure cost | Developer tenant | Consuming tenant | + +## Relationship to app model + +Billing model and app model are related but separate decisions. + +An enterprise LOB app often uses standard billing because the developer and consuming tenant are the same organization. + +An ISV multitenant app often uses pass-through billing when each customer should pay for their own usage. + +An ISV can use standard billing when the ISV wants to own all usage charges. + +For model selection, see [Choose an app model: single-tenant or multitenant](../plan/choose-app-model.md). + +## Setup links + +Use these setup references after you choose a model: + +- Create and configure container types: [SharePoint Embedded container types](../build/create-container-type.md). +- Set up billing: [PAYG billing for SharePoint Embedded](../admin/setup-billing-microsoft-365-admin-center.md). +- Review meters: [SharePoint Embedded billing meters](../reference/billing-meters.md). +- Register a consuming tenant: [Register file storage container type application permissions](../build/register-application-permissions.md). + +## Planning checklist + +- Decide whether the developer tenant or consuming tenant pays. +- Confirm the app model. +- Confirm whether the container type is standard or pass-through. +- Identify the Azure subscription and resource group if using standard billing. +- Identify the consuming tenant admin if using pass-through billing. +- Confirm SharePoint Embedded Administrator or Global Administrator roles. +- Confirm owner or contributor permissions on the Azure subscription. +- Plan cost monitoring in Azure Cost Management. +- Plan storage lifecycle to control storage consumption. +- Plan calling patterns to manage API transaction cost. + +## Next steps + +Plan governance responsibilities for tenant content: [Plan security, compliance, and governance](../plan/security-compliance-governance.md). diff --git a/docs/embedded/plan/container-types-containers.md b/docs/embedded/plan/container-types-containers.md new file mode 100644 index 0000000000..1f49d67b1f --- /dev/null +++ b/docs/embedded/plan/container-types-containers.md @@ -0,0 +1,198 @@ +--- +title: Understand container types and containers +description: Learn how SharePoint Embedded container types define app access and how containers store files in consuming tenants. +ms.date: 07/10/2026 +ms.reviewer: shsaravanan +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Understand container types and containers + +**Applies to:** Developer + + + +Use this article to understand the two core storage objects in SharePoint Embedded: container types and containers. + +For the full creation and management reference, see [SharePoint Embedded container types](../build/create-container-type.md). + +## Object model + +SharePoint Embedded stores files and documents in containers, which are grouped by container type. You create a container type before you can create any containers for an application. + +| Object | What it represents | Who usually manages it | +| --- | --- | --- | +| Container type | Relationship between an app and a set of containers, including access, behavior, and billing accountability. | Developer or container type owner. | +| Container | The storage and security boundary for files and folders. | Application through Microsoft Graph, and admins for governance operations. | + +## Container type concept + +A container type is a SharePoint Embedded resource. It defines: + +- The owning application. +- The access privileges between applications and containers. +- The billing accountability model. +- Selected behaviors that apply to containers of that type. + +Each container type is strongly coupled with one SharePoint Embedded application, called the owning application. SharePoint Embedded requires a 1:1 relationship between the owning application and the container type. The owning application developer is responsible for creating and managing the container type. + +## Container type identity + +The container type is represented on each container as an immutable property named `ContainerTypeID`. The property is used across the SharePoint Embedded ecosystem. It affects: + +- Access authorization. +- Trial exploration. +- Billing. +- Configurable behavior. + +> [!IMPORTANT] +> Plan the container type carefully. Some creation choices, such as trial versus production and standard versus pass-through billing, can't be converted after creation. To switch, you must delete and re-create the container type. + +## Containers + +A container is the basic storage unit in SharePoint Embedded, and it defines a security and compliance boundary. Applications create containers in consuming tenants by using Microsoft Graph. + +Files, folders, metadata, versions, and recycle bin content are stored within containers and are subject to current SharePoint Embedded limits. + +For limits, see [Understand limits and calling patterns](../plan/limits-calling-patterns.md). + +## Ownership + +Container type ownership and container residency are different. The owning tenant creates the container type. The consuming tenant uses the container type and hosts containers. + +All container content created through the application is stored within the consuming tenant's Microsoft 365 tenant boundary. + +For tenant architecture, see [Understand app and tenant architecture](../plan/app-tenant-architecture.md). + +## Access authorization + +A SharePoint Embedded application must be associated with a container type to access containers of that type. After association, the application has access to containers of that type according to application-container type permissions. The owning application has full access privilege by default to containers of the container type it's coupled with. Actual access also depends on whether the app uses delegated access or app-only access. + +For permission planning, see [Plan authentication and permissions](../plan/authentication-permissions.md). + +## Trial container types + +Use a trial container type to explore SharePoint Embedded development without linking an Azure billing profile. + +For trial container types: + +- The developer tenant is the same as the consuming tenant. +- Each developer can have only one trial container type in their tenant at a time. +- The trial is valid for up to 30 days. +- Up to five containers of the container type can be created, including active containers and containers in the recycle bin. +- Each container has up to 1 GB of storage. +- The container type is restricted to the developer tenant. + +A trial container type can't be converted to production. + +To create a trial container type, developers can use the SharePoint Embedded Visual Studio Code extension or the Microsoft Graph container type API. + +Container types are created with the Microsoft Graph `POST /v1.0/storage/fileStorage/containerTypes` endpoint, using the `trial` billing classification. This call requires the `FileStorageContainerType.Manage.All` delegated permission; app-only access isn't supported. The calling user must be a non-guest member of the owning tenant (no admin role required) and is automatically assigned as an owner of the new container type. + +## Standard container types + +A standard container type is used for non-trial scenarios. + +Each tenant can have 25 container types at a time. + +Standard container types are billable and must use a billing model. + +SharePoint Embedded supports: + +- Standard billing (`standard` billing classification). +- Pass-through billing (`directToCustomer` billing classification). + +For billing selection, see [Choose a billing model](../plan/choose-billing-model.md). + +## Standard billing container type + +With standard billing, consumption-based charges are billed to the tenant that owns or develops the application. + +The owning tenant attaches a billing profile after creating the standard container type. + +Create the container type with the Microsoft Graph `POST /v1.0/storage/fileStorage/containerTypes` endpoint using the `standard` billing classification, then attach an Azure billing profile: + +```http +POST https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes +``` + +```json +{ + "name": "{ContainerTypeName}", + "owningAppId": "{OwningApplicationId}", + "billingClassification": "standard" +} +``` + +## Pass-through billing container type + +With pass-through billing, charges are billed directly to the consuming tenant. + +The developer creates the container type with the `directToCustomer` billing classification and doesn't attach a billing profile in the developer tenant. + +```json +{ + "name": "{ContainerTypeName}", + "owningAppId": "{OwningApplicationId}", + "billingClassification": "directToCustomer" +} +``` + +After registration, a Global Administrator in the consuming tenant sets up billing in the consuming tenant. + +## Admin and developer interaction + +Developers and admins interact with different layers. + +| Activity | Container type | Container | +| --- | --- | --- | +| Create the app's storage family | Yes | No | +| Configure owning app relationship | Yes | No | +| Configure billing accountability | Yes | No | +| Create app storage instances | No | Yes | +| Store files and folders | No | Yes | +| Apply container-specific governance | No | Yes | +| Delete the storage family | Yes, after containers are removed | No | + +## Container type configuration + +Developers can configure selected container type settings after creation. + +You can configure these container type settings: + +- `ApplicationRedirectUrl` +- `DiscoverabilityDisabled` +- `SharingRestricted` + +Use the Microsoft Graph [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API for supported container type updates. For administrative settings, see [Create apps with PowerShell](../admin/create-apps-powershell.md). + +## Registration + +To create and interact with containers in a consuming tenant, the container type must be registered in that tenant. + +The owning application invokes the registration API to define application permissions for the container type. + +For full details, see [Register file storage container type application permissions](../build/register-application-permissions.md). + +## Planning checklist + +- Choose trial or standard. +- Choose standard billing or pass-through billing for production. +- Identify the owning application. +- Confirm the container type name. +- Confirm the consuming tenant or tenants. +- Plan container type registration. +- Plan application permissions. +- Plan which container type settings are required. +- Plan container lifecycle and deletion. + +## Next steps + +Plan authentication and authorization: [Plan authentication and permissions](../plan/authentication-permissions.md). diff --git a/docs/embedded/plan/limits-calling-patterns.md b/docs/embedded/plan/limits-calling-patterns.md new file mode 100644 index 0000000000..d5ef290b15 --- /dev/null +++ b/docs/embedded/plan/limits-calling-patterns.md @@ -0,0 +1,249 @@ +--- +title: Understand Limits and Calling Patterns +description: Plan SharePoint Embedded service limits, throttling behavior, retry handling, and performance-sensitive calling patterns. +ms.date: 07/13/2026 +ms.reviewer: mawin +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Understand limits and calling patterns + +**Applies to:** Developer + + + +Use this article to plan SharePoint Embedded calling patterns before you build high-volume container and content operations. SharePoint Embedded expresses throughput as **resource units per minute** (a normalized request-cost model) rather than as a fixed requests-per-second rate; the [API rate limits](#api-rate-limits) section explains how to translate resource units into an expected request rate. + +Limits marked with `*` can be increased on request through Microsoft support or your SharePoint Embedded onboarding contact; plan for the default limit and request an increase before you approach it in production. + +## Limit categories + +SharePoint Embedded limits affect: + +- *Container type counts +- *Container counts +- Storage per container type and container +- Files and folders +- Permissions +- File size +- Version count +- *API rate limits +- *Requests per app, container, and user + +> [!NOTE] +> These limits can change. Verify the current limits before you launch to production. + +## Size limits + +SharePoint Embedded enforces the following size limits. + +| Resource | Limit | +| --- | --- | +| Container types that a partner tenant can create | 25* | +| Container types that an app can own | 1 | +| Containers of a container type per consuming tenant | 100k* | +| Storage per container type per consuming tenant | 100 TB* | +| Files and folders per container | 30M | +| Storage per container | 25 TB | +| Files and folders with additive permissions per container | 5k | +| File size | 250 GB | +| Version count per file | 500 (Automatic Version History Limits Default Setting) | +| Number of users shared per folder or file | 5k | + +An asterisk (`*`) indicates a limit you can request to increase. + +Of the container types a tenant creates, one can be a free **trial container type** for development and testing, and the rest are **standard** (billed) container types. New tenants start with a lower default that can be raised on request. For trial-versus-standard details, see [Create and configure a container type](../build/create-container-type.md). + +## Design for container type limits + +An app can own one container type. + +Don't model each customer, project, workspace, or user as a separate container type. + +Use containers for application storage instances within the container type. + +Choose a container type for app-level behavior, access relationship, and billing accountability. + +For container type planning, see [Understand container types and containers](../plan/container-types-containers.md). + +## Design for container limits + +Containers provide the storage and security boundary. + +Plan how many containers each consuming tenant might create. + +Account for active containers and any deleted container lifecycle that might affect quotas or storage. + +Keep container boundaries aligned with access, lifecycle, and governance requirements. + +## Design for permission limits + +SharePoint Embedded allows up to 5,000 files and folders with additive permissions per container. + +Avoid designing every file or folder to have unique permissions when a container-level or folder-level model is sufficient. + +Use container membership and roles where possible. + +For permission concepts, see [Plan authentication and permissions](../plan/authentication-permissions.md). + +## Throttling responses + +When applications hit service limits, SharePoint Embedded can return: + +- HTTP `429 Too Many Requests`. +- HTTP `503 Server Too Busy`. + +Both responses include a `Retry-After` header. + +The header tells the app how long to wait before retrying or making a new request. + +> [!IMPORTANT] +> Throttled requests count toward usage limits. If you ignore `Retry-After`, your app can cause more throttling. + +## Retry guidance + +Implement retry logic that: + +- Detects HTTP `429` and `503`. +- Reads the `Retry-After` header. +- Waits for the specified duration before retrying. +- Reduces concurrency after throttling. +- Avoids immediate retry loops. +- Avoids request spikes after a wait period. + +Use bounded retries and surface persistent failures to operations telemetry. For general guidance on handling throttling responses, see [Microsoft Graph throttling guidance](/graph/throttling). + +## Concurrency guidance + +Reduce the number of concurrent requests when throttling occurs. + +Avoid burst patterns that send many requests at the same instant. + +Distribute work over time when processing large sets of containers or files. + +Use queues or background workers to smooth traffic. + +Prioritize user-visible operations over background maintenance when near limits. + +## API resource units + +Different APIs have different costs depending on functionality and complexity. + +The cost is normalized and expressed as resource units. + +API rate limits are also defined using resource units. + +Each request costs resource units based on its complexity: + +| Resource units per request | Operations | +| --- | --- | +| 1 | Single item query, such as get item. | +| 2 | Multi-item query, such as list children, create, update, delete, and upload. | +| 5 | All permission resource operations, including `$expand=permissions`. | + +> [!NOTE] +> Resource unit costs can change. + +## API rate limits + +SharePoint Embedded enforces these API rate limits. + +| Resource | Limit | +| --- | --- | +| Requests per container | 3k resource units per min | +| Requests per app per tenant | 12k resource units per min* | +| Requests per user | 600 resource units per min | + +An asterisk (`*`) indicates a limit you can request to increase. + +Application limits are defined in resource units. + +The actual requests per minute depends on the APIs you call and their resource unit cost. + +To estimate your request rate, average about two resource units per request and divide the application resource unit limit by two. + +## Container creation rate limiting + +Per consuming tenant, and during the tenant's peak hours, container creation is limited to 5 new containers per second. Requests beyond this limit are rate limited. Outside of peak hours, containers can be created at a faster rate. + +## Permission operation costs + +Permission resource operations have a higher resource unit cost. + +Operations that include `$expand=permissions` are listed at five resource units. + +Reduce unnecessary permission expansion. + +Cache permission-derived decisions only when it is safe for your security model. + +Refresh permission data when membership or role changes occur. + +## Batching considerations + +Batching can reduce client overhead, but it doesn't remove service limits or billing impact. + +Count each underlying operation when you estimate resource unit consumption and transaction cost. + +Avoid creating batches that concentrate too much work against one container, app, tenant, or user in a short interval. + +Honor throttling responses for batched operations according to the response details returned by the platform. + +## Performance considerations + +Design for: + +- Fewer permission-heavy calls. +- Predictable concurrency. +- Incremental synchronization. +- Backoff after throttling. +- Separation of foreground and background work. +- Tenant-level fairness for multitenant apps. +- Monitoring of request rate, response codes, and latency. + +For billing impact of API transactions, see [Choose a billing model](../plan/choose-billing-model.md). + +## Operational monitoring + +Track: + +- HTTP `429` and `503` response rates. +- Retry counts and wait durations. +- Resource-intensive operations. +- Requests by app, tenant, user, and container. +- Background job queue length. +- Storage growth per container and tenant. +- Permission operation frequency. + +Use these signals to tune concurrency and identify tenants or workflows that need design changes. + +## Planning checklist + +- Confirm current size limits before production launch. +- Model containers instead of creating many container types. +- Estimate storage per container and per consuming tenant. +- Estimate file and folder counts. +- Avoid unnecessary additive permissions. +- Implement `Retry-After` handling for `429` and `503`. +- Limit concurrency and avoid spikes. +- Estimate resource unit usage by operation type. +- Reduce permission-heavy operations. +- Monitor throttling and latency. +- Include billing impact in API design. + +## Related planning articles + +- [Understand app and tenant architecture](../plan/app-tenant-architecture.md) +- [Understand container types and containers](../plan/container-types-containers.md) +- [Plan authentication and permissions](../plan/authentication-permissions.md) +- [Choose a billing model](../plan/choose-billing-model.md) + +## Next steps + +Start building with [Quickstart: Build your first app with VS Code](../build/quickstart-vscode.md). diff --git a/docs/embedded/plan/security-compliance-governance.md b/docs/embedded/plan/security-compliance-governance.md new file mode 100644 index 0000000000..1a70f53c57 --- /dev/null +++ b/docs/embedded/plan/security-compliance-governance.md @@ -0,0 +1,232 @@ +--- +title: Plan Security, Compliance, and Governance +description: Plan how Microsoft Purview, audit, DLP, retention, labels, and access policies apply to SharePoint Embedded content. +ms.date: 07/13/2026 +ms.reviewer: mawin +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Plan security, compliance, and governance + +**Applies to:** Compliance administrator + + + +Use this article to plan security, compliance, and governance for content stored in SharePoint Embedded. + +SharePoint Embedded content resides in the consuming tenant's Microsoft 365 boundary. + +Supported consumer Microsoft 365 tenant settings and Microsoft Purview capabilities apply to the app documents stored there. + +## Governance model + +SharePoint Embedded is API-only and doesn't provide a built-in end-user interface. + +The owning application provides the user experience. + +Compliance administrators and SharePoint Embedded administrators enforce supported policies on containers and content by using Microsoft Purview, supported admin capabilities, and PowerShell. + +Some compliance scenarios require user interaction. Because SharePoint Embedded doesn't include a native UI, the app must provide the experience when those scenarios are required. + +## Tenant responsibility + +Content is stored in the consuming tenant. + +Therefore, consuming tenant policies and administrator decisions govern the content. + +For an enterprise LOB app, the enterprise tenant owns and consumes the app. + +For an ISV app, each customer tenant governs its own SharePoint Embedded content. + +For tenant role planning, see [Understand app and tenant architecture](../plan/app-tenant-architecture.md). + +## Discover applications and containers + +Compliance admins may need container details to target policies. + +Use this PowerShell discovery flow to retrieve container details for policy scope: + +1. View registered SharePoint Embedded applications in the tenant. + + ```powershell + Get-SPOApplication + ``` + +1. Retrieve containers for an application by using the application ID. + + ```powershell + Get-SPOContainer -OwningApplicationId + ``` + +1. Retrieve details for a container, including the container site URL. + + ```powershell + Get-SPOContainer -OwningApplicationId -Identity + ``` + +For cmdlet details, see [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer). + +## Microsoft Purview support + +SharePoint Embedded supports Microsoft Purview compliance features for content stored in the platform. + +SharePoint Embedded supports these Microsoft Purview capabilities: + +- Audit +- eDiscovery +- Data Lifecycle Management +- Data Loss Prevention + +These capabilities work similarly to SharePoint content, with limitations where the app must provide user interaction. + +## Audit + +Audit capabilities mirror the existing audit functionality supported in SharePoint. + +User and admin operations performed in applications hosted in SharePoint Embedded are captured, recorded, and retained in the organization's unified audit log. + +Audit events related to SharePoint Embedded include additional data to help filter results: + +- `ContainerInstanceId` +- `ContainerTypeId` + +Use these properties to isolate SharePoint Embedded content during audit searches. + +For more information, see [Auditing solutions in Microsoft Purview](/purview/audit-solutions-overview). + +## eDiscovery + +Compliance admins can use Microsoft Purview eDiscovery tools to search, hold, and export SharePoint Embedded content. + +To search all SharePoint Embedded content, configure eDiscovery Search for all SharePoint sites. + +This includes SharePoint sites and SharePoint Embedded containers. + +To limit eDiscovery Search to specific containers, choose sites under the SharePoint sites workload and provide the container URL. + +For more information, see [Microsoft Purview eDiscovery solutions](/purview/ediscovery). + +## Data Lifecycle Management + +SharePoint Embedded supports retention and hold policies through the Microsoft Purview compliance portal. + +Retention policies configured for all SharePoint sites apply to all SharePoint sites and all containers in SharePoint Embedded. + +To selectively enforce a policy on one or more SharePoint Embedded containers, use the container URL when configuring the policy. + +Because SharePoint Embedded has no built-in UI, app support is required for user-interaction scenarios such as an end user applying a retention label through the app. + +For more information, see [Learn about Microsoft Purview Data Lifecycle Management](/purview/data-lifecycle-management). + +## Data Loss Prevention + +Microsoft Purview Data Loss Prevention can identify, monitor, and automatically protect sensitive items stored in SharePoint Embedded applications. + +DLP policies can be enforced on all SharePoint sites and SharePoint Embedded containers by configuring the policy for all sites. + +Admins can also restrict DLP enforcement to specific SharePoint Embedded containers by specifying container URLs. + +Some DLP scenarios require user interaction. + +For example, a DLP policy that prevents external sharing might allow a business justification override. + +The client app must provide the user interaction if the scenario is required. + +Policy tips for SharePoint Embedded files also require app support through Microsoft Graph where applicable. + +For more information, see [Learn about data loss prevention](/purview/dlp-learn-about-dlp). + +## Sensitivity labels + +Global Administrators and SharePoint Embedded Administrators can set and remove sensitivity labels on a SharePoint Embedded container by using SharePoint PowerShell. + +Use this command: + +```powershell +Set-SPOContainer -Identity -SensitivityLabel +``` + +The label is applied at the **container level**: it sets the container's sensitivity and governs container settings such as conditional access and guest sharing. It doesn't retroactively relabel files that already exist in the container, and each file carries its own sensitivity label. For item-level labeling behavior, see [Learn about sensitivity labels](/purview/sensitivity-labels). + +## Block download policy + +SharePoint Administrators or Global Administrators can block file downloads from SharePoint Embedded containers. + +Use this command: + +```powershell +Set-SPOSite -Identity -BlockDownloadPolicy $true +``` + +A SharePoint Advanced Management license is needed to enforce this policy. + +For more information, see [Block download policy for SharePoint sites and OneDrive](/sharepoint/block-download-from-sites). + +## Conditional Access + +SharePoint Embedded supports basic Conditional Access policy configurations. + +Use this command: + +- `AllowFullAccess` +- `AllowLimitedAccess` +- `BlockAccess` + +These settings are available through: + +```powershell +Set-SPOContainer -Identity -ConditionalAccessPolicy +``` + +For more information, see [Control access from unmanaged devices](/sharepoint/control-access-from-unmanaged-devices). + +## Information barriers + +The `fileStorageContainer` resource has an **informationBarrier** property that lets you manage a container's information barrier (beta Microsoft Graph endpoint, March 2026). Use information barrier segments to restrict communication and collaboration between groups of users where required by compliance policy. + +For more information, see [Information barriers in SharePoint](/purview/information-barriers-sharepoint). + +## Tenant settings + +Consumer Microsoft 365 settings apply to app documents stored by SharePoint Embedded. + +This includes supported security, compliance, risk, and governance settings. + +Your application shouldn't assume that every consuming tenant has the same policy configuration. + +Design for policy enforcement results, blocked operations, and user-facing messages. + +## Governance responsibilities + +| Area | App owner | Consuming tenant admin | +| --- | --- | --- | +| User experience for files | Provide app UI. | Validate policy expectations. | +| Container discovery | Expose identifiers where appropriate. | Use PowerShell and admin tools. | +| Purview policies | Handle policy-driven UX requirements. | Configure audit, eDiscovery, DLP, retention, and labels. | +| Access model | Request least privilege. | Grant consent and manage tenant settings. | +| Compliance evidence | Preserve app context and auditability. | Use unified audit log and Purview tools. | + +## Planning checklist + +- Identify the consuming tenant governance owner. +- Inventory SharePoint Embedded applications and containers. +- Capture container URLs needed for targeted policies. +- Plan audit searches using `ContainerInstanceId` and `ContainerTypeId`. +- Decide whether policies apply to all sites or selected containers. +- Plan DLP user interaction in the app. +- Plan retention label user interaction in the app if required. +- Decide whether sensitivity labels are required on containers. +- Decide whether block download policy is required. +- Decide whether Conditional Access settings are required. +- Validate licensing requirements for advanced policies. + +## Next steps + +Review scale, throttling, and retry behavior: [Understand limits and calling patterns](../plan/limits-calling-patterns.md). diff --git a/docs/embedded/publish/choose-app-billing-model.md b/docs/embedded/publish/choose-app-billing-model.md new file mode 100644 index 0000000000..e97edf8e07 --- /dev/null +++ b/docs/embedded/publish/choose-app-billing-model.md @@ -0,0 +1,195 @@ +--- +title: Choose a billing model for your app +description: Compare standard and pass-through billing for SharePoint Embedded apps before onboarding customer tenants. +ms.date: 07/10/2026 +ms.reviewer: cindylay +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- +# Choose a billing model for your app + +**Applies to:** ISV + + + +SharePoint Embedded is a consumption-based pay-as-you-go service. +As an ISV, you choose the billing model when you create the production container type for your app. +That choice affects who pays for storage, API transactions, and egress, and it changes what the customer administrator must do during onboarding. + +Use this article to decide between standard billing and pass-through billing before you publish customer setup instructions. + +## Billing choices + +SharePoint Embedded supports two production billing models for standard container types. + +| Billing model | Who is billed | Who configures billing | Typical ISV use | +| --- | --- | --- | --- | +| Standard billing | Developer tenant | Developer | You include SharePoint Embedded consumption in your product price or centralize billing. | +| Pass-through billing | Consuming tenant | Customer admin | The customer pays Microsoft directly for their SharePoint Embedded consumption. | + +For current billing details, see [PAYG billing for SharePoint Embedded](../admin/setup-billing-microsoft-365-admin-center.md). + +> [!IMPORTANT] +> Choose the billing model before you create the container type. +> Standard and pass-through billing can't be converted after creation. + +## How billing relates to container types + +A container type defines access, behavior, and billing accountability for a set of containers. +Each container type is strongly coupled with one owning application. +The owning application developer creates and manages the container type. + +Container types are used for: + +- Access authorization between the app and containers. +- Trial exploration during development. +- Billing for non-trial workloads. +- Shared configuration settings such as discoverability and sharing behavior. + +For more about container types, see [Create New SharePoint Embedded Container Types](../plan/container-types-containers.md). + +## Standard billing + +With standard billing, all consumption-based SharePoint Embedded charges are billed to the tenant that owns or develops the application. +The developer must establish a valid Azure billing profile for the container type. + +Choose standard billing when: + +- You sell a bundled SaaS price and absorb or allocate SharePoint Embedded usage internally. +- You want a simpler customer setup path. +- Customers shouldn't configure an Azure subscription for your app. +- You operate a managed service where your tenant owns the consumption relationship. +- Your commercial agreement already covers storage and transaction costs. + +Standard billing usually reduces customer onboarding steps because the customer doesn't need to set up a SharePoint Embedded billing profile in the consuming tenant. +However, you must manage your own Azure subscription, resource group, cost tracking, and customer usage allocation. + +### Standard billing dependencies + +Before you create or activate a standard billing container type, confirm that your developer tenant has: + +- An active SharePoint tenant. +- A Microsoft Entra owning application. +- A SharePoint Embedded Administrator or Global Administrator. +- An Azure subscription in the developer tenant. +- A resource group attached to the subscription. +- Owner or contributor permissions for the admin who sets up the billing relationship. + +When you set up standard billing, provide the Azure subscription, resource group, and region for the billing profile. + +> [!NOTE] +> Standard billing doesn't remove the need for customer consent, container type registration, or validation. +> It only changes who configures and pays for SharePoint Embedded consumption. + +## Pass-through billing + +With pass-through billing, consumption charges are billed directly to the tenant registered to use the SharePoint Embedded application. +The developer creates the container type with pass-through billing enabled. +The customer administrator then configures billing in the consuming tenant before users can access the app. + +Choose pass-through billing when: + +- Customers must pay Microsoft directly for their own SharePoint Embedded usage. +- Your product contract excludes Microsoft 365 consumption charges. +- Customers require billing visibility in their own Azure Cost Management environment. +- Each tenant's storage, transaction, and egress costs should stay with that tenant. +- You want a cleaner separation between app subscription revenue and platform consumption. + +Pass-through billing adds customer onboarding work. +The customer admin must set up pay-as-you-go billing in the Microsoft 365 admin center and connect a valid Azure subscription and resource group. + +### Pass-through billing dependencies + +Before a customer can use a pass-through SharePoint Embedded app, the consuming tenant needs: + +- A SharePoint tenant. +- A Global Administrator or SharePoint Embedded Administrator. +- A valid Azure subscription. +- A valid Azure resource group. +- Owner or contributor permissions for the admin who creates the billing relationship. +- Completed app registration and consent steps. + +No user can access any pass-through SharePoint Embedded app before valid billing is set up for the SharePoint Embedded platform in the consuming tenant. +For the customer-facing setup path, see [Guide customers through tenant setup](customer-tenant-setup-guide.md). + +## Impact on customer onboarding + +Your billing choice changes the customer handoff. + +### If you choose standard billing + +Tell the customer: + +1. Your organization owns the SharePoint Embedded consumption billing relationship. +1. The customer still needs to review and consent to the app. +1. The customer still needs to complete tenant setup and validation. +1. The customer doesn't need to configure SharePoint Embedded pay-as-you-go billing for this app. +1. Any product charges are handled through your commercial agreement. + +### If you choose pass-through billing + +Tell the customer: + +1. The app uses SharePoint Embedded pass-through billing. +1. The customer must provide an Azure subscription and resource group. +1. The customer admin must turn on billing for SharePoint Embedded apps. +1. Users can't use the app until billing is valid. +1. The customer can track usage in Azure Cost Management. + +> [!TIP] +> Put the billing model in the first page of your installation guide. +> Customer admins often need to involve both Microsoft 365 and Azure billing owners. + +## Decision checklist + +Use this checklist before you create the production container type. + +| Question | Prefer standard billing when | Prefer pass-through billing when | +| --- | --- | --- | +| Who should receive Microsoft consumption charges? | You should. | The customer should. | +| Who owns Azure cost management? | Your operations team. | The customer's operations team. | +| How simple should customer setup be? | Minimize billing steps. | Customer billing control is required. | +| How is your product priced? | SharePoint Embedded consumption is bundled. | SharePoint Embedded consumption is separate. | +| Do customers require tenant-level billing visibility? | Not required. | Required. | +| Can customer admins configure Azure billing? | Not necessary. | Required before use. | + +## Avoid common mistakes + +Avoid these publishing mistakes: + +- Creating a trial container type for production customer tenants. +- Creating a standard-billed container type when the contract expects pass-through billing. +- Creating a pass-through container type without telling customers they must configure billing. +- Omitting Azure subscription and resource group prerequisites from customer setup instructions. +- Reusing one owning application for multiple container types. +- Sending cmdlet snippets without explaining the required parameters and owner responsibilities. + +## Communicate metering boundaries + +SharePoint Embedded billing uses consumption meters. +Storage, archived storage, API transactions, and egress are the major service meters. +Customers using pass-through billing should understand that the meter usage appears through their Azure billing relationship. +For pricing details, link to the product pricing page and the current [SharePoint Embedded meters](../reference/billing-meters.md) article. + +## Record your decision + +Before you proceed, record: + +- Billing model. +- Owning application ID. +- Container type name. +- Container type ID after creation. +- Azure subscription and resource group owner, if standard billing. +- Customer billing prerequisites, if pass-through billing. +- Commercial explanation to include in the installation guide. + +Use these values in [Prepare your app for customer installation](prepare-customer-installation.md) and [Guide customers through tenant setup](customer-tenant-setup-guide.md). + +## Next steps +After you choose a billing model, prepare customer-facing tenant setup instructions: [Guide customers through tenant setup](customer-tenant-setup-guide.md). diff --git a/docs/embedded/publish/customer-tenant-setup-guide.md b/docs/embedded/publish/customer-tenant-setup-guide.md new file mode 100644 index 0000000000..89ce708c37 --- /dev/null +++ b/docs/embedded/publish/customer-tenant-setup-guide.md @@ -0,0 +1,196 @@ +--- +title: Guide customers through tenant setup +description: Give customer admins the SharePoint Embedded setup, consent, billing, and validation steps needed to install an ISV app. +ms.date: 07/13/2026 +ms.reviewer: pemtaira +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- +# Guide customers through tenant setup + +**Applies to:** ISV + + + +Use this article to build the setup guide you hand to customers who install your multitenant SharePoint Embedded app. The customer administrator is the consuming tenant admin who manages SharePoint Embedded applications registered in the Microsoft 365 tenant and the containers that hold customer content. + +> [!IMPORTANT] +> Don't send customers only an app link. SharePoint Embedded onboarding can require admin consent, container type registration, role assignment, and billing setup. Walk the customer admin through each step below. + +## Customer admin role + +Tell customers who should perform the setup. A consuming tenant admin is either a **Global Administrator** or a user assigned the **SharePoint Embedded Administrator** role. The role is available in Microsoft Entra ID and the Microsoft 365 Admin Center. Global Administrators already have these permissions. + +For the role details, see [Install a SharePoint Embedded app](../admin/install-sharepoint-embedded-app.md). + +## Customer prerequisites + +Ask the customer to confirm these prerequisites before the setup meeting or installation window. + +| Area | Customer requirement | +| --- | --- | +| Microsoft 365 | An active Microsoft 365 tenant with at least one SharePoint license. | +| Admin role | A Global Administrator or SharePoint Embedded Administrator can complete setup. | +| Users | Users who authenticate to SharePoint Embedded containers exist in Microsoft Entra ID as members or guests. | +| Consent | The customer can review and grant the Microsoft Entra permissions your app requests. | +| Billing | An Azure subscription and resource group are available if the app uses pass-through billing. | +| Support | The customer has your app ID, support contact, and validation checklist. | + +Users don't need an Office license to collaborate on Microsoft Office documents stored in a container. + +## Information to give the customer + +Provide these values in your setup guide: + +- Product name. +- Publisher name. +- Owning application ID. +- Container type ID. +- Container type name. +- Billing model. +- Microsoft Entra permissions your app requests. +- Consent instructions for your app. +- Redirect or sign-in URL the app uses. +- Support contact. +- Expected setup duration. +- Validation steps. + +For ISV preparation guidance, see [Prepare your app for customer installation](prepare-customer-installation.md). + +## Permissions your app requests + +Tell customers exactly which Microsoft Graph permissions your app needs and why. SharePoint Embedded apps install with two permissions. + +| Permission | Purpose | Admin consent | +| --- | --- | --- | +| `FileStorageContainerTypeReg.Selected` | Register your container type in the consuming tenant. | The application permission requires admin consent. The delegated permission doesn't require admin consent, but the user who registers the container type must be a SharePoint Embedded Administrator or Global Administrator. | +| `FileStorageContainer.Selected` | Read and write SharePoint Embedded container content for the container type. | The application permission requires admin consent. The delegated permission does not require admin consent. | + +## Setup overview for customers + +Use this high-level sequence in your customer guide: + +1. Assign the right admin role. +1. Review the app publisher, app IDs, and requested permissions. +1. Grant admin consent when required. +1. Register the SharePoint Embedded container type in the consuming tenant through your app's setup flow. +1. Configure pass-through billing when required. +1. Validate that the app appears to the customer admin. +1. Create or access a test container. +1. Confirm the app can perform the expected file operations. +1. Remove or keep test content according to the customer's validation policy. + +## Step 1: Assign the administrator + +Ask the customer to choose an administrator who can complete the full setup. If the customer doesn't want to use a Global Administrator, they can assign the SharePoint Embedded Administrator role. + +Tell the customer to finish role assignment before the installation window. This avoids delays when billing or validation needs elevated access. + +## Step 2: Review the application + +Ask the customer administrator to review: + +- Publisher identity. +- Application ID. +- Container type ID. +- Requested permissions (see [Permissions your app requests](#permissions-your-app-requests)). +- Data stored in SharePoint Embedded containers. +- Whether the app permits guest access. +- Support and incident response commitments. +- Billing model. + +If your installation flow is hosted in your SaaS admin portal, include screenshots or tenant-specific values in your handoff, and keep links stable so customer admins can reuse the guide for production and disaster recovery. + +## Step 3: Grant admin consent + +The customer administrator grants consent for the permissions your app requires. Document the exact consent experience for your app rather than sending a raw consent URL without explaining what it does. + +Give the customer this guidance: + +1. Sign in with the customer administrator account. +1. Open the app setup or consent experience that you provide. +1. Review the publisher and requested permissions. +1. Grant consent only when the publisher and permissions match the customer handoff. +1. Record the time and the administrator who completed consent. + +Customer admins should grant consent only to the exact app ID in your signed installation package. Consenting to a different app ID is a security risk. + +## Step 4: Register the container type + +Before the app can create and use containers, the container type must be registered in the consuming tenant. Because this flow is app-specific, link customers to your product's setup experience and to the current registration documentation. + +Ask the customer to confirm that: + +- The setup flow uses the expected owning application ID. +- The registration targets the expected container type ID. +- The registration completes in the customer's tenant. +- Any error message is captured with time, tenant, and correlation information when available. + +## Step 5: Set up billing when required + +Skip this step when your app uses standard billing. If your app uses pass-through billing, tell the customer that SharePoint Embedded billing must be configured before users can access the app. + +The customer needs a valid Azure subscription and resource group. A Global Administrator sets up billing in the Microsoft 365 admin center, and the admin who creates the billing relationship also needs the Owner or Contributor role on the Azure subscription. Then set up billing: + +1. Open the [Microsoft 365 admin center](https://admin.microsoft.com/). +1. Go to **Setup**. +1. In **Files and Content**, select **Automate Content with Microsoft Syntex**. +1. Select **Go to Syntex settings**. +1. Under **Syntex services for**, select **Apps**. +1. Select **SharePoint Embedded**. +1. Follow the instructions on the **SharePoint Embedded** page to turn on SharePoint Embedded apps. + +> [!WARNING] +> If pass-through billing is turned off or the linked Azure subscription is disconnected, users can no longer create new containers. Existing containers and their content remain accessible. + +## Step 6: Validate administration visibility + +After consent, registration, and billing are complete, ask the customer admin to confirm the app can be managed. Admins can use SharePoint admin center and other administrative tools to manage SharePoint Embedded applications and containers. + +Customer admins can: + +- Enumerate applications in the tenant. +- Enumerate containers of an application. +- View container details. +- View active and deleted containers in admin experiences. +- Manage sensitivity labels and sharing settings where supported. +- Review security and compliance behavior. + +For deeper validation steps, see [Validate customer app installation](validate-customer-installation.md). + +## Customer setup checklist + +Give customers a checklist they can sign off. + +- [ ] The assigned admin has the Global Administrator or SharePoint Embedded Administrator role. +- [ ] The app ID and publisher match the ISV handoff. +- [ ] Admin consent is granted for the expected app. +- [ ] The container type is registered in the consuming tenant. +- [ ] Pass-through billing is configured, if required. +- [ ] A test user can sign in to the app. +- [ ] A test container can be created or opened. +- [ ] A test document can be uploaded, read, and deleted. +- [ ] The customer admin can view the app or containers in administration tools. +- [ ] Validation notes and support contacts are recorded. + +## Troubleshooting during setup + +Use this table to route early setup problems. + +| Symptom | Likely area | Action | +| --- | --- | --- | +| Customer can't grant consent | Microsoft Entra permissions | Confirm the admin role and app ID. | +| App can't create containers | Registration or permissions | Confirm container type registration and consent. | +| Users can't access a pass-through app | Billing | Confirm SharePoint Embedded billing is turned on in the consuming tenant. | +| Admin can't manage the app | Role or tooling | Confirm the SharePoint Embedded Administrator role and administrative tool access. | +| App works for members but not guests | Identity or sharing | Confirm guest identities and customer sharing policies. | + +## Next steps + +After setup, validate the installation with the customer administrator: [Validate customer app installation](validate-customer-installation.md). diff --git a/docs/embedded/publish/prepare-customer-installation.md b/docs/embedded/publish/prepare-customer-installation.md new file mode 100644 index 0000000000..6e2d0b330d --- /dev/null +++ b/docs/embedded/publish/prepare-customer-installation.md @@ -0,0 +1,221 @@ +--- +title: Prepare Your App for Customer Installation +description: Prepare a multitenant SharePoint Embedded app, container type, permissions, billing choice, and admin handoff for customer tenants. +ms.date: 07/13/2026 +ms.reviewer: stpuceli +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- +# Prepare your app for customer installation + +**Applies to:** ISV + + + +Use this article before you send a SharePoint Embedded application to a customer tenant. +SharePoint Embedded is API-only, so customer installation depends on container type registration, consent, permissions, and billing configuration instead of a traditional SharePoint site deployment. +Your goal is to give the customer administrator a complete, repeatable onboarding package. + +> [!IMPORTANT] +> Prepare production container types in your developer tenant before customer onboarding. +> Trial container types are for exploration and can't be deployed to other consuming tenants. + +## Customer installation flow + +A customer-ready SharePoint Embedded application usually follows this sequence: + +1. Choose the application model and tenant model for your product. +1. Register or configure the owning application in your developer tenant. +1. Create a standard production container type for that owning application. +1. Choose standard billing or pass-through billing for the container type. +1. Prepare Microsoft Entra consent information for the customer's admin. +1. Give the customer tenant setup instructions. +1. Ask the customer to complete container type registration, admin consent, and billing setup when required. +1. Validate that the application can create and use containers in the consuming tenant. + +For the next decision in the publishing path, see [Choose a billing model for your app](choose-app-billing-model.md). + +## Prerequisites + +Before you prepare customer installation materials, confirm the following items in your developer tenant. + +| Area | Requirement | +| --- | --- | +| Microsoft 365 tenant | An active SharePoint tenant is available. | +| Admin role | A Global Administrator or SharePoint Embedded Administrator can manage container types. | +| Application | You have a Microsoft Entra application that will own the container type. | +| Container type | You have a production standard container type, not a trial container type. | +| Billing decision | You know whether the app uses standard or pass-through billing. | +| Customer package | You can provide app IDs, redirect URLs, permissions, support contacts, and validation steps. | + +## Understand the developer responsibility + +The developer manages the SharePoint Embedded application and the container types that back it. +A container type defines the relationship between a SharePoint Embedded application and the containers that store content. +Each container type is associated with an owning application. +The owning application has default full access to containers of that type. + +Developers can use the SharePoint Embedded Visual Studio Code extension or Microsoft Graph `fileStorageContainerType` APIs to create, list, update, and delete container types. Graph creation is delegated-only and requires no admin role. For details, see [Create and configure a container type](../build/create-container-type.md). + +For model and tenant decisions, see [Choose an app model](../plan/choose-app-model.md). + +## Package the application configuration + +Give customers the exact identifiers and URLs they need to review and approve the app. +Don't ask a customer admin to infer these values from code. + +Include the following information in your installation package: + +- Product name and publisher name. +- Owning application ID. +- Container type ID, after it has been created. +- Container type name. +- Billing model: standard or pass-through. +- Application redirect URL, if configured on the container type. +- Customer-facing sign-in URL. +- Customer-facing support URL. +- List of Microsoft Entra permissions requested by the app. +- Whether the app uses delegated permissions, application permissions, or both. +- Whether a guest application requires access to the owning application. +- Data residency, retention, and support boundaries for your app. +- Validation steps the customer can run after setup. + +## Confirm the owning app and container type relationship + +Every production container type must have an owning application. +A single owning application can own only one container type at a time. +Don't reuse one owning application across multiple production container types. +If you need multiple isolation or billing boundaries, plan separate owning applications and container types. + +Create the production container type with the SharePoint Embedded Visual Studio Code extension or the Microsoft Graph [Create fileStorageContainerType](/graph/api/filestorage-post-containertypes) API. Microsoft Graph creation is delegated-only and doesn't require an admin role. + +## Configure a production container type + +Create a standard container type for customer use. +SharePoint Embedded supports two production billing choices: + +- Standard billing, where the developer tenant is billed. +- Pass-through billing, where the consuming tenant is billed after registration and setup. + +For standard billing, the developer must provide an Azure subscription, resource group, and region when attaching billing information. +For pass-through billing, the developer creates the container type with pass-through billing enabled, and the customer admin later sets up billing in the consuming tenant. + +> [!IMPORTANT] +> Standard and pass-through billing choices can't be converted after the container type is created. +> If you choose the wrong billing model, create a new container type with the intended billing model. + +## Decide what the customer must do + +Your customer handoff should clearly separate ISV tasks from customer administrator tasks. + +### ISV tasks + +Complete these tasks before the customer starts setup: + +1. Create or configure the owning Microsoft Entra application. +1. Create the production container type. +1. Configure container type settings that apply to all containers. +1. Document Microsoft Entra consent requirements. +1. Document whether pass-through billing is required. +1. Prepare the validation checklist. +1. Provide escalation contacts for installation failures. + +### Customer admin tasks + +Ask the customer administrator to complete these tasks in their tenant: + +1. Review the app publisher, permissions, and data handling documentation. +1. Grant admin consent when required. +1. Register the container type in the consuming tenant through the app's registration flow. +1. Set up billing if the app uses pass-through billing. +1. Validate that the app appears in tenant administration experiences. +1. Confirm that containers can be created and managed. + +For customer-facing steps, see [Guide customers through tenant setup](customer-tenant-setup-guide.md). + +## Prepare permission guidance + +Document the permissions your app requests and why each permission is needed. +Use product-specific descriptions instead of copying permission display names without context. + +At minimum, a SharePoint Embedded app installed on a consuming tenant requests these Microsoft Graph permissions: + +| Permission | Type | Purpose | +| --- | --- | --- | +| [`FileStorageContainerTypeReg.Selected`](/graph/permissions-reference#filestoragecontainertyperegselected) | Delegated or application | Register your container type in the consuming tenant. With the delegated permission, the user performing registration must be a [SharePoint Embedded Administrator](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) or Global Administrator. The application permission requires admin consent; the delegated permission doesn't. | +| [`FileStorageContainer.Selected`](/graph/permissions-reference#filestoragecontainerselected) | Delegated or application | Interact with SharePoint Embedded content for the container type. The application permission requires admin consent; the delegated permission does not. | + +> [!IMPORTANT] +> Using SharePoint Embedded on behalf of a user (delegated access) is the recommended approach. It improves both the security and the auditability of actions performed by your application. + +For single-tenant apps, you can [construct an admin consent URL](/entra/identity-platform/v2-admin-consent#request-the-permissions-from-a-directory-admin) and provide it to the tenant's Microsoft Entra administrator, for example: + +```http +https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id={client_id}&redirect_uri={redirect_uri} +``` + +Ensure your app's [redirect URI](/entra/identity-platform/reply-url) can handle admin consent flows. For the full permission model, see [Authentication and authorization](../build/configure-authentication-authorization.md). + +If your app uses guest application access, explain how the consuming tenant admin can view guest application permissions in administrative tools. + +> [!CAUTION] +> Don't hide optional or elevated permissions in an installation script. +> Customer admins should be able to review the requested permissions before they grant consent. + +## Prepare billing guidance + +Tell customers which billing model applies before they install the app. + +For standard billing: + +- Explain that your developer tenant owns the SharePoint Embedded consumption billing relationship. +- Tell the customer whether SharePoint Embedded usage is included in your commercial agreement. +- Confirm that the customer doesn't need to configure an Azure subscription for SharePoint Embedded billing. + +For pass-through billing: + +- Explain that consumption charges are billed to the consuming tenant. +- Tell the customer that no user can access pass-through SharePoint Embedded apps until valid billing is configured. +- Send the customer to [Guide customers through tenant setup](customer-tenant-setup-guide.md) and [Install a SharePoint Embedded app](../admin/install-sharepoint-embedded-app.md). + +## Prepare admin handoff materials + +Create a concise admin handoff packet that includes: + +- Installation overview. +- Publisher and app identity information. +- Security and compliance summary. +- Billing model summary. +- Microsoft Entra consent steps. +- Tenant setup steps. +- Validation checklist. +- Rollback or uninstall guidance. +- Support contacts and expected response times. + +Keep the handoff specific to one product and one container type. +If you publish multiple products, provide a separate handoff for each app. + +## Provide a validation checklist + +Include a checklist the customer can complete with you after installation: + +- The customer admin can identify the SharePoint Embedded application in the tenant. +- The customer admin has granted the expected consent. +- Pass-through billing is enabled when required. +- The application can create a test container. +- The application can upload, read, and delete test content. +- The customer admin can view container details. +- External sharing behavior matches the customer's policy. +- The test data is removed after validation. + +For detailed validation, see [Validate customer app installation](validate-customer-installation.md). + +## Next steps + +Choose the correct billing option before you send installation instructions to a customer: [Choose a billing model for your app](choose-app-billing-model.md). diff --git a/docs/embedded/publish/validate-customer-installation.md b/docs/embedded/publish/validate-customer-installation.md new file mode 100644 index 0000000000..cc13219e21 --- /dev/null +++ b/docs/embedded/publish/validate-customer-installation.md @@ -0,0 +1,241 @@ +--- +title: Validate customer app installation +description: Validate SharePoint Embedded container type registration, permissions, containers, and billing after a customer installs an ISV app. +ms.date: 07/13/2026 +ms.reviewer: dilucesr +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- +# Validate customer app installation + +**Applies to:** ISV / developer + + + +Use this article after a customer installs a SharePoint Embedded app. +Validation confirms that the container type registration, consent, billing, administration visibility, and basic container operations are working. +Run these checks with the customer admin before you announce the app to users. + +> [!IMPORTANT] +> Validate in the customer tenant that will run the production workload. +> A successful test in your developer tenant doesn't prove that the customer tenant is registered, consented, or billed correctly. + +## Validation goals + +Complete these goals before closing customer onboarding: + +1. Confirm that the app and container type are registered in the customer tenant. +1. Confirm that the expected permissions are granted. +1. Confirm that billing is valid for pass-through apps. +1. Confirm that the app can create or access a container. +1. Confirm that the customer admin can view the app and container. +1. Confirm that content operations work for a test user. +1. Confirm that common failure modes have been ruled out. + +For customer setup steps, see [Guide customers through tenant setup](customer-tenant-setup-guide.md). + +## People involved + +Validation usually needs both ISV and customer roles. + +| Role | Responsibility | +| --- | --- | +| ISV developer | Supplies expected app IDs, container type ID, app behavior, and support troubleshooting. | +| Customer Global Administrator or SharePoint Embedded Administrator | Confirms SharePoint Embedded app setup, billing, and administration visibility. | +| Customer Azure billing owner or contributor | Helps resolve pass-through billing setup issues. | +| Customer test user | Signs in and performs app-level document actions. | + +## Before you start + +Collect these values: + +- Customer tenant name or ID. +- Owning application ID. +- Application ID for guest apps, if your app uses them. +- Container type ID. +- Container type name. +- Billing model. +- Expected sharing behavior. +- Support ticket or onboarding record. + +> [!TIP] +> Keep the validation record with the customer's installation package. +> It helps future support teams distinguish setup issues from product regressions. + +## Step 1: Confirm container type registration + +Confirm that the container type is registered in the consuming tenant. +An app can't create or interact with containers until its container type is registered in that tenant. +Use your product's setup portal or registration flow to show the registration state. + +Ask the customer admin to use the [SharePoint admin center](https://go.microsoft.com/fwlink/?linkid=2185219) to verify that your SharePoint Embedded app is listed under the installed apps tab in the Active apps page under SharePoint Embedded. The customer admin may verify details of your SharePoint Embedded app such as: + +- The owning application ID. +- The container type ID. + +If registration isn't complete, return to [Guide customers through tenant setup](customer-tenant-setup-guide.md). + +## Step 2: Verify permissions + +To verify that your app is properly installed on the customer tenant: + +1. Using the owning app, request an access token for the Microsoft Graph `.default` scope in the consuming tenant. +1. Verify that the access token includes `FileStorageContainer.Selected` and `FileStorageContainerTypeReg.Selected` in either the `scp` claim (for access on behalf of a user) or `roles` claim (for access without a user). +1. Use the token to [get the registration for your container type in the tenant](/graph/api/filestoragecontainertyperegistration-get). If a registration is returned, it means that your SharePoint Embedded app is installed correctly. + +> [!TIP] +> You may also validate that your guest apps are properly set up by requesting an access token for the Microsoft Graph `.default` scope in the consuming tenant and validating that the scopes/roles you expect are present and that you can use the token to interact with content. Only the owning app can access a container type registration in a tenant. + +Confirm that the customer granted the expected permissions and no unexpected app ID was used. + +For most customer installations, validate at least these permissions: + +| Permission | Typical use | Validation note | +| --- | --- | --- | +| `FileStorageContainerTypeReg.Selected` | Register the container type in the consuming tenant. | The app can request this as delegated or application permission. If delegated registration is used, the user performing registration must be a SharePoint Embedded Administrator or Global Administrator. | +| `FileStorageContainer.Selected` | Access containers and content for the installed app. | The application permission requires admin consent; the delegated permission does not. Confirm the grant matches the app behavior the customer approved. | + +Validate the following items: + +- Admin consent was granted by an authorized customer admin for application permissions when required. +- The consented app ID matches the ISV installation package. +- The permission set includes the expected registration and content permissions for the app model. +- Guest application permissions are present when required. +- Delegated and app-only behavior matches your design. +- Test users are present in Microsoft Entra ID as members or guests. + +> [!CAUTION] +> Don't continue validation if the app ID or publisher doesn't match the installation package. +> Stop and resolve the consent mismatch first. + +If the owning app or any guest app is missing permissions, return to [Guide customers through tenant setup](customer-tenant-setup-guide.md). + +## Step 3: Verify billing status + +Billing validation depends on the selected billing model. + +### Standard billing + +For standard billing, confirm internally that your developer tenant billing relationship is active. +The customer doesn't need to configure a SharePoint Embedded billing profile for your app. +Still tell the customer how SharePoint Embedded consumption is handled for your application. + +Check: + +- The app is documented as standard billed. +- Your operations team can monitor consumption. +- The customer handoff doesn't ask the customer to configure pass-through billing. + +### Pass-through billing + +For pass-through billing, no user can access the app until the customer sets up valid billing. +Ask the customer admin to confirm billing in the [Microsoft 365 admin center](https://admin.cloud.microsoft). + +Check: + +- A valid Azure subscription is connected. +- A valid resource group is selected. +- The setup was completed for SharePoint Embedded apps. +- The customer billing admin has owner or contributor permissions where required. +- The customer understands that disabling billing interrupts user access. + +For billing model guidance, see [Choose a billing model for your app](choose-app-billing-model.md). + +## Step 4: Create or open a test container + +Use your app's normal product flow to create or open a test container in the customer tenant. +Don't use a hidden validation path that bypasses the same permissions and container type registration used by production users. + +Validate: + +- The app can create a container of the expected container type. +- The app can open an existing test container. +- The app can upload a small test document. +- The app can read the test document. +- The app can update or delete the test document if those actions are part of the product. +- The app reports errors in a way the customer and ISV support can troubleshoot. + +> [!WARNING] +> Avoid destructive validation in an existing production container. +> Use a clearly identified test container and remove test content when validation is complete. + +## Step 5: Verify container administration + +Customer admins can use the [SharePoint admin center](https://go.microsoft.com/fwlink/?linkid=2185219) to administer their installation of your SharePoint Embedded app and its containers: + +- Get details of containers for the SharePoint Embedded application. +- View details of a specific container. +- View containers sorted by storage. +- Set a sensitivity label where applicable. +- Manage deleted containers where applicable. +- Restore or permanently delete test containers only when intended. + +For customer administration guidance, see [Manage containers in SharePoint admin center](../admin/manage-containers-sharepoint-admin-center.md). + +## Step 6: Verify sharing and compliance expectations + +SharePoint Embedded uses Microsoft 365 security and compliance capabilities. +Ask the customer admin to validate the settings that matter for the app: + +- External sharing behavior. +- Guest user access. +- Sensitivity label expectations. +- Retention or deletion expectations. +- Audit or compliance review requirements. +- Customer policy exceptions, if any. + +If the app requires external collaboration, confirm that customer tenant sharing policies allow the intended behavior. +If sharing is restricted, document the product impact before users start using the app. + +## Common failure modes + +Use this table during onboarding. + +| Failure mode | What to check | Where to link | +| --- | --- | --- | +| App doesn't appear for admin | Container type registration and app ID | [Admin overview](../admin/admin-overview.md) | +| Consent error | Admin role and expected permissions | [Grant admin consent](../admin/grant-admin-consent-permissions.md) | +| Pass-through app inaccessible | Billing setup and Azure subscription | [Guide customers through tenant setup](customer-tenant-setup-guide.md) | +| Container create fails | Registration, permissions, and billing | [Install a SharePoint Embedded app](../admin/install-sharepoint-embedded-app.md) | +| Guest user can't access content | Guest identity and sharing policy | [Grant admin consent and permissions](../admin/grant-admin-consent-permissions.md) | +| Admin tools fail | Role assignment and administrative tool access | [Admin overview](../admin/admin-overview.md) | +| Billing was disconnected | New container creation is blocked; existing containers remain accessible | [Set up billing in Microsoft 365 admin center](../admin/setup-billing-microsoft-365-admin-center.md) | + +## Validation checklist + +Use this checklist as the final customer signoff. + +- [ ] Customer admin granted admin consent for your app. +- [ ] Container type registration is complete. +- [ ] Customer admin sees your SharePoint Embedded app in SharePoint admin center. +- [ ] Billing is valid or not required for the customer tenant. +- [ ] Test user can sign into your app. +- [ ] Test container can be created or opened. +- [ ] Test file operations work. +- [ ] Customer admin can view the app or container in administration tools. +- [ ] Sharing and compliance expectations are documented. +- [ ] Test content is removed or retained by agreement. +- [ ] Support handoff is complete. + +## After validation + +After validation succeeds: + +1. Record the date, tenant, app ID, and container type ID. +1. Save the billing model and customer setup result. +1. Share the validation record with the customer. +1. Move the app to the next release or rollout step. + +If validation fails, keep the customer in the setup phase and resolve the failure before broad user access. + +## Next steps + +- [Admin overview](../admin/admin-overview.md) +- [Install a SharePoint Embedded app](../admin/install-sharepoint-embedded-app.md) +- [Troubleshooting](../reference/troubleshooting.md) diff --git a/docs/embedded/reference/audit-events.md b/docs/embedded/reference/audit-events.md new file mode 100644 index 0000000000..6c5fabc149 --- /dev/null +++ b/docs/embedded/reference/audit-events.md @@ -0,0 +1,69 @@ +--- +title: Audit events +description: Reference for SharePoint Embedded container type audit events in the Microsoft Purview unified audit log. +ms.date: 07/10/2026 +ms.reviewer: pemtaira +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Audit events + +**Applies to:** Compliance administrator + + + +SharePoint Embedded container type and container type registration operations are captured in the Microsoft 365 unified audit log through [Microsoft Purview](/purview/audit-solutions-overview). These events let compliance administrators and developers track changes to container type definitions and registrations in consuming tenants. File and folder activity inside containers is captured by standard SharePoint file audit events. + +For step-by-step investigation guidance, see [Review audit events](../admin/review-audit-events.md). + +## Container type activities + +These events are logged when a container type is created, updated, or deleted. They use the **Workload** value **SharePoint** and appear under the **SharePoint Embedded Container Type activities** category in Microsoft Purview audit. + +| Friendly name | Operation | Description | +| --- | --- | --- | +| Created container type | `ContainerTypeCreated` | A new SharePoint Embedded container type definition was created. | +| Deleted container type | `ContainerTypeDeleted` | A SharePoint Embedded container type owned by the tenant was deleted. | +| Updated container type | `ContainerTypeUpdated` | Properties of a container type, such as name or configuration, were changed. | +| Updated container type owners | `ContainerTypeOwnersUpdated` | Owners were added to or removed from a container type. | + +For the full list of audit activities, see [Audit log activities](/purview/audit-log-activities#sharepoint-embedded-container-type-activities). + +## Container type registration activities + +These events are logged when a container type registration is created, updated, or deleted in a consuming tenant. A registration lets a SharePoint Embedded application operate in a given tenant. They use the **Workload** value **SharePoint** and appear under the **SharePoint Embedded Container Type Registration activities** category in Microsoft Purview audit. + +| Friendly name | Operation | Description | +| --- | --- | --- | +| Created container type registration | `ContainerTypeRegistrationCreated` | A SharePoint Embedded container type registration was created in a tenant. | +| Deleted container type registration | `ContainerTypeRegistrationDeleted` | A SharePoint Embedded container type registration was deleted from a tenant. | +| Updated container type registration | `ContainerTypeRegistrationUpdated` | A SharePoint Embedded container type registration was updated in a tenant. | + +For the full list of audit activities, see [Audit log activities](/purview/audit-log-activities#sharepoint-embedded-container-type-registration-activities). + +## Properties + +Container type and container type registration audit events include the `ContainerTypeId` property to identify the relevant container type. Unlike container-level file events, they don't include `ContainerInstanceId` because they apply at the type level, not to an individual container instance. + +Container type and container type registration audit events use the SharePoint base schema. For the full schema definition and enum values, see the [Office 365 Management Activity API schema](/office/office-365-management-api/office-365-management-activity-api-schema#sharepoint-base-schema). + +## Search for events + +Use the [Microsoft Purview audit log search](/purview/audit-search) and set the activity category filter to **SharePoint Embedded Container Type activities** or **SharePoint Embedded Container Type Registration activities**. You can also search with PowerShell: + +```powershell +Search-UnifiedAuditLog -Operations ContainerTypeCreated,ContainerTypeDeleted,ContainerTypeUpdated,ContainerTypeOwnersUpdated,ContainerTypeRegistrationCreated,ContainerTypeRegistrationDeleted,ContainerTypeRegistrationUpdated -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) +``` + +## Related content + +- [Review audit events](../admin/review-audit-events.md) +- [Apply security and compliance controls](../admin/apply-security-compliance-controls.md) +- [Search the audit log](/purview/audit-search) diff --git a/docs/embedded/reference/billing-meters.md b/docs/embedded/reference/billing-meters.md new file mode 100644 index 0000000000..a248ab22d2 --- /dev/null +++ b/docs/embedded/reference/billing-meters.md @@ -0,0 +1,63 @@ +--- +title: Billing Meters +description: Reference for SharePoint Embedded pay-as-you-go billing meters and pricing resources. +ms.date: 07/13/2026 +ms.reviewer: pemtaira +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Billing meters + +**Applies to:** Billing administrator + + + +SharePoint Embedded uses pay-as-you-go (PAYG) billing through an Azure subscription. SharePoint Embedded has four billing meters. Both standard billing container types and pass-through billing container types use the same meters. + +For setup guidance, see [choose a billing model](../plan/choose-billing-model.md). For monitoring, see [monitor usage, billing, and cost](../admin/monitor-usage-billing-cost.md). + +| Meter | Unit | What is metered | Notes | +| --- | --- | --- | --- | +| Storage | $/GB | Files, documents, metadata, versions, recycle bin content, and deleted container collection content, in both active and archived states. | Storage is based on data stored in SharePoint Embedded. | +| Archived Storage | $/GB | Storage consumed by archived containers within a tenant. | Archiving moves data to the cold storage tier, which offers lower storage costs than active storage. | +| API Transactions | $/Transactions | Each Microsoft Graph call made explicitly by the SharePoint Embedded application. | Internal service calls, such as eDiscovery queries and admin actions in SharePoint admin center or SharePoint PowerShell, aren't charged as application transactions. | +| Egress | $/GB | Data that exits the SharePoint Embedded platform, such as documents downloaded to a customer's client device or data transferred to a server operated by the customer. Charges are based on total volume transferred out (GB). | Downloads from the SharePoint Embedded application server to Office Desktop clients or Web Application Companion aren't charged as egress. | +| Pay-as-you-go message (private preview) | Message | SharePoint Embedded agent interactions. | SharePoint Embedded agents use the Copilot Studio meter. Each agent interaction uses 12 messages. | + +## Storage + +Storage consumption includes files and documents plus their metadata and versions, in both active and archived states. Content in the recycle bin and deleted container collection also contributes to storage consumption. + +## Archived storage + +The Archived Storage meter measures storage consumed by archived containers within a tenant. Archiving a container moves its data to the cold storage tier, which offers lower storage costs compared to active storage. Archived content is still billed, but at the archived-storage rate. + +## API transactions + +Each explicit Microsoft Graph request from the SharePoint Embedded application counts as one transaction. For examples of container APIs, see the [fileStorageContainer resource](/graph/api/resources/filestoragecontainer). + +## Egress + +Egress is data that exits the SharePoint Embedded platform, such as a document downloaded to a customer's client device or data transferred to a server operated by the customer. Egress charges are based on the total volume of data transferred out, measured in GB. Some Microsoft-integrated transfers are exempt, including downloads to Office Desktop clients and Web Application Companion. + +## Agent message meter + +The private preview SharePoint Embedded agent meter uses the Copilot Studio message meter. One SharePoint Embedded agent interaction uses 12 messages: two for generative answer and 10 for tenant graph grounding. + +## Pricing links + +- [SharePoint Embedded product page](https://adoption.microsoft.com/sharepoint/embedded/) +- [Azure Cost Management](https://portal.azure.com/) +- [Monitor usage, billing, and cost](../admin/monitor-usage-billing-cost.md) + +## Related resources + +- [Choose a billing model](../plan/choose-billing-model.md) +- [Monitor usage, billing, and cost](../admin/monitor-usage-billing-cost.md) diff --git a/docs/embedded/reference/glossary.md b/docs/embedded/reference/glossary.md new file mode 100644 index 0000000000..7b0a6ab423 --- /dev/null +++ b/docs/embedded/reference/glossary.md @@ -0,0 +1,39 @@ +--- +title: Glossary +description: Concise definitions of common SharePoint Embedded terms and concepts. +ms.date: 06/25/2026 +ms.reviewer: pemtaira +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Glossary + +**Applies to:** Developer + + + +| Term | Definition | +| --- | --- | +| Container | A File Storage Container: the basic SharePoint Embedded storage unit and security and compliance boundary for files. See [SharePoint Embedded overview](../overview.md). | +| Container type | A SharePoint Embedded resource that defines the relationship, access privileges, billing accountability, and behavior for a set of containers. See [container types](../plan/container-types-containers.md). | +| Developer tenant | The tenant that develops or owns the SharePoint Embedded application and creates its container type. See [container types](../plan/container-types-containers.md). | +| Consuming tenant | The Microsoft 365 tenant where a SharePoint Embedded app is used and where containers and content are stored. See [app architecture](../plan/app-tenant-architecture.md). | +| Container type registration | Registration of a container type in a consuming tenant so the app can perform allowed operations against containers of that type. See [register container type application permissions](../build/register-application-permissions.md). | +| Single-tenant app | An application model intended for use in one tenant, commonly for enterprise line-of-business scenarios. See [choose an app model](../plan/choose-app-model.md). | +| Multitenant app | An application model intended for use across customer tenants, commonly for ISV scenarios. See [choose an app model](../plan/choose-app-model.md). | +| Standard billing | A billing model where consumption charges are billed to the tenant that owns or develops the application. See [choose a billing model](../plan/choose-billing-model.md). | +| Pass-through (customer) billing | A billing model where consumption charges are billed directly to the consuming tenant registered to use the app. See [choose a billing model](../plan/choose-billing-model.md). | +| Owning application | The Microsoft Entra ID application registration strongly coupled with a container type; each owning app can own one container type at a time. See [app architecture](../plan/app-tenant-architecture.md). | +| Partition | The API-only SharePoint storage partition created in a consumer's Microsoft 365 tenant for SharePoint Embedded app documents. See [SharePoint Embedded overview](../overview.md). | + +## Related resources + +- [What is SharePoint Embedded?](../overview.md) +- [Understand app and tenant architecture](../plan/app-tenant-architecture.md) diff --git a/docs/embedded/reference/graph-api-links.md b/docs/embedded/reference/graph-api-links.md new file mode 100644 index 0000000000..43564bf894 --- /dev/null +++ b/docs/embedded/reference/graph-api-links.md @@ -0,0 +1,172 @@ +--- +title: Microsoft Graph API reference links +description: Curated Microsoft Graph v1.0 reference links for SharePoint Embedded containers, container types, and files. +ms.date: 07/08/2026 +ms.reviewer: pemtaira +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Microsoft Graph API reference links + +**Applies to:** Developer + + + +SharePoint Embedded applications store and manage containers and container content through Microsoft Graph. This page links the generally available (v1.0) Graph APIs for SharePoint Embedded. For task guidance, see [create and manage containers](../build/create-manage-containers.md) and [manage files](../build/manage-files.md). + +> [!NOTE] +> The `fileStorageContainerType`, `fileStorageContainerTypeRegistration`, and application permission grant APIs are generally available on the **v1.0** Microsoft Graph endpoint. + +## Container APIs + +| Operation | Microsoft Graph reference | +| --- | --- | +| `fileStorageContainer` resource | [fileStorageContainer resource type](/graph/api/resources/filestoragecontainer) | +| Create container | [Create fileStorageContainer](/graph/api/filestoragecontainer-post) | +| Get container | [Get fileStorageContainer](/graph/api/filestoragecontainer-get) | +| List containers | [List containers](/graph/api/filestorage-list-containers) | +| Update container | [Update fileStorageContainer](/graph/api/filestoragecontainer-update) | +| Delete container | [Delete fileStorageContainer](/graph/api/filestorage-delete-containers) | +| Activate container | [fileStorageContainer: activate](/graph/api/filestoragecontainer-activate) | +| Lock container | [fileStorageContainer: lock](/graph/api/filestoragecontainer-lock) | +| Unlock container | [fileStorageContainer: unlock](/graph/api/filestoragecontainer-unlock) | +| Get container drive | [Get drive for fileStorageContainer](/graph/api/filestoragecontainer-get-drive) | +| List deleted containers | [List deleted containers](/graph/api/filestorage-list-deletedcontainers) | +| Restore deleted container | [fileStorageContainer: restore](/graph/api/filestoragecontainer-restore) | +| Permanently delete container | [fileStorageContainer: permanentDelete](/graph/api/filestoragecontainer-permanentdelete) | +| Remove a deleted container | [Remove deleted fileStorageContainer](/graph/api/filestorage-delete-deletedcontainers) | + +## Container permission APIs + +| Operation | Microsoft Graph reference | +| --- | --- | +| List permissions | [List fileStorageContainer permissions](/graph/api/filestoragecontainer-list-permissions) | +| Get permission | [Get fileStorageContainer permission](/graph/api/filestoragecontainer-get-permissions) | +| Create permission | [Create fileStorageContainer permission](/graph/api/filestoragecontainer-post-permissions) | +| Update permission | [Update fileStorageContainer permission](/graph/api/filestoragecontainer-update-permissions) | +| Upsert permissions | [Upsert permissions](/graph/api/filestoragecontainer-patch-permissions) | +| Delete permission | [Delete permissions](/graph/api/filestoragecontainer-delete-permissions) | + +## Container metadata APIs + +Container columns define the metadata schema. Custom properties store key-value metadata on a container. + +| Operation | Microsoft Graph reference | +| --- | --- | +| List columns | [List columns](/graph/api/filestoragecontainer-list-columns) | +| Get column | [Get column](/graph/api/filestoragecontainer-get-column) | +| Create column | [Create column](/graph/api/filestoragecontainer-post-columns) | +| Update column | [Update column](/graph/api/filestoragecontainer-update-column) | +| Delete column | [Delete column](/graph/api/filestoragecontainer-delete-column) | +| List custom properties | [List custom properties](/graph/api/filestoragecontainer-list-customproperty) | +| Add custom properties | [Add custom properties](/graph/api/filestoragecontainer-post-customproperty) | +| Update custom properties | [Update custom properties](/graph/api/filestoragecontainer-update-customproperty) | +| Delete custom properties | [Delete custom properties](/graph/api/filestoragecontainer-delete-customproperty) | + +## Container recycle bin APIs + +| Operation | Microsoft Graph reference | +| --- | --- | +| List recycle bin items | [List recycleBinItem](/graph/api/filestoragecontainer-list-recyclebinitem) | +| Restore recycle bin item | [Restore recycleBinItem](/graph/api/filestoragecontainer-restore-recyclebinitem) | +| Delete recycle bin item | [Delete recycleBinItem](/graph/api/filestoragecontainer-delete-recyclebinitem) | +| Update recycle bin settings | [Update recycleBinSettings](/graph/api/filestoragecontainer-update-recyclebinsettings) | + +## SharePoint group APIs + +| Operation | Microsoft Graph reference | +| --- | --- | +| List SharePoint groups | [List sharePointGroups](/graph/api/filestoragecontainer-list-sharepointgroups) | +| Create SharePoint group | [Create sharePointGroup](/graph/api/filestoragecontainer-post-sharepointgroups) | +| Delete SharePoint group | [Delete sharePointGroup](/graph/api/filestoragecontainer-delete-sharepointgroups) | + +## Container migration APIs + +| Operation | Microsoft Graph reference | +| --- | --- | +| Provision migration containers | [fileStorageContainer: provisionMigrationContainers](/graph/api/filestoragecontainer-provisionmigrationcontainers) | +| Create migration job | [Create sharePointMigrationJob](/graph/api/filestoragecontainer-post-migrationjobs) | + +## Container type APIs + +| Operation | Microsoft Graph reference | +| --- | --- | +| `fileStorageContainerType` resource | [fileStorageContainerType resource type](/graph/api/resources/filestoragecontainertype) | +| List container types | [List containerTypes](/graph/api/filestorage-list-containertypes) | +| Create container type | [Create fileStorageContainerType](/graph/api/filestorage-post-containertypes) | +| Get container type | [Get fileStorageContainerType](/graph/api/filestoragecontainertype-get) | +| Update container type | [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) | +| Delete container type | [Delete fileStorageContainerType](/graph/api/filestorage-delete-containertypes) | + +## Container type registration APIs + +Register a container type in a consuming tenant, then grant application permissions on that registration. + +| Operation | Microsoft Graph reference | +| --- | --- | +| `fileStorageContainerTypeRegistration` resource | [fileStorageContainerTypeRegistration resource type](/graph/api/resources/filestoragecontainertyperegistration) | +| List registrations | [List containerTypeRegistrations](/graph/api/filestorage-list-containertyperegistrations) | +| Create registration | [Create fileStorageContainerTypeRegistration](/graph/api/filestorage-post-containertyperegistrations) | +| Get registration | [Get fileStorageContainerTypeRegistration](/graph/api/filestoragecontainertyperegistration-get) | +| Update registration | [Update fileStorageContainerTypeRegistration](/graph/api/filestoragecontainertyperegistration-update) | +| Delete registration | [Delete fileStorageContainerTypeRegistration](/graph/api/filestorage-delete-containertyperegistrations) | +| List application permission grants | [List applicationPermissionGrants](/graph/api/filestoragecontainertyperegistration-list-applicationpermissiongrants) | +| Create application permission grant | [Create fileStorageContainerTypeAppPermissionGrant](/graph/api/filestoragecontainertyperegistration-post-applicationpermissiongrants) | +| Get application permission grant | [Get fileStorageContainerTypeAppPermissionGrant](/graph/api/filestoragecontainertypeapppermissiongrant-get) | +| Update application permission grant | [Update fileStorageContainerTypeAppPermissionGrant](/graph/api/filestoragecontainertypeapppermissiongrant-update) | +| Delete application permission grant | [Delete fileStorageContainerTypeAppPermissionGrant](/graph/api/filestoragecontainertyperegistration-delete-applicationpermissiongrants) | + +## Drive and driveItem APIs + +All file system objects in a `fileStorageContainer` are returned as `driveItem` resources. + +| Operation | Microsoft Graph reference | +| --- | --- | +| `drive` resource | [drive resource type](/graph/api/resources/drive) | +| `driveItem` resource | [driveItem resource type](/graph/api/resources/driveitem) | +| Get item | [Get driveItem](/graph/api/driveitem-get) | +| List children | [List children of a driveItem](/graph/api/driveitem-list-children) | +| Create folder | [Create driveItem](/graph/api/driveitem-post-children) | +| Update item | [Update driveItem](/graph/api/driveitem-update) | +| Delete item | [Delete driveItem](/graph/api/driveitem-delete) | +| Move item | [Move a driveItem](/graph/api/driveitem-move) | +| Copy item | [Copy a driveItem](/graph/api/driveitem-copy) | +| Upload small file | [Upload or replace driveItem contents](/graph/api/driveitem-put-content) | +| Create upload session | [Create uploadSession](/graph/api/driveitem-createuploadsession) | +| Download file | [Download driveItem content](/graph/api/driveitem-get-content) | +| Share item | [Invite people to a driveItem](/graph/api/driveitem-invite) | +| Track changes | [Enumerate changes (delta)](/graph/api/driveitem-delta) | +| Search with Microsoft Search | [Query the Microsoft Search API](/graph/api/search-query) | +| Create webhook subscription | [Create subscription](/graph/api/subscription-post-subscriptions) | + +## Resource types + +| Resource | Microsoft Graph reference | +| --- | --- | +| `fileStorage` | [fileStorage resource type](/graph/api/resources/filestorage) | +| `fileStorageContainer` | [fileStorageContainer resource type](/graph/api/resources/filestoragecontainer) | +| `fileStorageContainerSettings` | [fileStorageContainerSettings resource type](/graph/api/resources/filestoragecontainersettings) | +| `fileStorageContainerViewpoint` | [fileStorageContainerViewpoint resource type](/graph/api/resources/filestoragecontainerviewpoint) | +| `fileStorageContainerCustomPropertyDictionary` | [fileStorageContainerCustomPropertyDictionary resource type](/graph/api/resources/filestoragecontainercustompropertydictionary) | +| `fileStorageContainerCustomPropertyValue` | [fileStorageContainerCustomPropertyValue resource type](/graph/api/resources/filestoragecontainercustompropertyvalue) | +| `fileStorageContainerType` | [fileStorageContainerType resource type](/graph/api/resources/filestoragecontainertype) | +| `fileStorageContainerTypeSettings` | [fileStorageContainerTypeSettings resource type](/graph/api/resources/filestoragecontainertypesettings) | +| `fileStorageContainerTypeRegistration` | [fileStorageContainerTypeRegistration resource type](/graph/api/resources/filestoragecontainertyperegistration) | +| `fileStorageContainerTypeRegistrationSettings` | [fileStorageContainerTypeRegistrationSettings resource type](/graph/api/resources/filestoragecontainertyperegistrationsettings) | +| `fileStorageContainerTypeAppPermissionGrant` | [fileStorageContainerTypeAppPermissionGrant resource type](/graph/api/resources/filestoragecontainertypeapppermissiongrant) | + +## Authentication + +SharePoint Embedded uses Microsoft Graph permissions plus container type application permissions. Start with [SharePoint Embedded authentication and authorization](../build/configure-authentication-authorization.md) before you implement the API calls. + +## Related resources + +- [Create and manage containers](../build/create-manage-containers.md) +- [Upload, download, and manage files](../build/manage-files.md) \ No newline at end of file diff --git a/docs/embedded/reference/powershell.md b/docs/embedded/reference/powershell.md new file mode 100644 index 0000000000..34c8f61052 --- /dev/null +++ b/docs/embedded/reference/powershell.md @@ -0,0 +1,65 @@ +--- +title: PowerShell Reference +description: Reference for SharePoint Online PowerShell cmdlets used to administer SharePoint Embedded. +ms.date: 07/13/2026 +ms.reviewer: dilucesr +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# PowerShell reference + +**Applies to:** Consuming tenant administrator + + + +SharePoint Embedded administrators use the latest [SharePoint Online Management Shell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online) and connect with [Connect-SPOService](/powershell/module/sharepoint-online/connect-sposervice). Users must be SharePoint Embedded Administrators or Global Administrators for the supported container administration cmdlets. + +For task guidance, see [manage containers with PowerShell](../admin/manage-containers-powershell.md). + +## Application administration + +| Task | Cmdlet | Parameters | Example | +| --- | --- | --- | --- | +| List SharePoint Embedded applications | [Get-SPOApplication](/powershell/module/sharepoint-online/get-spoapplication) | None | `Get-SPOApplication` | +| Get a specific owning application | [Get-SPOApplication](/powershell/module/sharepoint-online/get-spoapplication) | `-OwningApplicationId` | `Get-SPOApplication -OwningApplicationId ` | +| View guest application permissions | [Get-SPOApplication](/powershell/module/sharepoint-online/get-spoapplication) | `-OwningApplicationId`, `-ApplicationId` | `Get-SPOApplication -OwningApplicationId -ApplicationId ` | +| Set application sharing capability | Set-SPOApplication | `-OwningApplicationId`, `-SharingCapability`, `-OverrideTenantSharingCapability` | `Set-SPOApplication -OwningApplicationId -SharingCapability -OverrideTenantSharingCapability <$OverrideTenantSharingCapability>` | +| Manage guest application permission | [Set-SPOApplicationPermission](/powershell/module/sharepoint-online/set-spoapplicationpermission) | `-OwningApplicationId`, `-GuestApplicationId`, `-PermissionAppOnly`, `-PermissionDelegated` | `Set-SPOApplicationPermission -OwningApplicationId -GuestApplicationId -PermissionAppOnly -PermissionDelegated ` | + +`SharingCapability` accepts `Disabled`, `ExistingExternalUserSharingOnly`, `ExternalUserSharingOnly`, and `ExternalUserAndGuestSharing`. `OverrideTenantSharingCapability` can be `$true` or `$false`. + +> [!NOTE] +> Application administration cmdlets don't apply to Microsoft Loop. + +## Container administration + +| Task | Cmdlet | Parameters | Example | +| --- | --- | --- | --- | +| List active containers for an application | [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer) | `-OwningApplicationId` | `Get-SPOContainer -OwningApplicationId \| FT` | +| List containers sorted by storage | [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer) | `-OwningApplicationId`, `-SortByStorage` | `Get-SPOContainer -OwningApplicationId -SortByStorage \| FT` | +| List archived containers for an application | [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer) | `-OwningApplicationId`, `-ArchiveStatus` | `Get-SPOContainer -OwningApplicationId -ArchiveStatus Archived \| FT` | +| Get container details | [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer) | `-Identity` | `Get-SPOContainer -Identity ` | +| Get container details by site URL | [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer) | `-Identity` | `Get-SPOContainer -Identity ` | +| Set a sensitivity label | Set-SPOContainer | `-Identity`, `-SensitivityLabel` | `Set-SPOContainer -Identity -SensitivityLabel ` | +| Remove a sensitivity label | Set-SPOContainer | `-Identity`, `-RemoveLabel` | `Set-SPOContainer -Identity -RemoveLabel` | +| Soft delete a container | [Remove-SPOContainer](/powershell/module/sharepoint-online/remove-spocontainer) | `-Identity` | `Remove-SPOContainer -Identity ` | +| List deleted containers | [Get-SPODeletedContainer](/powershell/module/sharepoint-online/get-spodeletedcontainer) | None | `Get-SPODeletedContainer` | +| Restore a deleted container | Restore-SPODeletedContainer | `-Identity` | `Restore-SPODeletedContainer -Identity ` | +| Permanently delete a deleted container | [Remove-SPODeletedContainer](/powershell/module/sharepoint-online/remove-spodeletedcontainer) | `-Identity` | `Remove-SPODeletedContainer -Identity ` | + +Deleted containers can be restored from the deleted container collection within 93 days. Permanently deleting a container deletes all documents and files in it. If a container was in the archived state when it was deleted, restoring it returns it to the archived state. + +> [!NOTE] +> To enumerate Microsoft Loop containers, use owning app ID `a187e399-0c36-4b98-8f04-1edc167a0996`. + +## Related resources + +- [Manage containers with PowerShell](../admin/manage-containers-powershell.md) +- [Create and configure a container type](../build/create-container-type.md) diff --git a/docs/embedded/reference/troubleshooting.md b/docs/embedded/reference/troubleshooting.md new file mode 100644 index 0000000000..ed866d5a68 --- /dev/null +++ b/docs/embedded/reference/troubleshooting.md @@ -0,0 +1,49 @@ +--- +title: Troubleshooting +description: Common SharePoint Embedded setup, auth, billing, Office, search, webhook, and admin issues. +ms.date: 07/09/2026 +ms.reviewer: pemtaira +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# Troubleshooting + +**Applies to:** Developer + + + +Use this reference to identify likely causes and fixes. For end-to-end setup, see [create and manage containers](../build/create-manage-containers.md), [manage files](../build/manage-files.md), and [monitor usage, billing, and cost](../admin/monitor-usage-billing-cost.md). + +| Issue | Likely cause | Fix | Related task | +| --- | --- | --- | --- | +| Container type creation fails. | The user doesn't have the required permission, the owning app configuration is incomplete, or billing setup is missing. | Confirm the user can create container types with Microsoft Graph or the SharePoint Embedded Visual Studio Code extension. For admin-only operations, confirm the required role. | [Create and configure a container type](../build/create-container-type.md) | +| Standard container type billing setup fails with `SubscriptionNotRegistered`. | `Microsoft.Syntex` isn't registered as a resource provider in the subscription. | Wait 5-10 minutes after the cmdlet sends the registration request, then retry. Ensure the admin has Owner or Contributor permissions on the Azure subscription. | [Choose a billing model](../plan/choose-billing-model.md) | +| Access denied when calling container or file APIs. | The container type hasn't been registered in the consuming tenant, or the application lacks container type application permissions. | Grant admin consent, call the container type registration API, and verify delegated or app-only permissions include the required operations. | [Create and manage containers](../build/create-manage-containers.md) | +| Delegated API calls return `403 Forbidden` when listing containers. | The signed-in user doesn't have a OneDrive. The List containers operation on behalf of a user requires the user to have a OneDrive. | Use app-only mode for list containers, or ensure the user has a OneDrive until this dependency is removed. | [Create and manage containers](../build/create-manage-containers.md) | +| Pass-through app users can't create new containers (or can't use the app before billing is first configured). | Pass-through billing hasn't been configured, SharePoint Embedded was turned off, or the linked Azure subscription was disconnected. A Global Administrator must set up billing in the Microsoft 365 admin center. | Have a Global Administrator configure pay-as-you-go services for SharePoint Embedded in the Microsoft 365 admin center and confirm the Azure subscription remains linked. Existing containers stay accessible while billing is invalid. | [Monitor usage, billing, and cost](../admin/monitor-usage-billing-cost.md) | +| Office documents open but mentions don't resolve expected users. | Mentions require target users to have a Microsoft 365 license and are restricted to people inside the consuming tenant organization. | Assign the required Microsoft 365 license to internal target users; don't expect guest or cross-tenant users in the mentions picker. | [Manage files](../build/manage-files.md) | +| Search returns unexpected containers or content. | Microsoft Search runs in the context of the signed-in user and can return content the user can access unless scoped. | Include `ContainerTypeId` or `ContainerId` in the query string. If discoverability is disabled, set `includeHiddenContent` as documented. | [Build search experiences](../build/search-containers-files.md) | +| Search API calls fail because of permissions. | Search scenarios require delegated Microsoft Graph permissions during preview, including `Files.Read.All` in addition to `FileStorageContainer.Selected`. | Request and consent to the required delegated permissions and retest with a signed-in user. | [Build search experiences](../build/search-containers-files.md) | +| Webhook subscription validation fails. | The notification endpoint doesn't echo the `validationToken` as plain text, or the endpoint isn't publicly reachable. | Return `200` with the `validationToken` and `Content-Type: text/plain`; expose the endpoint through a reachable public URL. | [Use webhooks](../build/respond-to-changes-webhooks.md) | +| Webhook notifications don't identify the intended container. | The subscription notification URL doesn't carry the container ID, or the handler doesn't read it. | Append `driveId={{ContainerId}}` to the notification URL and have the handler read the `driveId` query parameter. | [Use webhooks](../build/respond-to-changes-webhooks.md) | +| Container isn't visible in SharePoint admin center. | The admin is using the wrong owning application ID, identity, or role. | Confirm the owning application ID and admin role, then refresh the admin experience. | [Admin overview](../admin/admin-overview.md) | + +## Diagnostic links + +- [Authentication and authorization](../build/configure-authentication-authorization.md) +- [Container types](../plan/container-types-containers.md) +- [Billing](../admin/setup-billing-microsoft-365-admin-center.md) +- [Admin overview](../admin/admin-overview.md) +- [Microsoft Graph API reference links](graph-api-links.md) + +## Related resources + +- [Configure authentication and authorization](../build/configure-authentication-authorization.md) +- [Plan authentication and permissions](../plan/authentication-permissions.md) diff --git a/docs/embedded/scenarios-and-use-cases.md b/docs/embedded/scenarios-and-use-cases.md index 2c199f2875..c4ccc9571b 100644 --- a/docs/embedded/scenarios-and-use-cases.md +++ b/docs/embedded/scenarios-and-use-cases.md @@ -1,71 +1,88 @@ --- title: Scenarios and Use Cases -description: Scenarios and Use Cases for SharePoint Embedded -ms.date: 05/21/2024 +description: Explore scenarios and use cases for SharePoint Embedded. +ms.date: 07/13/2026 +ms.reviewer: stpuceli ms.localizationpriority: high +ai-usage: ai-assisted --- # Scenarios and use cases for SharePoint Embedded -Use these example scenarios to prompt ideas about how custom applications can use SharePoint Embedded. +**Applies to:** All + +Use these example scenarios to spark ideas for how your custom application can use SharePoint Embedded. Each scenario combines several features to solve a common content-management problem. + + > [!NOTE] -> This article is not intended to be an exhaustive list of all SharePoint Embedded features and scenarios. The intention is that these scenarios are contextualized examples of how combinations of features can be used. +> This article isn't an exhaustive list of SharePoint Embedded features and scenarios. Each scenario shows one way to combine features in context. ## Scenario: Structured user experience ### Description -Where your application requires a guided user experience to make users work in a structured way, rather than the flexible experience of SharePoint. +Choose this pattern when your application needs a guided experience. You want users to work in a structured way rather than in the flexible SharePoint Online interface. -Where your application is enabling a business-critical or time sensitive process, use the dedicated resource allocation of SharePoint Embedded to simplify management of throttling. +This pattern also suits business-critical or time-sensitive processes. SharePoint Embedded allocates dedicated resources, so you can manage throttling more easily. ### Examples - Extended Relationship Management (XRM) applications - Engagement-based applications -- Workflow-based collaboration, with defined state +- Workflow-based collaboration with defined state -### Why use SharePoint Embedded instead of SharePoint? +### Why use SharePoint Embedded instead of SharePoint Online? -- Your application is the only user interface, allowing you to create a prescriptive user experience -- Resources are separate from your Microsoft 365 entitlements– allowing for simpler resource management. +- Your application is the only user interface, so you control the entire user experience. +- Resources sit apart from your Microsoft 365 entitlements, which simplifies resource management. ## Scenario: Highly controlled collaboration ### Description -When building applications on top of SharePoint, it will still be possible for a user with permissions to navigate to the underlying site. Based on their permission level, a user might complete actions in the SharePoint interface that weren't intended by your application, for example changing site settings. These actions might have unintended consequences for your application or content. +When you build on SharePoint Online directly, a user with permissions can still open the underlying site without awareness from your application. Depending on their permission level, that user might change site settings or take other actions your application didn't intend. Those actions can have unintended consequences for your application or content. -Because SharePoint Embedded is headless, there's no user interface other than what is provided by your custom application. If you don't supply a method to change content or settings through your application, then it won’t be possible for a user to circumvent this through SharePoint. You have the choice for which collaborative features are available in your application, for example sharing. +SharePoint Embedded is headless, so your custom application provides the only interface. If your application doesn't expose a way to change content or settings, a user can't bypass it through SharePoint Online. You decide which collaborative features, such as sharing, your application offers. ### Examples - Deal room applications - Shared research environments -### Why use SharePoint Embedded instead of SharePoint? +### Why use SharePoint Embedded instead of SharePoint Online? -- You need the collaborative capabilities of SharePoint, only via a highly customized user interface -- You're handling high-value content, where you want to manage risk by removing abilities for a user to discover or alter the content repository -- All containers for the application can share default sharing settings that are separate from your OneDrive and SharePoint settings -- Content is logically separated from other Microsoft 365 content +- You need SharePoint's collaborative capabilities, but only through a highly customized interface. +- You handle high-value content and want to limit who can discover or alter the repository. +- Every container in the application can share default sharing settings that stay separate from your OneDrive and SharePoint Online settings. +- Content stays logically separated from your other Microsoft 365 content. -## Scenario: Customer facing document upload +## Scenario: Customer-facing document upload ### Description -Your application is aimed at an end customer, either within your organization or externally, who needs to upload a file as part of their interaction. You require a simplified end-user experience in your custom application, along with the Microsoft 365 capabilities of document storage and compliance. +Your application serves an end customer, inside or outside your organization, who uploads a file as part of an interaction. You want a simple end-user experience plus the Microsoft 365 capabilities for document storage and compliance. -Using SharePoint Embedded will support this scenario, while not requiring the users of your application to have access or entitlement to your Microsoft 365 tenant. +SharePoint Embedded supports this scenario. The users of your application don't need access or entitlement to your Microsoft 365 tenant. ### Examples -- Applying evidence to mortgage application -- Identity document verification +- Attaching evidence to a mortgage application +- Verifying an identity document + +### Why use SharePoint Embedded instead of SharePoint Online? + +- You must segregate this data from the rest of your Microsoft 365 storage, yet keep it in scope for compliance tools like eDiscovery. +- Users need no Microsoft 365 licensing, and you avoid adding external users to SharePoint Online. +- Containers give you a simple, flexible unit of data storage. -### Why use SharePoint Embedded instead of SharePoint? +## Related content -- It's critical to segregate this data from the rest of your Microsoft 365 storage, while still being in scope for compliance tools like eDiscovery -- No Microsoft 365 licensing is required for users, or the use of external users in SharePoint -- Containers offer a simple, flexible unit of data storage +- [What is SharePoint Embedded?](overview.md) +- [Understand app and tenant architecture](plan/app-tenant-architecture.md) +- [Quickstart: Build your first app with VS Code](build/quickstart-vscode.md) diff --git a/docs/embedded/sharepoint-embedded-documentation.md b/docs/embedded/sharepoint-embedded-documentation.md new file mode 100644 index 0000000000..fc078831fd --- /dev/null +++ b/docs/embedded/sharepoint-embedded-documentation.md @@ -0,0 +1,114 @@ +--- +title: SharePoint Embedded documentation +description: Task-based index for SharePoint Embedded. Find the right page by what you're trying to do, whether you build apps or administer them. +ms.date: 07/13/2026 +ms.reviewer: dilucesr +ms.author: mawin +ms.localizationpriority: high +ai-usage: ai-assisted +--- + +# SharePoint Embedded documentation + +**Applies to:** All + +SharePoint Embedded is a cloud-based, API-only file and document management platform built on Microsoft 365. Developers embed Office collaboration, Microsoft Purview compliance, and Copilot into their own apps — while documents stay inside each customer's Microsoft 365 tenant. + +This page is organized by **task**. Find what you're trying to do and go straight to the page that does it. A machine-readable index is available in this folder as `llms.txt`. + +> [!TIP] +> New here? Read [What is SharePoint Embedded?](./overview.md) first, then come back to pick a task. + + + +## Two roads + +Almost everyone is one of two people. Architects, IT decision makers, billing admins, and compliance admins each merge onto one of these: + +| You are… | You want to… | Start at | +|---|---|---| +| Developer / architect | Build and ship an app | [Build an app](#build-an-app) | +| ISV / developer | Onboard customers and bill | [Publish and onboard customers](#publish-and-onboard-customers) | +| SharePoint Embedded admin | Install and manage apps | [Install and manage apps](#install-and-manage-apps) | +| Compliance admin | Govern and secure content | [Apply security and compliance controls](./admin/apply-security-compliance-controls.md) | +| Evaluating / planning | Decide and design | [Plan a solution](#plan-a-solution) | + +## Plan a solution + +Decide how SharePoint Embedded fits before you write code. + +- [Understand app and tenant architecture](./plan/app-tenant-architecture.md) +- [Choose an app model: single-tenant or multitenant](./plan/choose-app-model.md) +- [Understand container types and containers](./plan/container-types-containers.md) +- [Choose a billing model](./plan/choose-billing-model.md) +- [Plan authentication and permissions](./plan/authentication-permissions.md) +- [Plan security, compliance, and governance](./plan/security-compliance-governance.md) +- [Understand limits and calling patterns](./plan/limits-calling-patterns.md) + +## Build an app + +An ordered journey from first container to a full-featured app. + +1. [Quickstart: build your first app with VS Code](./build/quickstart-vscode.md) +2. [Create and configure a container type](./build/create-container-type.md) +3. [Register application permissions](./build/register-application-permissions.md) +4. [Configure authentication and authorization](./build/configure-authentication-authorization.md) +5. [Create and manage containers](./build/create-manage-containers.md) +6. [Upload, download, and manage files](./build/manage-files.md) +7. [Open Office files from your app](./build/open-office-files.md) +8. [Preview files in your app](./build/preview-files.md) +9. [Search containers and files](./build/search-containers-files.md) +10. [Store and query container metadata](./build/container-metadata.md) +11. [Share files and manage permissions](./build/share-files-manage-permissions.md) +12. [Respond to file and container changes with webhooks](./build/respond-to-changes-webhooks.md) +13. [Archive and restore containers](./build/archive-restore-containers.md) +14. [Add real-time collaboration with Fluid Framework](./build/fluid-framework.md) +15. [Add Microsoft 365 Copilot and agent experiences](./build/agent-experiences.md) +16. [Set up SharePoint Embedded as a Foundry knowledge source](./build/sharepoint-embedded-knowledge-source.md) +17. [Migrate from Azure Blob Storage](./build/migrate-azure-blob-storage.md) + +## Publish and onboard customers + +For ISVs shipping a multitenant app. + +- [Prepare your app for customer installation](./publish/prepare-customer-installation.md) +- [Choose a billing model for your app](./publish/choose-app-billing-model.md) +- [Guide customers through tenant setup](./publish/customer-tenant-setup-guide.md) +- [Validate customer app installation](./publish/validate-customer-installation.md) + +## Install and manage apps + +For administrators of a Microsoft 365 tenant that uses SharePoint Embedded apps. + +- [Admin overview](./admin/admin-overview.md) +- [Create apps in SharePoint admin center](./admin/create-apps-sharepoint-admin-center.md) +- [Create apps with PowerShell](./admin/create-apps-powershell.md) +- [Install a SharePoint Embedded app](./admin/install-sharepoint-embedded-app.md) +- [Grant admin consent and permissions](./admin/grant-admin-consent-permissions.md) +- [Set up billing in Microsoft 365 admin center](./admin/setup-billing-microsoft-365-admin-center.md) +- [Manage containers in SharePoint admin center](./admin/manage-containers-sharepoint-admin-center.md) +- [Manage containers with PowerShell](./admin/manage-containers-powershell.md) +- [Monitor usage, billing, and cost](./admin/monitor-usage-billing-cost.md) +- [Review audit events](./admin/review-audit-events.md) +- [Apply security and compliance controls](./admin/apply-security-compliance-controls.md) + +## Reference + +- [Billing meters](./reference/billing-meters.md) +- [Audit events](./reference/audit-events.md) +- [PowerShell reference](./reference/powershell.md) +- [Microsoft Graph API reference links](./reference/graph-api-links.md) +- [Troubleshooting](./reference/troubleshooting.md) +- [Glossary](./reference/glossary.md) +- `llms.txt` — machine-readable corpus index for coding agents + +## More + +- [Scenarios and use cases](./scenarios-and-use-cases.md) +- [What's new](./whats-new.md) +- [Microsoft Graph SharePoint Embedded API reference](/graph/api/resources/filestoragecontainer) diff --git a/docs/embedded/whats-new.md b/docs/embedded/whats-new.md index ab4496b4e3..e2a5404f00 100644 --- a/docs/embedded/whats-new.md +++ b/docs/embedded/whats-new.md @@ -2,32 +2,43 @@ title: What's new in SharePoint Embedded? description: Updates about Microsoft SharePoint Embedded. ms.date: 06/04/2025 -ms.localizationpriority: medium +ms.reviewer: dilucesr +ms.localizationpriority: high +ai-usage: ai-assisted --- # What's new in SharePoint Embedded +**Applies to:** All + + + ## July 2026 -- The [SharePoint Embedded Model Context Protocol (MCP) server](./getting-started/sharepoint-embedded-mcp-server.md) is available in preview as an open-source npm package ([`@microsoft/spe-mcp`](https://github.com/microsoft/SharePoint-Embedded-MCP-Server)), letting any MCP-compatible AI client—such as GitHub Copilot in Visual Studio Code, Claude, or Cursor—provision and manage SharePoint Embedded through natural language. +- You can [use the MCP server to build apps with a coding agent](./build/sharepoint-embedded-mcp-server.md). The open-source SharePoint Embedded MCP server npm package ([`@microsoft/spe-mcp`](https://github.com/microsoft/SharePoint-Embedded-MCP-Server)) lets MCP-compatible AI clients—such as GitHub Copilot in Visual Studio Code or the CLI, Claude, or Cursor—provision and manage SharePoint Embedded applications through natural language. ## June 2026 -- [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) resource has a new `urlTemplate` [setting](/graph/api/resources/filestoragecontainertypesettings). For more information on what the `urlTemplate` setting does, see [Configure redirect behavior](./development/content-experiences/configure-redirect-behavior.md). -- The [`FileStorageContainerType.Manage.All`](/graph/permissions-reference#filestoragecontainertypemanageall) Microsoft Graph permission no longer requires the [SharePoint Embedded Administrator](./administration/adminrole.md) or [Global Administrator](/entra/identity/role-based-access-control/permissions-reference#global-administrator) role. Any non-guest user in the owning tenant can [create a container type](./getting-started/containertypes.md#creating-container-types) and is automatically assigned as an [owner of that container type](./development/auth.md#container-type-owner-capabilities). +- [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) has a new `urlTemplate` [setting](/graph/api/resources/filestoragecontainertypesettings). For more information on what the `urlTemplate` setting does, see [Create and configure a container type](./build/create-container-type.md#configure-container-type-behavior). +- The [`FileStorageContainerType.Manage.All`](/graph/permissions-reference#filestoragecontainertypemanageall) Microsoft Graph permission no longer requires the [SharePoint Embedded Administrator](./admin/admin-overview.md#assign-the-sharepoint-embedded-administrator-role) or [Global Administrator](/entra/identity/role-based-access-control/permissions-reference#global-administrator) role. Any non-guest user in the owning tenant can [create a container type](./build/create-container-type.md) and is automatically assigned as an [owner of that container type](./build/configure-authentication-authorization.md#manage-container-type-owners). ## May 2026 -- [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) operations now emit audit logs for `ContainerTypeCreated`, `ContainerTypeDeleted`, `ContainerTypeUpdated` and `ContainerTypeOwnersUpdated`. For more information, see [SharePoint Embedded audit log events](./compliance/audit-events.md#container-type-activities). +- [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) operations now emit audit logs for `ContainerTypeCreated`, `ContainerTypeDeleted`, `ContainerTypeUpdated`, and `ContainerTypeOwnersUpdated`. For more information, see [Audit events](./reference/audit-events.md#container-type-activities). - [fileStorageContainer](/graph/api/resources/filestoragecontainer) supports bulk creation and update of `permissions` using delta patch. For more information, see [Upsert permissions](/graph/api/filestoragecontainer-patch-permissions). -- Clarified the authorization model for administrative actions on containers. For more information, see [Operations that involve administrative actions on containers](./development/auth.md#operations-that-involve-administrative-actions-on-containers). +- Clarified the authorization model for administrative actions on containers. For more information, see [Handle operations not exposed through Graph](./build/configure-authentication-authorization.md#handle-operations-not-exposed-through-graph). ## March 2026 -- [SharePoint Embedded agent SDK](./development/declarative-agent/spe-da.md) has been deprecated in favor of the new [SharePoint Embedded knowledge source in Microsoft Foundry](./development/declarative-agent/sharepoint-embedded-knowledge-source.md). -- [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) resource has a new **permissions** relationship that allows management of the container type's owners. This is available in the beta Microsoft Graph endpoint. For more information, see [Managing SharePoint Embedded applications created in the owning tenant](./development/auth.md#managing-sharepoint-embedded-applications-created-in-the-owning-tenant). -- [fileStorageContainer](/graph/api/resources/filestoragecontainer) resource has a new **informationBarrier** property that allows management of the container's information barrier. This is available in the beta Microsoft Graph endpoint. For more information, see [Information Barriers](/purview/information-barriers-sharepoint). -- The SharePoint Embedded native PDF viewing experience now supports searching within the file, viewing comments and sticky notes embedded on the file, and printing. The new features are now available via the [driveItem: preview](/graph/api/driveitem-preview) API in both the beta and v1.0 Microsoft Graph endpoints. +- [SharePoint Embedded agent SDK](./build/agent-experiences.md) has been deprecated in favor of the new [SharePoint Embedded knowledge source in Microsoft Foundry](./build/sharepoint-embedded-knowledge-source.md). +- [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) resource has a new `permissions` relationship that allows management of the container type's owners. This is available in the beta Microsoft Graph endpoint. For more information, see [Manage container type owners](./build/configure-authentication-authorization.md#manage-container-type-owners). +- [fileStorageContainer](/graph/api/resources/filestoragecontainer) resource has a new `informationBarrier` property that allows management of the container's information barrier. This is available in the beta Microsoft Graph endpoint. For more information, see [Information Barriers](/purview/information-barriers-sharepoint). +- The SharePoint Embedded native PDF viewing experience now supports searching within the file, viewing comments and sticky notes embedded on the file, and printing. The new features are now available through the [driveItem: preview](/graph/api/driveitem-preview) API in both the beta and v1.0 Microsoft Graph endpoints. ## February 2026 @@ -51,13 +62,13 @@ ms.localizationpriority: medium ## October 2025 -- [recycleBinItem: restore](/graph/api/filestoragecontainer-restore-recyclebinitem) supports `driveItemId` as an alternate key to enable restoring a **recycleBinItem** if the ID of the original **driveItem** is known. +- [recycleBinItem: restore](/graph/api/filestoragecontainer-restore-recyclebinitem) supports `driveItemId` as an alternate key to enable restoring a `recycleBinItem` if the ID of the original `driveItem` is known. - [Microsoft 365 Archive](/microsoft-365/archive/archive-overview) is previewing support for [SharePoint Embedded](./overview.md) to a limited number of customers. You can [sign up for the private preview](https://forms.office.com/r/98Z4iqSKya) today. ## September 2025 - [SharePoint Embedded migration](/graph/api/resources/sharepointmigration-api-overview) APIs are now available in the beta Microsoft Graph endpoint. -- [driveItem: invite](/graph/api/driveitem-invite) has clearer documentation on restrictions for the root item of drives in OneDrive for home, and inviting _new_ guests via app-only access. +- [driveItem: invite](/graph/api/driveitem-invite) has clearer documentation on restrictions for the root item of drives in OneDrive for home, and inviting _new_ guests by using app-only access. - [driveItem: copy](/graph/api/driveitem-copy) has clearer documentation on behaviors around metadata, versions, cross-geo operations, and known issues. - New cmdlets for consuming tenant administrators to [add](/powershell/module/microsoft.online.sharepoint.powershell/add-spocontaineruser), [remove](/powershell/module/microsoft.online.sharepoint.powershell/remove-spocontaineruser), or [change](/powershell/module/microsoft.online.sharepoint.powershell/set-spocontaineruser) container membership were added to the [SharePoint Embedded Containers Management Shell](/powershell/sharepoint/sharepoint-online/introduction-sharepoint-online-management-shell). @@ -70,13 +81,9 @@ ms.localizationpriority: medium - [driveItem: copy](/graph/api/driveitem-copy) now supports the `childrenOnly` and `includeAllVersionHistory` request parameters in the v1.0 Microsoft Graph endpoint. -## June 2025 - -- The `CopilotEmbeddedChatHosts` container type setting is now required to use [SharePoint Embedded agent](./development/declarative-agent/spe-da-adv.md#csp-policies). It must be set by the application owner via [`Set-SPOContainerTypeConfiguration`](/powershell/module/sharepoint-online/set-spocontainertypeconfiguration) and can optionally be overridden by consuming tenant administrators via [`Set-SPOApplication`](/powershell/module/SharePoint-online/set-spoapplication). - ## May 2025 -- The limit of container types that a partner tenant can create has been increased to 25 by default. For more information, see [Limits and Calling Patterns](./development/limits-calling.md#size-limits). -- SharePoint Embedded agent switched to a consumption-based model for all users regardless of whether they have a Copilot license or not. For more information, see [SharePoint Embedded agent](./development/declarative-agent/spe-da.md). -- The guidance on how to grant admin consent to a SharePoint Embedded application has been updated to use URL-based admin consent. For more information, see [Authentication and authorization](./development/auth.md#whats-next). -- Documented an exceptional access pattern for operations that may require a user license. For more information, see [Authentication and authorization](./development/auth.md#operations-that-require-a-user-license). +- The limit of container types that a partner tenant can create has been increased to 25 by default. For more information, see [Limits and Calling Patterns](./plan/limits-calling-patterns.md#size-limits). +- SharePoint Embedded agent switched to a consumption-based model for all users regardless of whether they have a Copilot license or not. For more information, see [SharePoint Embedded agent](./build/agent-experiences.md). +- The guidance on how to grant admin consent to a SharePoint Embedded application has been updated to use URL-based admin consent. For more information, see [Grant admin consent](./build/register-application-permissions.md#grant-admin-consent). +- Documented an exceptional access pattern for operations that may require a user license. For more information, see [Handle operations not exposed through Graph](./build/configure-authentication-authorization.md#handle-operations-not-exposed-through-graph). diff --git a/docs/toc.yml b/docs/toc.yml index 8bcff87345..9251fb8bad 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -605,93 +605,117 @@ - name: SharePoint Embedded items: - name: Overview - href: embedded/overview.md - - name: What's New - href: embedded/whats-new.md - - name: Scenarios and Use Cases - href: embedded/scenarios-and-use-cases.md - - name: Getting Started items: - - name: SharePoint Embedded Visual Studio Code Extension - href: embedded/getting-started/spembedded-for-vscode.md - - name: SharePoint Embedded Model Context Protocol (MCP) Server - href: embedded/getting-started/sharepoint-embedded-mcp-server.md - - name: Container Types - href: embedded/getting-started/containertypes.md - - name: Register Container Type API - href: embedded/getting-started/register-api-documentation.md - - name: Microsoft 365 Archive support for containers - href: embedded/getting-started/microsoft-365-archive-support-for-containers.md - - name: Development + - name: What is SharePoint Embedded? + href: embedded/overview.md + - name: Scenarios and use cases + href: embedded/scenarios-and-use-cases.md + - name: What's new + href: embedded/whats-new.md + - name: Plan a SharePoint Embedded solution items: - - name: Application Architecture - href: embedded/development/app-architecture.md - - name: Authentication and Authorization - href: embedded/development/auth.md - - name: Sharing and Permissions - href: embedded/development/sharing-and-perm.md - - name: Limits and Calling Patterns - href: embedded/development/limits-calling.md - - name: Fluid Framework - href: embedded/development/fluid.md - - name: Support archive funcationality in your application - href: embedded/development/support-archival-of-containers.md - - name: Office Experiences - href: embedded/development/content-experiences/office-experience.md - - name: Configuring redirect behavior - href: embedded/development/content-experiences/configure-redirect-behavior.md - - name: User Experiences - href: embedded/development/content-experiences/user-experiences-overview.md - - name: Search Content - href: embedded/development/content-experiences/search-content.md - - name: Launch Experience - href: embedded/development/tutorials/launch-experience.md - - name: Using Metadata with SharePoint Embedded Containers - href: embedded/development/tutorials/metadata.md - - name: Using File Preview - href: embedded/development/tutorials/using-file-preview.md - - name: Using Document Processing with Azure Cognitive Services - href: embedded/development/tutorials/doc-processing-acs.md - - name: Using Webhooks - href: embedded/development/tutorials/using-webhooks.md - - name: Migrate ABS to SPE - href: embedded/development/tutorials/migrate-abs-to-spe.md - - name: Install Your SPE App in a Consuming Tenant - href: embedded/development/tutorials/vendor-install-app-customer.md - - name: Administration + - name: Understand app and tenant architecture + href: embedded/plan/app-tenant-architecture.md + - name: 'Choose an app model: single-tenant or multitenant' + href: embedded/plan/choose-app-model.md + - name: Understand container types and containers + href: embedded/plan/container-types-containers.md + - name: Choose a billing model + href: embedded/plan/choose-billing-model.md + - name: Plan authentication and permissions + href: embedded/plan/authentication-permissions.md + - name: Plan security, compliance, and governance + href: embedded/plan/security-compliance-governance.md + - name: Understand limits and calling patterns + href: embedded/plan/limits-calling-patterns.md + - name: Build apps with SharePoint Embedded items: - - name: Billing - href: embedded/administration/billing/billing.md - - name: Billing Management - href: embedded/administration/billing/billingmanagement.md - - name: SharePoint Embedded Billing Meters - href: embedded/administration/billing/meters.md - - name: Consuming Tenant Admin - href: embedded/administration/consuming-tenant-admin/cta.md - - name: Container Management in PowerShell - href: embedded/administration/consuming-tenant-admin/ctapowershell.md - - name: Consuming Tenant Admin UX - href: embedded/administration/consuming-tenant-admin/ctaUX.md - - name: Developer Admin - href: embedded/administration/developer-admin/dev-admin.md - - name: SharePoint Embedded Admin - href: embedded/administration/adminrole.md - - name: Compliance + - name: 'Quickstart: Build your first app with VS Code' + href: embedded/build/quickstart-vscode.md + - name: Use the MCP server to build apps with a coding agent + href: embedded/build/sharepoint-embedded-mcp-server.md + - name: Create and configure a container type + href: embedded/build/create-container-type.md + - name: Register application permissions + href: embedded/build/register-application-permissions.md + - name: Configure authentication and authorization + href: embedded/build/configure-authentication-authorization.md + - name: Create and manage containers + href: embedded/build/create-manage-containers.md + - name: Upload, download, and manage files + href: embedded/build/manage-files.md + - name: Open Office files from your app + href: embedded/build/open-office-files.md + - name: Preview files in your app + href: embedded/build/preview-files.md + - name: Search containers and files + href: embedded/build/search-containers-files.md + - name: Store and query container metadata + href: embedded/build/container-metadata.md + - name: Share files and manage permissions + href: embedded/build/share-files-manage-permissions.md + - name: Respond to file and container changes with webhooks + href: embedded/build/respond-to-changes-webhooks.md + - name: Archive and restore containers + href: embedded/build/archive-restore-containers.md + - name: Add real-time collaboration with Fluid Framework + href: embedded/build/fluid-framework.md + - name: Add Microsoft 365 Copilot and agent experiences + href: embedded/build/agent-experiences.md + - name: Set up SharePoint Embedded as a Foundry knowledge source + href: embedded/build/sharepoint-embedded-knowledge-source.md + - name: Migrate from Azure Blob Storage + href: embedded/build/migrate-azure-blob-storage.md + - name: Publish and onboard customers items: - - name: Security and Compliance - href: embedded/compliance/security-and-compliance.md - - name: Audit log events - href: embedded/compliance/audit-events.md - - name: SharePoint Embedded Learning Modules + - name: Prepare your app for customer installation + href: embedded/publish/prepare-customer-installation.md + - name: Choose a billing model for your app + href: embedded/publish/choose-app-billing-model.md + - name: Guide customers through tenant setup + href: embedded/publish/customer-tenant-setup-guide.md + - name: Validate customer app installation + href: embedded/publish/validate-customer-installation.md + - name: Install and manage apps items: - - name: SharePoint Embedded - overview & configuration - href: /training/modules/sharepoint-embedded-setup - - name: SharePoint Embedded - building applications - href: /training/modules/sharepoint-embedded-create-app - - name: SharePoint Embedded agent + - name: Admin overview + href: embedded/admin/admin-overview.md + - name: Consuming tenant admin + href: embedded/admin/consuming-tenant-admin.md + - name: Create apps in SharePoint admin center + href: embedded/admin/create-apps-sharepoint-admin-center.md + - name: Create apps with PowerShell + href: embedded/admin/create-apps-powershell.md + - name: Install a SharePoint Embedded app + href: embedded/admin/install-sharepoint-embedded-app.md + - name: Grant admin consent and permissions + href: embedded/admin/grant-admin-consent-permissions.md + - name: Set up billing in Microsoft 365 admin center + href: embedded/admin/setup-billing-microsoft-365-admin-center.md + - name: Manage containers in SharePoint admin center + href: embedded/admin/manage-containers-sharepoint-admin-center.md + - name: Manage containers with PowerShell + href: embedded/admin/manage-containers-powershell.md + - name: Monitor usage, billing, and cost + href: embedded/admin/monitor-usage-billing-cost.md + - name: Review audit events + href: embedded/admin/review-audit-events.md + - name: Apply security and compliance controls + href: embedded/admin/apply-security-compliance-controls.md + - name: Reference items: - - name: SharePoint Embedded knowledge source in Microsoft Foundry (Preview) - href: embedded/development/declarative-agent/sharepoint-embedded-knowledge-source.md + - name: Billing meters + href: embedded/reference/billing-meters.md + - name: Audit events + href: embedded/reference/audit-events.md + - name: PowerShell reference + href: embedded/reference/powershell.md + - name: Microsoft Graph API reference links + href: embedded/reference/graph-api-links.md + - name: Troubleshooting + href: embedded/reference/troubleshooting.md + - name: Glossary + href: embedded/reference/glossary.md - name: Microsoft Teams items: - name: Overview