共用方式為

Exchange Online 管理員 API 中的 MailboxFolderPermission 端點

注意事項

本文所述的功能目前處於預覽階段，並非所有組織都能提供，且可能會有所變動。

Exchange Online 管理員 API 中的 MailboxFolderPermission 端點允許你管理信箱資料夾的權限。

典型的使用情境包括：

  • 在信箱資料夾中列出現有權限。
  • 在信箱資料夾中授予使用者或群組權限。
  • 修改信箱資料夾中現有使用者或群組的權限。
  • 從信箱資料夾移除現有使用者或群組的權限。

Exchange Online 管理員 API 提供基於 REST 的方式來執行特定的 PowerShell 指令集，取代舊有的 Exchange Web Services (EWS) 情境。 欲了解更多資訊，請參閱 Exchange Online 管理員 API 概述。

端點網址

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

提示

請依照 支援環境和基礎網址描述，使用你環境的基礎網址。

請求模型

標頭

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

關於 X-AnchorMailbox 的值，請參見 X-AnchorMailbox 路由提示。

內文

注意事項

以下的 Identity 範例使用 \\，符合 JSON 語法的直譯反斜線。 API 實際接收的資料夾路徑使用單一 \ (，例如 alex@contoso.com：\Calendar) 。 如果你使用 (PowerShell、Python 或 Postman 原始 JSON 編輯器) 的工具或 SDK 幫你序列化 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-MailboxFolderPermissions ：

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

Pagination

Get-MailboxFolderPermission 指令檔中的 ResultSize 參數控制分頁。 預設情況下，最多可回傳 1,000 筆結果。

若有更多結果，回應會包含 @odata.nextLink 帶有延續網址的屬性。 要取得下一頁，向包含相同主體的 URL @odata.nextLink 發出新的 POST 請求。

物業選擇

此端點支援 $select 查詢參數，僅回傳回應中的特定屬性。

支援的指令集與參數

以下列表描述該端點所支援的指令匣與參數。 該端點主體中的其他指令檔則會導致錯誤。

  • Get-MailboxFolderPermission：

    只有下表中描述的 Get-MailboxFolderPermission 參數可透過 REST 端點取得：

    參數 必要項目 類型 描述
    [身分識別] 必要 字串 目標資料夾，語法 <Mailbox UPN or Alias or Email address or Name>:\<FolderPath>為 。 例如，alex@contoso.com:\Calendar 或 alex:\Inbox\Reports。
    結果大小 選用 整數還是無限 限制回傳的結果數量。 有效的值為整數 (，例如10) 或值 "Unlimited"。

  • Add-MailboxFolderPermission：

    只有下表中描述的 Add-MailboxFolderPermission 參數可透過 REST 端點取得：

    參數 必要項目 類型 描述
    [身分識別] 必要 字串 目標資料夾，語法 <mailbox UPN or alias>:\<FolderPath>為 。 例如，alex@contoso.com:\Calendar 或 alex:\Inbox\Reports。
    使用者 必要 使用者或群組獲得該信箱資料夾權限。 有效的值包括 UPN、電子郵件地址、知名的安全主體 (， Default 或 Anonymous) 。
    存取權 必要 字串或陣列。 以下其中一種價值：
    • 角色：例如， Owner、、 Editor或 Reviewer。
    • 細緻權利：例如， CreateItems、、 DeleteAllItems或 FolderVisible。 多個值使用以下語法： ["Role1","Role2"...]
    共享許可旗標 選用 字串或陣列 僅限 Calendar。 設定 ViewPrivateItems 和/或 ReceiveCopiesOfMeetingMessages

  • Set-MailboxFolderPermission：

    只有下表中描述的 Set-MailboxFolderPermissions 參數可透過 REST 端點取得：

    參數 必要項目 類型 描述
    [身分識別] 必要 字串 目標資料夾，語法 <mailbox UPN or alias>:\<FolderPath>為 。 例如，alex@contoso.com:\Calendar 或 alex:\Inbox\Reports。
    使用者 必要 使用者或群組獲得該信箱資料夾權限。 有效的值包括 UPN、電子郵件地址、知名的安全主體 (， Default 或 Anonymous) 。
    存取權 必要 字串或陣列。 以下其中一種價值：
    • 角色：例如， Owner、、 Editor或 Reviewer。
    • 細緻權利：例如， CreateItems、、 DeleteAllItems或 FolderVisible。 多個值使用以下語法： ["Role1","Role2"...]
    共享許可旗標 選用 字串或陣列 僅限 Calendar。 設定 ViewPrivateItems 和/或 ReceiveCopiesOfMeetingMessages
    SendNotificationToUser 選用 布林值 這個值 True 會向獲得變更權限的使用者或群組發送通知。

    注意：此參數為分階段推行，可能並非所有組織皆有。

  • Remove-MailboxFolderPermissions ：

    只有下表中描述的 Remove-MailboxFolderPermission 參數可透過 REST 端點取得：

    參數 必要項目 類型 描述
    [身分識別] 必要 字串 目標資料夾，語法 <mailbox UPN or alias>:\<FolderPath>為 。 例如，alex@contoso.com:\Calendar 或 alex:\Inbox\Reports。
    使用者 必要 使用者或群組獲得該信箱資料夾權限。 有效的值包括 UPN、電子郵件地址、知名的安全主體 (， Default 或 Anonymous) 。
    SendNotificationToUser 選用 布林值 這個值 True 會向獲得變更權限的使用者或群組發送通知。

    注意：此參數為分階段推行，可能並非所有組織皆有。

回應概述

注意事項

在預覽階段，端點會在 API 回應中包含完整的 Get-MailboxFolderPermission 指令碼輸出。 在轉為公開釋放期間，回應將限於本節列出的核心物業 (符合EWS等效情境) 所需的物業。 我們建議您僅使用本節列出的物業。 我們會記錄任何可用物業的變更。

  • Get-MailboxFolderPermission 回應是一個可分頁的 JSON 權限陣列，用於指定信箱資料夾。 每個條目通常包含受讓人、存取權限、資料夾識別碼及元資料。 會傳回下列屬性：

    • Identity：使用語法 <mailbox>:\<FolderPath>.
    • 資料夾名稱：資料夾的顯示名稱。 例如，Inbox 或 Calendar。
    • 使用者：擁有資料夾權限的使用者或群組的唯一身份。 例如，顯示名稱、SMTP 位址或 UPN。
    • 存取權：在信箱資料夾中授予使用者或群組的角色或細緻權限。 例如 Reviewer、Editor 或 CreateItems。
    • SharingPermissionFlags：僅限 Calendar 的旗標。 例如，ViewPrivateItems 或 ReceiveCopiesOfMeetingMessages。
    • IsValid：表示該權限條目是否有效。
    • ObjectState：權限輸入狀態 (內部狀態元資料) 。

  • Add-MailboxFolderPermission、Set-MailboxFolderPermissions 和 Remove-MailboxFolderPermission 指令串成功後會返回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