Exchange Online 管理员 API 中的 MailboxFolderPermission 终结点

注意

本文中所述的功能目前为预览版，并非在所有组织中都可用，并且可能会发生更改。

Exchange Online 管理员 API 中的 MailboxFolderPermission 终结点允许管理邮箱文件夹的权限。

典型用例包括：

列出邮箱文件夹的现有权限。
向用户或组授予邮箱文件夹的权限。
修改邮箱文件夹上现有用户或组的权限。
从邮箱文件夹中删除现有用户或组的权限。

Exchange Online 管理员 API 提供了一种基于 REST 的方式来执行特定 PowerShell cmdlet，取代了旧版 Exchange Web Services (EWS) 方案。有关详细信息，请参阅 Exchange Online 管理员 API 概述。

端点 URL

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/MailboxFolderPermission

提示

按照支持的环境和基 URL 中所述，使用环境的基 URL。

请求模型

标题

Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <routing hint>

有关 X-AnchorMailbox 值，请参阅 X-AnchorMailbox 路由提示。

正文

注意

下面的标识示例使用 \\ 作为文本反斜杠的 JSON 语法的要求。 API 接收的实际文件夹路径使用单个 \ (例如 alex@contoso.com：\Calendar) 。如果使用的工具或 SDK (例如 PowerShell、Python 或 Postman 的原始 JSON 编辑器) 序列化 JSON，请在代码中编写一个 \，序列化程序会自动添加额外的 \ 。例如，如果要构造原始 JSON (，请在 curl 请求正文) 中使用 \\。

Get-MailboxFolderPermission：

{
  "CmdletInput": {
    "CmdletName": "Get-MailboxFolderPermission",
    "Parameters": {
      "Identity": "alex@contoso.com:\\Calendar",   // Required. Format: <mailbox>:\<FolderPath>
      "ResultSize": <Integer | "Unlimited">        // optional (pagination)
    }
  }
}

Add-MailboxFolderPermission：

{
  "CmdletInput": {
    "CmdletName": "Add-MailboxFolderPermission",
    "Parameters": {
      "Identity": "alex@contoso.com:\\Calendar",  // target folder
      "User": "delegate1@contoso.com",            // grantee
      "AccessRights": "Editor",                    // role or granular rights
      "SharingPermissionFlags": "ViewPrivateItems" // Calendar-only flag(s)
    }
  }
}

Set-MailboxFolderPermission：

{
  "CmdletInput": {
    "CmdletName": "Set-MailboxFolderPermission",
    "Parameters": {
      "Identity": "alex@contoso.com:\\Calendar",
      "User": "delegate1@contoso.com",
      "AccessRights": "PublishingEditor",          // optional
      "SharingPermissionFlags": "ReceiveCopiesOfMeetingMessages", // optional (Calendar-only)
      "SendNotificationToUser": false              // optional
    }
  }
}

Remove-MailboxFolderPermission：

{
  "CmdletInput": {
    "CmdletName": "Remove-MailboxFolderPermission",
    "Parameters": {
      "Identity": "alex@contoso.com:\\Calendar",
      "User": "delegate1@contoso.com",
      "SendNotificationToUser": true               // optional
    }
  }
}

分页

Get-MailboxFolderPermission cmdlet 上的 ResultSize 参数控制分页。默认情况下，最多返回 1,000 个结果。

如果有更多结果可用，则响应将包含具有 @odata.nextLink 延续 URL 的属性。若要提取下一页，请使用同一正文向中的 @odata.nextLink URL 发出新的 POST 请求。

属性选择

此终结点支持 $select 查询参数在响应中仅返回特定属性。

支持的 cmdlet 和参数

以下列表介绍了此终结点支持的 cmdlet 和参数。此终结点正文中的其他 cmdlet 会导致错误。

Get-MailboxFolderPermission：

只有下表中所述的 Get-MailboxFolderPermission 的参数可通过 REST 终结点使用：

参数	必需	类型	说明
Identity	必需	String	使用语法的目标文件夹： `<Mailbox UPN or Alias or Email address or Name>:\<FolderPath>`。例如，`alex@contoso.com:\Calendar` 或 `alex:\Inbox\Reports`。
ResultSize	可选	整数或无限制	限制返回的结果数。有效值是整数 (例如，10) 或值 `"Unlimited"`。

Add-MailboxFolderPermission：

只有下表中所述的 Add-MailboxFolderPermission 的参数可通过 REST 终结点使用：

参数	必需	类型	说明
Identity	必需	String	使用语法的目标文件夹： `<mailbox UPN or alias>:\<FolderPath>`。例如，`alex@contoso.com:\Calendar` 或 `alex:\Inbox\Reports`。
用户	必需	获取邮箱文件夹权限的用户或组。有效值为 UPN 或电子邮件地址，或已知安全主体 (例如， `Default` 或 `Anonymous`) 。
AccessRights	必需	字符串或数组。	以下类型的值之一：角色：例如 `Owner`、 `Editor`或 `Reviewer`。细化权限：例如 `CreateItems`、 `DeleteAllItems`或 `FolderVisible`。多个值使用语法： `["Role1","Role2"...]`
SharingPermissionFlags	可选	字符串或数组	仅限Calendar。配置 `ViewPrivateItems` 和/或 `ReceiveCopiesOfMeetingMessages`

Set-MailboxFolderPermission：

只有下表中所述的 Set-MailboxFolderPermission 的参数可通过 REST 终结点使用：

