Düzenle

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 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.

Know the lifecycle

A typical container lifecycle includes:

  1. Create a container.
  2. Add or confirm members.
  3. Upload and manage files.
  4. Read or update container metadata.
  5. Recycle a container when it's no longer active.
  6. Restore a recycled container when needed.
  7. Permanently delete containers during cleanup.

Continue to Upload, download, and manage files 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.
  • The app acquires its token as a confidential client, because container creation requires it.
  • For delegated calls, the signed-in user can receive the needed container role.
  • For trial container types, you're within trial limits.

Important

Trial container types can create up to five containers, including active containers and containers in the recycle bin.

Use a confidential client to create containers

Creating a container requires a confidential client application. A confidential client holds a credential, such as a client secret or certificate, and acquires tokens from a component that keeps that credential private, like a web app back-end or a service.

Create container calls that use a token from a public client application fail because public client tokens are accessible to the end user and can be re-used without the application's awareness. Public clients include single-page apps, mobile apps, and desktop apps.

This requirement applies to both delegated and app-only creation:

  • For delegated creation, acquire the token with the authorization code flow and a client credential, then call Microsoft Graph from your back-end.
  • For app-only creation, acquire the token with the client credentials flow, which is always confidential.

If your app has a public client front end, route container creation through a confidential back-end service instead of calling Microsoft Graph from the client.

For more information, see Public client and confidential client applications.

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.

Implementation steps:

  1. Acquire a valid Microsoft Graph token from a confidential client.
  2. Include the target container type information required by the API.
  3. Send the create request.
  4. Store the returned container ID.
  5. Store display metadata your app needs.
  6. 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.
  2. Expand the registered trial container type.
  3. Right-click Containers.
  4. Select Create container.
  5. Enter a name.
  6. Confirm the container appears under the container type.

See Quickstart: Build your first app with VS Code for the extension flow.

List containers

List containers to show available containers, validate provisioning, or run maintenance.

For the canonical API shape, see List containers.

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.

Update container metadata

Update metadata when supported properties change.

Before updating:

  1. Confirm the app has container type Write permission.
  2. Confirm the delegated user has an appropriate role.
  3. Read the current container state.
  4. Apply only intended changes.
  5. Validate the response.

Delete or recycle a container

Recycle or delete a container when it's 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.
  • Tell users how they can restore a recycled container.

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.
  2. Confirm the caller has permission.
  3. Restore the container.
  4. Refresh application state.
  5. Confirm files and metadata are available.
  6. 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.
  2. Retrieve it by ID.
  3. List containers and confirm it appears.
  4. Update a supported metadata value.
  5. Upload a small file.
  6. Recycle or delete the container.
  7. Restore it if supported.
  8. Permanently delete it during cleanup.

Troubleshoot lifecycle issues

Symptom Check
Create fails Registration and Create permission.
Create fails from a browser, mobile, or desktop app The token comes from a public client. Acquire it from a confidential client instead.
Delegated create fails User consent, confidential client token acquisition, and role assignment behavior.
List fails for delegated user OneDrive dependency noted in the auth article.
Delete fails Delete permission and user Owner role.
Trial create fails Active plus recycled containers may have reached the limit.
Container type delete fails All active and deleted containers must be removed first.

Next steps

Add file operations in Upload, download, and manage files.

  • Last updated on