适用于: 开发人员版
在 SharePoint Embedded 应用创建容器或访问使用租户中的内容之前,注册容器类型应用程序权限。
完成 首先 创建和配置容器类型 ,以便拥有容器类型 ID 和拥有应用程序。
为什么需要注册
在使用租户中注册容器类型之前,SharePoint Embedded 应用程序无法与该租户中的容器交互。
注册控制:
- 哪些应用程序 ID 可以访问容器类型。
- 每个应用程序拥有的委派权限。
- 每个应用程序具有哪些仅限应用的权限。
- 来宾应用程序是否可以与拥有应用程序的容器交互。
如果注册缺失或不完整,以后的调用可能会失败并出现拒绝访问错误。
了解谁可以注册
只有容器类型的拥有应用程序才能在使用租户中调用注册 API。
拥有的应用程序必须:
- 在使用租户上安装的服务主体。
- 管理员同意在使用租户中执行注册。
- Microsoft Graph 权限 (
FileStorageContainerTypeReg.Selected用户委派或仅限应用) 。 - Microsoft Graph 资源的有效令牌。
注意
容器类型注册 API 在 Microsoft Graph v1.0 中可用。
当拥有应用程序代表用户 (委派) 调用注册 API 时,必须为该用户分配 SharePoint 嵌入式管理员 或 全局管理员 角色。 当它在没有用户上下文 (仅限应用的) 进行调用时,它使用客户端凭据授予流。
授予管理员同意
请求使用租户管理员授予对拥有应用程序的管理员同意。
使用 Microsoft 标识平台管理员同意终结点:
https://login.microsoftonline.com/{consuming-tenant-id}/v2.0/adminconsent?client_id={owning-app-clientid}&scope=https://graph.microsoft.com/.default&redirect_uri={spe-app-redirect-uri}
为载入流程配置成功和错误处理。
有关国家/地区云终结点,请参阅国家/地区云上的 Microsoft 标识平台终结点。
获取令牌进行注册
使用委派或仅应用身份验证进行注册。
注册要求:
-
FileStorageContainerTypeReg.SelectedMicrosoft Graph 权限。 - 对于仅限应用的调用, 客户端凭据授予流。
- 对于委派调用,是具有 SharePoint Embedded 管理员或全局管理员角色的登录用户。
注册容器类型权限
调用使用租户中的注册终结点。
PUT https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypeRegistrations/{containerTypeId}
{containerTypeId} 是在开发人员租户中创建的容器类型 ID。
在请求正文中,为容器类型提供应用程序权限授予。
创建、替换或更新注册
根据是需要替换完整注册还是更新所选属性来选择操作:
| 目标 | Microsoft Graph 请求 | 行为 |
|---|---|---|
| 创建或替换注册 | PUT /storage/fileStorage/containerTypeRegistrations/{containerTypeId} |
使用容器类型 ID 创建注册。 如果注册存在,请求会将其替换为完整的有效负载。 |
| 更新所选注册属性 | PATCH /storage/fileStorage/containerTypeRegistrations/{registrationId} |
仅汇报 Microsoft Graph v1.0 中提供的属性。 |
该 PATCH 操作使用乐观并发的注册 etag 。 读取当前注册,并将其属性包含在 etag 更新正文中。 如果另一个请求首先更改注册,请读取最新值并核对更新,而不是覆盖它。
注册更新可能需要长达一小时才能传播。
有关 API 的详细信息,请参阅 创建 fileStorageContainerTypeRegistration 和 更新 fileStorageContainerTypeRegistration。
向拥有应用授予权限
通用首次注册会授予拥有应用对委派调用和仅应用调用的完全权限。
{
"applicationPermissionGrants": [
{
"appId": "71392b2f-1765-406e-86af-5907d9bdb2ab",
"delegatedPermissions": ["full"],
"applicationPermissions": ["full"]
}
]
}
将示例应用 ID 替换为你拥有的应用程序 ID。
警告
将最小权限用于生产。 仅当应用程序需要完全容器类型访问时才授予 full 。
向来宾应用授予权限
拥有的应用还可以注册其他应用程序的权限。
当来宾应用需要定义的工作负载(例如备份或处理)时,使用此模式。
{
"applicationPermissionGrants": [
{
"appId": "71392b2f-1765-406e-86af-5907d9bdb2ab",
"delegatedPermissions": ["full"],
"applicationPermissions": ["full"]
},
{
"appId": "89ea5c94-7736-4e25-95ad-3fa95f62b6cd",
"delegatedPermissions": ["read", "write"],
"applicationPermissions": ["none"]
}
]
}
将这两个应用 ID 替换为应用程序。
权限值
| 权限 | 用途 |
|---|---|
none |
不授予任何权限。 |
readContent |
读取此类型容器中的内容。 |
writeContent |
在此类型的容器中写入内容。 |
create |
创建此类型的容器。 |
delete |
删除此类型的容器。 |
read |
读取容器元数据。 |
write |
更新容器元数据。 |
enumeratePermissions |
枚举容器成员和角色。 |
addPermissions |
添加容器成员。 |
updatePermissions |
更新现有成员资格。 |
deletePermissions |
删除其他成员。 |
deleteOwnPermission |
删除调用方自己的成员身份。 |
managePermissions |
管理容器角色分配。 |
manageContent |
管理此类型容器的内容。 |
full |
授予所有权限。 |
注意
writeContent 如果没有 ,则 readContent无法授予。
验证注册
成功注册将返回,响应正文中配置的权限将返回 201 Created 。
注册成功后:
- 确认响应包含预期的应用 ID。
- 确认委派和仅限应用的数组与预期授权匹配。
- 获取具有 SharePoint Embedded 权限的 Microsoft Graph 令牌。
- 尝试与注册权限匹配的低风险操作。
- 继续 配置身份验证和授权。
排查同意问题
| 症状 | 可能的原因 | 操作 |
|---|---|---|
401 Unauthorized |
令牌缺失或无效 | 请求有效的仅应用令牌。 |
403 Forbidden |
应用缺乏权限或不拥有应用 | 确认 FileStorageContainerTypeReg.Selected、同意和应用 ID。 |
404 Not Found |
容器类型不存在 | 验证 ID 和租户。 |
| Graph 调用拒绝访问 | 注册缺失或不足 | 使用所需的权限重新注册。 |
| 管理员找不到隐藏的权限 | 门户不公开它 | 使用管理员同意 URL。 |
安全重新注册
可以调用注册 API 的次数没有限制。
上次成功的注册调用将确定在使用租户中使用的设置。
使用安全更新过程:
- 确定更改是需要完全
PUT替换还是有针对性的PATCH更新。 - 对于
PUT,生成完整的注册有效负载。 - 对于
PATCH,请阅读并包含当前注册。etag - 包括应保留访问权限的所有应用。
- 提交注册调用。
- 验证响应。
- 对每个应用角色运行冒烟测试。
重要
请勿发送部分有效负载,除非你希望生成的注册仅包含该组应用程序和权限。
后续步骤
在“ 配置身份验证和授权”中配置令牌和授权流。