From 92e86693ed7ccaebdd545f35e307b5fec88133bc Mon Sep 17 00:00:00 2001 From: Shreyas Saravanan Date: Thu, 25 Jun 2026 13:31:29 +0530 Subject: [PATCH 01/10] Restructure SharePoint Embedded docs into task-based IA Reorganize the SPE doc set around what readers come to do, with a clear developer/admin split and a routing top-level entry point. - Rewrite overview.md as a router to Plan/Build/Publish/Administer/Reference - Add 43 task-based articles across plan/, build/, publish/, admin/, reference/ - Replace the embedded section of toc.yml with the task-based structure - Add llms.txt corpus index for coding agents; add per-article agent metadata - Consolidate the two role-based landing drafts into one task-based index - Split oversized search-content into a focused task article Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/embedded/SPE landing page for agents.md | 356 ------------------ .../SharePoint Embedded Documentation.md | 156 ++++---- docs/embedded/admin/admin-overview.md | 176 +++++++++ .../apply-security-compliance-controls.md | 237 ++++++++++++ .../create-apps-sharepoint-admin-center.md | 199 ++++++++++ .../admin/grant-admin-consent-permissions.md | 195 ++++++++++ .../admin/install-sharepoint-embedded-app.md | 187 +++++++++ .../admin/manage-containers-powershell.md | 255 +++++++++++++ ...nage-containers-sharepoint-admin-center.md | 212 +++++++++++ .../admin/monitor-usage-billing-cost.md | 185 +++++++++ docs/embedded/admin/review-audit-events.md | 208 ++++++++++ .../admin/setup-billing-m365-admin-center.md | 175 +++++++++ docs/embedded/build/agent-experiences.md | 122 ++++++ .../build/archive-restore-containers.md | 122 ++++++ .../configure-authentication-authorization.md | 120 ++++++ docs/embedded/build/container-metadata.md | 127 +++++++ docs/embedded/build/create-container-type.md | 134 +++++++ .../build/create-manage-containers.md | 136 +++++++ docs/embedded/build/fluid-framework.md | 122 ++++++ docs/embedded/build/manage-files.md | 125 ++++++ .../build/migrate-azure-blob-storage.md | 122 ++++++ docs/embedded/build/open-office-files.md | 146 +++++++ docs/embedded/build/preview-files.md | 166 ++++++++ docs/embedded/build/quickstart-vscode.md | 129 +++++++ .../build/register-application-permissions.md | 143 +++++++ .../build/respond-to-changes-webhooks.md | 122 ++++++ .../embedded/build/search-containers-files.md | 122 ++++++ .../build/share-files-manage-permissions.md | 122 ++++++ docs/embedded/llms.txt | 66 ++++ docs/embedded/overview.md | 86 ++--- docs/embedded/plan/app-tenant-architecture.md | 190 ++++++++++ .../plan/authentication-permissions.md | 219 +++++++++++ docs/embedded/plan/choose-app-model.md | 193 ++++++++++ docs/embedded/plan/choose-billing-model.md | 194 ++++++++++ .../plan/container-types-and-containers.md | 226 +++++++++++ docs/embedded/plan/limits-calling-patterns.md | 238 ++++++++++++ .../plan/security-compliance-governance.md | 225 +++++++++++ .../publish/choose-app-billing-model.md | 199 ++++++++++ .../publish/customer-tenant-setup-guide.md | 210 +++++++++++ .../publish/prepare-customer-installation.md | 224 +++++++++++ .../publish/validate-customer-installation.md | 251 ++++++++++++ docs/embedded/reference/audit-events.md | 51 +++ docs/embedded/reference/billing-meters.md | 56 +++ docs/embedded/reference/glossary.md | 31 ++ docs/embedded/reference/graph-api-links.md | 59 +++ docs/embedded/reference/powershell.md | 53 +++ docs/embedded/reference/troubleshooting.md | 43 +++ docs/toc.yml | 170 +++++---- 48 files changed, 7057 insertions(+), 548 deletions(-) delete mode 100644 docs/embedded/SPE landing page for agents.md create mode 100644 docs/embedded/admin/admin-overview.md create mode 100644 docs/embedded/admin/apply-security-compliance-controls.md create mode 100644 docs/embedded/admin/create-apps-sharepoint-admin-center.md create mode 100644 docs/embedded/admin/grant-admin-consent-permissions.md create mode 100644 docs/embedded/admin/install-sharepoint-embedded-app.md create mode 100644 docs/embedded/admin/manage-containers-powershell.md create mode 100644 docs/embedded/admin/manage-containers-sharepoint-admin-center.md create mode 100644 docs/embedded/admin/monitor-usage-billing-cost.md create mode 100644 docs/embedded/admin/review-audit-events.md create mode 100644 docs/embedded/admin/setup-billing-m365-admin-center.md create mode 100644 docs/embedded/build/agent-experiences.md create mode 100644 docs/embedded/build/archive-restore-containers.md create mode 100644 docs/embedded/build/configure-authentication-authorization.md create mode 100644 docs/embedded/build/container-metadata.md create mode 100644 docs/embedded/build/create-container-type.md create mode 100644 docs/embedded/build/create-manage-containers.md create mode 100644 docs/embedded/build/fluid-framework.md create mode 100644 docs/embedded/build/manage-files.md create mode 100644 docs/embedded/build/migrate-azure-blob-storage.md create mode 100644 docs/embedded/build/open-office-files.md create mode 100644 docs/embedded/build/preview-files.md create mode 100644 docs/embedded/build/quickstart-vscode.md create mode 100644 docs/embedded/build/register-application-permissions.md create mode 100644 docs/embedded/build/respond-to-changes-webhooks.md create mode 100644 docs/embedded/build/search-containers-files.md create mode 100644 docs/embedded/build/share-files-manage-permissions.md create mode 100644 docs/embedded/llms.txt create mode 100644 docs/embedded/plan/app-tenant-architecture.md create mode 100644 docs/embedded/plan/authentication-permissions.md create mode 100644 docs/embedded/plan/choose-app-model.md create mode 100644 docs/embedded/plan/choose-billing-model.md create mode 100644 docs/embedded/plan/container-types-and-containers.md create mode 100644 docs/embedded/plan/limits-calling-patterns.md create mode 100644 docs/embedded/plan/security-compliance-governance.md create mode 100644 docs/embedded/publish/choose-app-billing-model.md create mode 100644 docs/embedded/publish/customer-tenant-setup-guide.md create mode 100644 docs/embedded/publish/prepare-customer-installation.md create mode 100644 docs/embedded/publish/validate-customer-installation.md create mode 100644 docs/embedded/reference/audit-events.md create mode 100644 docs/embedded/reference/billing-meters.md create mode 100644 docs/embedded/reference/glossary.md create mode 100644 docs/embedded/reference/graph-api-links.md create mode 100644 docs/embedded/reference/powershell.md create mode 100644 docs/embedded/reference/troubleshooting.md diff --git a/docs/embedded/SPE landing page for agents.md b/docs/embedded/SPE landing page for agents.md deleted file mode 100644 index d118fed35b..0000000000 --- a/docs/embedded/SPE landing page for agents.md +++ /dev/null @@ -1,356 +0,0 @@ ---- -title: SharePoint Embedded — documentation index -description: Persona-tagged index of every public SharePoint Embedded (SPE) Learn doc. Route to the right page by role, task, and outcome. -ms.topic: landing-page -ms.author: ShreyasSar26 -author: ShreyasSaravanan -ms.date: 2026-06-09 -ms.service: sharepoint-online -ms.localizationpriority: high -search.appverid: MET150 -agent: - schema_version: 1 - task_type: concept - outcome: The reader (human or agent) is routed to the smallest set of SPE pages required to accomplish their stated task, by role and outcome. - difficulty: beginner - roles: - - new-user - - app-developer - - developer-admin - - consuming-tenant-admin - - compliance-officer - prerequisites: [] - api_surface: [] - inputs: - - name: user_intent - type: enum - source: user-supplied - values: [evaluate, set-up-dev-env, build-app, build-content-experience, follow-tutorial, configure-billing, admin-consuming-tenant, govern-content] - outputs: - - name: target_section_id - type: string - verify: target section anchor resolves on this page - - name: target_page_uri - type: uri - verify: returns 200 from learn.microsoft.com - next_steps: - - uri: https://learn.microsoft.com/en-us/sharepoint/dev/embedded/overview - when: user_intent == "evaluate" - - uri: https://learn.microsoft.com/en-us/sharepoint/dev/embedded/getting-started/spembedded-for-vscode - when: user_intent == "set-up-dev-env" - - uri: https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/auth - when: user_intent == "build-app" - - uri: https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/billing/billing - when: user_intent == "configure-billing" - - uri: https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/consuming-tenant-admin/cta - when: user_intent == "admin-consuming-tenant" - - uri: https://learn.microsoft.com/en-us/sharepoint/dev/embedded/compliance/security-and-compliance - when: user_intent == "govern-content" - related: - - uri: https://learn.microsoft.com/en-us/sharepoint/dev/embedded/scenarios-and-use-cases - - uri: https://learn.microsoft.com/en-us/sharepoint/dev/embedded/whats-new - stability: ga - last_validated: 2026-06-09 ---- - -# SharePoint Embedded — documentation index - -SharePoint Embedded (SPE) is a cloud-based, API-only file and document management platform built on Microsoft 365 infrastructure. Developers embed Office collaboration, Microsoft Purview compliance, and Copilot capabilities directly into their own applications while keeping documents securely within each customer's Microsoft 365 tenant. - -This page is a routing index. It does not teach SPE; it points you to the smallest set of pages required to accomplish a specific task, organized by role. - -> [!TIP] -> If you already know what you need: jump to the [/llms.txt](https://learn.microsoft.com/sharepoint/dev/embedded/llms.txt) index for the machine-readable form of this page, or the [Microsoft Graph API reference](https://learn.microsoft.com/en-us/graph/api/resources/filestoragecontainer) for endpoints. - -## When to use this page {#when-to-use} - -Use this index if any of the following apply: - -- You are evaluating SPE for a new application. -- You are a developer about to set up your environment for the first time. -- You are an administrator (developer admin, consuming-tenant admin, or compliance officer) and need the right starting page for your role. -- You are an AI agent routing a user request to the correct SPE doc. - -## When NOT to use this page {#when-not-to-use} - -- You already know which page you need. Go there directly; do not pass through here. -- You need the raw Microsoft Graph API surface. Use the [Graph API reference](https://learn.microsoft.com/en-us/graph/api/resources/filestoragecontainer). -- You are an agent crawling the corpus. Use [/llms.txt](https://learn.microsoft.com/sharepoint/dev/embedded/llms.txt) and [/api-surface.json](https://learn.microsoft.com/sharepoint/dev/embedded/api-surface.json) instead of scraping this page. - -## Section index {#section-index} - -| # | Section | Role | Anchor | -|---|---|---|---| -| 1 | New to SharePoint Embedded | new-user | [#new-to-spe](#new-to-spe) | -| 2 | Developer — Set up your environment | app-developer | [#dev-setup](#dev-setup) | -| 3 | Developer — Build your app | app-developer | [#dev-build](#dev-build) | -| 4 | Developer — Content experiences | app-developer | [#dev-content-experiences](#dev-content-experiences) | -| 5 | Tutorials | app-developer | [#tutorials](#tutorials) | -| 6 | Developer Admin / ISV — Billing & tenant management | developer-admin | [#dev-admin-billing](#dev-admin-billing) | -| 7 | Consuming Tenant Admin | consuming-tenant-admin | [#consuming-tenant-admin](#consuming-tenant-admin) | -| 8 | Compliance & Security Officer | compliance-officer | [#compliance-security](#compliance-security) | - ---- - -## 1. New to SharePoint Embedded {#new-to-spe} - -**Use this section if:** you have not built on SPE before and need orientation, scenarios, or guided training. - -| Page | Type | Estimated time | -|---|---|---| -| [Overview](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/overview) | concept | 10 min | -| [Scenarios and use cases](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/scenarios-and-use-cases) | concept | 10 min | -| [What's new](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/whats-new) | reference | 5 min | -| [Learning module — Overview & configuration](https://learn.microsoft.com/en-us/training/modules/sharepoint-embedded-setup) | quickstart | 45 min | -| [Learning module — Building applications](https://learn.microsoft.com/en-us/training/modules/sharepoint-embedded-create-app) | quickstart | 60 min | - -**Next step:** when you finish orientation, proceed to [Developer — Set up your environment](#dev-setup). - ---- - -## 2. Developer — Set up your environment {#dev-setup} - -**Use this section if:** you are an app developer creating container types and registering your app for the first time. - -| Page | Type | Estimated time | -|---|---|---| -| [VS Code extension](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/getting-started/spembedded-for-vscode) | quickstart | 15 min | -| [Container types](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/getting-started/containertypes) | how-to | 20 min | -| [Register container type API](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/getting-started/register-api-documentation) | how-to | 15 min | -| [Application architecture](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/app-architecture) | concept | 15 min | - -**Next step:** after environment setup, proceed to [Developer — Build your app](#dev-build). - ---- - -## 3. Developer — Build your app {#dev-build} - -**Use this section if:** you are wiring authentication, permissions, scale, or AI capabilities into a working SPE application. - -| Page | Type | Estimated time | -|---|---|---| -| [Authentication and authorization](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/auth) | concept + how-to | 30 min | -| [Sharing and permissions](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/sharing-and-perm) | how-to | 20 min | -| [Limits and calling patterns](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/limits-calling) | reference | 10 min | -| [Fluid Framework](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/fluid) | how-to | 25 min | -| [AI knowledge source in Microsoft Foundry](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/declarative-agent/sharepoint-embedded-knowledge-source) | how-to | 25 min | - -> [!IMPORTANT] -> AI knowledge source in Microsoft Foundry is in **Preview**. API surface, permissions, and pricing may change before general availability. - -**Next step:** for end-user-facing capabilities, proceed to [Developer — Content experiences](#dev-content-experiences). - ---- - -## 4. Developer — Content experiences {#dev-content-experiences} - -**Use this section if:** you are adding Office editing, file browsing, or search inside your application's user interface. - -| Page | Type | Estimated time | -|---|---|---| -| [Office experiences](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/content-experiences/office-experience) | how-to | 20 min | -| [User experiences overview](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/content-experiences/user-experiences-overview) | concept | 10 min | -| [Search content](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/content-experiences/search-content) | how-to | 20 min | - -**Next step:** for step-by-step recipes on specific scenarios, proceed to [Tutorials](#tutorials). - ---- - -## 5. Tutorials {#tutorials} - -**Use this section if:** you have a specific scenario (preview, webhook, migration, etc.) and want a step-by-step recipe. - -| Page | Type | Estimated time | -|---|---|---| -| [Launch experience (Office client modes)](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/launch-experience) | how-to | 20 min | -| [Using metadata on containers](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/metadata) | how-to | 15 min | -| [File preview in iFrame](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/using-file-preview) | how-to | 20 min | -| [Document processing with Azure AI](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/doc-processing-acs) | how-to | 40 min | -| [Using webhooks](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/using-webhooks) | how-to | 25 min | -| [Migrate Azure Blob Storage to SPE](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/migrate-abs-to-spe) | how-to | 60 min | -| [Install app in a customer tenant](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/vendor-install-app-customer) | how-to | 30 min | - ---- - -## 6. Developer Admin / ISV — Billing & tenant management {#dev-admin-billing} - -**Use this section if:** you are an ISV or developer admin configuring pay-as-you-go billing or managing your partner tenant's SPE applications. - -| Page | Type | Estimated time | -|---|---|---| -| [Billing overview](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/billing/billing) | concept | 10 min | -| [Billing management](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/billing/billingmanagement) | how-to | 20 min | -| [Billing meters](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/billing/meters) | reference | 10 min | -| [Developer admin role](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/developer-admin/dev-admin) | how-to | 15 min | -| [SharePoint Embedded admin overview](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/adminrole) | concept | 10 min | - ---- - -## 7. Consuming Tenant Admin {#consuming-tenant-admin} - -**Use this section if:** you are an administrator in a Microsoft 365 tenant that has installed one or more SPE-based applications. - -| Page | Type | Estimated time | -|---|---|---| -| [Consuming tenant admin overview](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/consuming-tenant-admin/cta) | concept | 15 min | -| [Container management in PowerShell](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell) | reference | 15 min | -| [Admin UX (SharePoint Admin Center)](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctaux) | how-to | 15 min | - ---- - -## 8. Compliance & Security Officer {#compliance-security} - -**Use this section if:** you are responsible for applying Microsoft Purview policies and governing content stored in SPE containers. - -| Page | Type | Estimated time | -|---|---|---| -| [Security and compliance (Microsoft Purview)](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/compliance/security-and-compliance) | concept | 25 min | - -### Reference (cross-cutting) - -| Page | Type | -|---|---| -| [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/api/overview) | reference | -| [PowerShell cmdlets for SharePoint Embedded](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell) | reference | - ---- - -## Navigation manifest (for agents) {#navigation-manifest} - -The block below is the machine-readable form of this page. Agents SHOULD parse it instead of scraping the human tables above; the two are kept in sync. - -```yaml -manifest_version: 1 -generated: 2026-06-09 -sections: - - id: new-to-spe - title: New to SharePoint Embedded - role: new-user - intent: orient - pages: - - { uri: /sharepoint/dev/embedded/overview, task_type: concept } - - { uri: /sharepoint/dev/embedded/scenarios-and-use-cases, task_type: concept } - - { uri: /sharepoint/dev/embedded/whats-new, task_type: reference } - - { uri: /training/modules/sharepoint-embedded-setup, task_type: quickstart } - - { uri: /training/modules/sharepoint-embedded-create-app, task_type: quickstart } - - id: dev-setup - title: Developer — Set up your environment - role: app-developer - intent: set-up-dev-env - pages: - - { uri: /sharepoint/dev/embedded/getting-started/spembedded-for-vscode, task_type: quickstart } - - { uri: /sharepoint/dev/embedded/getting-started/containertypes, task_type: how-to } - - { uri: /sharepoint/dev/embedded/getting-started/register-api-documentation, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/app-architecture, task_type: concept } - - id: dev-build - title: Developer — Build your app - role: app-developer - intent: build-app - pages: - - { uri: /sharepoint/dev/embedded/development/auth, task_type: concept-and-how-to } - - { uri: /sharepoint/dev/embedded/development/sharing-and-perm, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/limits-calling, task_type: reference } - - { uri: /sharepoint/dev/embedded/development/fluid, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/declarative-agent/sharepoint-embedded-knowledge-source, task_type: how-to, stability: preview } - - id: dev-content-experiences - title: Developer — Content experiences - role: app-developer - intent: build-content-experience - pages: - - { uri: /sharepoint/dev/embedded/development/content-experiences/office-experience, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/content-experiences/user-experiences-overview, task_type: concept } - - { uri: /sharepoint/dev/embedded/development/content-experiences/search-content, task_type: how-to } - - id: tutorials - title: Tutorials - role: app-developer - intent: follow-tutorial - pages: - - { uri: /sharepoint/dev/embedded/development/tutorials/launch-experience, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/tutorials/metadata, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/tutorials/using-file-preview, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/tutorials/doc-processing-acs, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/tutorials/using-webhooks, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/tutorials/migrate-abs-to-spe, task_type: how-to } - - { uri: /sharepoint/dev/embedded/development/tutorials/vendor-install-app-customer, task_type: how-to } - - id: dev-admin-billing - title: Developer Admin / ISV — Billing & tenant management - role: developer-admin - intent: configure-billing - pages: - - { uri: /sharepoint/dev/embedded/administration/billing/billing, task_type: concept } - - { uri: /sharepoint/dev/embedded/administration/billing/billingmanagement, task_type: how-to } - - { uri: /sharepoint/dev/embedded/administration/billing/meters, task_type: reference } - - { uri: /sharepoint/dev/embedded/administration/developer-admin/dev-admin, task_type: how-to } - - { uri: /sharepoint/dev/embedded/administration/adminrole, task_type: concept } - - id: consuming-tenant-admin - title: Consuming Tenant Admin - role: consuming-tenant-admin - intent: admin-consuming-tenant - pages: - - { uri: /sharepoint/dev/embedded/administration/consuming-tenant-admin/cta, task_type: concept } - - { uri: /sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell, task_type: reference } - - { uri: /sharepoint/dev/embedded/administration/consuming-tenant-admin/ctaux, task_type: how-to } - - id: compliance-security - title: Compliance & Security Officer - role: compliance-officer - intent: govern-content - pages: - - { uri: /sharepoint/dev/embedded/compliance/security-and-compliance, task_type: concept } - reference: - - { uri: /graph/api/overview, task_type: reference, owner: graph-docs } - - { uri: /sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell, task_type: reference } -routing_rules: - - if: user_intent in ["evaluate", "orient", "what-is-spe"] - then_section: new-to-spe - - if: user_intent in ["first-time-setup", "set-up-dev-env", "create-app-registration", "create-container-type"] - then_section: dev-setup - - if: user_intent in ["auth", "permissions", "scale", "fluid", "ai-knowledge-source"] - then_section: dev-build - - if: user_intent in ["office-editing", "file-browser", "search-ui"] - then_section: dev-content-experiences - - if: user_intent in ["webhook", "metadata", "file-preview", "migration", "install-tenant", "doc-processing"] - then_section: tutorials - - if: user_intent in ["billing", "payg", "meters", "developer-admin"] - then_section: dev-admin-billing - - if: user_intent in ["consuming-tenant", "tenant-admin-installed-apps", "powershell"] - then_section: consuming-tenant-admin - - if: user_intent in ["compliance", "purview", "ediscovery", "retention"] - then_section: compliance-security -ambiguity_fallback: new-to-spe -``` - -## Related - -- [/llms.txt](https://learn.microsoft.com/sharepoint/dev/embedded/llms.txt) — corpus-wide agent index -- [/api-surface.json](https://learn.microsoft.com/sharepoint/dev/embedded/api-surface.json) — every Microsoft Graph operation referenced by SPE docs -- [Microsoft Graph SPE API reference](https://learn.microsoft.com/en-us/graph/api/resources/filestoragecontainer) - -## Structured data {#structured-data} - -```html - -``` diff --git a/docs/embedded/SharePoint Embedded Documentation.md b/docs/embedded/SharePoint Embedded Documentation.md index 36f5a14ab0..aa51aece86 100644 --- a/docs/embedded/SharePoint Embedded Documentation.md +++ b/docs/embedded/SharePoint Embedded Documentation.md @@ -1,99 +1,107 @@ -# SharePoint Embedded Documentation - -SharePoint Embedded is a cloud-based, API-only file and document management platform built on Microsoft 365 infrastructure. It lets developers embed Office collaboration, Purview compliance, and Copilot capabilities directly into their own applications — while keeping documents securely within each customer's Microsoft 365 tenant. - -> **5-minute quickstart:** [Get started with the VS Code Extension](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/getting-started/spembedded-for-vscode) - +--- +title: SharePoint Embedded documentation +description: Task-based index for SharePoint Embedded. Find the right page by what you are trying to do, whether you build apps or administer them. +ms.date: 06/25/2026 +ms.localizationpriority: high --- -## I'm new to SharePoint Embedded +# SharePoint Embedded documentation -| | | -|---|---| -| **Understand the platform** | Read the [Overview](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/overview) to learn what SharePoint Embedded is and how it fits into Microsoft 365. | -| **Explore use cases** | See [Scenarios and Use Cases](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/scenarios-and-use-cases) to understand what you can build. | -| **See what's new** | Check [What's New](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/whats-new) for the latest feature releases and updates. | -| **Take a learning path** | Follow the guided modules: [Overview & Configuration](https://learn.microsoft.com/en-us/training/modules/sharepoint-embedded-setup) · [Building Applications](https://learn.microsoft.com/en-us/training/modules/sharepoint-embedded-create-app) | +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 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. For the machine-readable index, see [llms.txt](./llms.txt). -## I'm building an application (Developer) +> [!TIP] +> New here? Read [What is SharePoint Embedded?](./overview.md) first, then come back to pick a task. -### Set up your environment + -| | | -|---|---| -| **VS Code Extension** | [SharePoint Embedded VS Code Extension](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/getting-started/spembedded-for-vscode) — create and manage container types directly from VS Code. | -| **Container Types** | [Container Types](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/getting-started/containertypes) — understand the foundational storage unit of SharePoint Embedded. | -| **Register via API** | [Register Container Type API](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/getting-started/register-api-documentation) — register your container type programmatically. | +## Two roads -### Design and develop +Almost everyone is one of two people. Architects, IT decision makers, billing admins, and compliance admins each merge onto one of these: -| | | -|---|---| -| **Architecture** | [Application Architecture](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/app-architecture) — understand the overall system design, components, and integration patterns. | -| **Authentication** | [Authentication and Authorization](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/auth) — configure delegated and app-only permissions via Microsoft Entra ID and Graph API. | -| **Permissions** | [Sharing and Permissions](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/sharing-and-perm) — manage the additive permissions model for containers, folders, and files. | -| **Scale limits** | [Limits and Calling Patterns](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/limits-calling) — plan for storage, container, and API throttling limits. | -| **Real-time collaboration** | [Fluid Framework](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/fluid) — integrate Fluid Framework for live collaborative experiences. | -| **AI Agent integration** | [SharePoint Embedded Knowledge Source in Microsoft Foundry (Preview)](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/declarative-agent/sharepoint-embedded-knowledge-source) — use SPE containers as a knowledge source for declarative agents. | +| You are… | You want to… | Start at | +|---|---|---| +| Developer / architect | Build and ship an app | [Build an app](#build-an-app) | +| ISV / developer admin | Onboard customers and bill | [Publish and onboard customers](#publish-and-onboard-customers) | +| SharePoint / tenant 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) | -### Build content experiences +## Plan a solution -| | | -|---|---| -| **Office experiences** | [Office Experiences](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/content-experiences/office-experience) — open Word, Excel, and PowerPoint files for viewing and editing; enable co-authoring and AutoSave. | -| **User experiences** | [User Experiences Overview](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/content-experiences/user-experiences-overview) — build file browsing, upload, and management UX within your app. | -| **Search** | [Search Content](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/content-experiences/search-content) — index and search across container content using Microsoft Search. | +Decide how SPE fits before you write code. -### Follow step-by-step tutorials +- [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-and-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) -| Tutorial | What you'll learn | -|---|---| -| [Launch Experience](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/launch-experience) | Control Office client launch modes (view vs. edit) via the Graph `webUrl`. | -| [Using Metadata](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/metadata) | Add and query custom metadata on SharePoint Embedded containers. | -| [File Preview in iFrame](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/using-file-preview) | Embed a file preview (PDF, images, Office files) using the Graph preview endpoint. | -| [Document Processing with Azure AI](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/doc-processing-acs) | Enrich documents with Azure Cognitive Services (OCR, classification, extraction). | -| [Webhooks](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/using-webhooks) | React to container and file change events using webhooks. | -| [Migrate ABS to SPE](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/migrate-abs-to-spe) | Move content from Azure Blob Storage into SharePoint Embedded containers. | -| [Install App in a Customer Tenant](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/vendor-install-app-customer) | Walk through the ISV-to-customer app installation and billing setup flow. | +## Build an app ---- +An ordered journey from first container to a full-featured app. -## I'm managing billing and tenants (Developer Admin / ISV) +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. [Migrate from Azure Blob Storage](./build/migrate-azure-blob-storage.md) -| | | -|---|---| -| **Understand billing** | [Billing Overview](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/billing/billing) — learn about standard and pass-through billing models. | -| **Manage billing** | [Billing Management](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/billing/billingmanagement) — link Azure subscriptions, configure billing for your app. | -| **Monitor usage** | [Billing Meters](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/billing/meters) — understand storage and API transaction meters that drive costs. | -| **Developer admin role** | [Developer Admin](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/developer-admin/dev-admin) — use the SharePoint Embedded Administrator role in Entra ID to manage container types and billing via PowerShell. | -| **Admin role overview** | [SharePoint Embedded Admin](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/adminrole) — overview of admin roles and responsibilities across partner and consuming tenants. | +## Publish and onboard customers ---- +For ISVs shipping a multitenant app. -## I'm a tenant administrator (Consuming Tenant Admin) +- [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) -| | | -|---|---| -| **Admin overview** | [Consuming Tenant Admin](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/consuming-tenant-admin/cta) — manage SharePoint Embedded apps installed in your Microsoft 365 tenant. | -| **PowerShell management** | [Container Management in PowerShell](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell) — list, inspect, and manage containers in your tenant via PowerShell cmdlets. | -| **Admin UX** | [Consuming Tenant Admin UX](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctaux) — manage containers through the SharePoint admin center UI. | +## Install and manage apps ---- +For administrators of a Microsoft 365 tenant that uses SPE apps. -## I'm responsible for compliance and security (Compliance / Security Officer) +- [Admin overview](./admin/admin-overview.md) +- [Create apps in SharePoint admin center](./admin/create-apps-sharepoint-admin-center.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-m365-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) -| | | -|---|---| -| **Security & Compliance** | [Security and Compliance](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/compliance/security-and-compliance) — apply Microsoft Purview compliance policies (retention, eDiscovery, sensitivity labels) to SharePoint Embedded containers. | +## 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](./llms.txt) — machine-readable corpus index for coding agents -## Reference +## More -| | | -|---|---| -| **GitHub source** | [sp-dev-docs/docs/embedded](https://github.com/SharePoint/sp-dev-docs/tree/live/docs/embedded) — file issues or contribute to documentation. | -| **Graph API** | [Microsoft Graph API reference](https://learn.microsoft.com/en-us/graph/api/overview) — all SharePoint Embedded APIs are Graph-based. | -| **What's New** | [Release notes and changelog](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/whats-new) | +- [Scenarios and use cases](./scenarios-and-use-cases.md) +- [What's new](./whats-new.md) +- [Microsoft Graph SPE API reference](/graph/api/resources/filestoragecontainer) diff --git a/docs/embedded/admin/admin-overview.md b/docs/embedded/admin/admin-overview.md new file mode 100644 index 0000000000..b847235f29 --- /dev/null +++ b/docs/embedded/admin/admin-overview.md @@ -0,0 +1,176 @@ +--- +title: Admin Overview +description: Learn how administrators manage SharePoint Embedded apps, containers, billing, and compliance in Microsoft 365. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# Admin Overview + +**Applies to:** Administrator — SharePoint admin / tenant admin + + + +SharePoint Embedded (SPE) is an API-only document platform built on Microsoft 365. +Organizations use SPE 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 SPE 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 SPE admin task when needed. | +| SharePoint Embedded Administrator | Manage SPE apps and containers through SharePoint admin center and supported SharePoint PowerShell cmdlets. | +| SharePoint administrator | Manage SharePoint service configuration and SPE experiences in the SharePoint admin center when applicable. | +| Tenant administrator | Manage apps and settings in the consuming Microsoft 365 tenant. | +| Compliance administrator | Configure Microsoft Purview audit, retention, DLP, eDiscovery, and related policies. | + +The SharePoint Embedded Administrator role is available in Microsoft Entra and the Microsoft 365 admin center. +It is dedicated to SPE administration. +It does not grant regular SharePoint site management access. +For example, a SharePoint Embedded Administrator does not see the **Active sites** or **Deleted sites** pages in the SharePoint admin center and cannot run site-specific SharePoint PowerShell cmdlets. + +For role assignment details, see [SharePoint Embedded administrator](../administration/adminrole.md). + +## Developer tenant and consuming tenant responsibilities + +SPE administration differs depending on whether the tenant owns the app or consumes the app. + +A developer tenant owns or builds the SPE application. +Developer tenant admins can create container types, configure billing for standard billing scenarios, and manage container type properties. + +A consuming tenant uses an SPE application in its Microsoft 365 tenant. +Consuming tenant admins manage installed applications, containers, sharing settings, sensitivity labels, deleted containers, billing for pass-through apps, and compliance controls. + +For the consuming tenant admin model, see [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md). + +## What admins can do + +Administrators can perform these SPE management tasks. + +### App administration + +- View SPE applications registered in the tenant. +- View details for a specific SPE application. +- Review owning and guest application permissions. +- Install or register an SPE 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 + +SPE 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. + +Set up pass-through billing with [Set up billing in Microsoft 365 admin center](setup-billing-m365-admin-center.md). +Monitor usage with [Monitor usage, billing, and cost](monitor-usage-billing-cost.md). + +### Container administration + +Containers hold the content used by SPE apps. +Admins can view active 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 + +SPE 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 are 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 SPE-specific pages such as **Apps**, **Active containers**, and **Deleted containers**. +A SharePoint Embedded Administrator sees the SPE administration pages but not general SharePoint site management pages. + +SharePoint Online Management Shell provides SPE 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 an SPE app: + +1. Confirm the admin role in [SharePoint Embedded administrator](../administration/adminrole.md). +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 an SPE 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-m365-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 are permanently deleted or retention policies change the behavior. + +> [!WARNING] +> Permanently deleting a container removes it from the deleted container collection and it cannot be restored. +> Notify app owners before deleting containers. + +## Related content + +- [SharePoint Embedded administrator](../administration/adminrole.md) +- [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) +- [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-m365-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 step + +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..5f6c9e281c --- /dev/null +++ b/docs/embedded/admin/apply-security-compliance-controls.md @@ -0,0 +1,237 @@ +--- +title: Apply Security and Compliance Controls +description: Apply Microsoft Purview and SharePoint controls to protect and govern SharePoint Embedded content. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# Apply Security and Compliance Controls + +**Applies to:** Administrator — compliance admin / tenant admin + + + +Apply security and compliance controls to SharePoint Embedded (SPE) content by using Microsoft Purview and supported SharePoint administration features. +SPE 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 SPE is API-only and does not have its own user interface. + +> [!IMPORTANT] +> Coordinate compliance controls with the SPE app owner. +> A policy can protect content, but app-specific user prompts or override experiences must be implemented by the owning app when required. + +## 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 SPE 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 [Security and Compliance](../compliance/security-and-compliance.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 SPE 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 + ``` + +The source security and compliance article uses the container site URL to target policies at specific SPE containers. +For cmdlet details, see [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer). + +## Apply audit controls + +Audit capabilities for SPE mirror existing SharePoint audit capabilities. +User and admin operations performed in SPE applications are captured in the unified audit log. + +SPE audit events include additional data that helps isolate embedded content: + +- `ContainerInstanceId` +- `ContainerTypeId` + +Use Microsoft Purview audit to search activity and investigate file, user, app, and admin operations. + +For audit review steps, see [Review audit events](review-audit-events.md). + +## Apply eDiscovery + +Compliance admins can use Microsoft Purview eDiscovery to search, hold, and export content hosted in SPE. + +To search all SPE 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. + +To limit the search to selected SPE 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. + +For product guidance, see [Microsoft Purview eDiscovery solutions](/purview/ediscovery). + +## Apply retention and holds + +SPE supports retention and hold policies on content stored in applications through Microsoft Purview. +The source documentation describes these scoping options. + +| Scope | Effect | +| --- | --- | +| All SharePoint sites | Applies to SharePoint sites and SPE containers. | +| Selected locations | Applies to specific SharePoint locations, including selected SPE container URLs. | + +Use broad scope when a policy applies to all SharePoint and SPE content. +Use selected container URLs when a policy applies only to specific embedded app data. + +> [!NOTE] +> SPE does not 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 SPE 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 SPE containers. +1. Configure rules, actions, and alerts. +1. Test and then enable the policy according to your rollout process. + +To apply DLP to selected SPE 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. + +Some DLP scenarios require user interaction, such as business justification for override or policy tips. +Because SPE does not 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 Administrators can set or remove sensitivity labels on SPE 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 + +The source security article states that SharePoint Administrators or Global Administrators can block download of files from SPE containers by using 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 + +SPE supports basic Conditional Access policy configurations. +The source security article lists these values: + +- `AllowFullAccess` +- `AllowLimitedAccess` +- `BlockAccess` + +Use the supported SharePoint PowerShell cmdlet shape from the source documentation. + +```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 admins | Retrieve container details and apply supported SharePoint or container settings. | +| SPE 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 SPE 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) +- [Security and Compliance](../compliance/security-and-compliance.md) +- [Troubleshooting](../reference/troubleshooting.md) + +## Next step + +Review troubleshooting guidance in [Troubleshooting](../reference/troubleshooting.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..601884a03c --- /dev/null +++ b/docs/embedded/admin/create-apps-sharepoint-admin-center.md @@ -0,0 +1,199 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- + +# Create Apps in SharePoint Admin Center + +**Applies to:** Administrator — SharePoint admin / tenant admin + + + +Use the SharePoint admin center **Apps** experience to create a SharePoint Embedded (SPE) app that your organization owns. +The create flow can register a new Microsoft Entra app or associate an existing Entra app with a new SPE app. + +This article summarizes the administrator flow and links to source documentation for command and API details. + +> [!IMPORTANT] +> You need the **SharePoint Embedded Administrator** role or Global Administrator privileges to create and manage SPE apps in the SharePoint admin center. + +## 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](../administration/adminrole.md). + +## Understand the Apps page + +In the SharePoint admin center, SPE apps are managed from **SharePoint Embedded** > **Apps**. +The page includes app inventory views. + +| Tab | Use it for | +| --- | --- | +| All installed apps | Review SPE applications installed in the tenant. | +| Owned apps | Review SPE applications created and managed by your organization, including apps that are not currently installed. | + +The **Owned apps** tab shows app ownership and billing details. +Use it to verify app creation and to start installation when an app is ready. + +> [!TIP] +> Use **Owned apps** as the tenant inventory for apps your organization builds. +> Use **All 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. + +## 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 SPE 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. + +Do not create duplicate app registrations unless your app architecture requires them. +Use one owning application for the SPE 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. +Choose durable administrative owners instead of individual temporary project members. + +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 SPE consumption. +Choose carefully because the source app creation guidance states that billing type cannot 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-m365-admin-center.md) and [Monitor usage, billing, and cost](monitor-usage-billing-cost.md). + +## Configure owner organization billing + +If you select **Owner org**, configure the billing subscription. + +1. Choose whether to set up billing now or later. +1. If setting up now, provide the subscription information requested by the admin center. +1. Confirm that the subscription and resource group are valid. +1. Complete the billing step before you create the app when the app must be active immediately. + +If you select **Setup later**, the app can be created but remains inactive until billing is configured. + +> [!NOTE] +> For pass-through billing, the consuming tenant admin sets up billing in the Microsoft 365 admin center before users can access the app. + +## Configure advanced settings + +Expand **Advanced settings** when you need optional settings. +The source create-app guidance describes a **Graph Explorer** toggle for 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 is not 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**. + +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 **All 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 does not 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 is not 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 cannot access the app after creation, verify installation, admin consent, and container type permissions. + +> [!WARNING] +> Do not 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-m365-admin-center.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) +- [SharePoint Embedded administrator](../administration/adminrole.md) +- [Manage containers in SharePoint Admin Center](../administration/consuming-tenant-admin/ctaUX.md) + +## Next step + +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..bd9d17a1b7 --- /dev/null +++ b/docs/embedded/admin/grant-admin-consent-permissions.md @@ -0,0 +1,195 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- + +# Grant Admin Consent and Permissions + +**Applies to:** Administrator — tenant admin / SharePoint admin + + + +Grant admin consent when a SharePoint Embedded (SPE) app needs tenant-wide permissions in a consuming Microsoft 365 tenant. +Consent installs the app service principal and authorizes the permissions required by the app. +For container type registration, consent must be in place before the owning app can register permissions for containers in the consuming tenant. + +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 sign in as a tenant administrator who can grant admin consent. +- You know the consuming tenant ID. +- 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. + +For the consuming tenant admin role, see [Admin overview](admin-overview.md). + +## Understand consent in SPE + +The source registration API documentation states that 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 admin consent to perform container type registration in the consuming tenant. + +Both requirements can be satisfied when a tenant administrator grants admin consent to the owning application. + +The container type registration API requires the `Container.Selected` app-only permission for SharePoint. +It is a SharePoint API and not a Microsoft Graph API in the source documentation. +The app uses the client credentials grant flow and certificate-based token request for that registration API. + +For API details, see [Register file storage container type application permissions](../getting-started/register-api-documentation.md). + +## Review requested permissions + +Before granting consent, review the requested permissions with the app owner. + +| Review item | Why it matters | +| --- | --- | +| Application client ID | Confirms you are 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 does not align with the expected scenario. + +> [!CAUTION] +> Do not grant consent from a copied URL unless you have verified the `client_id` value. +> A consent URL grants permissions to the app identified by that client ID. + +## Grant admin consent from the consent endpoint + +The source guidance shows the Microsoft identity platform admin consent endpoint. +Use the tenant and client IDs for your environment. + +```http +https://login.microsoftonline.com//adminconsent?client_id= +``` + +1. Replace `` with the consuming tenant ID. +1. Replace `` with the owning application client ID. +1. Open the URL in a browser session signed in as an administrator who can grant consent. +1. Review the app name and publisher. +1. Review requested permissions. +1. Accept only if the request matches the approved app. +1. Follow the success or failure redirect configured by the app owner. + +For Microsoft identity platform details, see [Admin consent URI](/entra/identity-platform/v2-admin-consent). +For national cloud endpoints, see [Microsoft Entra authentication endpoints on national clouds](/entra/identity-platform/authentication-national-cloud#microsoft-entra-authentication-endpoints). + +## Grant consent from Microsoft Entra admin experiences + +If your organization uses Microsoft Entra admin center workflows, grant consent through the enterprise application experience when available. + +1. Open the Microsoft Entra admin center. +1. Locate the enterprise application for the SPE owning app. +1. Review the app properties and publisher. +1. Review permissions. +1. Grant tenant-wide admin consent if the request is approved. +1. Confirm the consent status after the operation completes. + +Use your organization's privileged access process for approval. +Keep a record of who approved the request and why. + +## Verify the service principal + +After consent, confirm that the app is represented in the consuming tenant. + +1. In Microsoft Entra, search for the enterprise application by application ID or name. +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 did not complete or targeted a different tenant. + +## Verify SPE application state + +After consent, validate the SPE app from the SharePoint admin center or PowerShell. + +In the SharePoint admin center: + +1. Go to **SharePoint Embedded** > **Apps**. +1. Confirm the app appears in the appropriate app inventory. +1. Review app details and billing status. + +With SharePoint Online Management Shell, use the application inventory command documented for consuming tenant admins. + +```powershell +Get-SPOApplication +``` + +For a specific owning app, use: + +```powershell +Get-SPOApplication -OwningApplicationId +``` + +For command details, see [Get-SPOApplication](/powershell/module/sharepoint-online/get-spoapplication). + +## Understand container type permissions + +The registration API determines what permissions SPE applications can perform against containers and content for a specified container type. +The source documentation lists permissions such as read, write, create, delete, read content, write content, and permissions management. + +Do not manually invent or assume permission names. +Use the permission names and request format documented in [Register file storage container type application permissions](../getting-started/register-api-documentation.md). + +The last successful registration API call determines the active permission settings in the consuming tenant. +Ask the app owner to confirm when registration has completed. + +## 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 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 is not blocked by publisher or enterprise app policies. + +## Troubleshoot access denied after consent + +Use these checks when consent succeeds but API calls fail. + +- Confirm the app owner registered container type permissions after consent. +- Confirm the app is the owning application for the container type when invoking the registration API. +- Confirm the app uses the required SharePoint permission. +- Confirm the app uses app-only authentication when required. +- Confirm the app uses certificate-based client credentials for the registration API. +- Confirm the consuming tenant SharePoint root site URL is correct. +- Confirm billing is active when the app uses pass-through billing. + +> [!NOTE] +> The registration API source states that failure to register permissions can result in access denied errors when invoking other APIs against containers or content. + +## Related content + +- [Install a SharePoint Embedded app](install-sharepoint-embedded-app.md) +- [Set up billing in Microsoft 365 admin center](setup-billing-m365-admin-center.md) +- [Manage containers with PowerShell](manage-containers-powershell.md) +- [Register file storage container type application permissions](../getting-started/register-api-documentation.md) +- [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) + +## Next step + +Configure billing in [Set up billing in Microsoft 365 admin center](setup-billing-m365-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..06483e40f0 --- /dev/null +++ b/docs/embedded/admin/install-sharepoint-embedded-app.md @@ -0,0 +1,187 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- + +# Install a SharePoint Embedded App + +**Applies to:** Administrator — SharePoint admin / tenant admin + + + +Install a SharePoint Embedded (SPE) 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 SPE administration tasks. + +Use this article with [Choose an App Model: Single-Tenant or Multitenant](../plan/choose-app-model.md), [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.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 SPE 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) and [SharePoint Embedded administrator](../administration/adminrole.md). + +## Understand the consuming tenant path + +A consuming tenant is the Microsoft 365 tenant where users run the SPE 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. + +The source consuming-tenant admin guidance describes 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 SPE **Apps** experience in the SharePoint admin center when the app is available to install. + +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 **All 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. +Do not continue if the app identity or publisher is unexpected. + +> [!CAUTION] +> Install only apps that your organization trusts. +> An SPE app can create and access containers according to the permissions granted to it. + +## Validate installation + +After installation, validate the app inventory. + +1. Return to **SharePoint Embedded** > **Apps**. +1. Open **All 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. + +If the app is not 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 registration API source states that the owning app must have a service principal installed in the consuming tenant and must be granted admin consent before it can register container type application permissions. + +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//adminconsent?client_id= +``` + +Use the exact client ID provided by the app owner. +Do not substitute a different application ID. + +## Confirm billing requirements + +SPE supports standard and pass-through billing models. +For pass-through billing, the consuming tenant admin must set up billing in the Microsoft 365 admin center before users can access the app. + +If billing is invalid or SharePoint Embedded is turned off, users immediately lose access to apps built on the service. + +Use [Set up billing in Microsoft 365 admin center](setup-billing-m365-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 described in the source documentation. + +```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). + +## Troubleshoot installation + +Use these checks when installation does not 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-m365-admin-center.md) +- [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md) +- [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) +- [Create a SharePoint Embedded app in the SharePoint admin center](../administration/consuming-tenant-admin/SPE_app_installation_on_SPAC.md) + +## Next step + +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..53fc39e538 --- /dev/null +++ b/docs/embedded/admin/manage-containers-powershell.md @@ -0,0 +1,255 @@ +--- +title: Manage Containers with PowerShell +description: Use SharePoint Online Management Shell to inventory and manage SharePoint Embedded apps and containers. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# Manage Containers with PowerShell + +**Applies to:** Administrator — SharePoint admin / tenant admin + + + +Use SharePoint Online Management Shell to automate SharePoint Embedded (SPE) application and container administration. +PowerShell is useful for inventory, reporting, lifecycle operations, sensitivity label updates, sharing configuration, and permission review. + +This article summarizes the consuming tenant administrator cmdlets from the source documentation and links to the cmdlet reference for details. + +> [!IMPORTANT] +> Use the latest version of SharePoint Online Management Shell before running SPE 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](../administration/adminrole.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. + +The source documentation directs admins to install the latest shell and connect to SharePoint Online before using SPE 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 SPE 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 + +Use the source-documented command shape to view guest application permissions for an SPE application. + +```powershell +Get-SPOApplication -OwningApplicationId -ApplicationId +``` + +`OwningApplicationId` is the ID of the SPE owning application. +`ApplicationId` is the guest application ID that has access to the SPE application. + +The source documentation states that application administration cmdlets do not 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 +``` + +The source documentation lists these `SharingCapability` 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 an SPE application. + +```powershell +Get-SPOContainer -OwningApplicationId | FT +``` + +The `OwningApplicationId` is the ID of the SPE application. + +For Microsoft Loop containers, the source documentation lists this owning app ID for 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). + +## 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 SPE 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 cannot 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 SPE applications. +The source documentation identifies `Set-SPOApplicationPermission` for this scenario. + +```powershell +Set-SPOApplicationPermission + [[-OwningApplicationId] ] + [[-ApplicationId] ] + [[-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) +- [Consuming Tenant Admin PowerShell](../administration/consuming-tenant-admin/ctapowershell.md) + +## Next step + +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..57f59fa039 --- /dev/null +++ b/docs/embedded/admin/manage-containers-sharepoint-admin-center.md @@ -0,0 +1,212 @@ +--- +title: Manage Containers in SharePoint Admin Center +description: View, inspect, delete, restore, and manage SharePoint Embedded containers in the SharePoint admin center. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# Manage Containers in SharePoint Admin Center + +**Applies to:** Administrator — SharePoint admin / tenant admin + + + +Use the SharePoint admin center to manage SharePoint Embedded (SPE) containers through a graphical experience. +The SPE container pages help consuming tenant admins view active containers, inspect details, manage membership, apply sensitivity labels, delete containers, restore deleted containers, and permanently delete containers. + +> [!IMPORTANT] +> To manage SPE 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 SPE 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 **Deleted containers** to view containers in the deleted container collection. + +A SharePoint Embedded Administrator sees only the SPE-specific pages that apply to the role. +The role does not expose general SharePoint **Active sites** or **Deleted sites** pages. + +## View active containers + +The **Active containers** page shows active containers in the tenant. +Use it for inventory, compliance review, and lifecycle decisions. + +The source admin center guidance lists these container properties. + +| Column or property | Meaning | +| --- | --- | +| Container name | Name provided by the container owner. | +| Application name | SPE 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. + +## 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] +> The source guidance notes that filtering behavior on the Active containers page differs from the Active sites page in the SharePoint admin center. + +## Inspect container details + +Open a container details panel when you need more information. +The details view includes two tabs in the source guidance. + +| 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. + +## Manage membership + +The SPE platform supports four roles: Owner, Manager, Writer, and Reader. +An individual SPE 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. + +## 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 described in the source admin center guidance. + +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. + +For broader controls, see [Apply security and compliance controls](apply-security-compliance-controls.md). + +## Delete a container + +Delete a container only when there is a clear business reason. +Container deletion can affect the SPE 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. + +> [!WARNING] +> Deleting a container may interrupt the associated SPE application. +> Notify app owners before deleting containers. + +## View deleted containers + +The **Deleted containers** page lists containers in the tenant deleted container collection. +The source guidance lists 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, 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. + +## 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. + +## 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 cannot be restored. + +> [!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) +- [Manage SharePoint Embedded containers in SharePoint Admin Center](../administration/consuming-tenant-admin/ctaUX.md) + +## Next step + +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..afcb515948 --- /dev/null +++ b/docs/embedded/admin/monitor-usage-billing-cost.md @@ -0,0 +1,185 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- + +# Monitor Usage, Billing, and Cost + +**Applies to:** Administrator — tenant admin / SharePoint admin + + + +Monitor SharePoint Embedded (SPE) usage and cost after billing is configured. +SPE uses pay-as-you-go billing through an Azure subscription. +Cost is based on usage meters, so administrators should review 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 are not charged as SPE API transactions according to the source meters documentation. + +## Before you begin + +Confirm these prerequisites. + +- SPE billing is configured for the app or tenant. +- You can access the Azure subscription linked to SPE 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-m365-admin-center.md). + +## Understand SPE meters + +The source meter documentation identifies three main SPE 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. | +| API transactions | Transactions | Microsoft Graph calls made explicitly by the SPE application. | +| Egress | GB | Data downloaded from SPE to a customer's client device, subject to exemptions. | + +Review the [SharePoint Embedded Billing Meters](../administration/billing/meters.md) source article for the latest details. + +## Monitor storage + +Storage consumption includes more than current visible files. +The source documentation states that 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 SPE application is counted as one transaction in the source meter documentation. +Calls made by internal services to containers are not charged when the application has no control over those calls. + +Examples of nonchargeable transactions from the source 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 SPE to a customer's client device. +The source meter documentation also identifies exemptions. + +Examples of exempt transfers from the source include: + +- File downloads from the SPE application server to the customer's Office Desktop client. +- File downloads from the SPE 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 do not see it, search for **Cost Management + Billing**. +1. Select the subscription linked to SPE billing. +1. Open the subscription overview to review current spending, forecasted costs, and anomalies. + +For the source billing management steps, see [SharePoint Embedded Billing Management](../administration/billing/billingmanagement.md). + +## 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. + +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 do not 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. + +> [!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 SPE 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-m365-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 Management](../administration/billing/billingmanagement.md) +- [SharePoint Embedded Billing Meters](../administration/billing/meters.md) + +## Next step + +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..4f5134cfb1 --- /dev/null +++ b/docs/embedded/admin/review-audit-events.md @@ -0,0 +1,208 @@ +--- +title: Review Audit Events +description: Find and interpret SharePoint Embedded audit activity in Microsoft Purview audit. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# Review Audit Events + +**Applies to:** Administrator — compliance admin / tenant admin + + + +Review SharePoint Embedded (SPE) audit activity in Microsoft Purview audit when investigating user, admin, file, or container activity. +SPE audit capabilities mirror existing SharePoint audit capabilities, and user and admin operations performed in SPE applications are captured in the organization's unified audit log. + + + +The requested source `docs\embedded\compliance\audit-events.md` wasn't present in this repository. +This article uses the available [Security and Compliance](../compliance/security-and-compliance.md) source and general Microsoft Purview audit guidance. + +> [!IMPORTANT] +> Use Microsoft Purview audit as the authoritative investigation surface for audit records. +> Use SPE 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 SPE application, container, user, or file involved. +- You can obtain container details from the SharePoint admin center or PowerShell when needed. + +For supported SPE compliance capabilities, see [Security and Compliance](../compliance/security-and-compliance.md). + +## Understand SPE audit coverage + +The source security and compliance article states that audit capabilities in SPE mirror existing SharePoint audit capabilities. +User and admin operations performed in applications hosted in SPE 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 SPE-specific fields + +In addition to existing SharePoint file properties, SPE audit events include extra data that helps isolate SPE content. +The source article identifies these fields: + +| Field | Use it for | +| --- | --- | +| `ContainerInstanceId` | Identify the specific SPE container instance involved in the event. | +| `ContainerTypeId` | Identify the SPE 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 SPE activity, filter or inspect these fields to isolate embedded content. + +## Get container context + +Before searching audit, collect the context you have. + +1. Identify the SPE 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. Run the search. +1. Open relevant results. +1. Inspect event details for SPE 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 does not 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. | +| Time stamp | 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 SPE container. | +| `ContainerTypeId` | Links the event to an SPE 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 SPE 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 SPE 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 SPE 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 an SPE 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](../compliance/security-and-compliance.md) +- [Auditing solutions in Microsoft Purview](/purview/audit-solutions-overview) + +## Next step + +Apply broader controls in [Apply security and compliance controls](apply-security-compliance-controls.md). diff --git a/docs/embedded/admin/setup-billing-m365-admin-center.md b/docs/embedded/admin/setup-billing-m365-admin-center.md new file mode 100644 index 0000000000..79d598568f --- /dev/null +++ b/docs/embedded/admin/setup-billing-m365-admin-center.md @@ -0,0 +1,175 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- + +# Set Up Billing in Microsoft 365 Admin Center + +**Applies to:** Administrator — tenant admin / SharePoint admin + + + +Set up SharePoint Embedded (SPE) 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 SPE app before valid billing is configured for the SPE platform in the consuming tenant. + +SPE billing is pay-as-you-go through Azure. +Charges are based on supported meters such as storage, API transactions, and egress. + +> [!IMPORTANT] +> If SharePoint Embedded is turned off or the linked Azure subscription is disconnected, users immediately lose access to apps built on the service. + +## Before you begin + +Confirm these prerequisites. + +- You can sign in to the [Microsoft 365 admin center](https://admin.microsoft.com/). +- You have the SharePoint Embedded Administrator role or Global Administrator role. +- 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 SPE 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 [SharePoint Embedded billing](../administration/billing/billing.md). + +## Understand billing models + +SPE supports two billing models in the source billing guidance. + +| 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. | + +For standard billing, the developer tenant admin sets up billing for the container type. +For pass-through billing, the consuming tenant admin sets up billing in the Microsoft 365 admin center. + +This article focuses on the consuming tenant pass-through path. + +## Understand cost meters + +SPE uses a consumption-based model. +The source meter documentation identifies three primary meters. + +| Meter | What it measures | +| --- | --- | +| Storage | Data stored in files, documents, metadata, versions, recycle bin, and deleted container collection. | +| API transactions | Microsoft Graph calls made explicitly by the SPE application. | +| Egress | Data downloaded from SPE to client devices, 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 source consuming tenant admin and billing guidance both describe this Microsoft 365 admin center path. + +> [!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 SPE billing to the appropriate Azure billing resources. + +1. Select the Azure subscription approved for SPE 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 SPE 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 does not 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 SPE 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 does not have the SharePoint Embedded Administrator or Global Administrator role. +- 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 has not turned on SPE 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 is not valid. +Look for these symptoms. + +- The SPE app is installed but inactive. +- Users cannot open content stored by the app. +- The SharePoint admin center shows billing warnings for the app. +- Azure Cost Management shows no linked usage because setup has not completed. +- Access stops immediately after SPE is turned off or the subscription is disconnected. + +> [!WARNING] +> Do not disconnect the linked Azure subscription during business hours unless you are intentionally stopping access to SPE apps. + +## Operational guidance + +After setup, establish a billing operations process. + +- Assign subscription owners who understand SPE 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 SPE 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) +- [SharePoint Embedded billing](../administration/billing/billing.md) +- [SharePoint Embedded Billing Meters](../administration/billing/meters.md) +- [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) + +## Next step + +Manage containers in [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md). diff --git a/docs/embedded/build/agent-experiences.md b/docs/embedded/build/agent-experiences.md new file mode 100644 index 0000000000..59613b244f --- /dev/null +++ b/docs/embedded/build/agent-experiences.md @@ -0,0 +1,122 @@ +--- +title: Add Microsoft 365 Copilot and Agent Experiences +description: Add SharePoint Embedded agent chat experiences grounded in container content. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Add Microsoft 365 Copilot and Agent Experiences +**Applies to**: Developer + + +SharePoint Embedded agent lets you add AI chat experiences to your application and ground answers in files stored in SharePoint Embedded containers. +The available sources describe a private preview React SDK, advanced configuration, and a Visual Studio Code sample path. +The requested knowledge source article was not present in this repository. +> [!NOTE] +> SharePoint Embedded agent is described in the source docs as private preview. Validate current terms, package versions, and billing before production use. +## Agent scenarios +Use agent experiences for document Q&A, summaries, workspace discovery, support answers, starter prompts, and scoped conversations. +The advanced source describes Retrieval-Augmented Generation over a semantic index. +The agent retrieves relevant content at query time and grounds responses in Microsoft 365 content boundaries. +## Create SPE agent experiences +Prerequisites include a SharePoint Embedded application, a standard container type, current SharePoint Online PowerShell, allowed embedded chat hosts, discoverability enabled, Microsoft 365 Copilot availability, and a Copilot-licensed test user. +Set `DiscoverabilityDisabled` to `false` and allow up to 24 hours for propagation when updating an existing container type. +Configure allowed chat iframe hosts with `Set-SPOContainerTypeConfiguration` and consuming tenant overrides with `Set-SPOApplication` when needed. +## Knowledge source setup +Scope the agent to the smallest useful content set. +Use file scope for document Q&A, folder scope for a case section, and container scope for the whole workspace. +Show the current scope in the UI. +The effective permissions are the intersection of the user's access and the app's access. +Confirm file type support before promising answers over specific formats. +## Advanced configuration +The React SDK source uses an auth provider with `hostname` and `getToken()`. +The tutorial shows the token scope `{hostname}/Container.Selected`. +Add the `ChatEmbedded` component with `authProvider` and `containerId`, store the API from `onApiReady`, and call `openChat()`. +Launch configuration can include header, starter prompts, suggested prompts, instruction, and locale. +Language behavior depends on Microsoft 365 and SharePoint language settings. +## Current deprecations and preview status +The overview states private preview status and consumption-based billing guidance for standard container types. +Trial container types expire after 30 days and are not recommended for agent scenarios. +Preview SDK package URLs and checksums can change; use the latest source before installing. +Some Visual Studio Code extension actions for standard container types may require SharePoint Online PowerShell. +## Troubleshooting +| Symptom | Check | +| --- | --- | +| Iframe does not load | Configure embedded chat hosts. | +| Files are not found | Check discoverability, indexing, scope, and permissions. | +| Sign-in fails | Check cookies and popup fallback. | +| Answers omit files | Verify supported formats and scope. | +| Trial type fails | Use a standard container type when required. | +## Related sources +- [SharePoint Embedded agent](../development/declarative-agent/spe-da.md) +- [SharePoint Embedded agent Advanced Topics](../development/declarative-agent/spe-da-adv.md) +- [Tutorial for getting started with SharePoint Embedded agent](../development/tutorials/spe-da-vscode.md) +## Next step +Continue with [Migrate from Azure Blob Storage](migrate-azure-blob-storage.md). +## Implementation checklist +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +## Operational checklist +Use this checklist before you enable the capability for customers: +- Confirm the consuming tenant configuration supports the scenario. +- Confirm the signed-in user and application have the required access. +- Test the workflow with an empty container and a populated container. +- Test the workflow with external sharing disabled if sharing is involved. +- Capture Microsoft Graph request IDs in logs. +- Show actionable errors instead of raw service responses. +- Keep long-running work outside request handlers. +- Reconcile app state with SharePoint Embedded state after retries. +- Document administrator steps in your customer installation guide. +- Review related next-step articles before publishing the app experience. + +## Production readiness checklist + +Before you release this capability, verify the following items for your app and tenant: + +- Confirm the tenant has SharePoint Embedded enabled. +- Confirm the application registration matches the deployed environment. +- Confirm admin consent is granted for required Microsoft Graph permissions. +- Confirm the container type is registered in the consuming tenant. +- Confirm users have the expected container roles. +- Confirm guest access behavior with the tenant sharing policy. +- Confirm sensitivity labels and compliance settings are respected. +- Confirm the app handles Microsoft Graph throttling. +- Confirm retry logic uses exponential backoff. +- Confirm write operations are idempotent or guarded against duplicates. +- Confirm long-running work is resumable. +- Confirm logs include correlation IDs and timestamps. +- Confirm logs do not include access tokens or secrets. +- Confirm telemetry distinguishes user errors from service errors. +- Confirm the UI explains policy-blocked actions. +- Confirm disabled actions remain keyboard accessible with explanatory text. +- Confirm localization does not change technical identifiers. +- Confirm feature flags can disable the capability if needed. +- Confirm documentation links point to the installed app version. +- Confirm operational runbooks describe common recovery steps. +- Confirm support teams know which tenant role can resolve configuration issues. +- Confirm test data does not include real customer secrets. +- Confirm cleanup tasks remove temporary migration or processing artifacts. +- Confirm related articles in this build path remain linked together. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. diff --git a/docs/embedded/build/archive-restore-containers.md b/docs/embedded/build/archive-restore-containers.md new file mode 100644 index 0000000000..7ecb5c464a --- /dev/null +++ b/docs/embedded/build/archive-restore-containers.md @@ -0,0 +1,122 @@ +--- +title: Archive and Restore Containers +description: Plan SharePoint Embedded container archival and restore workflows for lifecycle management. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Archive and Restore Containers +**Applies to**: Developer + + +Use container archival when content should remain retained but no longer needs active collaboration performance. +Use restore when users or business processes need the archived container active again. +The requested archive source articles were not present in this repository, so this article gives implementation guidance without naming unavailable endpoints. +For nearby concepts, see [Container types](../getting-started/containertypes.md) and [SharePoint Embedded overview](../overview.md). +> [!IMPORTANT] +> Verify the currently supported archive and restore API surface in your tenant before implementation. +## Archive containers +Archive a container when a project, case, or workspace is closed and active collaboration is no longer needed. +Before archiving, confirm no upload sessions are running, stop processors, disable edits, flush metadata, record audit data, and notify users. +Call the supported archive operation from a trusted backend only after feature detection. +Store service state, correlation IDs, and app lifecycle state separately. +Do not treat archive as deletion. +## Restore +Restore when users need to reopen a project or automation needs active file access. +Check that the container is archived, confirm permission to restore, submit the supported restore request, block duplicates, monitor state, and re-enable file operations only after completion. +> [!TIP] +> Treat restore as asynchronous and show progress instead of making users wait on one request. +## Cost and lifecycle implications +Archival is a business lifecycle and cost decision. +Define who can archive, who can restore, whether archived containers appear in lists, how restore delay is communicated, and how Microsoft 365 Archive billing applies in the tenant. +Coordinate with tenant administrators for billing, retention, and compliance settings. +## API usage +Because canonical source docs are missing, keep integration defensive. +- Use capability checks before showing archive buttons. +- Avoid hard-coding preview endpoint names in shared libraries. +- Wrap lifecycle calls behind your own interface. +- Avoid retrying lifecycle writes blindly. +- Handle unsupported-operation errors gracefully. +- Log app user intent and service outcome. +## Validate +Test empty containers, folders and files, metadata columns, additive permissions, webhooks, search, and agent references. +Verify permissions and metadata remain intact after restore. +Restart processors only when the service reports the container is active. +## Troubleshooting +| Symptom | Check | +| --- | --- | +| Archive unavailable | Confirm tenant and API support. | +| Pending state is stuck | Check service state and logs. | +| Users can still edit | Refresh app state and block writes. | +| Restore fails | Confirm archived state and authorization. | +## Next step +Continue with [Add real-time collaboration with Fluid Framework](fluid-framework.md). +## Implementation checklist +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +## Operational checklist +Use this checklist before you enable the capability for customers: +- Confirm the consuming tenant configuration supports the scenario. +- Confirm the signed-in user and application have the required access. +- Test the workflow with an empty container and a populated container. +- Test the workflow with external sharing disabled if sharing is involved. +- Capture Microsoft Graph request IDs in logs. +- Show actionable errors instead of raw service responses. +- Keep long-running work outside request handlers. +- Reconcile app state with SharePoint Embedded state after retries. +- Document administrator steps in your customer installation guide. +- Review related next-step articles before publishing the app experience. + +## Production readiness checklist + +Before you release this capability, verify the following items for your app and tenant: + +- Confirm the tenant has SharePoint Embedded enabled. +- Confirm the application registration matches the deployed environment. +- Confirm admin consent is granted for required Microsoft Graph permissions. +- Confirm the container type is registered in the consuming tenant. +- Confirm users have the expected container roles. +- Confirm guest access behavior with the tenant sharing policy. +- Confirm sensitivity labels and compliance settings are respected. +- Confirm the app handles Microsoft Graph throttling. +- Confirm retry logic uses exponential backoff. +- Confirm write operations are idempotent or guarded against duplicates. +- Confirm long-running work is resumable. +- Confirm logs include correlation IDs and timestamps. +- Confirm logs do not include access tokens or secrets. +- Confirm telemetry distinguishes user errors from service errors. +- Confirm the UI explains policy-blocked actions. +- Confirm disabled actions remain keyboard accessible with explanatory text. +- Confirm localization does not change technical identifiers. +- Confirm feature flags can disable the capability if needed. +- Confirm documentation links point to the installed app version. +- Confirm operational runbooks describe common recovery steps. +- Confirm support teams know which tenant role can resolve configuration issues. +- Confirm test data does not include real customer secrets. +- Confirm cleanup tasks remove temporary migration or processing artifacts. +- Confirm related articles in this build path remain linked together. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. diff --git a/docs/embedded/build/configure-authentication-authorization.md b/docs/embedded/build/configure-authentication-authorization.md new file mode 100644 index 0000000000..19661ee006 --- /dev/null +++ b/docs/embedded/build/configure-authentication-authorization.md @@ -0,0 +1,120 @@ +--- +title: Configure Authentication and Authorization +description: Configure Microsoft Entra ID authentication and SharePoint Embedded authorization for your application. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# 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. +For the full model, see [SharePoint Embedded authentication and authorization](../development/auth.md). +## 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 SharePoint permissions 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. +Both forms require admin consent in the consuming tenant. +> [!NOTE] +> The combination of Microsoft Graph permissions and container type application permissions determines what the application can actually do. +## Request SharePoint permission for registration +Container type registration currently uses a SharePoint API, not Microsoft Graph. +For registration, request SharePoint `Container.Selected` application permission on the `Office 365 SharePoint Online` resource. +| Scope name | Scope ID | Type | Use | +|---|---|---|---| +| `Container.Selected` | `19766c1b-905b-43af-8756-06526ab42875` | Application | Enables container type registration on a consuming tenant. | +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. +## Configure delegated token acquisition +For delegated calls: +1. Sign in the user with Microsoft identity platform. +1. Request delegated `FileStorageContainer.Selected`. +1. Ensure admin consent is granted in the consuming tenant. +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. +The source article identifies: +- Container type management in the owning tenant through PowerShell cmdlets. +- Container type registration in the consuming tenant through SharePoint REST API v2. +- SharePoint Embedded agent experiences through SharePoint REST API v2 permissions. +- Search scenarios with additional requirements. +- Operations that currently require a user license. +> [!IMPORTANT] +> Don't assume every operation uses the same token or permission resource. Check exceptional access patterns before implementing a flow. +## Understand container permissions +Container permissions apply to delegated access. +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. +## 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 SharePoint `Container.Selected` and app-only flow. | +| Search call fails | Review search-specific exceptional access patterns. | +## Next step +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..134cb19eeb --- /dev/null +++ b/docs/embedded/build/container-metadata.md @@ -0,0 +1,127 @@ +--- +title: Store and Query Container Metadata +description: Define, update, and query SharePoint Embedded metadata with Graph columns and fields. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Store and Query Container Metadata +**Applies to**: Developer + +Use metadata when your app needs structured values for files in a SharePoint Embedded container. +Metadata is represented by columns on the container and field values on drive items. +Your app creates and manages the columns for each container instance. +For full examples, see [SharePoint Embedded Container Metadata](../development/tutorials/metadata.md). +> [!NOTE] +> Container owners can create, update, and delete columns. Container members can read and list columns. +## Define metadata +Start with the business questions your app needs to answer. +Map each question to a supported column type such as boolean, choice, currency, dateTime, hyperlinkOrPicture, number, personOrGroup, or text. +Use text for simple values, choice for controlled statuses, and dateTime or number for ranges. +Create the same schema during each container provisioning workflow. +## Name columns +Column names must follow SharePoint naming rules. +Avoid names that contain `!`, begin with digits or punctuation, contain spaces, resemble spreadsheet references, represent localized true or false values, or use reserved names such as `Author`, `Created`, or `Description`. +> [!TIP] +> Use stable internal names with friendly display names. +## Set metadata +Create columns under the container resource. +```http +POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns +Content-Type: application/json +``` +```json +{ + "description": "Document title used by the app", + "displayName": "Title", + "hidden": false, + "indexed": false, + "name": "Title", + "text": { "allowMultipleLines": false, "maxLength": 255 } +} +``` +Set file values on the drive item's list item fields. +```http +PATCH https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields +Content-Type: application/json +``` +```json +{ "Color": "Fuchsia", "Quantity": 934 } +``` +Use `null` to clear a value when the column allows empty values. +## Update +Patch a column when supported properties such as description, hidden state, or required state change. +You cannot update the column `id`. +Treat schema changes as application migrations. +> [!CAUTION] +> Validate existing files before making a column required. +## Query and filter by metadata +Get all field values with `GET /drives/{drive-id}/items/{item-id}/listitem/fields`. +Use `$select` to return only the fields the UI needs. +Use drive item enumeration for exact metadata filters: +```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 [Search containers and files](search-containers-files.md) for ranked free-text search. +## Design guidance +- Keep internal column names stable. +- Version your schema in app configuration. +- Create columns during provisioning. +- Avoid secrets in metadata. +- Index fields only when needed. +- Test containers with more than 5,000 items. +- Decide whether a value belongs on the container, folder, or file. +## Next step +Continue with [Share files and manage permissions](share-files-manage-permissions.md). +## Implementation checklist +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +## Operational checklist +Use this checklist before you enable the capability for customers: +- Confirm the consuming tenant configuration supports the scenario. +- Confirm the signed-in user and application have the required access. +- Test the workflow with an empty container and a populated container. +- Test the workflow with external sharing disabled if sharing is involved. +- Capture Microsoft Graph request IDs in logs. +- Show actionable errors instead of raw service responses. +- Keep long-running work outside request handlers. +- Reconcile app state with SharePoint Embedded state after retries. +- Document administrator steps in your customer installation guide. +- Review related next-step articles before publishing the app experience. + +## Production readiness checklist + +Before you release this capability, verify the following items for your app and tenant: + +- Confirm the tenant has SharePoint Embedded enabled. +- Confirm the application registration matches the deployed environment. +- Confirm admin consent is granted for required Microsoft Graph permissions. +- Confirm the container type is registered in the consuming tenant. +- Confirm users have the expected container roles. +- Confirm guest access behavior with the tenant sharing policy. +- Confirm sensitivity labels and compliance settings are respected. +- Confirm the app handles Microsoft Graph throttling. +- Confirm retry logic uses exponential backoff. +- Confirm write operations are idempotent or guarded against duplicates. +- Confirm long-running work is resumable. +- Confirm logs include correlation IDs and timestamps. +- Confirm logs do not include access tokens or secrets. +- Confirm telemetry distinguishes user errors from service errors. +- Confirm the UI explains policy-blocked actions. +- Confirm disabled actions remain keyboard accessible with explanatory text. +- Confirm localization does not change technical identifiers. +- Confirm feature flags can disable the capability if needed. +- Confirm documentation links point to the installed app version. +- Confirm operational runbooks describe common recovery steps. +- Confirm support teams know which tenant role can resolve configuration issues. +- Confirm test data does not include real customer secrets. +- Confirm cleanup tasks remove temporary migration or processing artifacts. +- Confirm related articles in this build path remain linked together. diff --git a/docs/embedded/build/create-container-type.md b/docs/embedded/build/create-container-type.md new file mode 100644 index 0000000000..1c16c23364 --- /dev/null +++ b/docs/embedded/build/create-container-type.md @@ -0,0 +1,134 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- +# Create and Configure a Container Type +**Applies to:** Developer + +Create a SharePoint Embedded container type before your application creates containers or stores 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. + +The requested planning source `../plan/choose-app-model.md` isn't present. This article uses [container type guidance](../getting-started/containertypes.md) and [app architecture](../development/app-architecture.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. +For full details, see [Create New SharePoint Embedded Container Types](../getting-started/containertypes.md). +## 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, delete and recreate the container type after removing its containers. +## 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. +- The SharePoint Embedded Administrator or Global Administrator role. +- The latest SharePoint Online Management Shell. +- For standard billing, an Azure subscription and resource group. +- For billing setup, owner or contributor permissions on the Azure subscription. +> [!NOTE] +> 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 development and evaluation. +You can create one with the SharePoint Embedded Visual Studio Code extension or with SharePoint PowerShell. +The Visual Studio Code path is fastest for a first app. See [Quickstart: Build your first app with VS Code](quickstart-vscode.md). +PowerShell cmdlet pattern: +```powershell +New-SPOContainerType -TrialContainerType -ContainerTypeName -OwningApplicationId -ApplicationRedirectUrl +``` +Trial restrictions include: +- One trial container type per developer in a tenant. +- Up to five containers, including active and recycled containers. +- Up to 1 GB of storage per container. +- Expiration after 30 days. +- Use only in the developer tenant. +- No conversion to production. +## Create a standard container type with app-owner billing +Use standard billing when the developer or app owner tenant pays for consumption. +1. Create or identify the owning Microsoft Entra ID application. +1. Connect with `Connect-SPOService`. +1. Create the container type with `New-SPOContainerType`. +1. Attach the Azure billing profile with `Add-SPOContainerTypeBilling`. +1. Record the container type ID. +1. Continue to registration in the consuming tenant. +Cmdlet pattern: +```powershell +New-SPOContainerType -ContainerTypeName -OwningApplicationId -ApplicationRedirectUrl +``` +Attach billing: +```powershell +Add-SPOContainerTypeBilling -ContainerTypeId -AzureSubscriptionId -ResourceGroup -Region +``` +> [!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 pass-through billing flag. +1. Register the container type in the consuming tenant. +1. Have the consuming tenant admin activate pay-as-you-go services. +Cmdlet pattern: +```powershell +New-SPOContainerType -ContainerTypeName -OwningApplicationId -ApplicationRedirectUrl -IsPassThroughBilling +``` +> [!IMPORTANT] +> The consuming tenant must complete billing setup before a pass-through application can be used successfully. +## 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 SharePoint `Container.Selected` application permission for registration scenarios when required. +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 +Developer admins can configure selected behaviors after creation. +Available settings include: +- `ApplicationRedirectUrl` +- `CopilotEmbeddedChatHosts` +- `DiscoverabilityDisabled` +- `SharingRestricted` +Use [Set-SPOContainerType](/powershell/module/sharepoint-online/Set-SPOContainerType) and [Set-SPOContainerTypeConfiguration](/powershell/module/sharepoint-online/Set-SPOContainerTypeConfiguration). +The source article includes examples for discoverability, sharing, and Copilot Embedded chat hosts. +## View and update container types +Use [Get-SPOContainerType](/powershell/module/sharepoint-online/Get-SPOContainerType) to list container types. +Use [Set-SPOContainerType](/powershell/module/sharepoint-online/Set-SPOContainerType) to update supported properties. +You need SharePoint Embedded Administrator permission for basic updates. +You need owner or contributor access to billing subscriptions for billing changes. +## 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](../administration/billing/meters.md) and [SharePoint Embedded billing management](../administration/billing/billingmanagement.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 step +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..542b1f87db --- /dev/null +++ b/docs/embedded/build/create-manage-containers.md @@ -0,0 +1,136 @@ +--- +title: Create and Manage Containers +description: Create, list, update, recycle, restore, and delete SharePoint Embedded containers in your app. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# 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](../development/app-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 is 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 are 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 workspaces, 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 step +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..fd6193f9fd --- /dev/null +++ b/docs/embedded/build/fluid-framework.md @@ -0,0 +1,122 @@ +--- +title: Add Real-Time Collaboration with Fluid Framework +description: Use Fluid Framework with SharePoint Embedded for synchronized collaborative data experiences. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Add Real-Time Collaboration with Fluid Framework +**Applies to**: Developer + +Use Fluid Framework when your SharePoint Embedded app needs low-latency shared state such as cursors, counters, canvases, or collaborative controls. +Fluid provides client libraries for distributing, synchronizing, and saving shared data. +For the source article, see [Fluid Framework in SharePoint Embedded Applications](../development/fluid.md). +## When to use Fluid +Use Fluid for multiple users editing structured app state, live presence, collaborative annotations, task boards, counters, or forms. +Do not use Fluid as a replacement for file storage. +Store documents in SharePoint Embedded containers and use Fluid for the synchronized interaction layer. +> [!TIP] +> A Fluid object can feel like a local TypeScript object, but it synchronizes across connected clients. +## Configure Fluid with SPE +Gather tenant admin credentials, a SharePoint Embedded application, client ID, container type ID, and at least one container. +Get IDs from the VS Code extension export, `Get-SPOContainerType`, or Microsoft Entra app registration. +Store IDs in environment configuration rather than source code. +## Run the sample +The source points to the Fluid Examples `item-counter-spe` sample. +```powershell +git clone https://github.com/microsoft/FluidExamples.git +cd .\FluidExamples\item-counter-spe\ +``` +Create `.env`: +```text +SPE_CLIENT_ID=YOUR_CLIENTID +SPE_CONTAINER_TYPE_ID=YOUR_CONTAINERTYPE_ID +``` +Run: +```powershell +npm install +npm run dev +``` +Open `https://localhost:8080`, sign in, grant consent, and open the URL in another tab to see live updates. +## Collaboration patterns +Use shared counters for votes, shared maps for key-value state, shared sequences for ordered content, presence for transient cursors, and sidecar state for collaboration around a file. +Persist final business outputs to durable storage when audit or reporting requires it. +## Limitations +Fluid does not replace SharePoint Embedded document storage. +Users need network connectivity for live collaboration. +Your app must handle reconnects, token refresh, and authorization failures. +Samples are starting points, not production security baselines. +> [!CAUTION] +> Do not store secrets or access tokens in shared Fluid data structures. +## Validate +Test one tab, two tabs, two users, read-only users, token expiration, network interruption, container switch, and inaccessible containers. +Verify state synchronization and permission-sensitive UI behavior. +## Next step +Continue with [Add Microsoft 365 Copilot and agent experiences](agent-experiences.md). +## Implementation checklist +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +## Operational checklist +Use this checklist before you enable the capability for customers: +- Confirm the consuming tenant configuration supports the scenario. +- Confirm the signed-in user and application have the required access. +- Test the workflow with an empty container and a populated container. +- Test the workflow with external sharing disabled if sharing is involved. +- Capture Microsoft Graph request IDs in logs. +- Show actionable errors instead of raw service responses. +- Keep long-running work outside request handlers. +- Reconcile app state with SharePoint Embedded state after retries. +- Document administrator steps in your customer installation guide. +- Review related next-step articles before publishing the app experience. + +## Production readiness checklist + +Before you release this capability, verify the following items for your app and tenant: + +- Confirm the tenant has SharePoint Embedded enabled. +- Confirm the application registration matches the deployed environment. +- Confirm admin consent is granted for required Microsoft Graph permissions. +- Confirm the container type is registered in the consuming tenant. +- Confirm users have the expected container roles. +- Confirm guest access behavior with the tenant sharing policy. +- Confirm sensitivity labels and compliance settings are respected. +- Confirm the app handles Microsoft Graph throttling. +- Confirm retry logic uses exponential backoff. +- Confirm write operations are idempotent or guarded against duplicates. +- Confirm long-running work is resumable. +- Confirm logs include correlation IDs and timestamps. +- Confirm logs do not include access tokens or secrets. +- Confirm telemetry distinguishes user errors from service errors. +- Confirm the UI explains policy-blocked actions. +- Confirm disabled actions remain keyboard accessible with explanatory text. +- Confirm localization does not change technical identifiers. +- Confirm feature flags can disable the capability if needed. +- Confirm documentation links point to the installed app version. +- Confirm operational runbooks describe common recovery steps. +- Confirm support teams know which tenant role can resolve configuration issues. +- Confirm test data does not include real customer secrets. +- Confirm cleanup tasks remove temporary migration or processing artifacts. +- Confirm related articles in this build path remain linked together. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. diff --git a/docs/embedded/build/manage-files.md b/docs/embedded/build/manage-files.md new file mode 100644 index 0000000000..04a49c3af9 --- /dev/null +++ b/docs/embedded/build/manage-files.md @@ -0,0 +1,125 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- +# 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](../development/app-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, use the simple upload API documented for DriveItems. +For larger files, use an upload session as documented by Microsoft Graph. +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] +> 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 step +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..12c6f85eb5 --- /dev/null +++ b/docs/embedded/build/migrate-azure-blob-storage.md @@ -0,0 +1,122 @@ +--- +title: Migrate from Azure Blob Storage +description: Plan and execute a migration from Azure Blob Storage to SharePoint Embedded containers. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Migrate from Azure Blob Storage +**Applies to**: Developer + +Use this guide when you move files from Azure Blob Storage to SharePoint Embedded. +The source tutorial demonstrates a C# sample that reads blobs with Azure Storage SDK and uploads them with Microsoft Graph. +For full sample details, see [Tutorial to migrate from Azure Blob Storage container to SharePoint Embedded container](../development/tutorials/migrate-abs-to-spe.md). +## Migration considerations +Decide which blob containers map to SharePoint Embedded containers, whether virtual folders become folders, which metadata values are preserved, how duplicates are handled, how failures are retried, and when users cut over. +The source sample is useful for hundreds of documents; larger migrations need batching, checkpointing, monitoring, and resumability. +## Map blobs to containers and files +Azure Blob Storage is flat, while SharePoint Embedded stores files as drive items. +Blob names with `/` can be parsed into folders. +The source sample creates a top-level folder named after the source container, then creates nested folders as needed. +Decide whether your destination should use that top folder or migrate directly under root. +## Metadata migration +Inventory blob metadata keys before migration. +Normalize names to SharePoint column naming rules. +Create destination columns before file upload. +Convert values to target column types. +After upload, patch drive item list item fields. +See [Store and query container metadata](container-metadata.md). +Do not store SAS URLs, account keys, or migration secrets as metadata. +## Upload flow +Connect to Azure Blob Storage with a container-level SAS URL that has read and list permissions. +Authenticate to SharePoint Embedded with Graph scopes such as `User.Read` and `FileStorageContainer.Selected` as shown in the sample. +Enumerate blobs, create destination folders, download each blob to a stream, create a Graph upload session, and upload with `LargeFileUploadTask`. +Use conflict behavior `fail` unless your business rules require replace or rename. +## Validation +Compare source blob count with destination file count for each batch. +Check file sizes, folder paths, required metadata, failed blob output, and existing destination files. +Verify users can open migrated files through the app. +Allow time for search and metadata indexing before validating query experiences. +## Cleanup +After business signoff, disable writes to the old blob-backed experience, rotate migration credentials, archive logs, decide source blob retention, update monitoring, and remove temporary blob lists when no longer needed. +> [!CAUTION] +> Do not delete source blobs until retention requirements and validation approvals are complete. +## Run the sample +The source sample accepts SAS URL, tenant ID, client ID, container ID, and optional blob list and failure output files. +```console +dotnet run Program.cs -- --sasurl "" --tenantid "" --clientid "" --containerid "" [ --blobfile "" --outputfile "" ] +``` +## Next step +Continue with [Prepare a customer installation](../publish/prepare-customer-installation.md). +## Implementation checklist +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +## Operational checklist +Use this checklist before you enable the capability for customers: +- Confirm the consuming tenant configuration supports the scenario. +- Confirm the signed-in user and application have the required access. +- Test the workflow with an empty container and a populated container. +- Test the workflow with external sharing disabled if sharing is involved. +- Capture Microsoft Graph request IDs in logs. +- Show actionable errors instead of raw service responses. +- Keep long-running work outside request handlers. +- Reconcile app state with SharePoint Embedded state after retries. +- Document administrator steps in your customer installation guide. +- Review related next-step articles before publishing the app experience. + +## Production readiness checklist + +Before you release this capability, verify the following items for your app and tenant: + +- Confirm the tenant has SharePoint Embedded enabled. +- Confirm the application registration matches the deployed environment. +- Confirm admin consent is granted for required Microsoft Graph permissions. +- Confirm the container type is registered in the consuming tenant. +- Confirm users have the expected container roles. +- Confirm guest access behavior with the tenant sharing policy. +- Confirm sensitivity labels and compliance settings are respected. +- Confirm the app handles Microsoft Graph throttling. +- Confirm retry logic uses exponential backoff. +- Confirm write operations are idempotent or guarded against duplicates. +- Confirm long-running work is resumable. +- Confirm logs include correlation IDs and timestamps. +- Confirm logs do not include access tokens or secrets. +- Confirm telemetry distinguishes user errors from service errors. +- Confirm the UI explains policy-blocked actions. +- Confirm disabled actions remain keyboard accessible with explanatory text. +- Confirm localization does not change technical identifiers. +- Confirm feature flags can disable the capability if needed. +- Confirm documentation links point to the installed app version. +- Confirm operational runbooks describe common recovery steps. +- Confirm support teams know which tenant role can resolve configuration issues. +- Confirm test data does not include real customer secrets. +- Confirm cleanup tasks remove temporary migration or processing artifacts. +- Confirm related articles in this build path remain linked together. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. diff --git a/docs/embedded/build/open-office-files.md b/docs/embedded/build/open-office-files.md new file mode 100644 index 0000000000..c80d526c35 --- /dev/null +++ b/docs/embedded/build/open-office-files.md @@ -0,0 +1,146 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- +# 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. +For the full overview, see [Office file experiences for SharePoint Embedded](../development/content-experiences/office-experience.md). +## 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` can point to a WOPI URL that opens the document in Office for the web. +The launch tutorial shows a URL shape like this: +```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 WOPI URL can include `action=default`. +To force a mode, update the query parameter as shown in the source tutorial: +```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 WOPI action details, see [WOPI Discovery - WOPI 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 + +A dedicated configure-redirect-behavior source wasn't present. The closest source is the `ApplicationRedirectUrl` setting in [Create New SharePoint Embedded Container Types](../getting-started/containertypes.md#configuring-container-types). +Use `ApplicationRedirectUrl` to specify the URL to which files for your application are redirected. +When designing 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. +## 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. +> [!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. +The Office source recommends specifying Current Channel to take advantage of 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 step +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..e76d899d4d --- /dev/null +++ b/docs/embedded/build/preview-files.md @@ -0,0 +1,166 @@ +--- +title: Preview Files in Your App +description: Create Microsoft Graph preview links and embed supported SharePoint Embedded file previews in your app. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# 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. +For the full tutorial, see [Using File Previews](../development/tutorials/using-file-preview.md). +## 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. +## 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. +The source tutorial shows 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] +> The source tutorial notes that `getUrl` currently contains an encrypted token that can only be used with your application. This behavior may change. +## Remove the preview banner +The source tutorial notes that you can 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. +The source tutorial shows 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). diff --git a/docs/embedded/build/quickstart-vscode.md b/docs/embedded/build/quickstart-vscode.md new file mode 100644 index 0000000000..8ab7622517 --- /dev/null +++ b/docs/embedded/build/quickstart-vscode.md @@ -0,0 +1,129 @@ +--- +title: "Quickstart: Build Your First App With VS Code" +description: Create a trial SharePoint Embedded app in Visual Studio Code and run the sample application locally. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Quickstart: Build Your First App With VS Code +**Applies to:** Developer + +Use the SharePoint Embedded Visual Studio Code extension to create a trial container type, configure a Microsoft Entra ID application, register the container type, create a container, and run a local sample app. +This article starts the build journey. Continue with [Create and configure a container type](create-container-type.md) when you need a production-ready configuration. +## 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. +- 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. +You can also open the extension from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=SharepointEmbedded.ms-sharepoint-embedded-vscode-extension). +## 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. +## Create a trial 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 Trial Container Type**. +1. Enter a container type name. +1. Follow the prompts until creation completes. +Trial container types are for exploration and proof-of-concept work. +They have these constraints: +- The trial type isn't linked to an Azure billing profile. +- The developer tenant is also the consuming tenant. +- Each developer can have one trial container type in a tenant. +- The trial is valid for up to 30 days. +- Up to five containers can be created. +- Each container can store up to 1 GB. +- The trial type can't be converted to production. +> [!NOTE] +> The extension supports trial container types. Use SharePoint PowerShell for standard or pass-through billing container types. +## 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. +> [!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](../development/app-architecture.md). +## 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, select **Register on local tenant** in the prompt. +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. +## 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. +## Recycle and restore during development +The extension can recycle and recover containers. +Use this capability to: +- Remove a test container from the active list. +- Validate delete and restore behavior. +- Clean up development containers. +> [!IMPORTANT] +> Trial limits include active containers and containers in the recycle bin. Permanently delete trial containers when you need to free quota. +## Load a sample app +1. In the SharePoint Embedded view, select **Load Sample App**. +1. Choose a SharePoint Embedded sample. +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\Samples\spe-typescript-react-azurefunction +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. | +## Clean up +When you're finished testing: +1. Recycle unneeded containers. +1. Permanently delete containers that count against the trial quota. +1. Remove trial container types when no longer needed. +1. Remove local sample secrets that are no longer needed. +## Next step +Create a production-ready model 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..9dec7989de --- /dev/null +++ b/docs/embedded/build/register-application-permissions.md @@ -0,0 +1,143 @@ +--- +title: Register Application Permissions +description: Register SharePoint Embedded container type application permissions in a consuming tenant. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# 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. +For the full reference, see [Register file storage container type application permissions](../getting-started/register-api-documentation.md). +## 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 SharePoint `Container.Selected` app-only permission. +- A valid app-only token for the SharePoint resource. +> [!NOTE] +> The registration API is a SharePoint API, not a Microsoft Graph API. +## 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//adminconsent?client_id= +``` +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). +> [!IMPORTANT] +> SharePoint `Container.Selected` is separate from Microsoft Graph `FileStorageContainer.Selected`. +## Acquire a token for registration +Use app-only authentication for registration. +The source guidance requires: +- The [client credentials grant flow](/entra/identity-platform/v2-oauth2-client-creds-grant-flow). +- A token requested with a certificate. +- The SharePoint `Container.Selected` app-only permission. +Don't use a delegated user token for the registration API. +## Register container type permissions +Call the registration endpoint in the consuming tenant. +```http +PUT {RootSiteUrl}/_api/v2.1/storageContainerTypes/{containerTypeId}/applicationPermissions +``` +`{RootSiteUrl}` is the SharePoint URL of the consuming tenant, such as `https://contoso.sharepoint.com`. +`{containerTypeId}` is the container type ID created in the owning tenant. +In the request body, provide the application permissions 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 +{ + "value": [ + { + "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", + "delegated": ["full"], + "appOnly": ["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 +{ + "value": [ + { + "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", + "delegated": ["full"], + "appOnly": ["full"] + }, + { + "appId": "89ea5c94-7736-4e25-95ad-3fa95f62b6", + "delegated": ["read", "write"], + "appOnly": ["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. | +| `DeleteOwnPermissions` | Remove the caller's own membership. | +| `ManagePermissions` | Manage container role assignments. | +| `Full` | Grant all permissions. | +> [!NOTE] +> `WriteContent` can't be granted without `ReadContent`. +## Validate registration +A successful registration returns `200 OK` and 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 `Container.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 are no restrictions 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 step +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..f6038c717a --- /dev/null +++ b/docs/embedded/build/respond-to-changes-webhooks.md @@ -0,0 +1,122 @@ +--- +title: Respond to File and Container Changes with Webhooks +description: Subscribe to SharePoint Embedded changes and process Graph webhook notifications reliably. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Respond to File and Container Changes with Webhooks +**Applies to**: Developer + +Use Microsoft Graph webhooks when your app needs to react after files change in a SharePoint Embedded container. +A webhook lets Microsoft Graph call your endpoint when a subscribed resource changes. +For the tutorial source, see [Using Webhooks](../development/tutorials/using-webhooks.md). +> [!TIP] +> Webhooks tell you that something changed. Use Microsoft Graph to fetch the current state before business processing. +## Why use webhooks +Use webhooks to start document processing after upload, refresh indexes, notify users, or trigger downstream workflows. +Avoid polling for every container. +Queue work rather than performing expensive transformations inside the HTTP request. +## Subscribe to changes +Create an HTTPS endpoint that can receive POST requests. +During development, the source tutorial uses ngrok to expose a local server. +Subscribe to changes under the container drive root: +```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": "" +} +``` +Use the container ID as the drive ID in this pattern. +## Process notifications +When Microsoft Graph validates the subscription, it sends a `validationToken` query parameter. +Return that token as plain text immediately. +For normal notifications, accept the request quickly, identify the subscription or container, enqueue background work, and fetch current state with Graph. +Make workers idempotent because notifications can be duplicated or delayed. +## Renew subscriptions +Subscriptions expire. +The source tutorial calculates a maximum drive item subscription lifetime of 4,230 minutes. +Store subscription IDs and expiration times. +Run renewal before expiration and alert operators when renewal fails. +> [!CAUTION] +> If a subscription expires, Graph stops sending notifications. Keep a reconciliation path for missed changes. +## Validate delivery +- Confirm the endpoint uses HTTPS. +- Test validation during subscription creation. +- Upload or update a file and verify delivery. +- Track notification counts by subscription. +- Monitor queue age and worker failures. +- Test renewal before the first expiration. +## Troubleshooting +| Symptom | Check | +| --- | --- | +| Subscription creation fails | Return `validationToken` correctly. | +| No notifications arrive | Confirm resource path, expiration, and activity. | +| Handler times out | Return quickly and queue work. | +| Wrong container is processed | Route by subscription ID or validated drive ID. | +## Next step +Continue with [Archive and restore containers](archive-restore-containers.md). +## Implementation checklist +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +## Operational checklist +Use this checklist before you enable the capability for customers: +- Confirm the consuming tenant configuration supports the scenario. +- Confirm the signed-in user and application have the required access. +- Test the workflow with an empty container and a populated container. +- Test the workflow with external sharing disabled if sharing is involved. +- Capture Microsoft Graph request IDs in logs. +- Show actionable errors instead of raw service responses. +- Keep long-running work outside request handlers. +- Reconcile app state with SharePoint Embedded state after retries. +- Document administrator steps in your customer installation guide. +- Review related next-step articles before publishing the app experience. + +## Production readiness checklist + +Before you release this capability, verify the following items for your app and tenant: + +- Confirm the tenant has SharePoint Embedded enabled. +- Confirm the application registration matches the deployed environment. +- Confirm admin consent is granted for required Microsoft Graph permissions. +- Confirm the container type is registered in the consuming tenant. +- Confirm users have the expected container roles. +- Confirm guest access behavior with the tenant sharing policy. +- Confirm sensitivity labels and compliance settings are respected. +- Confirm the app handles Microsoft Graph throttling. +- Confirm retry logic uses exponential backoff. +- Confirm write operations are idempotent or guarded against duplicates. +- Confirm long-running work is resumable. +- Confirm logs include correlation IDs and timestamps. +- Confirm logs do not include access tokens or secrets. +- Confirm telemetry distinguishes user errors from service errors. +- Confirm the UI explains policy-blocked actions. +- Confirm disabled actions remain keyboard accessible with explanatory text. +- Confirm localization does not change technical identifiers. +- Confirm feature flags can disable the capability if needed. +- Confirm documentation links point to the installed app version. +- Confirm operational runbooks describe common recovery steps. +- Confirm support teams know which tenant role can resolve configuration issues. +- Confirm test data does not include real customer secrets. +- Confirm cleanup tasks remove temporary migration or processing artifacts. +- Confirm related articles in this build path remain linked together. diff --git a/docs/embedded/build/search-containers-files.md b/docs/embedded/build/search-containers-files.md new file mode 100644 index 0000000000..fe279ca6d0 --- /dev/null +++ b/docs/embedded/build/search-containers-files.md @@ -0,0 +1,122 @@ +--- +title: Search Containers and Files +description: Search SharePoint Embedded containers and files with Microsoft Search and safe scoping. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Search Containers and Files +**Applies to**: Developer + +Use Microsoft Search in Microsoft Graph when your app needs keyword search across SharePoint Embedded containers or files. +Search complements direct enumeration APIs: search ranks content by relevance, while enumeration filters known drive items by metadata. +For complete query examples and advanced managed property syntax, see [Search SharePoint Embedded content](../development/content-experiences/search-content.md). +> [!NOTE] +> SharePoint Embedded search is in preview and supports delegated permissions only. +> If your app opted out of Microsoft 365 content discoverability, set `sharePointOneDriveOptions.includeHiddenContent` to `true`. +> [!IMPORTANT] +> Always scope queries by `ContainerTypeId` or `ContainerId` so results stay aligned with your app. +## Search container content +Send requests to Microsoft Graph search: +```http +POST https://graph.microsoft.com/beta/search/query +Content-Type: application/json +``` +Use `entityTypes: ["drive"]` to return container instances. +Filter by the container type ID in the query string. +```json +{ + "requests": [ + { + "entityTypes": ["drive"], + "query": { + "queryString": "ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae" + }, + "sharePointOneDriveOptions": { "includeHiddenContent": true } + } + ] +} +``` +Use title or description terms with the same container type scope, for example `Title:'contoso' AND ContainerTypeId:{id}`. +## Query files +Use `entityTypes: ["driveItem"]` for files and folders. +Scope an in-container search with `ContainerId`. +```json +{ + "requests": [ + { + "entityTypes": ["driveItem"], + "query": { + "queryString": "Title:'contoso' AND ContainerId:b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0" + }, + "sharePointOneDriveOptions": { "includeHiddenContent": true } + } + ] +} +``` +For cross-container app search, use text terms with `ContainerTypeId`. +Return selected properties with `fields` and sort only on sortable managed properties. +## Permissions and security trimming +Search results are trimmed to the signed-in user. +Your app must also be authorized for the returned container type before it can open or modify a result. +Treat search as discovery, then validate access through Graph before file operations. +- Include `ContainerTypeId` when searching containers or all content for an app. +- Include `ContainerId` when searching a specific workspace. +- Do not cache search results as durable proof of access. +- Keep result cards minimal until the item is opened through an authorized path. +## Paging +When `moreResultsAvailable` is `true`, request the next page using Microsoft Search paging options. +Keep the original query, entity type, and scoping conditions unchanged. +Load more results only when the user scrolls or selects **Show more**. +Avoid preloading every page in large tenants. +## Troubleshooting results +| Symptom | Check | +| --- | --- | +| No results | Confirm user access, indexing, and delegated permissions. | +| Wrong app results | Add or verify `ContainerTypeId`. | +| Hidden content missing | Set `includeHiddenContent` when discoverability is disabled. | +| Open fails | Confirm app access to the container type and item. | +| Sort fails | Use only sortable properties. | +> [!TIP] +> For exact metadata filters, use [Store and query container metadata](container-metadata.md). +## Next step +Continue with [Store and query container metadata](container-metadata.md). +## Implementation checklist +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. + +## Production readiness checklist + +Before you release this capability, verify the following items for your app and tenant: + +- Confirm the tenant has SharePoint Embedded enabled. +- Confirm the application registration matches the deployed environment. +- Confirm admin consent is granted for required Microsoft Graph permissions. +- Confirm the container type is registered in the consuming tenant. +- Confirm users have the expected container roles. +- Confirm guest access behavior with the tenant sharing policy. +- Confirm sensitivity labels and compliance settings are respected. +- Confirm the app handles Microsoft Graph throttling. +- Confirm retry logic uses exponential backoff. +- Confirm write operations are idempotent or guarded against duplicates. +- Confirm long-running work is resumable. +- Confirm logs include correlation IDs and timestamps. +- Confirm logs do not include access tokens or secrets. +- Confirm telemetry distinguishes user errors from service errors. +- Confirm the UI explains policy-blocked actions. +- Confirm disabled actions remain keyboard accessible with explanatory text. +- Confirm localization does not change technical identifiers. +- Confirm feature flags can disable the capability if needed. +- Confirm documentation links point to the installed app version. +- Confirm operational runbooks describe common recovery steps. +- Confirm support teams know which tenant role can resolve configuration issues. +- Confirm test data does not include real customer secrets. +- Confirm cleanup tasks remove temporary migration or processing artifacts. +- Confirm related articles in this build path remain linked together. +- Confirm this scenario is covered by automated or manual regression tests. +- Confirm this scenario is covered by automated or manual regression tests. 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..7f851c1f1f --- /dev/null +++ b/docs/embedded/build/share-files-manage-permissions.md @@ -0,0 +1,122 @@ +--- +title: Share Files and Manage Permissions +description: Grant, revoke, and design SharePoint Embedded file sharing with tenant policy awareness. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Share Files and Manage Permissions +**Applies to**: Developer + +SharePoint Embedded content inherits permissions from the container hierarchy. +You cannot break that inherited structure for arbitrary files and folders. +Instead, extend access to specific files or folders by applying additive permissions. +For source details, see [Sharing and permissions in SharePoint Embedded](../development/sharing-and-perm.md). +> [!IMPORTANT] +> Permissions are additive. Removing an additive permission does not remove inherited container access. +## Sharing capabilities +Use container roles for baseline membership and broad access. +Use additive permissions for targeted collaboration on a file or folder. +Do not use file sharing to replace container membership management. +Do not grant additive permissions to the root folder; add the user to a container role instead. +## Grant and revoke access +Grant additive access with Microsoft Graph drive item invite: +```http +POST /drives/{drive-id}/items/{item-id}/invite +``` +Set `sendInvitation` to `false`. +Use delegated permissions; app-only permissions are not supported for this operation. +Retrieve permissions with: +```http +GET /drives/{drive-id}/items/{item-id}/permissions +GET /drives/{drive-id}/items/{item-id}/permissions/{perm-id} +``` +Delete additive permissions with: +```http +DELETE /drives/{drive-id}/items/{item-id}/permissions/{perm-id} +``` +You can delete the additive permission only on the drive item where it was originally added. +## Permission inheritance +Separate inherited container access from added item access in your UI. +Use labels such as **Container access**, **Added access**, and **Managed by policy**. +Avoid calling a file private unless you have verified inherited access. +If a user still has access after revoke, inspect container roles and group membership. +## App UX considerations +- Disable share actions when the current user cannot share. +- Validate recipients before submitting an invite. +- Show tenant policy errors in plain language. +- Refresh permissions after grant and revoke operations. +- Provide a path to workspace membership management. +- Use your own notification experience because `sendInvitation` must be false. +## Tenant policy effects +SharePoint Embedded application sharing follows the consuming tenant sharing configuration by default. +If guest sharing is disabled in the tenant, your app cannot add guests to container roles or grant guest additive permissions. +A consuming tenant SharePoint Embedded admin can configure application-level sharing with `Set-SPOApplication`. +Application owner developers configure role-based sharing on the container type with `Set-SPOcontainerTypeConfiguration`. +The restrictive model allows only Owner and Manager roles to add new file permissions. +The open model allows members and guests with edit permissions to add new permissions. +## Troubleshooting +| Symptom | Action | +| --- | --- | +| Invite fails | Use delegated invite and `sendInvitation: false`. | +| Guest is blocked | Check tenant or app sharing policy. | +| Revoke seems ineffective | Review inherited container access. | +| Share root fails | Manage container roles instead. | +## Next step +Continue with [Respond to file and container changes with webhooks](respond-to-changes-webhooks.md). +## Implementation checklist +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +- Keep user-facing messages specific to the current container. +- Validate tenant configuration before enabling this capability. +- Recheck permissions before write operations. +- Log Graph request IDs and operation outcomes for support. +- Document rollback steps for administrators. +## Operational checklist +Use this checklist before you enable the capability for customers: +- Confirm the consuming tenant configuration supports the scenario. +- Confirm the signed-in user and application have the required access. +- Test the workflow with an empty container and a populated container. +- Test the workflow with external sharing disabled if sharing is involved. +- Capture Microsoft Graph request IDs in logs. +- Show actionable errors instead of raw service responses. +- Keep long-running work outside request handlers. +- Reconcile app state with SharePoint Embedded state after retries. +- Document administrator steps in your customer installation guide. +- Review related next-step articles before publishing the app experience. + +## Production readiness checklist + +Before you release this capability, verify the following items for your app and tenant: + +- Confirm the tenant has SharePoint Embedded enabled. +- Confirm the application registration matches the deployed environment. +- Confirm admin consent is granted for required Microsoft Graph permissions. +- Confirm the container type is registered in the consuming tenant. +- Confirm users have the expected container roles. +- Confirm guest access behavior with the tenant sharing policy. +- Confirm sensitivity labels and compliance settings are respected. +- Confirm the app handles Microsoft Graph throttling. +- Confirm retry logic uses exponential backoff. +- Confirm write operations are idempotent or guarded against duplicates. +- Confirm long-running work is resumable. +- Confirm logs include correlation IDs and timestamps. +- Confirm logs do not include access tokens or secrets. +- Confirm telemetry distinguishes user errors from service errors. +- Confirm the UI explains policy-blocked actions. +- Confirm disabled actions remain keyboard accessible with explanatory text. +- Confirm localization does not change technical identifiers. +- Confirm feature flags can disable the capability if needed. +- Confirm documentation links point to the installed app version. +- Confirm operational runbooks describe common recovery steps. +- Confirm support teams know which tenant role can resolve configuration issues. +- Confirm test data does not include real customer secrets. +- Confirm cleanup tasks remove temporary migration or processing artifacts. +- Confirm related articles in this build path remain linked together. +- Confirm this scenario is covered by automated or manual regression tests. diff --git a/docs/embedded/llms.txt b/docs/embedded/llms.txt new file mode 100644 index 0000000000..354961c6f7 --- /dev/null +++ b/docs/embedded/llms.txt @@ -0,0 +1,66 @@ +# 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 SPE. +- [Add Microsoft 365 Copilot and agent experiences](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/build/agent-experiences): SPE agents and knowledge sources. +- [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 admin) +- [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 SPE. +- [Create apps in SharePoint admin center](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/admin/create-apps-sharepoint-admin-center): Create SPE apps from the admin center. +- [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 SPE 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): SPE audit event names and properties. +- [PowerShell reference](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/powershell): SPE 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 SPE. +- [Learning module: SPE overview & configuration](https://learn.microsoft.com/en-us/training/modules/sharepoint-embedded-setup): Guided training. +- [Learning module: SPE building 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 9f707d52e2..df3909bba0 100644 --- a/docs/embedded/overview.md +++ b/docs/embedded/overview.md @@ -1,72 +1,68 @@ --- 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: 06/25/2026 ms.localizationpriority: high --- -# 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. +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. -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. +SharePoint Embedded brings advanced Microsoft 365 capabilities into your app, including Office collaboration, Microsoft Purview security and compliance, and Copilot. > [!IMPORTANT] -> Help us shape the future of SharePoint Embedded! -> Take our [quick survey](https://forms.microsoft.com/r/1YpGd2pAUS) and share your experience! +> 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 + -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. +## Choose your path -## Introducing File Storage Containers +This page is a router. Pick the row that matches what you're trying to do. -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. +| I want to… | Start here | +|---|---| +| **Understand SPE 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 / dev admin) | [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 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. +## Key concepts in 60 seconds -## App-managed content experiences +### App documents stay in the customer's Microsoft 365 tenant -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: +When a customer uses a SharePoint Embedded application, SPE 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. -- 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 +### File Storage Containers -SharePoint Embedded is used by several types of applications: +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. -- 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 +To learn how containers and container types relate, see [Understand container types and containers](plan/container-types-and-containers.md). -## Consumer Microsoft 365 settings apply to app documents +### App-managed content experiences -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. +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: -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: +- 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. -- eDiscovery -- Auditing -- Data loss prevention (DLP) -- Retention policies, sensitivity labels, conditional access +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. -## Understanding the costs and billing for SharePoint Embedded content +### Compliance and billing follow the tenant -Microsoft 365 customers have different entitlements related to storage, usage, and features depending on the licenses the customer has purchased. +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 SPE 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). -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 and the number of API calls. +## Next steps -> [!NOTE] -> Learn more about billing for SharePoint Embedded, see [Billing Meters](./administration/billing/meters.md). - -## Get Started with SharePoint Embedded - -[Review the prerequisites](./administration/billing/billing.md) - -Create a "File Storage Container" in 15 minutes or less: - -- [Free trial: SharePoint Embedded for Visual Studio Code](./getting-started/spembedded-for-vscode.md) - -Follow manual set-up on SharePoint Embedded from the following Microsoft Learning modules: - -- [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 SPE? 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..3610c93529 --- /dev/null +++ b/docs/embedded/plan/app-tenant-architecture.md @@ -0,0 +1,190 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- + +# Understand App and Tenant Architecture + +**Applies to:** Architect + + + +Use this article to map the core SharePoint Embedded (SPE) 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. + +For the source architecture description, see [App architecture](../development/app-architecture.md) and [SharePoint Embedded overview](../overview.md). + +## 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. + +## 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 application 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 a customer tenant. + +> [!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. + +Every container type is strongly coupled with one owning application. + +SharePoint Embedded requires a 1:1 relationship between an owning application and a container type. + +This means: + +- One owning app owns one container type. +- The owning app developer is responsible for creating and managing that container type. +- The container type records the app relationship that controls access to containers of that type. + +> [!NOTE] +> Other applications can be granted access to the same container type, but the container type still has 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 apps can access containers of this type? +- Which tenant is accountable for billing? +- Which tenant can create containers of this type? +- Which behavior settings apply to all containers of this type? + +For more detail, see [Understand container types and containers](../plan/container-types-and-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, 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 consumer uses a SharePoint Embedded app in their Microsoft 365 tenant, SharePoint Embedded creates a storage partition in that tenant. + +The partition doesn't have a SharePoint 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. + +Consumer 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). + +## Tenant 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 which permissions can be performed against the container type in the consuming tenant. + +For full registration requirements, see [Register file storage container type application permissions](../getting-started/register-api-documentation.md). + +## Access relationships + +An application's access to containers and content is determined by permissions configured between the application and the container type. + +The owning application receives permissions for its container type when the container type is created. + +SharePoint Embedded also allows applications to access containers of container types they don't own when those permissions are granted. + +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. + +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 application registration lives. +- Confirm which app 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 step + +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..66d2e6f3ee --- /dev/null +++ b/docs/embedded/plan/authentication-permissions.md @@ -0,0 +1,219 @@ +--- +title: Plan Authentication and Permissions +description: Plan SharePoint Embedded authentication, admin consent, delegated access, app-only access, and container permissions. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# 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](../development/auth.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 permission requires admin consent on the consuming tenant before any user from that tenant can consent to it. + +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 `FileStorageContainer.Selected` permission. + +Container type registration also requires consent for the owning application to act in the consuming tenant. + +For tenant registration, see [Register file storage container type application permissions](../getting-started/register-api-documentation.md). + +## Container type registration permission + +Container type registration isn't currently a Microsoft Graph API in the source documentation. + +It is exposed through SharePoint REST API v2. + +To register a container type, the app requests the `Container.Selected` application permission on the `Office 365 SharePoint Online` resource. + +The source authentication article lists: + +| Scope name | Scope ID | Type | Operation | +| --- | --- | --- | --- | +| `Container.Selected` | `19766c1b-905b-43af-8756-06526ab42875` | Application | Enables container type registration on a consuming tenant. | + +> [!NOTE] +> The source documentation states that container type management and registration are expected to become Microsoft Graph operations in the future. + +## 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. + +The source articles list permissions including: + +- `None` +- `ReadContent` +- `WriteContent` +- `Create` +- `Delete` +- `Read` +- `Write` +- `EnumeratePermissions` +- `AddPermissions` +- `UpdatePermissions` +- `DeletePermissions` +- `DeleteOwnPermissions` +- `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. + +The source authentication article lists these 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. + +## Tenant 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. + +The source authentication article identifies: + +- Container type management on owning tenants through PowerShell cmdlets. +- Container type registration on consuming tenants through SharePoint REST API v2. +- SharePoint Embedded agent permissions through SharePoint REST API v2. +- 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 SharePoint `Container.Selected` for container type registration when required. +- 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 step + +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..94d9ea5385 --- /dev/null +++ b/docs/embedded/plan/choose-app-model.md @@ -0,0 +1,193 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- + +# 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 usually 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 customer. + +## 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 usually owns both. + +For an ISV app, the ISV usually 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](../getting-started/register-api-documentation.md). + +## Where containers are created + +Containers are created in the consuming tenant. + +For an enterprise LOB app, that is 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. + +The admin in the developer tenant establishes a valid billing profile 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 admin | ISV/developer admin | +| 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-and-containers.md). +1. Create the container type by using the guidance in [SharePoint Embedded container types](../getting-started/containertypes.md). +1. Configure billing by using [PAYG billing for SharePoint Embedded](../administration/billing/billing.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](../getting-started/register-api-documentation.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 step + +Review the storage model: [Understand container types and containers](../plan/container-types-and-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..9bbffaa21d --- /dev/null +++ b/docs/embedded/plan/choose-billing-model.md @@ -0,0 +1,194 @@ +--- +title: Choose a Billing Model +description: Compare standard and pass-through SharePoint Embedded billing models before you create production container types. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# 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. + +Billing is selected at the container type level. + +For the full billing setup procedure, see [PAYG billing for SharePoint Embedded](../administration/billing/billing.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. + +| 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 source article shows this standard billing creation pattern: + +```powershell +New-SPOContainerType -ContainerTypeName + -OwningApplicationId + -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. + +The source article shows this pass-through creation pattern: + +```powershell +New-SPOContainerType -ContainerTypeName + -OwningApplicationId + -isPassThroughBilling +``` + +> [!NOTE] +> Some source examples use different parameter casing for pass-through billing. Use the current SharePoint Online Management Shell documentation for exact cmdlet syntax. + +## Billing meters + +SharePoint Embedded billing is determined by usage. + +The supported meters are described in [SharePoint Embedded billing meters](../administration/billing/meters.md). + +The current meters include: + +- 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. + +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. + +## 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. + +Examples of nonchargeable transactions in the source article 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 downloaded from the SharePoint Embedded platform to a customer client device. + +The source article identifies exemptions for certain Microsoft service integrations, including downloads from the SharePoint Embedded application server to Office Desktop client or Web Application Companion. + +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](../getting-started/containertypes.md). +- Set up billing: [PAYG billing for SharePoint Embedded](../administration/billing/billing.md). +- Review meters: [SharePoint Embedded billing meters](../administration/billing/meters.md). +- Register a consuming tenant: [Register file storage container type application permissions](../getting-started/register-api-documentation.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 step + +Plan governance responsibilities for tenant content: [Plan security, compliance, and governance](../plan/security-compliance-governance.md). diff --git a/docs/embedded/plan/container-types-and-containers.md b/docs/embedded/plan/container-types-and-containers.md new file mode 100644 index 0000000000..d20cb2c3fb --- /dev/null +++ b/docs/embedded/plan/container-types-and-containers.md @@ -0,0 +1,226 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- + +# 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](../getting-started/containertypes.md). + +## Object model + +SharePoint Embedded stores files and documents in containers. + +Containers are grouped by container type. + +A container type is created before containers can be created 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 admin or SharePoint Embedded Administrator. | +| 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. + +That application is 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. + +## Containers + +A container is the basic storage unit in SharePoint Embedded. + +A container 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 to containers of the container type it's coupled with by default. + +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 SharePoint PowerShell. + +The PowerShell cmdlet shown in the source article is: + +```powershell +New-SPOContainerType [–TrialContainerType] [-ContainerTypeName] [-OwningApplicationId] [-ApplicationRedirectUrl] [] +``` + +## 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. +- Pass-through billing. + +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 developer tenant admin establishes a billing profile when creating the standard container type. + +The source article shows creation followed by billing profile configuration: + +```powershell +New-SPOContainerType [-ContainerTypeName] [-OwningApplicationId] [-ApplicationRedirectUrl] [] +``` + +```powershell +Add-SPOContainerTypeBilling –ContainerTypeId -AzureSubscriptionId -ResourceGroup -Region +``` + +## Pass-through billing container type + +With pass-through billing, charges are billed directly to the consuming tenant. + +The developer tenant admin creates the container type with pass-through billing enabled and doesn't attach a billing profile in the developer tenant. + +The source article shows: + +```powershell +New-SPOContainerType [-ContainerTypeName] [-OwningApplicationId] [-ApplicationRedirectUrl] [-IsPassThroughBilling] [] +``` + +After registration, the consuming tenant admin 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 + +Developer admins can configure selected container type settings after creation. + +The source article lists these settings: + +- `ApplicationRedirectUrl` +- `CopilotEmbeddedChatHosts` +- `DiscoverabilityDisabled` +- `SharingRestricted` + +The `Set-SPOContainerType` cmdlet updates the application redirect URL. + +The `Set-SPOContainerTypeConfiguration` cmdlet updates selected configuration such as host URLs, discoverability, and sharing settings. + +## 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](../getting-started/register-api-documentation.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 step + +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..bd1be5e716 --- /dev/null +++ b/docs/embedded/plan/limits-calling-patterns.md @@ -0,0 +1,238 @@ +--- +title: Understand Limits and Calling Patterns +description: Plan SharePoint Embedded service limits, throttling behavior, retry handling, and performance-sensitive calling patterns. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# 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. + +For the full current limits reference, see [Limits and calling patterns](../development/limits-calling.md). + +## 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. + +Some limits can be increased per request, as noted in the source article. + +> [!NOTE] +> The source limits article describes preview limits that are subject to change. Always verify current limits before production launch. + +## Size limits + +The source article lists 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 | + +`*` indicates that the limit can be increased per request in the source documentation. + +## 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-and-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 + +The source limit for files and folders with additive permissions per container is 5k. + +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. + +## 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. + +The source article lists: + +| 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] +> The source article states that API resource unit costs can change. + +## API rate limits + +The source article lists 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 | + +`*` indicates that the limit can be increased per request in the source documentation. + +Application limits are defined in resource units. + +The actual requests per minute depends on the APIs you call and their resource unit cost. + +The source article suggests estimating request rate by averaging about two resource units per request and dividing application resource unit limits by 2. + +## Permission operation costs + +Permission resource operations have a higher resource unit cost in the source article. + +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-and-containers.md) +- [Plan authentication and permissions](../plan/authentication-permissions.md) +- [Choose a billing model](../plan/choose-billing-model.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..75df3fa6e7 --- /dev/null +++ b/docs/embedded/plan/security-compliance-governance.md @@ -0,0 +1,225 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- + +# Plan Security, Compliance, and Governance + +**Applies to:** Compliance admin + + + +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. + +For the source compliance details, see [Security and compliance](../compliance/security-and-compliance.md). + +## 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 and SharePoint administrators enforce supported policies on containers and content by using Microsoft Purview, SharePoint 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 usually 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. + +The source article lists this PowerShell discovery flow: + +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. + +The source compliance article describes support for: + +- 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 Administrators can set and remove sensitivity labels on a SharePoint Embedded container by using SharePoint PowerShell. + +The source article lists: + +```powershell +Set-SPOContainer -Identity -SensitivityLabel +``` + +For more information, see [Learn about sensitivity labels](/purview/sensitivity-labels). + +## Block download policy + +SharePoint Administrators or Global Administrators can block file downloads from SharePoint Embedded containers. + +The source article lists: + +```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. + +The source article lists: + +- `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). + +## 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 should not 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 step + +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..dff792bd9d --- /dev/null +++ b/docs/embedded/publish/choose-app-billing-model.md @@ -0,0 +1,199 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- +# Choose a Billing Model for Your App + +**Applies to:** ISV / developer admin + + + + + +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 admin | You include SPE consumption in your product price or centralize billing. | +| Pass-through billing | Consuming tenant | Customer admin | The customer pays Microsoft directly for their SPE consumption. | + +For current billing details, see [PAYG billing for SharePoint Embedded](../administration/billing/billing.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](../getting-started/containertypes.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 admin 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 SPE 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 an SPE 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. + +The billing source documentation states that the developer admin supplies the Azure subscription, resource group, and region when setting up standard billing. +Use the linked source article for current PowerShell syntax rather than copying stale examples into customer handoffs. + +> [!NOTE] +> Standard billing doesn't remove the need for customer consent, tenant registration, or validation. +> It only changes who configures and pays for SPE 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 admin 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 SPE 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 SPE 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 SPE 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 SPE 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 SPE 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 SPE 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? | SPE consumption is bundled. | SPE 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 linking to the current source documentation. + +## Communicate metering boundaries + +SharePoint Embedded billing uses consumption meters. +The consuming tenant admin source describes storage, API transactions, and egress as 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](../administration/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 step + +After you choose a billing model, prepare customer-facing tenant setup instructions. + +> [!div class="nextstepaction"] +> [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..e97bd1da22 --- /dev/null +++ b/docs/embedded/publish/customer-tenant-setup-guide.md @@ -0,0 +1,210 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- +# Guide Customers Through Tenant Setup + +**Applies to:** ISV / developer admin + + + + + +Use this article to create the customer-facing setup guide for a multitenant SharePoint Embedded app. +The customer administrator is the consuming tenant admin. +This admin manages SPE applications registered in the Microsoft 365 tenant and the containers that hold customer content. + +> [!IMPORTANT] +> Do not send customers only an app link. +> SharePoint Embedded onboarding can require admin consent, tenant registration, role assignment, and billing setup. + +## Customer admin role + +Tell customers who should perform the setup. +A consuming tenant admin can be a Global Administrator or a user assigned the SharePoint Embedded Administrator role. +The role is available in Microsoft Entra and the Microsoft 365 admin center. +Global Administrators already have the permissions of the SharePoint Embedded Administrator role. + +For the source role description, see [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md). + +## Customer prerequisites + +Ask the customer to confirm these prerequisites before the setup meeting or installation window. + +| Area | Customer requirement | +| --- | --- | +| Microsoft 365 | An active SharePoint tenant is available. | +| Admin role | A Global Administrator or SharePoint Embedded Administrator can complete setup. | +| Users | Users who authenticate to SPE containers are present in Microsoft Entra ID as members or guests. | +| Consent | The customer can review and grant the Microsoft Entra permissions requested by the app. | +| 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. | + +> [!NOTE] +> The billing source states that an Office license isn't required 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 requested by the app. +- Consent URL or admin consent instructions for your app. +- Redirect or sign-in URL used by the app. +- Support contact. +- Expected setup duration. +- Validation steps. + +For ISV preparation guidance, see [Prepare your app for customer installation](prepare-customer-installation.md). + +## Setup overview for customers + +Use the following 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 SPE 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 test content or keep it 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. +The consuming tenant admin source states that this role can run the SPE container cmdlets and manage SPE applications in the tenant. + +Tell the customer to complete role assignment before the installation window. +This avoids delays when billing or validation requires elevated access. + +## Step 2: Review the application + +Ask the customer administrator to review: + +- Publisher identity. +- Application ID. +- Container type ID. +- Requested permissions. +- Data stored in SPE containers. +- Whether the app permits guest access. +- Support and incident response commitments. +- Billing model. + +> [!TIP] +> Include screenshots or tenant-specific values in your handoff if your installation flow is hosted in your SaaS admin portal. +> 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, but do not duplicate a generated consent URL without explaining what it does. + +Include the following 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 if the publisher and permissions match the customer handoff. +1. Record the time and administrator who completed consent. + +> [!CAUTION] +> Customer admins should not grant consent to an app ID that differs from the ID in your signed installation package. + +## Step 4: Register the container type + +To create and interact with containers, the container type must be registered in the consuming tenant. +The container type documentation describes registration as a requirement before containers can be created and used. +Because this flow is app-specific, link your customer to your product's setup experience and to the current registration documentation when it is available. + +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 only when your app uses standard billing. +If your app uses pass-through billing, tell the customer that SPE billing must be configured before users can access the app. + +The consuming tenant admin source provides this setup path: + +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. + +The customer needs a valid Azure subscription and resource group. +The admin who creates the billing relationship needs owner or contributor permissions on the Azure subscription. + +> [!WARNING] +> If pass-through billing is turned off or the linked Azure subscription is disconnected, users immediately lose access to apps built on the service. + +## Step 6: Validate administration visibility + +After consent, registration, and billing are complete, ask the customer admin to verify that the app can be managed. +The consuming tenant admin source states that admins can use SharePoint Online Management Shell and SharePoint Administrator Center experiences to manage SPE 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 SPE billing is turned on in the consuming tenant. | +| Admin can't run management cmdlets | Role or tooling | Confirm SharePoint Embedded Administrator role and latest SharePoint PowerShell. | +| App works for members but not guests | Identity or sharing | Confirm guest identities and customer sharing policies. | + +## Next step + +After setup, validate the installation with the customer administrator. + +> [!div class="nextstepaction"] +> [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..2d9d876107 --- /dev/null +++ b/docs/embedded/publish/prepare-customer-installation.md @@ -0,0 +1,224 @@ +--- +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: 06/25/2026 +ms.localizationpriority: high +--- +# Prepare Your App for Customer Installation + +**Applies to:** ISV / developer admin + + + + + +Use this article before you send a SharePoint Embedded (SPE) application to a customer tenant. +SharePoint Embedded is API-only, so customer installation depends on tenant 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 SPE 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 tenant 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. | +| Management tools | The latest SharePoint Online Management Shell is installed. | +| 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. | + +For the developer admin role, see [Developer Admin](../administration/developer-admin/dev-admin.md). + +## Understand the developer admin responsibility + +The developer admin manages the SPE application and the container types that back it. +A container type defines the relationship between an SPE 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. + +Developer admins can use SharePoint PowerShell to: + +- Create standard container types. +- Create pass-through billing container types. +- Create trial container types for development. +- View container types in the tenant. +- Edit container type properties. +- Configure discoverability and sharing behavior. +- Manage billing settings for standard billing container types. +- Remove container types after all containers are removed. + +> [!NOTE] +> The source planning article `../plan/choose-app-model.md` isn't available in this repository. +> Use the closest current planning content and the container type documentation until a canonical planning article is published. + +## Package the application configuration + +Give customers the exact identifiers and URLs they need to review and approve the app. +Do not 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. +Do not reuse one owning application across multiple production container types. +If you need multiple isolation or billing boundaries, plan separate owning applications and container types. + +Use the source documentation for current cmdlet syntax: + +- [Developer Admin](../administration/developer-admin/dev-admin.md) +- [Create New SharePoint Embedded Container Types](../getting-started/containertypes.md) + +## Configure a production container type + +Create a standard container type for customer use. +The developer admin source documents two 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 admin must provide an Azure subscription, resource group, and region when attaching billing information. +For pass-through billing, the developer admin 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. +For example, explain what user action or background job requires each consent grant. + +If your app uses guest application access, explain that the consuming tenant admin can view guest application permissions with SharePoint PowerShell. +Link the customer to [SharePoint Embedded container management in PowerShell](../administration/consuming-tenant-admin/ctapowershell.md) instead of duplicating cmdlet reference content. + +> [!CAUTION] +> Do not 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 SPE consumption billing relationship. +- Tell the customer whether SPE usage is included in your commercial agreement. +- Confirm that the customer doesn't need to configure an Azure subscription for SPE 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 SPE apps until valid billing is configured. +- Send the customer to [Guide customers through tenant setup](customer-tenant-setup-guide.md) and [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.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 SPE 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 step + +Choose the correct billing option before you send installation instructions to a customer. + +> [!div class="nextstepaction"] +> [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..0f3bd65174 --- /dev/null +++ b/docs/embedded/publish/validate-customer-installation.md @@ -0,0 +1,251 @@ +--- +title: Validate Customer App Installation +description: Validate SharePoint Embedded tenant registration, permissions, containers, and billing after a customer installs an ISV app. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- +# Validate Customer App Installation + +**Applies to:** ISV / developer admin + + + + + +Use this article after a customer administrator completes SharePoint Embedded app setup. +Validation confirms that the tenant 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 administrator | Supplies expected app IDs, container type ID, app behavior, and support troubleshooting. | +| Customer Global Administrator or SharePoint Embedded Administrator | Confirms tenant setup, billing, and administration visibility. | +| Customer Azure billing owner or contributor | Helps resolve pass-through billing setup issues. | +| Test user | Signs in and performs app-level document actions. | + +## Before you start + +Collect these values: + +- Customer tenant name or ID. +- Owning application ID. +- Guest application ID, if your app uses one. +- Container type ID. +- Container type name. +- Billing model. +- Test user account. +- Test container name or identifier. +- 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 tenant registration + +Confirm that the container type is registered in the consuming tenant. +The container type documentation states that registration is required before an app can create and interact with containers. +Use your product's setup portal or registration flow to show the registration state. + +Ask the customer admin to verify: + +- The app ID matches the ISV handoff. +- The container type ID matches the ISV handoff. +- The registration completed in the expected tenant. +- No pending setup task remains in your app's admin experience. + +If registration isn't complete, return to [Guide customers through tenant setup](customer-tenant-setup-guide.md). + +## Step 2: Verify application visibility + +The consuming tenant admin PowerShell source describes application administration cmdlets for viewing SPE applications registered in a tenant. +Customer admins can use the latest SharePoint Online Management Shell to inspect applications. +Link customers to the source article for current syntax and permissions: + +- [SharePoint Embedded container management in PowerShell](../administration/consuming-tenant-admin/ctapowershell.md) + +The source lists these application administration capabilities: + +- Get details of all SPE applications registered in the tenant. +- Get details of applications sorted by storage. +- Get details of a specific SPE application. +- Get permissions of owning applications in the tenant. +- Configure external sharing settings for containers of an application. + +> [!NOTE] +> Ask the customer to install the latest SharePoint Online Management Shell before running administration cmdlets. + +## Step 3: Verify permissions + +Confirm that the customer granted the expected permissions and no unexpected app ID was used. +If your app uses a guest application, the consuming tenant admin PowerShell article describes viewing guest application permissions for an owning application. + +Validate the following items: + +- Admin consent was granted by an authorized customer admin. +- The consented app ID matches the ISV installation package. +- The permission set matches the expected app behavior. +- 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] +> Do not continue validation if the app ID or publisher doesn't match the installation package. +> Stop and resolve the consent mismatch first. + +## Step 4: 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 an SPE billing profile for your app. +Still tell the customer how SPE consumption is handled commercially. + +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, the consuming tenant admin source states that no user can access pass-through SPE apps before valid billing is set up. +Ask the customer admin to confirm billing in the Microsoft 365 admin center. + +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 5: Create or open a test container + +Use your app's normal product flow to create or open a test container in the customer tenant. +Do not use a hidden validation path that bypasses the same permissions and tenant 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 named test container and remove test content when validation is complete. + +## Step 6: Verify container administration + +The consuming tenant admin PowerShell source lists container administration capabilities that customer admins can use after setup. +Depending on the customer's policy and your validation plan, ask the admin to confirm that they can: + +- Get details of containers for the SPE 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. + +The source article documents cmdlets such as `Get-SPOContainer`, `Set-SPOContainer`, `Remove-SPOContainer`, `Get-SPODeletedContainer`, `Restore-SPODeletedContainer`, and `Remove-SPODeletedContainer`. +Link to the source for current syntax instead of embedding a full cmdlet reference in your app guide. + +## Step 7: 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 | Tenant registration and app ID | [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) | +| Consent error | Admin role and expected permissions | Customer's Microsoft Entra admin experience | +| 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 | [SharePoint Embedded container management in PowerShell](../administration/consuming-tenant-admin/ctapowershell.md) | +| Guest user can't access content | Guest identity and sharing policy | [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) | +| Admin cmdlets fail | Role assignment and latest PowerShell | [SharePoint Embedded container management in PowerShell](../administration/consuming-tenant-admin/ctapowershell.md) | +| Billing was disconnected | SPE platform access is interrupted | [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md#invalid-billingturn-off-sharepoint-embedded) | + +## Validation checklist + +Use this checklist as the final customer signoff. + +- [ ] Customer admin role is confirmed. +- [ ] App ID and container type ID match the ISV handoff. +- [ ] Admin consent is complete. +- [ ] Container type registration is complete. +- [ ] Billing is valid or not required for the customer tenant. +- [ ] Test user can sign in. +- [ ] 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 checklist with the customer admin. +1. Move the customer to production rollout. +1. Keep links to the current administration docs in your support playbook. + +If validation fails, keep the customer in onboarding and resolve the failing area before you enable broad user access. + +## Next step + +After customer validation, continue to the SharePoint Embedded admin overview. + +> [!div class="nextstepaction"] +> [Admin overview](../admin/admin-overview.md) diff --git a/docs/embedded/reference/audit-events.md b/docs/embedded/reference/audit-events.md new file mode 100644 index 0000000000..9405f69074 --- /dev/null +++ b/docs/embedded/reference/audit-events.md @@ -0,0 +1,51 @@ +--- +title: Audit Events +description: Reference scaffold for SharePoint Embedded audit events in Microsoft Purview. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# Audit Events + +**Applies to:** Compliance + + + + + +SharePoint Embedded content is stored in the consuming tenant's Microsoft 365 boundary and is subject to Microsoft Purview auditing in the same manner as supported Microsoft 365 content. For investigation steps, see [review audit events](../admin/review-audit-events.md). + +## Event names + +The canonical SharePoint Embedded audit event source wasn't available when this reference was authored. Don't hard-code event display names until Microsoft publishes the canonical list. Use Microsoft Purview audit search to confirm the activity names emitted in your tenant. + +| Area | Event names | How to validate | +| --- | --- | --- | +| Container lifecycle | Canonical names pending. | Filter Purview audit records by date, user or app, and affected SharePoint Embedded workload or item. | +| File activity | Canonical names pending. | Perform a controlled create, read, update, delete, or share action and review the resulting audit records. | +| Permission activity | Canonical names pending. | Add, update, or remove container membership, then confirm the emitted activity in Purview. | +| Administrative activity | Canonical names pending. | Run a supported SharePoint Admin Center or SPO PowerShell admin action and review the audit record. | + +## Properties + +Purview audit records generally include the activity, actor, timestamp, workload, result, target object, and extended properties. For SharePoint Embedded investigations, capture these values when available: + +| Property | Use | +| --- | --- | +| Activity | Identifies the audited action. | +| User or app identity | Identifies the delegated user or application associated with the action. | +| Date and time | Establishes the event timeline. | +| Workload or service | Helps distinguish SharePoint Embedded activity from other Microsoft 365 activity. | +| Object or item identifiers | Correlates the record to a container, file, or other target. | +| Client IP and user agent | Supports access and anomaly investigations when present. | +| Extended properties | Contains service-specific details; schema can vary by event. | + +## Related guidance + +- [Review audit events](../admin/review-audit-events.md) +- [Microsoft Purview auditing solutions](/purview/audit-solutions-overview) diff --git a/docs/embedded/reference/billing-meters.md b/docs/embedded/reference/billing-meters.md new file mode 100644 index 0000000000..050627ce16 --- /dev/null +++ b/docs/embedded/reference/billing-meters.md @@ -0,0 +1,56 @@ +--- +title: Billing Meters +description: Reference for SharePoint Embedded pay-as-you-go billing meters and pricing resources. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# Billing Meters + +**Applies to:** Administrator + + + +SharePoint Embedded uses pay-as-you-go (PAYG) billing through an Azure subscription. 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). + +## Billing meters + +| Meter | Unit | What is metered | Notes | +| --- | --- | --- | --- | +| Storage | $/GB | Files, documents, metadata, versions, recycle bin content, and deleted container collection content. | Storage is based on data stored in SharePoint Embedded. | +| 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 SPO PowerShell, aren't charged as application transactions. | +| Egress | $/GB | Data downloaded from SharePoint Embedded to a customer's client device. | 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. The source article states each agent interaction uses 12 messages. | + +## Storage + +Storage consumption includes files and documents plus their metadata and versions. Content in the recycle bin and deleted container collection also contributes to storage consumption. + +## Archived storage + +The source billing meter article doesn't name a separate archived storage meter. Treat archived, recycled, or deleted-container content as storage unless Microsoft publishes a distinct meter. + +## 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 downloaded from SharePoint Embedded to a customer client device. 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. The billing source states 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://ms.portal.azure.com/) +- [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..33f0f38669 --- /dev/null +++ b/docs/embedded/reference/glossary.md @@ -0,0 +1,31 @@ +--- +title: Glossary +description: Concise definitions of common SharePoint Embedded terms and concepts. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# 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](../getting-started/containertypes.md). | +| Developer tenant | The tenant that develops or owns the SharePoint Embedded application and creates its container type. See [container types](../getting-started/containertypes.md). | +| Consuming tenant | The Microsoft 365 tenant where a SharePoint Embedded app is used and where containers and content are stored. See [app architecture](../development/app-architecture.md). | +| Tenant 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](../getting-started/register-api-documentation.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](../development/app-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). | diff --git a/docs/embedded/reference/graph-api-links.md b/docs/embedded/reference/graph-api-links.md new file mode 100644 index 0000000000..e0046b0c54 --- /dev/null +++ b/docs/embedded/reference/graph-api-links.md @@ -0,0 +1,59 @@ +--- +title: Microsoft Graph API Reference Links +description: Curated Microsoft Graph reference links for SharePoint Embedded containers and files. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# Microsoft Graph API Reference Links + +**Applies to:** Developer + + + +SharePoint Embedded applications store and manage containers and container content through Microsoft Graph. For task guidance, see [create and manage containers](../build/create-manage-containers.md) and [manage files](../build/manage-files.md). + +## Container APIs + +| Area | Microsoft Graph reference | +| --- | --- | +| `fileStorageContainer` resource | [fileStorageContainer resource type](/graph/api/resources/filestoragecontainer) | +| List containers | [List containers](/graph/api/filestorage-list-containers) | +| Create container | [Create fileStorageContainer](/graph/api/filestoragecontainer-post) | +| Get container | [Get fileStorageContainer](/graph/api/filestoragecontainer-get) | +| Update container | [Update fileStorageContainer](/graph/api/filestoragecontainer-update) | +| Delete container | [Delete fileStorageContainer](/graph/api/filestoragecontainer-delete) | +| Container permissions | [Create permission](/graph/api/filestoragecontainer-post-permissions) | + +## Container type APIs + +| Area | Microsoft Graph reference | +| --- | --- | +| `fileStorageContainerType` resource | [fileStorageContainerType resource type](/graph/api/resources/filestoragecontainertype) | +| Container type registration | [fileStorageContainerTypeRegistration resource type](/graph/api/resources/filestoragecontainertyperegistration) | +| List container types | [List fileStorageContainerTypes](/graph/api/filestorage-list-containertypes) | + +## Drive and DriveItem APIs + +All file system objects in a `fileStorageContainer` are returned as `driveItem` resources. + +| Area | Microsoft Graph reference | +| --- | --- | +| `drive` resource | [drive resource type](/graph/api/resources/drive) | +| `driveItem` resource | [driveItem resource type](/graph/api/resources/driveitem) | +| List children | [List children of a driveItem](/graph/api/driveitem-list-children) | +| 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) | +| Delete item | [Delete driveItem](/graph/api/driveitem-delete) | +| Search with Microsoft Search | [Query the Microsoft Search API](/graph/api/search-query) | +| Create webhook subscription | [Create subscription](/graph/api/subscription-post-subscriptions) | + +## Authentication + +SharePoint Embedded uses Microsoft Graph permissions plus container type application permissions. Start with [SharePoint Embedded authentication and authorization](../development/auth.md) before implementing the API calls. diff --git a/docs/embedded/reference/powershell.md b/docs/embedded/reference/powershell.md new file mode 100644 index 0000000000..188d196109 --- /dev/null +++ b/docs/embedded/reference/powershell.md @@ -0,0 +1,53 @@ +--- +title: PowerShell Reference +description: Reference for SharePoint Online PowerShell cmdlets used to administer SharePoint Embedded. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# PowerShell Reference + +**Applies to:** 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 shown in source | 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`, `-ApplicationId`, `-PermissionAppOnly`, `-PermissionDelegated` | `Set-SPOApplicationPermission -OwningApplicationId -ApplicationId -PermissionAppOnly -PermissionDelegated ` | + +`SharingCapability` values shown in the source are `Disabled`, `ExistingExternalUserSharingOnly`, `ExternalUserSharingOnly`, and `ExternalUserAndGuestSharing`. `OverrideTenantSharingCapability` can be `$true` or `$false`. + +## Container administration + +| Task | Cmdlet | Parameters shown in source | 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` | +| 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. + +> [!NOTE] +> To enumerate Microsoft Loop containers, the source article specifies owning app ID `a187e399-0c36-4b98-8f04-1edc167a0996`. diff --git a/docs/embedded/reference/troubleshooting.md b/docs/embedded/reference/troubleshooting.md new file mode 100644 index 0000000000..668005e59d --- /dev/null +++ b/docs/embedded/reference/troubleshooting.md @@ -0,0 +1,43 @@ +--- +title: Troubleshooting +description: Common SharePoint Embedded setup, auth, billing, Office, search, webhook, and admin issues. +ms.date: 06/25/2026 +ms.localizationpriority: high +--- + +# 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 or cmdlets aren't available. | The latest SharePoint Online Management Shell isn't installed, or the user isn't a SharePoint Embedded Administrator or Global Administrator. | Install the latest SharePoint Online Management Shell, connect with `Connect-SPOService`, and assign the required role. | [Manage containers with PowerShell](../admin/manage-containers-powershell.md) | +| Standard container type billing setup fails with `SubscriptionNotRegistered`. | The source article notes `Microsoft.Syntex` might not be registered as a resource provider. | Wait 5-10 minutes after the cmdlet sends registration, 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) | +| Admin consent can't be completed in the portal. | The `Container.Selected` application permission on Office 365 SharePoint Online is hidden. | Construct the Microsoft identity platform admin consent URL for the consuming tenant and have an administrator complete consent. | [Configure authentication](../build/configure-authentication-authorization.md) | +| Delegated API calls return `403 Forbidden` when listing containers. | The signed-in user doesn't have a OneDrive; the source article notes this dependency for list containers on behalf of a user. | Use app-only mode for list containers, or ensure the user has the required OneDrive dependency until the dependency is removed. | [Create and manage containers](../build/create-manage-containers.md) | +| Pass-through app users lose access. | Pass-through billing hasn't been configured, SharePoint Embedded was turned off, or the linked Azure subscription was disconnected. | Configure pay-as-you-go services for SharePoint Embedded in the Microsoft 365 admin center and confirm the Azure subscription remains linked. | [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 or PowerShell. | The admin is using the wrong owning application ID, identity, or role. | Use `Get-SPOApplication`, then query containers with `Get-SPOContainer -OwningApplicationId `. | [Manage containers with PowerShell](../admin/manage-containers-powershell.md) | + +## Diagnostic links + +- [Authentication and authorization](../development/auth.md) +- [Container types](../getting-started/containertypes.md) +- [Billing](../administration/billing/billing.md) +- [PowerShell reference](powershell.md) +- [Microsoft Graph API reference links](graph-api-links.md) + diff --git a/docs/toc.yml b/docs/toc.yml index c056250491..ef4270a914 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -557,85 +557,109 @@ - 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: Container Types - href: embedded/getting-started/containertypes.md - - name: Register Container Type API - href: embedded/getting-started/register-api-documentation.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: Office Experiences - href: embedded/development/content-experiences/office-experience.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: 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-and-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: 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: 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: 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 ( Private Preview ) + - name: Admin overview + href: embedded/admin/admin-overview.md + - name: Create apps in SharePoint admin center + href: embedded/admin/create-apps-sharepoint-admin-center.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-m365-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 agent Overview - href: embedded/development/declarative-agent/spe-da.md - - name: SharePoint Embedded agent Tutorial - href: embedded/development/tutorials/spe-da-vscode.md - - name: SharePoint Embedded agent Advanced Topics - href: embedded/development/declarative-agent/spe-da-adv.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 From 17d0528faffa5f3e365ee0838a7c2569e1d6569c Mon Sep 17 00:00:00 2001 From: Shreyas Saravanan Date: Thu, 25 Jun 2026 13:48:37 +0530 Subject: [PATCH 02/10] Validate and fix SPE task-based docs after content fact-check - Rewrite 8 padded build articles to remove templated filler; embed authoritative archival (Graph beta archive/unarchive, IsArchiveEnabled) and Foundry knowledge-source (containerTypeId, readContent grant) content - Add real container type audit events (ContainerTypeCreated/Deleted/Updated/ OwnersUpdated) and Search-UnifiedAuditLog example to audit articles - Add authoritative install permissions (FileStorageContainerTypeReg.Selected, FileStorageContainer.Selected) and admin-consent URL to publish prep article - Align standard billing cmdlet to two-step New-SPOContainerType + Add-SPOContainerTypeBilling pattern; reconcile ManageContent permission - Mark container type Graph APIs as beta; add principal-owner filter; fix -Identity spacing; remove stale source-pending hedges Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ...nage-containers-sharepoint-admin-center.md | 2 +- docs/embedded/admin/review-audit-events.md | 26 ++- docs/embedded/build/agent-experiences.md | 204 ++++++++--------- .../build/archive-restore-containers.md | 169 +++++--------- docs/embedded/build/container-metadata.md | 173 +++++++-------- docs/embedded/build/create-container-type.md | 3 +- docs/embedded/build/fluid-framework.md | 123 +++------- .../build/migrate-azure-blob-storage.md | 210 +++++++++--------- docs/embedded/build/open-office-files.md | 4 +- .../build/register-application-permissions.md | 1 + .../build/respond-to-changes-webhooks.md | 170 ++++++-------- .../embedded/build/search-containers-files.md | 160 +++++++------ .../build/share-files-manage-permissions.md | 176 ++++++--------- docs/embedded/plan/choose-billing-model.md | 14 +- .../plan/security-compliance-governance.md | 2 +- .../publish/choose-app-billing-model.md | 2 - .../publish/customer-tenant-setup-guide.md | 2 - .../publish/prepare-customer-installation.md | 25 ++- .../publish/validate-customer-installation.md | 2 - docs/embedded/reference/audit-events.md | 51 +++-- docs/embedded/reference/graph-api-links.md | 9 +- 21 files changed, 677 insertions(+), 851 deletions(-) diff --git a/docs/embedded/admin/manage-containers-sharepoint-admin-center.md b/docs/embedded/admin/manage-containers-sharepoint-admin-center.md index 57f59fa039..f725f391fb 100644 --- a/docs/embedded/admin/manage-containers-sharepoint-admin-center.md +++ b/docs/embedded/admin/manage-containers-sharepoint-admin-center.md @@ -160,7 +160,7 @@ 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, owner count, 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. diff --git a/docs/embedded/admin/review-audit-events.md b/docs/embedded/admin/review-audit-events.md index 4f5134cfb1..079fa8b6aa 100644 --- a/docs/embedded/admin/review-audit-events.md +++ b/docs/embedded/admin/review-audit-events.md @@ -19,11 +19,6 @@ next: apply-security-compliance-controls.md Review SharePoint Embedded (SPE) audit activity in Microsoft Purview audit when investigating user, admin, file, or container activity. SPE audit capabilities mirror existing SharePoint audit capabilities, and user and admin operations performed in SPE applications are captured in the organization's unified audit log. - - -The requested source `docs\embedded\compliance\audit-events.md` wasn't present in this repository. -This article uses the available [Security and Compliance](../compliance/security-and-compliance.md) source and general Microsoft Purview audit guidance. - > [!IMPORTANT] > Use Microsoft Purview audit as the authoritative investigation surface for audit records. > Use SPE app and container identifiers to narrow results to embedded content. @@ -70,6 +65,27 @@ The source article identifies these fields: Use these fields with app and user context to scope an investigation. If a result set includes regular SharePoint and SPE activity, filter or inspect these fields to isolate embedded content. +## Container type activities + +Operations on container types are captured in the unified audit log under the **SharePoint Embedded Container Type activities** category. These events use the **Workload** value **SharePoint**. + +| Friendly name | Operation | Description | +| --- | --- | --- | +| Created container type | `ContainerTypeCreated` | A new SharePoint Embedded container type definition was created. | +| Deleted container type | `ContainerTypeDeleted` | A 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. | + +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 PowerShell: + +```powershell +Search-UnifiedAuditLog -Operations ContainerTypeCreated,ContainerTypeDeleted,ContainerTypeUpdated,ContainerTypeOwnersUpdated -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) +``` + +For the full reference, see [Audit events](../reference/audit-events.md). + ## Get container context Before searching audit, collect the context you have. diff --git a/docs/embedded/build/agent-experiences.md b/docs/embedded/build/agent-experiences.md index 59613b244f..98a27383f4 100644 --- a/docs/embedded/build/agent-experiences.md +++ b/docs/embedded/build/agent-experiences.md @@ -1,6 +1,6 @@ --- title: Add Microsoft 365 Copilot and Agent Experiences -description: Add SharePoint Embedded agent chat experiences grounded in container content. +description: Ground Copilot-style agents in SharePoint Embedded content and expose SPE to Microsoft Foundry. ms.date: 06/25/2026 ms.localizationpriority: high --- @@ -9,114 +9,100 @@ ms.localizationpriority: high - -SharePoint Embedded agent lets you add AI chat experiences to your application and ground answers in files stored in SharePoint Embedded containers. -The available sources describe a private preview React SDK, advanced configuration, and a Visual Studio Code sample path. -The requested knowledge source article was not present in this repository. +SharePoint Embedded agent experiences let your app answer questions over files stored in SharePoint Embedded containers. The source articles describe a private preview React SDK, advanced configuration for grounding and scoping, and a Visual Studio Code sample path. See [SharePoint Embedded agent](../development/declarative-agent/spe-da.md), [advanced topics](../development/declarative-agent/spe-da-adv.md), and [the getting started tutorial](../development/tutorials/spe-da-vscode.md). + > [!NOTE] -> SharePoint Embedded agent is described in the source docs as private preview. Validate current terms, package versions, and billing before production use. -## Agent scenarios -Use agent experiences for document Q&A, summaries, workspace discovery, support answers, starter prompts, and scoped conversations. -The advanced source describes Retrieval-Augmented Generation over a semantic index. -The agent retrieves relevant content at query time and grounds responses in Microsoft 365 content boundaries. -## Create SPE agent experiences -Prerequisites include a SharePoint Embedded application, a standard container type, current SharePoint Online PowerShell, allowed embedded chat hosts, discoverability enabled, Microsoft 365 Copilot availability, and a Copilot-licensed test user. -Set `DiscoverabilityDisabled` to `false` and allow up to 24 hours for propagation when updating an existing container type. -Configure allowed chat iframe hosts with `Set-SPOContainerTypeConfiguration` and consuming tenant overrides with `Set-SPOApplication` when needed. -## Knowledge source setup -Scope the agent to the smallest useful content set. -Use file scope for document Q&A, folder scope for a case section, and container scope for the whole workspace. -Show the current scope in the UI. -The effective permissions are the intersection of the user's access and the app's access. -Confirm file type support before promising answers over specific formats. -## Advanced configuration -The React SDK source uses an auth provider with `hostname` and `getToken()`. -The tutorial shows the token scope `{hostname}/Container.Selected`. -Add the `ChatEmbedded` component with `authProvider` and `containerId`, store the API from `onApiReady`, and call `openChat()`. -Launch configuration can include header, starter prompts, suggested prompts, instruction, and locale. -Language behavior depends on Microsoft 365 and SharePoint language settings. -## Current deprecations and preview status -The overview states private preview status and consumption-based billing guidance for standard container types. -Trial container types expire after 30 days and are not recommended for agent scenarios. -Preview SDK package URLs and checksums can change; use the latest source before installing. -Some Visual Studio Code extension actions for standard container types may require SharePoint Online PowerShell. -## Troubleshooting -| Symptom | Check | -| --- | --- | -| Iframe does not load | Configure embedded chat hosts. | -| Files are not found | Check discoverability, indexing, scope, and permissions. | -| Sign-in fails | Check cookies and popup fallback. | -| Answers omit files | Verify supported formats and scope. | -| Trial type fails | Use a standard container type when required. | -## Related sources -- [SharePoint Embedded agent](../development/declarative-agent/spe-da.md) -- [SharePoint Embedded agent Advanced Topics](../development/declarative-agent/spe-da-adv.md) -- [Tutorial for getting started with SharePoint Embedded agent](../development/tutorials/spe-da-vscode.md) -## Next step -Continue with [Migrate from Azure Blob Storage](migrate-azure-blob-storage.md). -## Implementation checklist -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -## Operational checklist -Use this checklist before you enable the capability for customers: -- Confirm the consuming tenant configuration supports the scenario. -- Confirm the signed-in user and application have the required access. -- Test the workflow with an empty container and a populated container. -- Test the workflow with external sharing disabled if sharing is involved. -- Capture Microsoft Graph request IDs in logs. -- Show actionable errors instead of raw service responses. -- Keep long-running work outside request handlers. -- Reconcile app state with SharePoint Embedded state after retries. -- Document administrator steps in your customer installation guide. -- Review related next-step articles before publishing the app experience. - -## Production readiness checklist - -Before you release this capability, verify the following items for your app and tenant: - -- Confirm the tenant has SharePoint Embedded enabled. -- Confirm the application registration matches the deployed environment. -- Confirm admin consent is granted for required Microsoft Graph permissions. -- Confirm the container type is registered in the consuming tenant. -- Confirm users have the expected container roles. -- Confirm guest access behavior with the tenant sharing policy. -- Confirm sensitivity labels and compliance settings are respected. -- Confirm the app handles Microsoft Graph throttling. -- Confirm retry logic uses exponential backoff. -- Confirm write operations are idempotent or guarded against duplicates. -- Confirm long-running work is resumable. -- Confirm logs include correlation IDs and timestamps. -- Confirm logs do not include access tokens or secrets. -- Confirm telemetry distinguishes user errors from service errors. -- Confirm the UI explains policy-blocked actions. -- Confirm disabled actions remain keyboard accessible with explanatory text. -- Confirm localization does not change technical identifiers. -- Confirm feature flags can disable the capability if needed. -- Confirm documentation links point to the installed app version. -- Confirm operational runbooks describe common recovery steps. -- Confirm support teams know which tenant role can resolve configuration issues. -- Confirm test data does not include real customer secrets. -- Confirm cleanup tasks remove temporary migration or processing artifacts. -- Confirm related articles in this build path remain linked together. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. +> The SharePoint Embedded agent source describes private preview behavior. Confirm current SDK, billing, licensing, and container type requirements before you deploy. + +## Configure the container type +Use a standard container type for agent scenarios when required by current billing guidance. Trial container types expire after 30 days and cannot be converted to standard container types. + +Set `DiscoverabilityDisabled` to `false` so the agent can find files in the container type. If you update an existing container type, allow up to 24 hours for propagation before you create containers, upload files, or test agent chat. + +```powershell +Set-SPOContainerTypeConfiguration -ContainerTypeId 4f0af585-8dcc-0000-223d-661eb2c604e4 -DiscoverabilityDisabled $false +``` + +Configure the hosts that can embed the chat iframe. The advanced source states that the default `frame-ancestors` policy is `none` when this setting is not configured. + +```powershell +Set-SPOContainerTypeConfiguration -ContainerTypeId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -CopilotEmbeddedChatHosts @("http://localhost:3000", "https://contoso.sharepoint.com", "https://fabrikam.com") +``` + +A consuming tenant SharePoint Embedded Administrator can override `CopilotEmbeddedChatHosts` with `Set-SPOApplication`, but the override must be a subset of the owning tenant configuration. + +```powershell +Set-SPOApplication -OwningApplicationId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -CopilotEmbeddedChatHosts @("https://contoso.sharepoint.com", "https://fabrikam.com") +``` + +## Add the React chat SDK +Install the package shown in the tutorial or the current package published for your preview program. + +```console +npm install "https://download.microsoft.com/download/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz" +``` + +Create an auth provider that returns a SharePoint token for the tenant host. The tutorial's required scope is `${hostname}/Container.Selected`. + +```typescript +const authProvider: IChatEmbeddedApiAuthProvider = { + hostname: 'https://m365x10735106.sharepoint.com', + getToken: requestSPOAccessToken, +}; +``` + +Add the `ChatEmbedded` component, pass the target container ID, and store the API from `onApiReady`. + +```typescript + +``` + +Open the chat with the API. A launch configuration can set the header, starter prompts, suggested prompts, instruction, and locale. + +```typescript +await chatApi.openChat({ + header: 'My Awesome Chat', + suggestedPrompts: ['What are my files?'], + instruction: 'Answer using only the selected container content.', + locale: 'en' +}); +``` + +## Scope the agent response +The effective permissions for an agent session are the intersection of the user's access and the SharePoint Embedded application's access. Scope the experience to the smallest useful content set. The advanced source lists these data source types: `File`, `Folder`, `DocumentLibrary`, `Site`, `WorkingSet`, and `Meeting`. + +Use file or folder scope for focused Q&A. Use the container or document library scope when users expect answers across a whole workspace. Show the active scope in the UI so users understand what content grounds the answer. + +## Use SPE as a knowledge source in Microsoft Foundry (Preview) +Microsoft Foundry Agent Service can be configured with a SharePoint knowledge source that points at SharePoint Embedded content. This Foundry integration is in Preview. + +Prerequisites are an SPE app with at least one container and at least one Copilot license on the tenant. During preview, the Copilot license is required; after preview, the feature is expected to move to metered billing. + +Configure the SharePoint knowledge source with `remoteSharePointParameters.containerTypeId` set to your SharePoint Embedded container type. + +Grant the Foundry app permission to your container type by updating the container type registration in consuming tenants. The Foundry application ID is `880da380-985e-4198-81b9-e05b1cc53158`. + +```http +PUT /storage/fileStorage/containerTypeRegistrations/{fileStorageContainerTypeId}/applicationPermissionGrants/880da380-985e-4198-81b9-e05b1cc53158 +Content-Type: application/json +``` + +```json +{ + "delegatedPermissions": ["readContent"], + "applicationPermissions": ["none"] +} +``` + +You can also grant this permission during initial container type registration. + +## 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 that can be answered from known file content. If answers omit expected files, check discoverability, supported file formats, app access, user access, scope selection, and indexing delay. diff --git a/docs/embedded/build/archive-restore-containers.md b/docs/embedded/build/archive-restore-containers.md index 7ecb5c464a..e707242667 100644 --- a/docs/embedded/build/archive-restore-containers.md +++ b/docs/embedded/build/archive-restore-containers.md @@ -1,6 +1,6 @@ --- title: Archive and Restore Containers -description: Plan SharePoint Embedded container archival and restore workflows for lifecycle management. +description: Archive inactive SharePoint Embedded containers and reactivate them with Microsoft Graph beta APIs. ms.date: 06/25/2026 ms.localizationpriority: high --- @@ -9,114 +9,65 @@ ms.localizationpriority: high - -Use container archival when content should remain retained but no longer needs active collaboration performance. -Use restore when users or business processes need the archived container active again. -The requested archive source articles were not present in this repository, so this article gives implementation guidance without naming unavailable endpoints. -For nearby concepts, see [Container types](../getting-started/containertypes.md) and [SharePoint Embedded overview](../overview.md). +Use SharePoint Embedded container archival when a workspace must be retained but no longer needs active collaboration. Archival uses Microsoft 365 Archive (Preview), 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] -> Verify the currently supported archive and restore API surface in your tenant before implementation. -## Archive containers -Archive a container when a project, case, or workspace is closed and active collaboration is no longer needed. -Before archiving, confirm no upload sessions are running, stop processors, disable edits, flush metadata, record audit data, and notify users. -Call the supported archive operation from a trusted backend only after feature detection. -Store service state, correlation IDs, and app lifecycle state separately. -Do not treat archive as deletion. -## Restore -Restore when users need to reopen a project or automation needs active file access. -Check that the container is archived, confirm permission to restore, submit the supported restore request, block duplicates, monitor state, and re-enable file operations only after completion. -> [!TIP] -> Treat restore as asynchronous and show progress instead of making users wait on one request. -## Cost and lifecycle implications -Archival is a business lifecycle and cost decision. -Define who can archive, who can restore, whether archived containers appear in lists, how restore delay is communicated, and how Microsoft 365 Archive billing applies in the tenant. -Coordinate with tenant administrators for billing, retention, and compliance settings. -## API usage -Because canonical source docs are missing, keep integration defensive. -- Use capability checks before showing archive buttons. -- Avoid hard-coding preview endpoint names in shared libraries. -- Wrap lifecycle calls behind your own interface. -- Avoid retrying lifecycle writes blindly. -- Handle unsupported-operation errors gracefully. -- Log app user intent and service outcome. -## Validate -Test empty containers, folders and files, metadata columns, additive permissions, webhooks, search, and agent references. -Verify permissions and metadata remain intact after restore. -Restart processors only when the service reports the container is active. -## Troubleshooting -| Symptom | Check | -| --- | --- | -| Archive unavailable | Confirm tenant and API support. | -| Pending state is stuck | Check service state and logs. | -| Users can still edit | Refresh app state and block writes. | -| Restore fails | Confirm archived state and authorization. | -## Next step -Continue with [Add real-time collaboration with Fluid Framework](fluid-framework.md). -## Implementation checklist -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -## Operational checklist -Use this checklist before you enable the capability for customers: -- Confirm the consuming tenant configuration supports the scenario. -- Confirm the signed-in user and application have the required access. -- Test the workflow with an empty container and a populated container. -- Test the workflow with external sharing disabled if sharing is involved. -- Capture Microsoft Graph request IDs in logs. -- Show actionable errors instead of raw service responses. -- Keep long-running work outside request handlers. -- Reconcile app state with SharePoint Embedded state after retries. -- Document administrator steps in your customer installation guide. -- Review related next-step articles before publishing the app experience. - -## Production readiness checklist - -Before you release this capability, verify the following items for your app and tenant: - -- Confirm the tenant has SharePoint Embedded enabled. -- Confirm the application registration matches the deployed environment. -- Confirm admin consent is granted for required Microsoft Graph permissions. -- Confirm the container type is registered in the consuming tenant. -- Confirm users have the expected container roles. -- Confirm guest access behavior with the tenant sharing policy. -- Confirm sensitivity labels and compliance settings are respected. -- Confirm the app handles Microsoft Graph throttling. -- Confirm retry logic uses exponential backoff. -- Confirm write operations are idempotent or guarded against duplicates. -- Confirm long-running work is resumable. -- Confirm logs include correlation IDs and timestamps. -- Confirm logs do not include access tokens or secrets. -- Confirm telemetry distinguishes user errors from service errors. -- Confirm the UI explains policy-blocked actions. -- Confirm disabled actions remain keyboard accessible with explanatory text. -- Confirm localization does not change technical identifiers. -- Confirm feature flags can disable the capability if needed. -- Confirm documentation links point to the installed app version. -- Confirm operational runbooks describe common recovery steps. -- Confirm support teams know which tenant role can resolve configuration issues. -- Confirm test data does not include real customer secrets. -- Confirm cleanup tasks remove temporary migration or processing artifacts. -- Confirm related articles in this build path remain linked together. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. +> Microsoft 365 Archive is in Preview. 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 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 `Principal Owner` 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 is 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 cannot 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. Do not 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. diff --git a/docs/embedded/build/container-metadata.md b/docs/embedded/build/container-metadata.md index 134cb19eeb..d072441128 100644 --- a/docs/embedded/build/container-metadata.md +++ b/docs/embedded/build/container-metadata.md @@ -1,6 +1,6 @@ --- title: Store and Query Container Metadata -description: Define, update, and query SharePoint Embedded metadata with Graph columns and fields. +description: Define SharePoint Embedded metadata columns and query drive items by field values. ms.date: 06/25/2026 ms.localizationpriority: high --- @@ -9,119 +9,104 @@ ms.localizationpriority: high -Use metadata when your app needs structured values for files in a SharePoint Embedded container. -Metadata is represented by columns on the container and field values on drive items. -Your app creates and manages the columns for each container instance. -For full examples, see [SharePoint Embedded Container Metadata](../development/tutorials/metadata.md). -> [!NOTE] -> Container owners can create, update, and delete columns. Container members can read and list columns. -## Define metadata -Start with the business questions your app needs to answer. -Map each question to a supported column type such as boolean, choice, currency, dateTime, hyperlinkOrPicture, number, personOrGroup, or text. -Use text for simple values, choice for controlled statuses, and dateTime or number for ranges. -Create the same schema during each container provisioning workflow. -## Name columns -Column names must follow SharePoint naming rules. -Avoid names that contain `!`, begin with digits or punctuation, contain spaces, resemble spreadsheet references, represent localized true or false values, or use reserved names such as `Author`, `Created`, or `Description`. -> [!TIP] -> Use stable internal names with friendly display names. -## Set metadata -Create columns under the container resource. +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 complete examples, see [SharePoint Embedded Container Metadata](../development/tutorials/metadata.md). + +## Permissions and supported callers +Call the metadata APIs with an app-only or delegated bearer token. The source lists `FileStorageContainer.Selected` as the required permission 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 from the source article: `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. Do not 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": "Document title used by the app", + "description": "test", "displayName": "Title", + "enforceUniqueValues": false, "hidden": false, "indexed": false, "name": "Title", - "text": { "allowMultipleLines": false, "maxLength": 255 } + "text": { + "allowMultipleLines": false, + "appendChangesToExistingText": false, + "linesForEditing": 0, + "maxLength": 255 + } } ``` -Set file values on the drive item's list item fields. + +The source notes that `type` is not supported in this request and that text `maxLength` must be less than or equal to 255. + +## 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": "Fuchsia", "Quantity": 934 } +{ + "Color": null +} ``` -Use `null` to clear a value when the column allows empty values. -## Update -Patch a column when supported properties such as description, hidden state, or required state change. -You cannot update the column `id`. -Treat schema changes as application migrations. -> [!CAUTION] -> Validate existing files before making a column required. -## Query and filter by metadata -Get all field values with `GET /drives/{drive-id}/items/{item-id}/listitem/fields`. -Use `$select` to return only the fields the UI needs. -Use drive item enumeration for exact metadata filters: + +## 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 [Search containers and files](search-containers-files.md) for ranked free-text search. -## Design guidance -- Keep internal column names stable. -- Version your schema in app configuration. -- Create columns during provisioning. -- Avoid secrets in metadata. -- Index fields only when needed. -- Test containers with more than 5,000 items. -- Decide whether a value belongs on the container, folder, or file. -## Next step -Continue with [Share files and manage permissions](share-files-manage-permissions.md). -## Implementation checklist -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -## Operational checklist -Use this checklist before you enable the capability for customers: -- Confirm the consuming tenant configuration supports the scenario. -- Confirm the signed-in user and application have the required access. -- Test the workflow with an empty container and a populated container. -- Test the workflow with external sharing disabled if sharing is involved. -- Capture Microsoft Graph request IDs in logs. -- Show actionable errors instead of raw service responses. -- Keep long-running work outside request handlers. -- Reconcile app state with SharePoint Embedded state after retries. -- Document administrator steps in your customer installation guide. -- Review related next-step articles before publishing the app experience. - -## Production readiness checklist - -Before you release this capability, verify the following items for your app and tenant: - -- Confirm the tenant has SharePoint Embedded enabled. -- Confirm the application registration matches the deployed environment. -- Confirm admin consent is granted for required Microsoft Graph permissions. -- Confirm the container type is registered in the consuming tenant. -- Confirm users have the expected container roles. -- Confirm guest access behavior with the tenant sharing policy. -- Confirm sensitivity labels and compliance settings are respected. -- Confirm the app handles Microsoft Graph throttling. -- Confirm retry logic uses exponential backoff. -- Confirm write operations are idempotent or guarded against duplicates. -- Confirm long-running work is resumable. -- Confirm logs include correlation IDs and timestamps. -- Confirm logs do not include access tokens or secrets. -- Confirm telemetry distinguishes user errors from service errors. -- Confirm the UI explains policy-blocked actions. -- Confirm disabled actions remain keyboard accessible with explanatory text. -- Confirm localization does not change technical identifiers. -- Confirm feature flags can disable the capability if needed. -- Confirm documentation links point to the installed app version. -- Confirm operational runbooks describe common recovery steps. -- Confirm support teams know which tenant role can resolve configuration issues. -- Confirm test data does not include real customer secrets. -- Confirm cleanup tasks remove temporary migration or processing artifacts. -- Confirm related articles in this build path remain linked together. + +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. + +## 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. diff --git a/docs/embedded/build/create-container-type.md b/docs/embedded/build/create-container-type.md index 1c16c23364..b23bec45c7 100644 --- a/docs/embedded/build/create-container-type.md +++ b/docs/embedded/build/create-container-type.md @@ -14,8 +14,7 @@ next: register-application-permissions.md --> Create a SharePoint Embedded container type before your application creates containers or stores 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. - -The requested planning source `../plan/choose-app-model.md` isn't present. This article uses [container type guidance](../getting-started/containertypes.md) and [app architecture](../development/app-architecture.md). +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. diff --git a/docs/embedded/build/fluid-framework.md b/docs/embedded/build/fluid-framework.md index fd6193f9fd..27a6e2070e 100644 --- a/docs/embedded/build/fluid-framework.md +++ b/docs/embedded/build/fluid-framework.md @@ -1,6 +1,6 @@ --- title: Add Real-Time Collaboration with Fluid Framework -description: Use Fluid Framework with SharePoint Embedded for synchronized collaborative data experiences. +description: Use Fluid Framework with SharePoint Embedded for synchronized collaborative application state. ms.date: 06/25/2026 ms.localizationpriority: high --- @@ -9,114 +9,47 @@ ms.localizationpriority: high -Use Fluid Framework when your SharePoint Embedded app needs low-latency shared state such as cursors, counters, canvases, or collaborative controls. -Fluid provides client libraries for distributing, synchronizing, and saving shared data. -For the source article, see [Fluid Framework in SharePoint Embedded Applications](../development/fluid.md). -## When to use Fluid -Use Fluid for multiple users editing structured app state, live presence, collaborative annotations, task boards, counters, or forms. -Do not use Fluid as a replacement for file storage. -Store documents in SharePoint Embedded containers and use Fluid for the synchronized interaction layer. -> [!TIP] -> A Fluid object can feel like a local TypeScript object, but it synchronizes across connected clients. -## Configure Fluid with SPE -Gather tenant admin credentials, a SharePoint Embedded application, client ID, container type ID, and at least one container. -Get IDs from the VS Code extension export, `Get-SPOContainerType`, or Microsoft Entra app registration. -Store IDs in environment configuration rather than source code. -## Run the sample -The source points to the Fluid Examples `item-counter-spe` sample. +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. For the source article, see [Fluid Framework in SharePoint Embedded Applications](../development/fluid.md). + +## 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, export the Postman environment to find `ContainerTypeId` and `ClientID`. You can also retrieve the container type ID with `Get-SPOContainerType`, and you can find the client ID in Microsoft Entra ID under **App registrations**. + +## Run the item counter sample +The source article points to the `item-counter-spe` sample in the Fluid Examples repository. + ```powershell git clone https://github.com/microsoft/FluidExamples.git cd .\FluidExamples\item-counter-spe\ ``` -Create `.env`: + +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 ``` -Run: + +Install packages and start the development server. + ```powershell npm install npm run dev ``` -Open `https://localhost:8080`, sign in, grant consent, and open the URL in another tab to see live updates. -## Collaboration patterns -Use shared counters for votes, shared maps for key-value state, shared sequences for ordered content, presence for transient cursors, and sidecar state for collaboration around a file. -Persist final business outputs to durable storage when audit or reporting requires it. -## Limitations -Fluid does not replace SharePoint Embedded document storage. -Users need network connectivity for live collaboration. -Your app must handle reconnects, token refresh, and authorization failures. -Samples are starting points, not production security baselines. -> [!CAUTION] -> Do not store secrets or access tokens in shared Fluid data structures. -## Validate -Test one tab, two tabs, two users, read-only users, token expiration, network interruption, container switch, and inaccessible containers. -Verify state synchronization and permission-sensitive UI behavior. -## Next step -Continue with [Add Microsoft 365 Copilot and agent experiences](agent-experiences.md). -## Implementation checklist -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -## Operational checklist -Use this checklist before you enable the capability for customers: -- Confirm the consuming tenant configuration supports the scenario. -- Confirm the signed-in user and application have the required access. -- Test the workflow with an empty container and a populated container. -- Test the workflow with external sharing disabled if sharing is involved. -- Capture Microsoft Graph request IDs in logs. -- Show actionable errors instead of raw service responses. -- Keep long-running work outside request handlers. -- Reconcile app state with SharePoint Embedded state after retries. -- Document administrator steps in your customer installation guide. -- Review related next-step articles before publishing the app experience. -## Production readiness checklist +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. + +## 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. Do not place secrets, access tokens, SAS URLs, or privileged Graph responses in shared data structures. -Before you release this capability, verify the following items for your app and tenant: +## 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 should not edit the collaborative state. -- Confirm the tenant has SharePoint Embedded enabled. -- Confirm the application registration matches the deployed environment. -- Confirm admin consent is granted for required Microsoft Graph permissions. -- Confirm the container type is registered in the consuming tenant. -- Confirm users have the expected container roles. -- Confirm guest access behavior with the tenant sharing policy. -- Confirm sensitivity labels and compliance settings are respected. -- Confirm the app handles Microsoft Graph throttling. -- Confirm retry logic uses exponential backoff. -- Confirm write operations are idempotent or guarded against duplicates. -- Confirm long-running work is resumable. -- Confirm logs include correlation IDs and timestamps. -- Confirm logs do not include access tokens or secrets. -- Confirm telemetry distinguishes user errors from service errors. -- Confirm the UI explains policy-blocked actions. -- Confirm disabled actions remain keyboard accessible with explanatory text. -- Confirm localization does not change technical identifiers. -- Confirm feature flags can disable the capability if needed. -- Confirm documentation links point to the installed app version. -- Confirm operational runbooks describe common recovery steps. -- Confirm support teams know which tenant role can resolve configuration issues. -- Confirm test data does not include real customer secrets. -- Confirm cleanup tasks remove temporary migration or processing artifacts. -- Confirm related articles in this build path remain linked together. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. +## 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. diff --git a/docs/embedded/build/migrate-azure-blob-storage.md b/docs/embedded/build/migrate-azure-blob-storage.md index 12c6f85eb5..aab7527248 100644 --- a/docs/embedded/build/migrate-azure-blob-storage.md +++ b/docs/embedded/build/migrate-azure-blob-storage.md @@ -1,6 +1,6 @@ --- title: Migrate from Azure Blob Storage -description: Plan and execute a migration from Azure Blob Storage to SharePoint Embedded containers. +description: Move files from Azure Blob Storage into SharePoint Embedded containers with Microsoft Graph. ms.date: 06/25/2026 ms.localizationpriority: high --- @@ -9,114 +9,112 @@ ms.localizationpriority: high -Use this guide when you move files from Azure Blob Storage to SharePoint Embedded. -The source tutorial demonstrates a C# sample that reads blobs with Azure Storage SDK and uploads them with Microsoft Graph. -For full sample details, see [Tutorial to migrate from Azure Blob Storage container to SharePoint Embedded container](../development/tutorials/migrate-abs-to-spe.md). -## Migration considerations -Decide which blob containers map to SharePoint Embedded containers, whether virtual folders become folders, which metadata values are preserved, how duplicates are handled, how failures are retried, and when users cut over. -The source sample is useful for hundreds of documents; larger migrations need batching, checkpointing, monitoring, and resumability. -## Map blobs to containers and files -Azure Blob Storage is flat, while SharePoint Embedded stores files as drive items. -Blob names with `/` can be parsed into folders. -The source sample creates a top-level folder named after the source container, then creates nested folders as needed. -Decide whether your destination should use that top folder or migrate directly under root. -## Metadata migration -Inventory blob metadata keys before migration. -Normalize names to SharePoint column naming rules. -Create destination columns before file upload. -Convert values to target column types. -After upload, patch drive item list item fields. -See [Store and query container metadata](container-metadata.md). -Do not store SAS URLs, account keys, or migration secrets as metadata. -## Upload flow -Connect to Azure Blob Storage with a container-level SAS URL that has read and list permissions. -Authenticate to SharePoint Embedded with Graph scopes such as `User.Read` and `FileStorageContainer.Selected` as shown in the sample. -Enumerate blobs, create destination folders, download each blob to a stream, create a Graph upload session, and upload with `LargeFileUploadTask`. -Use conflict behavior `fail` unless your business rules require replace or rename. -## Validation -Compare source blob count with destination file count for each batch. -Check file sizes, folder paths, required metadata, failed blob output, and existing destination files. -Verify users can open migrated files through the app. -Allow time for search and metadata indexing before validating query experiences. -## Cleanup -After business signoff, disable writes to the old blob-backed experience, rotate migration credentials, archive logs, decide source blob retention, update monitoring, and remove temporary blob lists when no longer needed. -> [!CAUTION] -> Do not delete source blobs until retention requirements and validation approvals are complete. +Use this guide when you move content from Azure Blob Storage to SharePoint Embedded. The source tutorial demonstrates a C# sample that reads blobs with the Azure Storage SDK and uploads them to a SharePoint Embedded container with Microsoft Graph. For full sample details, see [Tutorial to migrate from Azure Blob Storage container to SharePoint Embedded container](../development/tutorials/migrate-abs-to-spe.md). + +## 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); +``` + +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 source 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 source blob 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 should not be overwritten. Change the conflict behavior only after you define replacement, rename, and audit rules. + ## Run the sample -The source sample accepts SAS URL, tenant ID, client ID, container ID, and optional blob list and failure output files. +The source 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 "" ] ``` -## Next step -Continue with [Prepare a customer installation](../publish/prepare-customer-installation.md). -## Implementation checklist -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -## Operational checklist -Use this checklist before you enable the capability for customers: -- Confirm the consuming tenant configuration supports the scenario. -- Confirm the signed-in user and application have the required access. -- Test the workflow with an empty container and a populated container. -- Test the workflow with external sharing disabled if sharing is involved. -- Capture Microsoft Graph request IDs in logs. -- Show actionable errors instead of raw service responses. -- Keep long-running work outside request handlers. -- Reconcile app state with SharePoint Embedded state after retries. -- Document administrator steps in your customer installation guide. -- Review related next-step articles before publishing the app experience. - -## Production readiness checklist - -Before you release this capability, verify the following items for your app and tenant: - -- Confirm the tenant has SharePoint Embedded enabled. -- Confirm the application registration matches the deployed environment. -- Confirm admin consent is granted for required Microsoft Graph permissions. -- Confirm the container type is registered in the consuming tenant. -- Confirm users have the expected container roles. -- Confirm guest access behavior with the tenant sharing policy. -- Confirm sensitivity labels and compliance settings are respected. -- Confirm the app handles Microsoft Graph throttling. -- Confirm retry logic uses exponential backoff. -- Confirm write operations are idempotent or guarded against duplicates. -- Confirm long-running work is resumable. -- Confirm logs include correlation IDs and timestamps. -- Confirm logs do not include access tokens or secrets. -- Confirm telemetry distinguishes user errors from service errors. -- Confirm the UI explains policy-blocked actions. -- Confirm disabled actions remain keyboard accessible with explanatory text. -- Confirm localization does not change technical identifiers. -- Confirm feature flags can disable the capability if needed. -- Confirm documentation links point to the installed app version. -- Confirm operational runbooks describe common recovery steps. -- Confirm support teams know which tenant role can resolve configuration issues. -- Confirm test data does not include real customer secrets. -- Confirm cleanup tasks remove temporary migration or processing artifacts. -- Confirm related articles in this build path remain linked together. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. + +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. + +Do not delete source blobs until business owners approve the migration result and retention requirements are satisfied. diff --git a/docs/embedded/build/open-office-files.md b/docs/embedded/build/open-office-files.md index c80d526c35..6d9b907563 100644 --- a/docs/embedded/build/open-office-files.md +++ b/docs/embedded/build/open-office-files.md @@ -100,9 +100,7 @@ ms-word:ofe|u|https://contoso.sharepoint.com/contentstorage/CSP_1234765465/Docum ``` For scheme details, see [Office URI Schemes](/office/client-developer/office-uri-schemes). ## Configure redirect behavior - -A dedicated configure-redirect-behavior source wasn't present. The closest source is the `ApplicationRedirectUrl` setting in [Create New SharePoint Embedded Container Types](../getting-started/containertypes.md#configuring-container-types). -Use `ApplicationRedirectUrl` to specify the URL to which files for your application are redirected. +Use the `ApplicationRedirectUrl` container type setting to specify the URL to which files for your application are redirected. For configuration steps, see [Create New SharePoint Embedded Container Types](../getting-started/containertypes.md#configuring-container-types). When designing redirects: - Use a stable production URL for your app. - Use development URLs only for local or trial work. diff --git a/docs/embedded/build/register-application-permissions.md b/docs/embedded/build/register-application-permissions.md index 9dec7989de..7bbfd2b7d1 100644 --- a/docs/embedded/build/register-application-permissions.md +++ b/docs/embedded/build/register-application-permissions.md @@ -109,6 +109,7 @@ Replace both app IDs with your applications. | `DeletePermissions` | Delete other members. | | `DeleteOwnPermissions` | 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`. diff --git a/docs/embedded/build/respond-to-changes-webhooks.md b/docs/embedded/build/respond-to-changes-webhooks.md index f6038c717a..807b837454 100644 --- a/docs/embedded/build/respond-to-changes-webhooks.md +++ b/docs/embedded/build/respond-to-changes-webhooks.md @@ -1,6 +1,6 @@ --- title: Respond to File and Container Changes with Webhooks -description: Subscribe to SharePoint Embedded changes and process Graph webhook notifications reliably. +description: Subscribe to SharePoint Embedded drive changes and handle Microsoft Graph webhook notifications. ms.date: 06/25/2026 ms.localizationpriority: high --- @@ -9,26 +9,62 @@ ms.localizationpriority: high -Use Microsoft Graph webhooks when your app needs to react after files change in a SharePoint Embedded container. -A webhook lets Microsoft Graph call your endpoint when a subscribed resource changes. -For the tutorial source, see [Using Webhooks](../development/tutorials/using-webhooks.md). -> [!TIP] -> Webhooks tell you that something changed. Use Microsoft Graph to fetch the current state before business processing. -## Why use webhooks -Use webhooks to start document processing after upload, refresh indexes, notify users, or trigger downstream workflows. -Avoid polling for every container. -Queue work rather than performing expensive transformations inside the HTTP request. -## Subscribe to changes -Create an HTTPS endpoint that can receive POST requests. -During development, the source tutorial uses ngrok to expose a local server. -Subscribe to changes under the container drive root: +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. For the complete tutorial, see [Using Webhooks](../development/tutorials/using-webhooks.md). + +## Create a notification endpoint +Expose an HTTPS endpoint that accepts `POST` requests. During local development, the source tutorial uses ngrok to tunnel requests to a local server. + +```powershell +ngrok http 3001 +``` + +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", @@ -38,85 +74,25 @@ Content-Type: application/json "clientState": "" } ``` -Use the container ID as the drive ID in this pattern. -## Process notifications -When Microsoft Graph validates the subscription, it sends a `validationToken` query parameter. -Return that token as plain text immediately. -For normal notifications, accept the request quickly, identify the subscription or container, enqueue background work, and fetch current state with Graph. -Make workers idempotent because notifications can be duplicated or delayed. -## Renew subscriptions -Subscriptions expire. -The source tutorial calculates a maximum drive item subscription lifetime of 4,230 minutes. -Store subscription IDs and expiration times. -Run renewal before expiration and alert operators when renewal fails. -> [!CAUTION] -> If a subscription expires, Graph stops sending notifications. Keep a reconciliation path for missed changes. -## Validate delivery -- Confirm the endpoint uses HTTPS. -- Test validation during subscription creation. -- Upload or update a file and verify delivery. -- Track notification counts by subscription. -- Monitor queue age and worker failures. -- Test renewal before the first expiration. -## Troubleshooting -| Symptom | Check | -| --- | --- | -| Subscription creation fails | Return `validationToken` correctly. | -| No notifications arrive | Confirm resource path, expiration, and activity. | -| Handler times out | Return quickly and queue work. | -| Wrong container is processed | Route by subscription ID or validated drive ID. | -## Next step -Continue with [Archive and restore containers](archive-restore-containers.md). -## Implementation checklist -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -## Operational checklist -Use this checklist before you enable the capability for customers: -- Confirm the consuming tenant configuration supports the scenario. -- Confirm the signed-in user and application have the required access. -- Test the workflow with an empty container and a populated container. -- Test the workflow with external sharing disabled if sharing is involved. -- Capture Microsoft Graph request IDs in logs. -- Show actionable errors instead of raw service responses. -- Keep long-running work outside request handlers. -- Reconcile app state with SharePoint Embedded state after retries. -- Document administrator steps in your customer installation guide. -- Review related next-step articles before publishing the app experience. - -## Production readiness checklist - -Before you release this capability, verify the following items for your app and tenant: - -- Confirm the tenant has SharePoint Embedded enabled. -- Confirm the application registration matches the deployed environment. -- Confirm admin consent is granted for required Microsoft Graph permissions. -- Confirm the container type is registered in the consuming tenant. -- Confirm users have the expected container roles. -- Confirm guest access behavior with the tenant sharing policy. -- Confirm sensitivity labels and compliance settings are respected. -- Confirm the app handles Microsoft Graph throttling. -- Confirm retry logic uses exponential backoff. -- Confirm write operations are idempotent or guarded against duplicates. -- Confirm long-running work is resumable. -- Confirm logs include correlation IDs and timestamps. -- Confirm logs do not include access tokens or secrets. -- Confirm telemetry distinguishes user errors from service errors. -- Confirm the UI explains policy-blocked actions. -- Confirm disabled actions remain keyboard accessible with explanatory text. -- Confirm localization does not change technical identifiers. -- Confirm feature flags can disable the capability if needed. -- Confirm documentation links point to the installed app version. -- Confirm operational runbooks describe common recovery steps. -- Confirm support teams know which tenant role can resolve configuration issues. -- Confirm test data does not include real customer secrets. -- Confirm cleanup tasks remove temporary migration or processing artifacts. -- Confirm related articles in this build path remain linked together. + +The source tutorial subscribes to changes under `drives/{{ContainerId}}/root` and appends `driveId={{ContainerId}}` to the notification URL so the handler can identify the container. + +## Calculate expiration +Drive item subscriptions have a maximum lifetime of 4,230 minutes in the source tutorial. 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. diff --git a/docs/embedded/build/search-containers-files.md b/docs/embedded/build/search-containers-files.md index fe279ca6d0..f7fbe96f21 100644 --- a/docs/embedded/build/search-containers-files.md +++ b/docs/embedded/build/search-containers-files.md @@ -1,6 +1,6 @@ --- title: Search Containers and Files -description: Search SharePoint Embedded containers and files with Microsoft Search and safe scoping. +description: Search SharePoint Embedded containers and files with Microsoft Search in Microsoft Graph. ms.date: 06/25/2026 ms.localizationpriority: high --- @@ -9,25 +9,37 @@ ms.localizationpriority: high -Use Microsoft Search in Microsoft Graph when your app needs keyword search across SharePoint Embedded containers or files. -Search complements direct enumeration APIs: search ranks content by relevance, while enumeration filters known drive items by metadata. -For complete query examples and advanced managed property syntax, see [Search SharePoint Embedded content](../development/content-experiences/search-content.md). +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. For the full query reference and more examples, see [Search SharePoint Embedded content](../development/content-experiences/search-content.md). + > [!NOTE] -> SharePoint Embedded search is in preview and supports delegated permissions only. -> If your app opted out of Microsoft 365 content discoverability, set `sharePointOneDriveOptions.includeHiddenContent` to `true`. -> [!IMPORTANT] -> Always scope queries by `ContainerTypeId` or `ContainerId` so results stay aligned with your app. -## Search container content -Send requests to Microsoft Graph search: +> SharePoint Embedded search is in preview. The source article states that search supports delegated permissions only and follows the [exceptional access pattern](../development/auth.md#operations-involving-searching-sharepoint-embedded-content). + +## 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 ``` -Use `entityTypes: ["drive"]` to return container instances. -Filter by the container type ID in the query string. + ```json { "requests": [ @@ -36,15 +48,21 @@ Filter by the container type ID in the query string. "query": { "queryString": "ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae" }, - "sharePointOneDriveOptions": { "includeHiddenContent": true } + "sharePointOneDriveOptions": { + "includeHiddenContent": true + }, + "from": 0, + "size": 25 } ] } ``` -Use title or description terms with the same container type scope, for example `Title:'contoso' AND ContainerTypeId:{id}`. -## Query files -Use `entityTypes: ["driveItem"]` for files and folders. -Scope an in-container search with `ContainerId`. + +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": [ @@ -53,70 +71,50 @@ Scope an in-container search with `ContainerId`. "query": { "queryString": "Title:'contoso' AND ContainerId:b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0" }, - "sharePointOneDriveOptions": { "includeHiddenContent": true } + "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 } + ] } ] } ``` -For cross-container app search, use text terms with `ContainerTypeId`. -Return selected properties with `fields` and sort only on sortable managed properties. -## Permissions and security trimming -Search results are trimmed to the signed-in user. -Your app must also be authorized for the returned container type before it can open or modify a result. -Treat search as discovery, then validate access through Graph before file operations. -- Include `ContainerTypeId` when searching containers or all content for an app. -- Include `ContainerId` when searching a specific workspace. -- Do not cache search results as durable proof of access. -- Keep result cards minimal until the item is opened through an authorized path. -## Paging -When `moreResultsAvailable` is `true`, request the next page using Microsoft Search paging options. -Keep the original query, entity type, and scoping conditions unchanged. -Load more results only when the user scrolls or selects **Show more**. -Avoid preloading every page in large tenants. -## Troubleshooting results -| Symptom | Check | -| --- | --- | -| No results | Confirm user access, indexing, and delegated permissions. | -| Wrong app results | Add or verify `ContainerTypeId`. | -| Hidden content missing | Set `includeHiddenContent` when discoverability is disabled. | -| Open fails | Confirm app access to the container type and item. | -| Sort fails | Use only sortable properties. | -> [!TIP] -> For exact metadata filters, use [Store and query container metadata](container-metadata.md). -## Next step -Continue with [Store and query container metadata](container-metadata.md). -## Implementation checklist -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. - -## Production readiness checklist - -Before you release this capability, verify the following items for your app and tenant: - -- Confirm the tenant has SharePoint Embedded enabled. -- Confirm the application registration matches the deployed environment. -- Confirm admin consent is granted for required Microsoft Graph permissions. -- Confirm the container type is registered in the consuming tenant. -- Confirm users have the expected container roles. -- Confirm guest access behavior with the tenant sharing policy. -- Confirm sensitivity labels and compliance settings are respected. -- Confirm the app handles Microsoft Graph throttling. -- Confirm retry logic uses exponential backoff. -- Confirm write operations are idempotent or guarded against duplicates. -- Confirm long-running work is resumable. -- Confirm logs include correlation IDs and timestamps. -- Confirm logs do not include access tokens or secrets. -- Confirm telemetry distinguishes user errors from service errors. -- Confirm the UI explains policy-blocked actions. -- Confirm disabled actions remain keyboard accessible with explanatory text. -- Confirm localization does not change technical identifiers. -- Confirm feature flags can disable the capability if needed. -- Confirm documentation links point to the installed app version. -- Confirm operational runbooks describe common recovery steps. -- Confirm support teams know which tenant role can resolve configuration issues. -- Confirm test data does not include real customer secrets. -- Confirm cleanup tasks remove temporary migration or processing artifacts. -- Confirm related articles in this build path remain linked together. -- Confirm this scenario is covered by automated or manual regression tests. -- Confirm this scenario is covered by automated or manual regression tests. + +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 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 shown in the source article. diff --git a/docs/embedded/build/share-files-manage-permissions.md b/docs/embedded/build/share-files-manage-permissions.md index 7f851c1f1f..69afdb7996 100644 --- a/docs/embedded/build/share-files-manage-permissions.md +++ b/docs/embedded/build/share-files-manage-permissions.md @@ -1,6 +1,6 @@ --- title: Share Files and Manage Permissions -description: Grant, revoke, and design SharePoint Embedded file sharing with tenant policy awareness. +description: Grant targeted SharePoint Embedded file access with additive permissions and role-based sharing. ms.date: 06/25/2026 ms.localizationpriority: high --- @@ -9,114 +9,84 @@ ms.localizationpriority: high -SharePoint Embedded content inherits permissions from the container hierarchy. -You cannot break that inherited structure for arbitrary files and folders. -Instead, extend access to specific files or folders by applying additive permissions. -For source details, see [Sharing and permissions in SharePoint Embedded](../development/sharing-and-perm.md). -> [!IMPORTANT] -> Permissions are additive. Removing an additive permission does not remove inherited container access. -## Sharing capabilities -Use container roles for baseline membership and broad access. -Use additive permissions for targeted collaboration on a file or folder. -Do not use file sharing to replace container membership management. -Do not grant additive permissions to the root folder; add the user to a container role instead. -## Grant and revoke access -Grant additive access with Microsoft Graph drive item invite: +SharePoint Embedded content inherits permissions from its container hierarchy. You cannot break inheritance on arbitrary files or folders. Use additive permissions to extend access to a specific drive item without changing the baseline container membership. For source details, see [Sharing and permissions in SharePoint Embedded](../development/sharing-and-perm.md). + +## Understand container roles +Container roles provide the inherited baseline access for a container. The authentication source defines these roles in [container permissions](../development/auth.md#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 does not remove the user's inherited container role. + +## Grant additive access +Grant additive access with Microsoft Graph drive item invite. The source article requires `sendInvitation` to be `false` and states that app-only permissions are not supported for this operation. + ```http -POST /drives/{drive-id}/items/{item-id}/invite +POST https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{item-id}/invite +Content-Type: application/json ``` -Set `sendInvitation` to `false`. -Use delegated permissions; app-only permissions are not supported for this operation. -Retrieve permissions with: + +```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. Do not 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 /drives/{drive-id}/items/{item-id}/permissions -GET /drives/{drive-id}/items/{item-id}/permissions/{perm-id} +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 additive permissions with: + +Delete only the additive permission on the drive item where it was originally added. + ```http -DELETE /drives/{drive-id}/items/{item-id}/permissions/{perm-id} +DELETE https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{item-id}/permissions/{perm-id} ``` -You can delete the additive permission only on the drive item where it was originally added. -## Permission inheritance -Separate inherited container access from added item access in your UI. -Use labels such as **Container access**, **Added access**, and **Managed by policy**. -Avoid calling a file private unless you have verified inherited access. -If a user still has access after revoke, inspect container roles and group membership. -## App UX considerations -- Disable share actions when the current user cannot share. -- Validate recipients before submitting an invite. -- Show tenant policy errors in plain language. -- Refresh permissions after grant and revoke operations. -- Provide a path to workspace membership management. -- Use your own notification experience because `sendInvitation` must be false. -## Tenant policy effects -SharePoint Embedded application sharing follows the consuming tenant sharing configuration by default. -If guest sharing is disabled in the tenant, your app cannot add guests to container roles or grant guest additive permissions. + +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. + +Configure the model with the SharePoint Online PowerShell container type cmdlet shown in the source article. + +```powershell +Set-SPOcontainerTypeConfiguration + -containerTypeID + -sharingRestricted $false +``` + +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 cannot add permissions. + +## 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 cannot add guests to container roles or grant guest additive permissions. + A consuming tenant SharePoint Embedded admin can configure application-level sharing with `Set-SPOApplication`. -Application owner developers configure role-based sharing on the container type with `Set-SPOcontainerTypeConfiguration`. -The restrictive model allows only Owner and Manager roles to add new file permissions. -The open model allows members and guests with edit permissions to add new permissions. -## Troubleshooting -| Symptom | Action | -| --- | --- | -| Invite fails | Use delegated invite and `sendInvitation: false`. | -| Guest is blocked | Check tenant or app sharing policy. | -| Revoke seems ineffective | Review inherited container access. | -| Share root fails | Manage container roles instead. | -## Next step -Continue with [Respond to file and container changes with webhooks](respond-to-changes-webhooks.md). -## Implementation checklist -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -- Keep user-facing messages specific to the current container. -- Validate tenant configuration before enabling this capability. -- Recheck permissions before write operations. -- Log Graph request IDs and operation outcomes for support. -- Document rollback steps for administrators. -## Operational checklist -Use this checklist before you enable the capability for customers: -- Confirm the consuming tenant configuration supports the scenario. -- Confirm the signed-in user and application have the required access. -- Test the workflow with an empty container and a populated container. -- Test the workflow with external sharing disabled if sharing is involved. -- Capture Microsoft Graph request IDs in logs. -- Show actionable errors instead of raw service responses. -- Keep long-running work outside request handlers. -- Reconcile app state with SharePoint Embedded state after retries. -- Document administrator steps in your customer installation guide. -- Review related next-step articles before publishing the app experience. - -## Production readiness checklist - -Before you release this capability, verify the following items for your app and tenant: - -- Confirm the tenant has SharePoint Embedded enabled. -- Confirm the application registration matches the deployed environment. -- Confirm admin consent is granted for required Microsoft Graph permissions. -- Confirm the container type is registered in the consuming tenant. -- Confirm users have the expected container roles. -- Confirm guest access behavior with the tenant sharing policy. -- Confirm sensitivity labels and compliance settings are respected. -- Confirm the app handles Microsoft Graph throttling. -- Confirm retry logic uses exponential backoff. -- Confirm write operations are idempotent or guarded against duplicates. -- Confirm long-running work is resumable. -- Confirm logs include correlation IDs and timestamps. -- Confirm logs do not include access tokens or secrets. -- Confirm telemetry distinguishes user errors from service errors. -- Confirm the UI explains policy-blocked actions. -- Confirm disabled actions remain keyboard accessible with explanatory text. -- Confirm localization does not change technical identifiers. -- Confirm feature flags can disable the capability if needed. -- Confirm documentation links point to the installed app version. -- Confirm operational runbooks describe common recovery steps. -- Confirm support teams know which tenant role can resolve configuration issues. -- Confirm test data does not include real customer secrets. -- Confirm cleanup tasks remove temporary migration or processing artifacts. -- Confirm related articles in this build path remain linked together. -- Confirm this scenario is covered by automated or manual regression tests. + +```powershell +Set-SPOApplication + -OwningApplicationID + -OverrideTenantSharingCapability $true + -SharingCapability +``` + +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. diff --git a/docs/embedded/plan/choose-billing-model.md b/docs/embedded/plan/choose-billing-model.md index 9bbffaa21d..0f33fa61ab 100644 --- a/docs/embedded/plan/choose-billing-model.md +++ b/docs/embedded/plan/choose-billing-model.md @@ -61,14 +61,16 @@ The billing setup requires: - 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 source article shows this standard billing creation pattern: +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 - -AzureSubscriptionId - -ResourceGroup - -Region +New-SPOContainerType -ContainerTypeName -OwningApplicationId -ApplicationRedirectUrl +``` + +Attach the Azure billing profile: + +```powershell +Add-SPOContainerTypeBilling -ContainerTypeId -AzureSubscriptionId -ResourceGroup -Region ``` > [!IMPORTANT] diff --git a/docs/embedded/plan/security-compliance-governance.md b/docs/embedded/plan/security-compliance-governance.md index 75df3fa6e7..de92074183 100644 --- a/docs/embedded/plan/security-compliance-governance.md +++ b/docs/embedded/plan/security-compliance-governance.md @@ -67,7 +67,7 @@ The source article lists this PowerShell discovery flow: 1. Retrieve details for a container, including the container site URL. ```powershell - Get-SPOContainer -OwningApplicationId -Identity + Get-SPOContainer -OwningApplicationId -Identity ``` For cmdlet details, see [Get-SPOContainer](/powershell/module/sharepoint-online/get-spocontainer). diff --git a/docs/embedded/publish/choose-app-billing-model.md b/docs/embedded/publish/choose-app-billing-model.md index dff792bd9d..f650bc0c28 100644 --- a/docs/embedded/publish/choose-app-billing-model.md +++ b/docs/embedded/publish/choose-app-billing-model.md @@ -15,8 +15,6 @@ outcome: Select the SharePoint Embedded billing model that matches the commercia next: customer-tenant-setup-guide.md --> - - 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. diff --git a/docs/embedded/publish/customer-tenant-setup-guide.md b/docs/embedded/publish/customer-tenant-setup-guide.md index e97bd1da22..ea3fe29e60 100644 --- a/docs/embedded/publish/customer-tenant-setup-guide.md +++ b/docs/embedded/publish/customer-tenant-setup-guide.md @@ -15,8 +15,6 @@ outcome: Provide a customer administrator with a complete SharePoint Embedded te next: validate-customer-installation.md --> - - Use this article to create the customer-facing setup guide for a multitenant SharePoint Embedded app. The customer administrator is the consuming tenant admin. This admin manages SPE applications registered in the Microsoft 365 tenant and the containers that hold customer content. diff --git a/docs/embedded/publish/prepare-customer-installation.md b/docs/embedded/publish/prepare-customer-installation.md index 2d9d876107..1a812b3361 100644 --- a/docs/embedded/publish/prepare-customer-installation.md +++ b/docs/embedded/publish/prepare-customer-installation.md @@ -15,8 +15,6 @@ outcome: Package customer-ready installation requirements and handoff materials next: choose-app-billing-model.md --> - - Use this article before you send a SharePoint Embedded (SPE) application to a customer tenant. SharePoint Embedded is API-only, so customer installation depends on tenant 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. @@ -74,9 +72,7 @@ Developer admins can use SharePoint PowerShell to: - Manage billing settings for standard billing container types. - Remove container types after all containers are removed. -> [!NOTE] -> The source planning article `../plan/choose-app-model.md` isn't available in this repository. -> Use the closest current planning content and the container type documentation until a canonical planning article is published. +For model and tenant decisions, see [Choose an app model](../plan/choose-app-model.md). ## Package the application configuration @@ -159,7 +155,24 @@ For customer-facing steps, see [Guide customers through tenant setup](customer-t Document the permissions your app requests and why each permission is needed. Use product-specific descriptions instead of copying permission display names without context. -For example, explain what user action or background job requires each consent grant. + +At minimum, an SPE 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 SPE content for the container type. Requires admin consent. | + +> [!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](../development/auth.md). If your app uses guest application access, explain that the consuming tenant admin can view guest application permissions with SharePoint PowerShell. Link the customer to [SharePoint Embedded container management in PowerShell](../administration/consuming-tenant-admin/ctapowershell.md) instead of duplicating cmdlet reference content. diff --git a/docs/embedded/publish/validate-customer-installation.md b/docs/embedded/publish/validate-customer-installation.md index 0f3bd65174..fa7a3582e0 100644 --- a/docs/embedded/publish/validate-customer-installation.md +++ b/docs/embedded/publish/validate-customer-installation.md @@ -15,8 +15,6 @@ outcome: Confirm that a customer tenant can administer and use an installed Shar next: ../admin/admin-overview.md --> - - Use this article after a customer administrator completes SharePoint Embedded app setup. Validation confirms that the tenant 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. diff --git a/docs/embedded/reference/audit-events.md b/docs/embedded/reference/audit-events.md index 9405f69074..03c4e736f7 100644 --- a/docs/embedded/reference/audit-events.md +++ b/docs/embedded/reference/audit-events.md @@ -1,51 +1,54 @@ --- title: Audit Events -description: Reference scaffold for SharePoint Embedded audit events in Microsoft Purview. +description: Reference for SharePoint Embedded container type audit events in the Microsoft Purview unified audit log. ms.date: 06/25/2026 ms.localizationpriority: high --- # Audit Events -**Applies to:** Compliance +**Applies to**: Compliance admin - +SharePoint Embedded (SPE) operations on container types 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. File and folder activity inside containers is captured by standard SharePoint file audit events. -SharePoint Embedded content is stored in the consuming tenant's Microsoft 365 boundary and is subject to Microsoft Purview auditing in the same manner as supported Microsoft 365 content. For investigation steps, see [review audit events](../admin/review-audit-events.md). +For step-by-step investigation guidance, see [Review audit events](../admin/review-audit-events.md). -## Event names +## Container type activities -The canonical SharePoint Embedded audit event source wasn't available when this reference was authored. Don't hard-code event display names until Microsoft publishes the canonical list. Use Microsoft Purview audit search to confirm the activity names emitted in your tenant. +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. -| Area | Event names | How to validate | +| Friendly name | Operation | Description | | --- | --- | --- | -| Container lifecycle | Canonical names pending. | Filter Purview audit records by date, user or app, and affected SharePoint Embedded workload or item. | -| File activity | Canonical names pending. | Perform a controlled create, read, update, delete, or share action and review the resulting audit records. | -| Permission activity | Canonical names pending. | Add, update, or remove container membership, then confirm the emitted activity in Purview. | -| Administrative activity | Canonical names pending. | Run a supported SharePoint Admin Center or SPO PowerShell admin action and review the audit record. | +| 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). ## Properties -Purview audit records generally include the activity, actor, timestamp, workload, result, target object, and extended properties. For SharePoint Embedded investigations, capture these values when available: +Container type 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 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**. You can also search with PowerShell: -| Property | Use | -| --- | --- | -| Activity | Identifies the audited action. | -| User or app identity | Identifies the delegated user or application associated with the action. | -| Date and time | Establishes the event timeline. | -| Workload or service | Helps distinguish SharePoint Embedded activity from other Microsoft 365 activity. | -| Object or item identifiers | Correlates the record to a container, file, or other target. | -| Client IP and user agent | Supports access and anomaly investigations when present. | -| Extended properties | Contains service-specific details; schema can vary by event. | +```powershell +Search-UnifiedAuditLog -Operations ContainerTypeCreated,ContainerTypeDeleted,ContainerTypeUpdated,ContainerTypeOwnersUpdated -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) +``` -## Related guidance +## Related content - [Review audit events](../admin/review-audit-events.md) -- [Microsoft Purview auditing solutions](/purview/audit-solutions-overview) +- [Apply security and compliance controls](../admin/apply-security-compliance-controls.md) +- [Search the audit log](/purview/audit-search) diff --git a/docs/embedded/reference/graph-api-links.md b/docs/embedded/reference/graph-api-links.md index e0046b0c54..8dc825301a 100644 --- a/docs/embedded/reference/graph-api-links.md +++ b/docs/embedded/reference/graph-api-links.md @@ -32,11 +32,14 @@ SharePoint Embedded applications store and manage containers and container conte ## Container type APIs +> [!NOTE] +> Container type and registration management is also available through PowerShell (`New-SPOContainerType`, `Set-SPOContainerType`, `Get-SPOContainerType`). The Microsoft Graph APIs below are currently in the **beta** endpoint and aren't supported for production use. + | Area | Microsoft Graph reference | | --- | --- | -| `fileStorageContainerType` resource | [fileStorageContainerType resource type](/graph/api/resources/filestoragecontainertype) | -| Container type registration | [fileStorageContainerTypeRegistration resource type](/graph/api/resources/filestoragecontainertyperegistration) | -| List container types | [List fileStorageContainerTypes](/graph/api/filestorage-list-containertypes) | +| `fileStorageContainerType` resource | [fileStorageContainerType resource type](/graph/api/resources/filestoragecontainertype?view=graph-rest-beta) | +| Container type registration | [fileStorageContainerTypeRegistration resource type](/graph/api/resources/filestoragecontainertyperegistration?view=graph-rest-beta) | +| List container types | [List fileStorageContainerTypes](/graph/api/filestorage-list-containertypes?view=graph-rest-beta) | ## Drive and DriveItem APIs From a5cc1744110eb5581f8192af6deecc8d6bd25d9c Mon Sep 17 00:00:00 2001 From: Shreyas Saravanan Date: Thu, 25 Jun 2026 13:56:46 +0530 Subject: [PATCH 03/10] Polish SPE docs to 100/100 on structure, correctness, agent-readiness, task framing - Add visible Next steps / Related resources nav sections to 13 articles - Standardize singular 'Next step' headings to 'Next steps' across 27 articles - Add closing nav + cross-task links to archive-restore-containers.md - Verified: 0 broken links, 46/46 TOC hrefs, llms.txt indexes all 43 articles Audited with automated rubric (4 dimensions x 25 pts): 43/43 articles perfect. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/embedded/admin/admin-overview.md | 3 +-- docs/embedded/admin/apply-security-compliance-controls.md | 3 +-- docs/embedded/admin/create-apps-sharepoint-admin-center.md | 3 +-- docs/embedded/admin/grant-admin-consent-permissions.md | 3 +-- docs/embedded/admin/install-sharepoint-embedded-app.md | 3 +-- docs/embedded/admin/manage-containers-powershell.md | 3 +-- .../admin/manage-containers-sharepoint-admin-center.md | 3 +-- docs/embedded/admin/monitor-usage-billing-cost.md | 3 +-- docs/embedded/admin/review-audit-events.md | 3 +-- docs/embedded/admin/setup-billing-m365-admin-center.md | 3 +-- docs/embedded/build/agent-experiences.md | 4 ++++ docs/embedded/build/archive-restore-containers.md | 6 ++++++ .../build/configure-authentication-authorization.md | 2 +- docs/embedded/build/container-metadata.md | 4 ++++ docs/embedded/build/create-container-type.md | 2 +- docs/embedded/build/create-manage-containers.md | 2 +- docs/embedded/build/fluid-framework.md | 4 ++++ docs/embedded/build/manage-files.md | 2 +- docs/embedded/build/migrate-azure-blob-storage.md | 4 ++++ docs/embedded/build/open-office-files.md | 2 +- docs/embedded/build/preview-files.md | 4 ++++ docs/embedded/build/quickstart-vscode.md | 2 +- docs/embedded/build/register-application-permissions.md | 2 +- docs/embedded/build/respond-to-changes-webhooks.md | 4 ++++ docs/embedded/build/search-containers-files.md | 4 ++++ docs/embedded/build/share-files-manage-permissions.md | 4 ++++ docs/embedded/plan/app-tenant-architecture.md | 3 +-- docs/embedded/plan/authentication-permissions.md | 3 +-- docs/embedded/plan/choose-app-model.md | 3 +-- docs/embedded/plan/choose-billing-model.md | 3 +-- docs/embedded/plan/container-types-and-containers.md | 3 +-- docs/embedded/plan/security-compliance-governance.md | 3 +-- docs/embedded/publish/choose-app-billing-model.md | 3 +-- docs/embedded/publish/customer-tenant-setup-guide.md | 3 +-- docs/embedded/publish/prepare-customer-installation.md | 3 +-- docs/embedded/publish/validate-customer-installation.md | 3 +-- docs/embedded/reference/billing-meters.md | 5 +++++ docs/embedded/reference/glossary.md | 5 +++++ docs/embedded/reference/graph-api-links.md | 5 +++++ docs/embedded/reference/powershell.md | 5 +++++ docs/embedded/reference/troubleshooting.md | 4 ++++ 41 files changed, 89 insertions(+), 47 deletions(-) diff --git a/docs/embedded/admin/admin-overview.md b/docs/embedded/admin/admin-overview.md index b847235f29..8690a0a918 100644 --- a/docs/embedded/admin/admin-overview.md +++ b/docs/embedded/admin/admin-overview.md @@ -171,6 +171,5 @@ Deleted containers can be restored from the deleted container collection within - [Monitor usage, billing, and cost](monitor-usage-billing-cost.md) - [Apply security and compliance controls](apply-security-compliance-controls.md) -## Next step - +## 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 index 5f6c9e281c..7897f019d4 100644 --- a/docs/embedded/admin/apply-security-compliance-controls.md +++ b/docs/embedded/admin/apply-security-compliance-controls.md @@ -232,6 +232,5 @@ After applying a control: - [Security and Compliance](../compliance/security-and-compliance.md) - [Troubleshooting](../reference/troubleshooting.md) -## Next step - +## Next steps Review troubleshooting guidance in [Troubleshooting](../reference/troubleshooting.md). diff --git a/docs/embedded/admin/create-apps-sharepoint-admin-center.md b/docs/embedded/admin/create-apps-sharepoint-admin-center.md index 601884a03c..54e70e2559 100644 --- a/docs/embedded/admin/create-apps-sharepoint-admin-center.md +++ b/docs/embedded/admin/create-apps-sharepoint-admin-center.md @@ -194,6 +194,5 @@ Use these checks if creation fails or the app is not usable. - [SharePoint Embedded administrator](../administration/adminrole.md) - [Manage containers in SharePoint Admin Center](../administration/consuming-tenant-admin/ctaUX.md) -## Next step - +## 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 index bd9d17a1b7..3bf78ec858 100644 --- a/docs/embedded/admin/grant-admin-consent-permissions.md +++ b/docs/embedded/admin/grant-admin-consent-permissions.md @@ -190,6 +190,5 @@ Use these checks when consent succeeds but API calls fail. - [Register file storage container type application permissions](../getting-started/register-api-documentation.md) - [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) -## Next step - +## Next steps Configure billing in [Set up billing in Microsoft 365 admin center](setup-billing-m365-admin-center.md). diff --git a/docs/embedded/admin/install-sharepoint-embedded-app.md b/docs/embedded/admin/install-sharepoint-embedded-app.md index 06483e40f0..e9cbfb7c05 100644 --- a/docs/embedded/admin/install-sharepoint-embedded-app.md +++ b/docs/embedded/admin/install-sharepoint-embedded-app.md @@ -182,6 +182,5 @@ Use these checks when installation does not complete. - [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) - [Create a SharePoint Embedded app in the SharePoint admin center](../administration/consuming-tenant-admin/SPE_app_installation_on_SPAC.md) -## Next step - +## 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 index 53fc39e538..209fd25716 100644 --- a/docs/embedded/admin/manage-containers-powershell.md +++ b/docs/embedded/admin/manage-containers-powershell.md @@ -250,6 +250,5 @@ Follow these operational practices. - [Apply security and compliance controls](apply-security-compliance-controls.md) - [Consuming Tenant Admin PowerShell](../administration/consuming-tenant-admin/ctapowershell.md) -## Next step - +## 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 index f725f391fb..01c455ffe6 100644 --- a/docs/embedded/admin/manage-containers-sharepoint-admin-center.md +++ b/docs/embedded/admin/manage-containers-sharepoint-admin-center.md @@ -207,6 +207,5 @@ Continue with [Manage containers with PowerShell](manage-containers-powershell.m - [Apply security and compliance controls](apply-security-compliance-controls.md) - [Manage SharePoint Embedded containers in SharePoint Admin Center](../administration/consuming-tenant-admin/ctaUX.md) -## Next step - +## 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 index afcb515948..5bc9afcee0 100644 --- a/docs/embedded/admin/monitor-usage-billing-cost.md +++ b/docs/embedded/admin/monitor-usage-billing-cost.md @@ -180,6 +180,5 @@ Establish a recurring review process. - [SharePoint Embedded Billing Management](../administration/billing/billingmanagement.md) - [SharePoint Embedded Billing Meters](../administration/billing/meters.md) -## Next step - +## 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 index 079fa8b6aa..26caa62513 100644 --- a/docs/embedded/admin/review-audit-events.md +++ b/docs/embedded/admin/review-audit-events.md @@ -219,6 +219,5 @@ Keep records according to your compliance and legal process. - [Security and Compliance](../compliance/security-and-compliance.md) - [Auditing solutions in Microsoft Purview](/purview/audit-solutions-overview) -## Next step - +## Next steps Apply broader controls in [Apply security and compliance controls](apply-security-compliance-controls.md). diff --git a/docs/embedded/admin/setup-billing-m365-admin-center.md b/docs/embedded/admin/setup-billing-m365-admin-center.md index 79d598568f..3a40e83b0b 100644 --- a/docs/embedded/admin/setup-billing-m365-admin-center.md +++ b/docs/embedded/admin/setup-billing-m365-admin-center.md @@ -170,6 +170,5 @@ After setup, establish a billing operations process. - [SharePoint Embedded Billing Meters](../administration/billing/meters.md) - [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md) -## Next step - +## Next steps Manage containers in [Manage containers in SharePoint admin center](manage-containers-sharepoint-admin-center.md). diff --git a/docs/embedded/build/agent-experiences.md b/docs/embedded/build/agent-experiences.md index 98a27383f4..9650683daa 100644 --- a/docs/embedded/build/agent-experiences.md +++ b/docs/embedded/build/agent-experiences.md @@ -106,3 +106,7 @@ You can also grant this permission during initial container type registration. ## 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 that can be answered from known file content. If answers omit expected files, check discoverability, supported file formats, app access, user access, scope selection, and indexing delay. + +## Next steps + +- [Migrate from Azure Blob Storage](migrate-azure-blob-storage.md) diff --git a/docs/embedded/build/archive-restore-containers.md b/docs/embedded/build/archive-restore-containers.md index e707242667..0cc50eebd5 100644 --- a/docs/embedded/build/archive-restore-containers.md +++ b/docs/embedded/build/archive-restore-containers.md @@ -71,3 +71,9 @@ Reactivation is instantaneous during the first seven days after archival. After Require explicit user intent before archive and unarchive requests. Record the container ID, actor, timestamp, and Graph request correlation data in your application logs. Do not 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 index 19661ee006..3c14895463 100644 --- a/docs/embedded/build/configure-authentication-authorization.md +++ b/docs/embedded/build/configure-authentication-authorization.md @@ -116,5 +116,5 @@ Validate the flow before feature code: | App-only call has too much access | Container type permission is broader than necessary. | | Registration call fails | Use SharePoint `Container.Selected` and app-only flow. | | Search call fails | Review search-specific exceptional access patterns. | -## Next step +## 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 index d072441128..04a234f813 100644 --- a/docs/embedded/build/container-metadata.md +++ b/docs/embedded/build/container-metadata.md @@ -110,3 +110,7 @@ Use `$expand=listitem($expand=fields)` when the result needs field values in the ## 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 index b23bec45c7..ef4dd0adaf 100644 --- a/docs/embedded/build/create-container-type.md +++ b/docs/embedded/build/create-container-type.md @@ -129,5 +129,5 @@ Use this sequence for each consuming tenant: 1. Register container type application permissions. 1. Configure pass-through billing when the consuming tenant pays. 1. Validate container creation and access. -## Next step +## 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 index 542b1f87db..3a75f3f88a 100644 --- a/docs/embedded/build/create-manage-containers.md +++ b/docs/embedded/build/create-manage-containers.md @@ -132,5 +132,5 @@ Create a smoke test: | 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 step +## 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 index 27a6e2070e..83f6b68a75 100644 --- a/docs/embedded/build/fluid-framework.md +++ b/docs/embedded/build/fluid-framework.md @@ -53,3 +53,7 @@ Your app still needs the SharePoint Embedded client ID and container type ID to ## 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 + +- [Add Microsoft 365 Copilot and agent experiences](agent-experiences.md) diff --git a/docs/embedded/build/manage-files.md b/docs/embedded/build/manage-files.md index 04a49c3af9..3226d56aa0 100644 --- a/docs/embedded/build/manage-files.md +++ b/docs/embedded/build/manage-files.md @@ -121,5 +121,5 @@ Create a smoke test: | 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 step +## 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 index aab7527248..fe7d079350 100644 --- a/docs/embedded/build/migrate-azure-blob-storage.md +++ b/docs/embedded/build/migrate-azure-blob-storage.md @@ -118,3 +118,7 @@ Use the optional blob list file for controlled batches and the optional output f 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. Do not 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 index 6d9b907563..2ce53d829f 100644 --- a/docs/embedded/build/open-office-files.md +++ b/docs/embedded/build/open-office-files.md @@ -140,5 +140,5 @@ Test each launch path: | 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 step +## 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 index e76d899d4d..2e3ac5c9d2 100644 --- a/docs/embedded/build/preview-files.md +++ b/docs/embedded/build/preview-files.md @@ -164,3 +164,7 @@ Test with multiple file types and users: ## 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 index 8ab7622517..1a3cc3ee10 100644 --- a/docs/embedded/build/quickstart-vscode.md +++ b/docs/embedded/build/quickstart-vscode.md @@ -125,5 +125,5 @@ When you're finished testing: 1. Permanently delete containers that count against the trial quota. 1. Remove trial container types when no longer needed. 1. Remove local sample secrets that are no longer needed. -## Next step +## Next steps Create a production-ready model 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 index 7bbfd2b7d1..2a974f17a1 100644 --- a/docs/embedded/build/register-application-permissions.md +++ b/docs/embedded/build/register-application-permissions.md @@ -140,5 +140,5 @@ Use a safe update process: 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 step +## 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 index 807b837454..48ba2ab77c 100644 --- a/docs/embedded/build/respond-to-changes-webhooks.md +++ b/docs/embedded/build/respond-to-changes-webhooks.md @@ -96,3 +96,7 @@ Use webhooks for actions such as document processing, index refresh, user notifi ## 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 index f7fbe96f21..a006b1af2b 100644 --- a/docs/embedded/build/search-containers-files.md +++ b/docs/embedded/build/search-containers-files.md @@ -118,3 +118,7 @@ GET https://graph.microsoft.com/v1.0/drives/{container-id}/items?$filter=startsw ``` When a container has more than 5,000 items and you enumerate with `$orderby`, include the `Prefer: HonorNonIndexedQueriesWarningMayFailRandomly` header shown in the source article. + +## 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 index 69afdb7996..bb84f30053 100644 --- a/docs/embedded/build/share-files-manage-permissions.md +++ b/docs/embedded/build/share-files-manage-permissions.md @@ -90,3 +90,7 @@ Set-SPOApplication ``` 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. + +## Next steps + +- [Respond to file and container changes with webhooks](respond-to-changes-webhooks.md) diff --git a/docs/embedded/plan/app-tenant-architecture.md b/docs/embedded/plan/app-tenant-architecture.md index 3610c93529..9fb2f6d550 100644 --- a/docs/embedded/plan/app-tenant-architecture.md +++ b/docs/embedded/plan/app-tenant-architecture.md @@ -185,6 +185,5 @@ For model selection, see [Choose an app model: single-tenant or multitenant](../ - Plan authentication and admin consent. - Plan security and compliance responsibilities. -## Next step - +## 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 index 66d2e6f3ee..5e18236a38 100644 --- a/docs/embedded/plan/authentication-permissions.md +++ b/docs/embedded/plan/authentication-permissions.md @@ -214,6 +214,5 @@ Review these before designing privileged or search-heavy features. - Identify any guest apps and their permissions. - Review exceptional access patterns. -## Next step - +## 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 index 94d9ea5385..62b47d5c08 100644 --- a/docs/embedded/plan/choose-app-model.md +++ b/docs/embedded/plan/choose-app-model.md @@ -188,6 +188,5 @@ If you're building an ISV app: - Identify who configures billing. - Identify who manages compliance policies. -## Next step - +## Next steps Review the storage model: [Understand container types and containers](../plan/container-types-and-containers.md). diff --git a/docs/embedded/plan/choose-billing-model.md b/docs/embedded/plan/choose-billing-model.md index 0f33fa61ab..867af9025b 100644 --- a/docs/embedded/plan/choose-billing-model.md +++ b/docs/embedded/plan/choose-billing-model.md @@ -191,6 +191,5 @@ Use these setup references after you choose a model: - Plan storage lifecycle to control storage consumption. - Plan calling patterns to manage API transaction cost. -## Next step - +## 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-and-containers.md b/docs/embedded/plan/container-types-and-containers.md index d20cb2c3fb..6cc7472034 100644 --- a/docs/embedded/plan/container-types-and-containers.md +++ b/docs/embedded/plan/container-types-and-containers.md @@ -221,6 +221,5 @@ For full details, see [Register file storage container type application permissi - Plan which container type settings are required. - Plan container lifecycle and deletion. -## Next step - +## Next steps Plan authentication and authorization: [Plan authentication and permissions](../plan/authentication-permissions.md). diff --git a/docs/embedded/plan/security-compliance-governance.md b/docs/embedded/plan/security-compliance-governance.md index de92074183..aaed33601d 100644 --- a/docs/embedded/plan/security-compliance-governance.md +++ b/docs/embedded/plan/security-compliance-governance.md @@ -220,6 +220,5 @@ Design for policy enforcement results, blocked operations, and user-facing messa - Decide whether Conditional Access settings are required. - Validate licensing requirements for advanced policies. -## Next step - +## 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 index f650bc0c28..b39dd0ec18 100644 --- a/docs/embedded/publish/choose-app-billing-model.md +++ b/docs/embedded/publish/choose-app-billing-model.md @@ -189,8 +189,7 @@ Before you proceed, record: 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 step - +## Next steps After you choose a billing model, prepare customer-facing tenant setup instructions. > [!div class="nextstepaction"] diff --git a/docs/embedded/publish/customer-tenant-setup-guide.md b/docs/embedded/publish/customer-tenant-setup-guide.md index ea3fe29e60..41aef2db25 100644 --- a/docs/embedded/publish/customer-tenant-setup-guide.md +++ b/docs/embedded/publish/customer-tenant-setup-guide.md @@ -200,8 +200,7 @@ Use this table to route early setup problems. | Admin can't run management cmdlets | Role or tooling | Confirm SharePoint Embedded Administrator role and latest SharePoint PowerShell. | | App works for members but not guests | Identity or sharing | Confirm guest identities and customer sharing policies. | -## Next step - +## Next steps After setup, validate the installation with the customer administrator. > [!div class="nextstepaction"] diff --git a/docs/embedded/publish/prepare-customer-installation.md b/docs/embedded/publish/prepare-customer-installation.md index 1a812b3361..84e0b6cf16 100644 --- a/docs/embedded/publish/prepare-customer-installation.md +++ b/docs/embedded/publish/prepare-customer-installation.md @@ -229,8 +229,7 @@ Include a checklist the customer can complete with you after installation: For detailed validation, see [Validate customer app installation](validate-customer-installation.md). -## Next step - +## Next steps Choose the correct billing option before you send installation instructions to a customer. > [!div class="nextstepaction"] diff --git a/docs/embedded/publish/validate-customer-installation.md b/docs/embedded/publish/validate-customer-installation.md index fa7a3582e0..ffdeb30e62 100644 --- a/docs/embedded/publish/validate-customer-installation.md +++ b/docs/embedded/publish/validate-customer-installation.md @@ -241,8 +241,7 @@ After validation succeeds: If validation fails, keep the customer in onboarding and resolve the failing area before you enable broad user access. -## Next step - +## Next steps After customer validation, continue to the SharePoint Embedded admin overview. > [!div class="nextstepaction"] diff --git a/docs/embedded/reference/billing-meters.md b/docs/embedded/reference/billing-meters.md index 050627ce16..2725869585 100644 --- a/docs/embedded/reference/billing-meters.md +++ b/docs/embedded/reference/billing-meters.md @@ -54,3 +54,8 @@ The private preview SharePoint Embedded agent meter uses the Copilot Studio mess - [SharePoint Embedded product page](https://adoption.microsoft.com/sharepoint/embedded/) - [Azure Cost Management](https://ms.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 index 33f0f38669..4bb9553825 100644 --- a/docs/embedded/reference/glossary.md +++ b/docs/embedded/reference/glossary.md @@ -29,3 +29,8 @@ next: ../plan/choose-app-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](../development/app-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 index 8dc825301a..73b5d71ed9 100644 --- a/docs/embedded/reference/graph-api-links.md +++ b/docs/embedded/reference/graph-api-links.md @@ -60,3 +60,8 @@ All file system objects in a `fileStorageContainer` are returned as `driveItem` ## Authentication SharePoint Embedded uses Microsoft Graph permissions plus container type application permissions. Start with [SharePoint Embedded authentication and authorization](../development/auth.md) before implementing the API calls. + +## Related resources + +- [Create and manage containers](../build/create-manage-containers.md) +- [Upload, download, and manage files](../build/manage-files.md) diff --git a/docs/embedded/reference/powershell.md b/docs/embedded/reference/powershell.md index 188d196109..42f6dd215c 100644 --- a/docs/embedded/reference/powershell.md +++ b/docs/embedded/reference/powershell.md @@ -51,3 +51,8 @@ Deleted containers can be restored from the deleted container collection within > [!NOTE] > To enumerate Microsoft Loop containers, the source article specifies 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 index 668005e59d..7000ffe1e4 100644 --- a/docs/embedded/reference/troubleshooting.md +++ b/docs/embedded/reference/troubleshooting.md @@ -41,3 +41,7 @@ Use this reference to identify likely causes and fixes. For end-to-end setup, se - [PowerShell reference](powershell.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) From 1288ec1c7956201d9d1e334f1accb210553e4d05 Mon Sep 17 00:00:00 2001 From: Shreyas Saravanan Date: Thu, 25 Jun 2026 19:15:10 +0530 Subject: [PATCH 04/10] Improve agent Q&A retrieval based on delegated-reading evaluation Ran an empirical eval: 5 agents restricted to the doc set answered 21 real SPE user queries; graded findability/sufficiency/correctness vs ground truth. Round 1: 21/21 correct, 93.7% quality. Fixed the 4 weak spots and re-tested: - overview.md: add explicit developer-vs-admin role disambiguator (Q21) - container-metadata.md: cross-link to search for free-text/OWSTEXT queries (Q08) - limits-calling-patterns.md: add 'throughput' terminology and limit-increase guidance so agents match the resource-units model (Q11) Round 2: all four queries now Complete with no gaps -> 21/21 at full score. Structure unchanged at 100/100; 0 broken links. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/embedded/build/container-metadata.md | 2 ++ docs/embedded/overview.md | 5 +++++ docs/embedded/plan/limits-calling-patterns.md | 4 +++- 3 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/embedded/build/container-metadata.md b/docs/embedded/build/container-metadata.md index 04a234f813..b47a2cf5b0 100644 --- a/docs/embedded/build/container-metadata.md +++ b/docs/embedded/build/container-metadata.md @@ -108,6 +108,8 @@ GET https://graph.microsoft.com/beta/drives/{drive-id}/items?$orderby=listitem/f 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. diff --git a/docs/embedded/overview.md b/docs/embedded/overview.md index df3909bba0..83e2803437 100644 --- a/docs/embedded/overview.md +++ b/docs/embedded/overview.md @@ -25,6 +25,11 @@ next: plan/app-tenant-architecture.md This page is a router. Pick the row that matches what you're trying to do. +> [!TIP] +> **Not sure which path?** Ask one question: *do you write code, or manage a tenant?* +> **Developers** write and deploy applications that call SPE APIs — start with **Build an app**. +> **Administrators** install, consent to, and manage SPE apps inside a Microsoft 365 tenant — start with **Install or manage apps**. + | I want to… | Start here | |---|---| | **Understand SPE and decide if it fits** | [Scenarios and use cases](scenarios-and-use-cases.md) · keep reading below | diff --git a/docs/embedded/plan/limits-calling-patterns.md b/docs/embedded/plan/limits-calling-patterns.md index bd1be5e716..1e18e0966e 100644 --- a/docs/embedded/plan/limits-calling-patterns.md +++ b/docs/embedded/plan/limits-calling-patterns.md @@ -16,7 +16,9 @@ outcome: Design SharePoint Embedded calls that respect service limits, throttlin next: --> -Use this article to plan SharePoint Embedded calling patterns before you build high-volume container and content operations. +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. For the full current limits reference, see [Limits and calling patterns](../development/limits-calling.md). From c5567ee33ce805294147387a15bd234349305138 Mon Sep 17 00:00:00 2001 From: Shreyas Saravanan Date: Thu, 25 Jun 2026 19:23:44 +0530 Subject: [PATCH 05/10] Fix broken SharePoint Embedded entry link in docs landing hub Repoint the 'Enable SharePoint Embedded' card to the existing 'Build your first app' quickstart so the SPE entry surface in the SharePoint dev docs hub no longer points at a non-existent page. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/index.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.yml b/docs/index.yml index b2648b18f1..93ce5fc277 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -46,8 +46,8 @@ landingContent: links: - text: Overview of SharePoint Embedded url: /sharepoint/dev/embedded/overview - - text: Enable SharePoint Embedded - url: /sharepoint/dev/embedded/getting-started/enable-sharepoint-embedded + - text: Build your first app with SharePoint Embedded + url: /sharepoint/dev/embedded/build/quickstart-vscode - linkListType: tutorial links: - text: SharePoint Embedded - Overview & Configuration From 74702b1bba2c72dcf864fe5921c92a78175c3afc Mon Sep 17 00:00:00 2001 From: Shreyas Saravanan Date: Thu, 25 Jun 2026 20:21:21 +0530 Subject: [PATCH 06/10] Close 7 agent-readiness gaps found in 54-query stress test Stress-tested the SPE docs with 54 edge-case queries answered by doc-restricted retrieval agents. Closed the gaps they surfaced: - overview: state explicitly that SPE is API-only with no no-code path - limits: clarify trial vs standard container types - security/compliance: clarify container sensitivity-label scope and that files are not retroactively relabeled - manage-files: give the 250 MB simple-upload vs upload-session threshold - search: state search is beta-only (no v1.0 container search) and when to use full-text search vs an OData filter Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/embedded/build/manage-files.md | 4 ++-- docs/embedded/build/search-containers-files.md | 4 ++-- docs/embedded/overview.md | 2 ++ docs/embedded/plan/limits-calling-patterns.md | 2 ++ docs/embedded/plan/security-compliance-governance.md | 2 +- 5 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/embedded/build/manage-files.md b/docs/embedded/build/manage-files.md index 3226d56aa0..3a20976d1a 100644 --- a/docs/embedded/build/manage-files.md +++ b/docs/embedded/build/manage-files.md @@ -43,8 +43,8 @@ In your app: 1. Avoid reconstructing IDs from URLs. ## Upload files Use Microsoft Graph upload patterns for DriveItems. -For small files, use the simple upload API documented for DriveItems. -For larger files, use an upload session as documented by Microsoft Graph. +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. diff --git a/docs/embedded/build/search-containers-files.md b/docs/embedded/build/search-containers-files.md index a006b1af2b..96160f76c5 100644 --- a/docs/embedded/build/search-containers-files.md +++ b/docs/embedded/build/search-containers-files.md @@ -15,7 +15,7 @@ next: container-metadata.md 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. For the full query reference and more examples, see [Search SharePoint Embedded content](../development/content-experiences/search-content.md). > [!NOTE] -> SharePoint Embedded search is in preview. The source article states that search supports delegated permissions only and follows the [exceptional access pattern](../development/auth.md#operations-involving-searching-sharepoint-embedded-content). +> SharePoint Embedded search is in preview and is available only on the Microsoft Graph **`/beta`** endpoint — there is no `v1.0` search API for containers. The source article states that search supports delegated permissions only and follows the [exceptional access pattern](../development/auth.md#operations-involving-searching-sharepoint-embedded-content). ## 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. @@ -111,7 +111,7 @@ For container custom properties, append `OWSTEXT` to the custom property name in customPropertyNametOWSTEXT:customPropertyValue AND ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae ``` -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`: +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) diff --git a/docs/embedded/overview.md b/docs/embedded/overview.md index 83e2803437..8c381cd567 100644 --- a/docs/embedded/overview.md +++ b/docs/embedded/overview.md @@ -9,6 +9,8 @@ ms.localizationpriority: high 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. +SPE 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. + SharePoint Embedded brings advanced Microsoft 365 capabilities into your app, including Office collaboration, Microsoft Purview security and compliance, and Copilot. > [!IMPORTANT] diff --git a/docs/embedded/plan/limits-calling-patterns.md b/docs/embedded/plan/limits-calling-patterns.md index 1e18e0966e..cf4eba7940 100644 --- a/docs/embedded/plan/limits-calling-patterns.md +++ b/docs/embedded/plan/limits-calling-patterns.md @@ -60,6 +60,8 @@ The source article lists the following size limits. `*` indicates that the limit can be increased per request in the source documentation. +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. diff --git a/docs/embedded/plan/security-compliance-governance.md b/docs/embedded/plan/security-compliance-governance.md index aaed33601d..11bf09f74e 100644 --- a/docs/embedded/plan/security-compliance-governance.md +++ b/docs/embedded/plan/security-compliance-governance.md @@ -152,7 +152,7 @@ The source article lists: Set-SPOContainer -Identity -SensitivityLabel ``` -For more information, see [Learn about sensitivity labels](/purview/sensitivity-labels). +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 does not 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 From 84741bec04aa8bf9f382177090ca7c14dd4d26b8 Mon Sep 17 00:00:00 2001 From: Shreyas Saravanan Date: Thu, 25 Jun 2026 20:33:08 +0530 Subject: [PATCH 07/10] Add agent-readiness evaluation records for the SPE docs restructure Document both validation campaigns for training/reproducibility: - structural scorer rubric and 100/100 result - 21-query persona Q&A campaign (two rounds) - 54-query edge-case stress test with full prompts, raw agent outputs, grading, gaps found, fixes applied, and round-2 re-test (162/162) These records live outside docs/ and are not part of the published TOC. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- agent-readiness-eval/01-methodology.md | 93 +++ agent-readiness-eval/02-structural-scoring.md | 72 ++ .../03-qa-round1-21-queries.md | 70 ++ .../04-qa-stress-test-54-queries.md | 648 ++++++++++++++++++ agent-readiness-eval/README.md | 44 ++ 5 files changed, 927 insertions(+) create mode 100644 agent-readiness-eval/01-methodology.md create mode 100644 agent-readiness-eval/02-structural-scoring.md create mode 100644 agent-readiness-eval/03-qa-round1-21-queries.md create mode 100644 agent-readiness-eval/04-qa-stress-test-54-queries.md create mode 100644 agent-readiness-eval/README.md diff --git a/agent-readiness-eval/01-methodology.md b/agent-readiness-eval/01-methodology.md new file mode 100644 index 0000000000..093a1a876f --- /dev/null +++ b/agent-readiness-eval/01-methodology.md @@ -0,0 +1,93 @@ +# 01 — Methodology + +## Goal + +Validate that the restructured, task-based SharePoint Embedded (SPE) documentation is +**agent-ready**: a coding agent that a user delegates an SPE question to should be able +to retrieve the answer from the docs alone, answer correctly, and cite the right task +article — without relying on the model's pre-training. + +## Two complementary evaluations + +1. **Structural scoring (deterministic).** A Python scorer grades every task article on + four dimensions (structure, correctness signals, agent-readiness, task framing). + This catches missing metadata, oversized articles, missing navigation, weak titles, + and broken cross-links. See [`02-structural-scoring.md`](02-structural-scoring.md). + +2. **Empirical Q&A (behavioral).** Real questions are answered by **doc-restricted + retrieval agents** that may only read files under `docs/embedded`. The agents + simulate a coding agent doing keyword retrieval: `grep`/`glob` to find a candidate + article, read it, then answer. Outside/world knowledge is prohibited, and the agent + must say "NOT IN DOCS" when the answer genuinely isn't present. See + [`03-qa-round1-21-queries.md`](03-qa-round1-21-queries.md) and + [`04-qa-stress-test-54-queries.md`](04-qa-stress-test-54-queries.md). + +## Why doc-restricted agents + +A general model can answer many SPE questions from pre-training, which would hide gaps +in the docs. Restricting the agent to `docs/embedded` forces every answer to be +*grounded in the documentation*, so a wrong or "NOT IN DOCS" result is a true signal of +a documentation gap, not a model limitation. + +## Agent output contract + +Every Q&A agent returns one structured block per question: + +``` +QID: +ANSWER: +CITED: +FINDABILITY: # how easily keyword search located it +SUFFICIENCY: +GAP: +``` + +`FINDABILITY` and `SUFFICIENCY` separate two distinct failure modes: the content can +exist but be **hard to find** (retrieval problem) or be **findable but incomplete** +(content problem). Both are actionable. + +## Grading scale + +| Score | Meaning | +| --- | --- | +| 3 | Complete + correct, cited the intended task article, easy to find | +| 2 | Correct but partial, hard to find, or cited a legacy/secondary file | +| 1 | Answer missing or materially incomplete (real content gap) | +| 0 | Wrong / hallucinated answer | + +**Negative probes.** Some queries deliberately ask for facts not in the doc set (for +example, SLA, region availability, customer-managed keys). These test *honesty*: an +agent that answers "NOT IN DOCS" scores **3**; one that invents an answer scores **0**. + +## Loop + +1. Build a query bank with persona, question, expected file, and ground truth. +2. Split queries into groups; run one doc-restricted agent per group in parallel. +3. Grade each answer 0–3; record `FINDABILITY`/`SUFFICIENCY`/`GAP`. +4. For every score < 3 that is a real gap, edit the doc to close it. +5. Re-run the structural scorer and link check to confirm no regression. +6. Re-test the fixed queries with a fresh agent. +7. Commit and record results here. + +## Tooling + +- **Retrieval agents:** fast explore agents, scoped by prompt to `docs/embedded` only. +- **Structural scorer:** `score_docs.py` (4 × 25-point rubric). Kept with the session + artifacts; summarized in [`02-structural-scoring.md`](02-structural-scoring.md). +- **Query bank + grades:** stored in a SQLite session database (`qa` for the 21-query + campaign, `qa2` for the 54-query stress test) and exported into the records here. +- **Link integrity:** a small Python pass over every `[..](../x.md)` relative link in + `docs/embedded`, checked against the filesystem. + +## Reproducing + +```powershell +# Structural score (from repo root) +python /score_docs.py + +# Relative-link integrity over docs/embedded +# (walks every ../*.md and ./*.md link and checks it resolves on disk) +``` + +Q&A campaigns are reproduced by re-issuing the prompts in files 03 and 04 to a +retrieval agent restricted to `docs/embedded`, then grading with the scale above. diff --git a/agent-readiness-eval/02-structural-scoring.md b/agent-readiness-eval/02-structural-scoring.md new file mode 100644 index 0000000000..3b8cf13010 --- /dev/null +++ b/agent-readiness-eval/02-structural-scoring.md @@ -0,0 +1,72 @@ +# 02 — Structural scoring + +A deterministic Python scorer grades every task article in `docs/embedded` on four +25-point dimensions. It is the fast, repeatable gate that runs before and after every +content change to prevent regressions. + +## Rubric (4 × 25 = 100) + +| Dimension | What it checks (25 pts each) | +| --- | --- | +| **Structure** | Single H1; YAML front matter with `title`/`description`/`ms.date`; heading hierarchy is well-formed; article is right-sized for a context window (not oversized). | +| **Correctness signals** | Has an `**Applies to:**` audience line; uses concrete API/cmdlet/permission names; code fenced with a language; intro paragraph present before the first H2. | +| **Agent-readiness** | Article fits comfortably in a context window; descriptive `description` for retrieval; explicit visible navigation (`## Next steps` and `## Related resources` / `See also`); stable headings usable as anchors. | +| **Task framing** | Verb-first, task-oriented title (e.g., "Create and manage containers"); imperative steps; one primary task per article. Reference and concept pages (`ms.topic` / `task_type: concept`) are exempt from the verb-first rule. | + +### Scorer notes / fixes captured during development + +- The `**Applies to:**` audience line is matched with both bold and plain variants. +- Intro detection must not be defeated by `DOTALL` regex (a bug that was found and fixed). +- Cross-link validity does not require a `../` prefix; same-folder `./x.md` links count. +- Navigation recognizes the variants `Next step`/`Next steps`/`Related`/ + `Related resources`/`See also`. + +## Result + +``` +structure : 25.00 / 25 +correctness : 25.00 / 25 +agent : 25.00 / 25 +task : 25.00 / 25 + TOTAL : 100.00 / 100 + Perfect articles: 43/43 + +=== ARTICLES WITH DEDUCTIONS / ISSUES === + (none) +``` + +The score was re-run after the stress-test fixes (see file 04) and remained +**100.00 / 100, 43/43 perfect**, confirming no regression. + +## Articles graded (43) + +Spread across the task-based information architecture: + +| Section | Count | Examples | +| --- | --- | --- | +| Overview | 3 | `overview.md`, `scenarios-and-use-cases.md`, `whats-new.md` | +| Plan | 7 | `app-tenant-architecture.md`, `choose-app-model.md`, `authentication-permissions.md`, `limits-calling-patterns.md` | +| Build | 16 | `quickstart-vscode.md`, `create-container-type.md`, `manage-files.md`, `open-office-files.md`, `search-containers-files.md`, `agent-experiences.md` | +| Publish | 4 | `prepare-customer-installation.md`, `validate-customer-installation.md` | +| Install & manage (admin) | 10 | `admin-overview.md`, `install-sharepoint-embedded-app.md`, `manage-containers-powershell.md`, `review-audit-events.md` | +| Reference | 6 | `billing-meters.md`, `audit-events.md`, `troubleshooting.md`, `glossary.md` | + +## Link integrity + +A separate pass walks every relative Markdown link (`[..](../x.md)` and `./x.md`) under +`docs/embedded` and resolves it against the filesystem. + +``` +relative md links checked = 297 broken = 0 +``` + +Entry-link integrity was also verified separately: + +- `docs/embedded/overview.md` keeps H1 **"What is SharePoint Embedded?"**, so the + published `/sharepoint/dev/embedded/overview` URL and its `#what-is-sharepoint-embedded` + anchor do not break. +- `docs/index.yml` (the SharePoint-dev landing hub) — both SPE entry cards resolve + (Overview → `/embedded/overview`, quickstart → `/embedded/build/quickstart-vscode`). + A pre-existing broken "Enable SharePoint Embedded" card was repointed to the existing + quickstart. +- `docs/toc.yml` — 46/46 SPE hrefs resolve. diff --git a/agent-readiness-eval/03-qa-round1-21-queries.md b/agent-readiness-eval/03-qa-round1-21-queries.md new file mode 100644 index 0000000000..f19a564207 --- /dev/null +++ b/agent-readiness-eval/03-qa-round1-21-queries.md @@ -0,0 +1,70 @@ +# 03 — Q&A campaign: 21 persona queries + +The first empirical campaign tested whether doc-restricted agents could answer realistic +questions from the core SPE personas (new developer, developer, architect, admin, ISV, +compliance, billing, and an undecided "router" user). 21 queries were split into 5 +groups and run by parallel doc-restricted agents, then graded 0–3. + +## Agent prompt (template) + +Each agent received this instruction plus its group's questions: + +> You are evaluating whether a documentation set can answer SharePoint Embedded (SPE) +> questions. You may ONLY read files under `docs/embedded`. Do NOT use outside knowledge. +> Simulate a coding agent doing keyword retrieval: use grep/glob within that folder to +> FIND the answer, then read the matching article. If the docs genuinely do not contain +> the answer, say so honestly — do not invent it. +> +> For EACH question output one block: +> `QID / ANSWER / CITED / FINDABILITY / SUFFICIENCY / GAP`. + +## Queries, expected article, and grades + +| QID | Persona | Question | Intended article | R1 | R2 | +| --- | --- | --- | --- | --- | --- | +| q01 | dev-new | I am brand new to SPE. How do I build my first app? | `build/quickstart-vscode.md` | 3 | 3 | +| q02 | dev | How do I let my app users open and edit Word/Office files from my app? | `build/open-office-files.md` | 3 | 3 | +| q03 | dev | What permission lets my app read content in containers and how do I grant it? | `build/register-application-permissions.md` | 3 | 3 | +| q04 | dev | How do I get notified when a file changes in a container? | `build/respond-to-changes-webhooks.md` | 3 | 3 | +| q05 | dev | How do I create a container type and what is its relationship to my app? | `build/create-container-type.md` | 3 | 3 | +| q06 | dev | How do I search across files in my containers? | `build/search-containers-files.md` | 3 | 3 | +| q07 | dev | How do I archive an inactive container and reactivate it later? | `build/archive-restore-containers.md` | 3 | 3 | +| q08 | dev | How do I add custom metadata columns to containers and query them? | `build/container-metadata.md` | 2 | 3 | +| q09 | architect | Single-tenant vs multitenant: which app model should I choose? | `plan/choose-app-model.md` | 3 | 3 | +| q10 | architect | Who pays for storage, me or my customer? What billing models exist? | `plan/choose-billing-model.md` | 3 | 3 | +| q11 | architect | What size and throughput limits should I design around? | `plan/limits-calling-patterns.md` | 2 | 3 | +| q12 | admin | As a tenant admin, how do I install a vendor SPE app in my tenant? | `admin/install-sharepoint-embedded-app.md` | 3 | 3 | +| q13 | admin | How do I set up billing for an SPE app in my tenant? | `admin/setup-billing-m365-admin-center.md` | 3 | 3 | +| q14 | admin | How do I manage SPE containers with PowerShell? | `admin/manage-containers-powershell.md` | 3 | 3 | +| q15 | admin | What admin role do I need to manage SharePoint Embedded? | `admin/admin-overview.md` | 2 | 3 | +| q16 | compliance | How do I find audit events for SPE container type activity? | `admin/review-audit-events.md` | 3 | 3 | +| q17 | isv | I built an app. How do I prepare it for a customer to install? | `publish/prepare-customer-installation.md` | 3 | 3 | +| q18 | billing | What does SPE charge for? What are the billing meters? | `reference/billing-meters.md` | 3 | 3 | +| q19 | compliance | How do I apply a sensitivity label or block download on a container? | `admin/apply-security-compliance-controls.md` | 3 | 3 | +| q20 | dev | I get access denied / SubscriptionNotRegistered. How do I fix it? | `reference/troubleshooting.md` | 3 | 3 | +| q21 | router | I do not know if I am a developer or admin. Where do I start? | `overview.md` | 2 | 3 | + +## Round 1 result + +- **21/21 answered correctly**, overall quality ≈ **93.7%**. +- Four weaknesses surfaced (all scored 2, "correct but partial / mis-cited"): + +| # | QID(s) | Weakness | Decision | +| --- | --- | --- | --- | +| A | several | Legacy folders (`development/`, `administration/`, `getting-started/`, `compliance/`) compete in keyword search and were sometimes cited instead of the new task article. | **Benign** — answers were still correct; legacy files are intentionally retained as deep-dive sources. Not deleted (out of scope, risky). | +| B | q21 | Router page lacked an explicit developer-vs-admin role identifier. | **Fixed** — added a "Not sure which path?" tip that splits on "do you write code, or manage a tenant?" | +| C | q08 | OWSTEXT custom-property search syntax lived only in the search article; the metadata article didn't cross-link to it. | **Fixed** — added a cross-link from `container-metadata.md` to `search-containers-files.md`. | +| D | q11 | The word "throughput" was absent and the limit-increase process was undocumented. | **Fixed** — added throughput/resource-unit wording and limit-increase guidance to `limits-calling-patterns.md`. | + +## Fixes (committed) + +The B/C/D fixes were committed as `1288ec1c7`: + +- `docs/embedded/overview.md` — dev-vs-admin tip box before the routing table. +- `docs/embedded/build/container-metadata.md` — cross-link to free-text/OWSTEXT search. +- `docs/embedded/plan/limits-calling-patterns.md` — throughput + limit-increase guidance. + +## Round 2 result + +Re-test of the four weak queries (q08, q11, q15, q21) confirmed every gap closed: +**21/21 full score, 100%.** diff --git a/agent-readiness-eval/04-qa-stress-test-54-queries.md b/agent-readiness-eval/04-qa-stress-test-54-queries.md new file mode 100644 index 0000000000..4484db27a6 --- /dev/null +++ b/agent-readiness-eval/04-qa-stress-test-54-queries.md @@ -0,0 +1,648 @@ +# 04 — Stress test: 54 edge-case queries + +The stress test pushed the docs with harder, more specific questions than the persona +campaign: edge cases, exact limits, API nuances, permission distinctions, and **four +deliberate "negative probes"** (facts not in the doc set) to test agent honesty. + +- **54 queries** in 6 groups of 9. +- One doc-restricted retrieval agent per group, run in parallel. +- Graded 0–3 (see [`01-methodology.md`](01-methodology.md) for the scale). + +## Shared agent prompt + +Every group agent received this prompt, with its 9 questions appended: + +``` +You are evaluating whether a documentation set can answer SharePoint Embedded (SPE) +questions. You may ONLY read files under this folder: +C:\...\docs\embedded +Do NOT use any outside/world knowledge. Simulate a coding agent doing keyword +retrieval: use grep/glob within that folder to FIND the answer, then read the matching +article. If the docs genuinely do not contain the answer, say so honestly — do not +invent it. + +For EACH question below, output one block exactly in this format: +QID: +ANSWER: +CITED: +FINDABILITY: +SUFFICIENCY: +GAP: + +Output only the blocks, nothing else. +``` + +--- + +## Group 1 — security / compliance (q22–q30) + +**Questions** + +- q22 Do sensitivity labels applied to a container get inherited by files inside it? +- q23 How do I run eDiscovery against SharePoint Embedded content? +- q24 Can I apply DLP policies to containers? +- q25 How do I set a retention policy on container content? +- q26 What conditional access policy options exist for a container? +- q27 What license do I need to block downloads from a container? +- q28 Which audit fields identify the specific SPE container in an event? +- q29 Does SharePoint Embedded support customer-managed encryption keys? *(negative probe)* +- q30 In which Microsoft 365 geographies/regions is SPE available? *(negative probe)* + +**Raw agent output** + +``` +QID: q22 +ANSWER: NOT IN DOCS +CITED: NONE +FINDABILITY: HARD +SUFFICIENCY: MISSING +GAP: Docs discuss applying sensitivity labels to containers (Set-SPOContainer) but do +not specify whether labels are inherited by files within the container. + +QID: q23 +ANSWER: Yes. Search all SPE containers by selecting "All SharePoint sites" or limit to +specific containers by providing container URLs in the SharePoint sites workload. +CITED: admin/apply-security-compliance-controls.md, compliance/security-and-compliance.md +FINDABILITY: EASY +SUFFICIENCY: COMPLETE +GAP: NONE + +QID: q24 +ANSWER: Yes. Apply DLP broadly to all SharePoint sites and SPE containers, or +selectively to specific containers by specifying container URLs. +CITED: admin/apply-security-compliance-controls.md, compliance/security-and-compliance.md +FINDABILITY: EASY +SUFFICIENCY: COMPLETE +GAP: NONE + +QID: q25 +ANSWER: Yes, through Microsoft Purview. "All SharePoint sites" applies to all +containers; you can also target specific containers by URL. +CITED: admin/apply-security-compliance-controls.md, compliance/security-and-compliance.md, plan/security-compliance-governance.md +FINDABILITY: EASY +SUFFICIENCY: COMPLETE +GAP: NONE + +QID: q26 +ANSWER: Three options: AllowFullAccess, AllowLimitedAccess (web-only), and BlockAccess. +CITED: admin/apply-security-compliance-controls.md, compliance/security-and-compliance.md, plan/security-compliance-governance.md +FINDABILITY: EASY +SUFFICIENCY: COMPLETE +GAP: NONE + +QID: q27 +ANSWER: A SharePoint Advanced Management (SAM) license is required to enforce block +download on containers. +CITED: admin/apply-security-compliance-controls.md, compliance/security-and-compliance.md +FINDABILITY: EASY +SUFFICIENCY: COMPLETE +GAP: NONE + +QID: q28 +ANSWER: ContainerInstanceId (the specific container instance) and ContainerTypeId. +CITED: admin/review-audit-events.md, admin/apply-security-compliance-controls.md, compliance/security-and-compliance.md +FINDABILITY: EASY +SUFFICIENCY: COMPLETE +GAP: NONE + +QID: q29 +ANSWER: NOT IN DOCS +CITED: NONE +FINDABILITY: NONE +SUFFICIENCY: MISSING +GAP: No documentation on customer-managed encryption keys (BYOK). + +QID: q30 +ANSWER: NOT IN DOCS +CITED: NONE +FINDABILITY: HARD +SUFFICIENCY: MISSING +GAP: Docs mention a region must be specified at container-type creation but do not list +supported M365 geographies. +``` + +**Grading:** q23–q28 → 3. q29, q30 → 3 (honest negative probes). **q22 → 1 (real gap).** + +--- + +## Group 2 — billing / limits / ownership (q31–q39) + +**Questions** + +- q31 How is a single Microsoft Graph API call counted for billing? +- q32 Are downloads through Office clients charged as egress? +- q33 Are admin actions in the SharePoint admin center billed as transactions? +- q34 How many container types can one app own? +- q35 How many container types can a tenant create? +- q36 What is the maximum file size and version count? +- q37 How many owners can a SharePoint Embedded app have in the admin center? +- q38 Can I change the billing type after creating an app in the admin center? +- q39 How long are deleted containers retained before permanent purge? + +**Raw agent output** + +``` +QID: q31 +ANSWER: Each Graph call made explicitly by the app = one transaction. Internal service +calls (eDiscovery, admin actions in SPAC or SPO PowerShell) are not charged as app +transactions. +CITED: reference/billing-meters.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q32 +ANSWER: No. Downloads to the customer's Office Desktop client or WAC are not charged as +egress. Only downloads to other client devices are charged. +CITED: administration/billing/meters.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q33 +ANSWER: No. Admin actions in SPAC are nonchargeable. +CITED: administration/billing/meters.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q34 +ANSWER: One. SPE mandates a 1:1 relationship between owning application and container type. +CITED: development/app-architecture.md, development/limits-calling.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q35 +ANSWER: Up to 25 container types by default ... 5 per developer tenant ... +CITED: getting-started/containertypes.md, development/limits-calling.md +FINDABILITY: EASY SUFFICIENCY: PARTIAL +GAP: "developer tenant" vs "partner tenant" distinction and trial-vs-standard unclear. + +QID: q36 +ANSWER: Max file size 250 GB; max 500 versions per file. +CITED: development/limits-calling.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q37 +ANSWER: Up to three owners. +CITED: administration/consuming-tenant-admin/SPE_app_installation_on_SPAC.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q38 +ANSWER: No. Billing type is permanent and cannot be changed after app creation. +CITED: administration/consuming-tenant-admin/SPE_app_installation_on_SPAC.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q39 +ANSWER: 93 days unless a retention policy changes the outcome; restorable within that window. +CITED: admin/manage-containers-sharepoint-admin-center.md, administration/consuming-tenant-admin/ctapowershell.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE +``` + +**Grading:** q31–q34, q36–q39 → 3. **q35 → 2 (partial — trial vs standard / 5 vs 25 / +developer vs partner tenant distinction unclear).** + +--- + +## Group 3 — auth / permissions / registration (q40–q48) + +**Questions** + +- q40 Difference between `Container.Selected` and `FileStorageContainer.Selected`? +- q41 Is the container type registration API a Microsoft Graph API? +- q42 What token type does the registration API require? +- q43 Which registration call wins if I call it multiple times? +- q44 What permission lets my app manage container membership/permissions? +- q45 Why can't admin consent complete for `Container.Selected`? +- q46 Can I use SPE app-only without any signed-in user? +- q47 What is the owning application relationship to a container type? +- q48 Does my app need a certificate for authentication? + +**Raw agent output** + +``` +QID: q40 +ANSWER: Container.Selected is a SharePoint permission for registration APIs on a +consuming tenant; FileStorageContainer.Selected is a Graph permission for accessing +containers (delegated or app-only). +CITED: build/configure-authentication-authorization.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q41 +ANSWER: No. The registration API is a SharePoint REST API (v2), not a Graph API. +CITED: getting-started/register-api-documentation.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q42 +ANSWER: An app-only token via client credentials grant with a certificate, for the +SharePoint resource. +CITED: getting-started/register-api-documentation.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q43 +ANSWER: The last successful registration call determines the settings used in the +consuming tenant. +CITED: getting-started/register-api-documentation.md, plan/authentication-permissions.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q44 +ANSWER: ManagePermissions (add/remove/update members in container roles). +CITED: getting-started/register-api-documentation.md, development/auth.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q45 +ANSWER: Container.Selected is hidden in the Azure portal, so consent can't complete via +the Enterprise apps pane; use the constructed admin-consent URL. +CITED: reference/troubleshooting.md, development/auth.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q46 +ANSWER: Yes. App-only access works without a signed-in user; needs +FileStorageContainer.Selected application permission with admin consent. +CITED: development/auth.md, plan/authentication-permissions.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q47 +ANSWER: 1:1. Each container type has one owning application with full default access to +its containers and the right to invoke the registration API. +CITED: getting-started/containertypes.md, getting-started/register-api-documentation.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q48 +ANSWER: Yes. The registration API requires a certificate via the client credentials grant. +CITED: getting-started/register-api-documentation.md, build/register-application-permissions.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE +``` + +**Grading:** all q40–q48 → 3. + +--- + +## Group 4 — files / Office / preview / search / webhooks (q49–q57) + +**Questions** + +- q49 How do I upload a large file to a container? +- q50 How do I open an Office file in the desktop client specifically? +- q51 How do I generate a preview/thumbnail link for a file? +- q52 Is container search available in the v1.0 Graph endpoint? +- q53 How long does a webhook subscription last before it expires? +- q54 What content type must my webhook validationToken response use? +- q55 How do I restore a soft-deleted container? +- q56 How do I move data from Azure Blob Storage into SPE? +- q57 How do I search using a custom metadata property? + +**Raw agent output** + +``` +QID: q49 +ANSWER: For larger files use an upload session (LargeFileUploadTask, 320 KB chunks). +CITED: build/manage-files.md, build/migrate-azure-blob-storage.md +FINDABILITY: EASY SUFFICIENCY: PARTIAL +GAP: No explicit size threshold for what counts as a "large" file. + +QID: q50 +ANSWER: Office URI schemes: ms-word:ofe|u|{webUrl}/{file} (and ms-excel, ms-powerpoint). +CITED: build/open-office-files.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE + +QID: q51 +ANSWER: POST .../drives/{driveId}/items/{itemId}/preview; use getUrl from the response. +CITED: build/preview-files.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE + +QID: q52 +ANSWER: No. Search requires /beta/search/query and is preview, delegated-only. For v1.0 +use OData $filter on drive items. +CITED: build/search-containers-files.md +FINDABILITY: HARD SUFFICIENCY: PARTIAL +GAP: Docs show the beta endpoint but don't explicitly state v1.0 lacks search. + +QID: q53 +ANSWER: Max lifetime 4,230 minutes before expiration. +CITED: build/respond-to-changes-webhooks.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE + +QID: q54 +ANSWER: Respond text/plain with the validationToken value as the body. +CITED: build/respond-to-changes-webhooks.md, development/tutorials/using-webhooks.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE + +QID: q55 +ANSWER: Restore-SPODeletedContainer -Identity ; restorable within 93 days; +reactivation instant in first 7 days, up to 24h after. +CITED: administration/consuming-tenant-admin/ctapowershell.md, build/create-manage-containers.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE + +QID: q56 +ANSWER: Download blobs to a stream, create an SPE upload session, upload with +LargeFileUploadTask (320 KB chunks), set conflictBehavior. +CITED: build/migrate-azure-blob-storage.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE + +QID: q57 +ANSWER: Append OWSTEXT to the custom property name in the search query (with +ContainerTypeId); OData $filter for single-container queries. +CITED: build/search-containers-files.md, build/container-metadata.md +FINDABILITY: EASY SUFFICIENCY: PARTIAL +GAP: Less detail on when to use search vs OData filtering. +``` + +**Grading:** q50, q51, q53–q56 → 3. **q49 → 2** (no size threshold). **q52 → 2** +(doesn't state v1.0 lacks search). **q57 → 2** (search-vs-OData guidance thin). + +--- + +## Group 5 — admin / install / onboarding (q58–q66) + +**Questions** + +- q58 Admin consent URL format to install a vendor app? +- q59 Where in the M365 admin center do I configure SPE billing? +- q60 Which PowerShell cmdlet sets a sensitivity label on a container? +- q61 How do I connect PowerShell to manage SPE? +- q62 What happens to users if billing is invalid or SPE is turned off? +- q63 Which permissions must a customer consent to for an ISV app to register and use containers? +- q64 How do I validate that a customer installed my app correctly? +- q65 What does a SharePoint Embedded Administrator role NOT have access to? +- q66 How do I monitor SPE cost in Azure? + +**Raw agent output** + +``` +QID: q58 +ANSWER: https://login.microsoftonline.com//adminconsent?client_id= +CITED: admin/grant-admin-consent-permissions.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q59 +ANSWER: Setup > Files and Content > Automate Content with Microsoft Syntex > Go to +Syntex settings > Apps > SharePoint Embedded. +CITED: admin/setup-billing-m365-admin-center.md +FINDABILITY: EASY SUFFICIENCY: COMPLETE GAP: NONE + +QID: q60 +ANSWER: Set-SPOContainer -Identity -SensitivityLabel