参数	必需	类型	说明
Identity	必需	String	使用语法的目标文件夹： `<mailbox UPN or alias>:\<FolderPath>`。例如，`alex@contoso.com:\Calendar` 或 `alex:\Inbox\Reports`。
用户	必需	获取邮箱文件夹权限的用户或组。有效值为 UPN 或电子邮件地址，或已知安全主体 (例如， `Default` 或 `Anonymous`) 。
AccessRights	必需	字符串或数组。	以下类型的值之一：角色：例如 `Owner`、 `Editor`或 `Reviewer`。细化权限：例如 `CreateItems`、 `DeleteAllItems`或 `FolderVisible`。多个值使用语法： `["Role1","Role2"...]`
SharingPermissionFlags	可选	字符串或数组	仅限Calendar。配置 `ViewPrivateItems` 和/或 `ReceiveCopiesOfMeetingMessages`
SendNotificationToUser	可选	布尔值	值 `True` 向获取更改权限的用户或组发送通知。注意：此参数正在分阶段推出，可能并非在所有组织中都可用。

Remove-MailboxFolderPermission：

只有下表中所述的 Remove-MailboxFolderPermission 的参数可通过 REST 终结点使用：

参数	必需	类型	说明
Identity	必需	String	使用语法的目标文件夹： `<mailbox UPN or alias>:\<FolderPath>`。例如，`alex@contoso.com:\Calendar` 或 `alex:\Inbox\Reports`。
用户	必需	获取邮箱文件夹权限的用户或组。有效值为 UPN 或电子邮件地址，或已知安全主体 (例如， `Default` 或 `Anonymous`) 。
SendNotificationToUser	可选	布尔值	值 `True` 向获取更改权限的用户或组发送通知。注意：此参数正在分阶段推出，可能并非在所有组织中都可用。

响应概述

注意

在预览期间，终结点在 API 响应中包含完整的 Get-MailboxFolderPermission cmdlet 输出。在过渡到公共版本期间，响应将仅限于本节中列出的核心属性， (EWS 等效方案) 所需的属性。建议仅使用本节中列出的属性。我们将记录对可用属性所做的任何更改。

Get-MailboxFolderPermission 响应是指定邮箱文件夹的权限条目的可分页 JSON 数组。每个条目通常包括被授权者、访问权限、文件夹标识和元数据。将返回下列属性：
- 标识：使用语法的目标文件夹标识： <mailbox>:\<FolderPath>。
- FolderName：文件夹显示名称。例如，Inbox 或 Calendar。
- 用户：获取文件夹权限的用户或组的唯一标识。例如，显示名称、SMTP 地址或 UPN。
- AccessRights：在邮箱文件夹上授予用户或组的角色或精细权限。例如，Reviewer、Editor 或 CreateItems。
- SharingPermissionFlags：仅Calendar标志。例如，ViewPrivateItems 或 ReceiveCopiesOfMeetingMessages。
- IsValid：指示权限项是否有效。
- ObjectState：权限输入状态 (内部状态元数据) 。
Add-MailboxFolderPermission、Set-MailboxFolderPermission 和 Remove-MailboxFolderPermission cmdlet 在成功时返回HTTP 200 OK。
- 默认情况下，这些操作不返回有效负载。
- Set-MailboxFolderPermission 可能会返回更新的权限条目，具体取决于操作和服务行为。

示例

示例 1：获取分页日历权限：

此示例在指定邮箱的 Calendar 文件夹中返回最多 50 个权限条目。使用 @odata.nextLink 继续。

POST /adminapi/v2.0/<TenantID>/MailboxFolderPermission HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Get-MailboxFolderPermission",
    "Parameters": {
      "Identity": "alex@contoso.com:\\Calendar",
      "ResultSize": 50
    }
  }
}

示例 2：使用 ViewPrivateItems 添加编辑器权限：

本示例向指定的委托授予“编辑者”角色，并允许) 查看仅 (Calendar 标志的私有项。

POST /adminapi/v2.0/<TenantID>/MailboxFolderPermission HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Add-MailboxFolderPermission",
    "Parameters": {
      "Identity": "alex@contoso.com:\\Calendar",
      "User": "delegate1@contoso.com",
      "AccessRights": "Editor",
      "SharingPermissionFlags": "ViewPrivateItems"
    }
  }
}

示例 3：在不通知的情况下更新现有委托的权限：

此示例将指定代理在指定邮箱上的角色修改为 PublishingEditor 并接收会议邀请的副本。代理不会收到有关更改的通知。

POST /adminapi/v2.0/<TenantID>/MailboxFolderPermission HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Set-MailboxFolderPermission",
    "Parameters": {
      "Identity": "alex@contoso.com:\\Calendar",
      "User": "delegate1@contoso.com",
      "AccessRights": "PublishingEditor",
      "SharingPermissionFlags": "ReceiveCopiesOfMeetingMessages",
      "SendNotificationToUser": false
    }
  }
}

示例 4：使用通知删除代理人的权限：

此示例从指定邮箱文件夹中删除指定代理人的所有权限。代理将收到有关更改的通知。

POST /adminapi/v2.0/<TenantID>/MailboxFolderPermission HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Remove-MailboxFolderPermission",
    "Parameters": {
      "Identity": "alex@contoso.com:\\Inbox",
      "User": "delegate1@contoso.com",
      "SendNotificationToUser": true
    }
  }
}

Last updated on 2026-03-25

通过