開始使用 Exchange Online 管理員 API

注意事項

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

本文將教你如何成功呼叫 Exchange Online 管理員 API，並說明適用於所有端點的關鍵行為與模式。

本文將協助你完成以下任務：

如何 (標頭和主體) 來呼叫 Exchange Online 管理員 API。
支援的環境以及每個環境可用的基本網址。
分頁與物業選擇的運作方式。
何時以及如何使用 X-AnchorMailbox 進行路由。
常見問題與最佳實務。

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

前提條件：設定認證與權限

在你第一次呼叫 Exchange Online 管理員 API 之前，你需要先設定認證和權限，讓你的應用程式或腳本能安全地存取你的組織。完整說明請參閱 Exchange Online 管理員 API 的認證與授權。

以下是摘要步驟：

在 Microsoft Entra ID 註冊應用程式：建立應用程式註冊以授權或僅限應用程式存取。
授予 API 權限：
- 委派： Exchange.ManageV2。
- 僅限應用程式：Exchange.ManageAsAppV2。
取得管理員同意：確保組織層級的權限獲得同意。
指派 RBAC 角色：將角色分配給使用者 (委派的) 或服務主體 (僅包含應用程式) ，涵蓋你所管理的物件。
取得存取權杖：使用委派或僅限應用程式的流程取得有效的 OAuth 令牌。
了解你的組織背景：識別你的 TenantID、 (GUID) 和基礎網址。

支援環境與基礎網址

Exchange Online 管理員 API 在所有Exchange Online環境中皆可用。每個環境對請求使用不同的基礎 URL，因此請確保使用符合你環境的正確 URL，如下表所示：

環境	基礎網址
Microsoft 365 或 Microsoft 365 GCC	`https://outlook.office365.com`
Office 365由中國 (21Vianet營運)	`https://outlook.office365.cn`
Microsoft 365 GCC High	`https://outlook.office365.us`
Microsoft 365 DoD	`https://outlook-dod.office365.us`

最終請求的網址取決於你的環境，包含你的 TenantID 和端點名稱，語法如下：

POST <BaseUrl>/adminapi/v2.0/<TenantID>/<EndpointName>

例如：

POST https://outlook.office365.com/adminapi/v2.0/0550b473-9fd2-4dbb-a058-a1640b4bf458/OrganizationConfig

請求型號 (標頭與主體)

每次 Exchange Online 管理員 API 呼叫都使用 POST 方法，並遵循一致的請求模型。主體必須包含一個 CmdletInput 包絡，指定 cmdlet 名稱及所選 REST 端點內支援的參數。

關於支援的指令匣和參數細節，請參見 Exchange Online 管理員 API 端點參考。

必填標頭：
- 授權： Bearer <access_token>。
- 內容類型： application/json
- X-AnchorMailbox：即將推出的 X-AnchorMailbox 路由提示章節中描述的路由鍵值。

本文：

{
  "CmdletInput": {
    "CmdletName": "<Cmdlet Name>",
    "Parameters": {
      /* parameters supported for this cmdlet in the endpoint & their value */
    }
  }
}

注意事項

傳遞不支援的指令匣或參數會產生錯誤： 400 錯誤請求。務必查看端點的具體文件，確認允許的指令匣和參數。

第一次叫牌範例

現在你已經了解請求結構和標頭，讓我們來做你的第一次成功呼叫。此範例使用 Microsoft 365 的基礎網址，並取得您的組織設定。

POST https://outlook.office365.com/adminapi/v2.0/12345678-90ab-cdef-1234-567890abcdef/OrganizationConfig
Authorization: Bearer <access_token>
Content-Type: application/json
X-AnchorMailbox: <appropriate routing key>

{
  "CmdletInput": {
    "CmdletName": "Get-OrganizationConfig"
  }
}

預期結果： 200 個 OK 和一個包含組織層級屬性的 JSON 有效載荷，例如 MailTipsAllTipsEnabled (，以及 MailTipsExternalRecipientsTipsEnabled) 。

X-AnchorMailbox 路由提示

X-AnchorMailbox 標頭是所有 v2.0 管理員 API 呼叫的必備。它提供路由提示，將請求導向正確的後端伺服器。若沒有路由提示，請求可能會被低效率地路由甚至完全失敗。提供正確的信箱識別碼可確保請求抵達信箱的主伺服器，降低延遲，避免不必要的跳躍，並提升一致性。

要在請求中加入標頭，請使用以下語法：

X-AnchorMailbox: <routing key>

支援的路由鍵值如下表說明：

路由金鑰	格式	範例
UPN (偏好)	`AAD-UPN:<user@domain>`	`AAD-UPN:alex@contoso.com`
SMTP	`AAD-SMTP:<user@domain>`	`AAD-SMTP:alex@contoso.com`
Microsoft Entra 物件 ID / 外部目錄物件 ID (EDOID)	`OID:<ExternalDirectoryObjectId>@<tenantId>`	`OID:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8`
信箱 GUID	`MBX:<mailboxGuid>@<tenantId>`	`MBX:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8`
系統信箱 (僅應用程式)	`APP:SystemMailbox{<systemMailboxGuid>}@<tenantIdOrOrganization>`	`APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com`

提示

使用 UPN 來確保郵箱重命名間的穩定性。僅用於應用程式情境，請使用系統信箱格式。

何時使用哪個路由金鑰

綁定特定信箱的操作：針對特定信箱 ( /Mailbox 、 /MailboxFolderPermission ) 的呼叫，請使用該信箱的路由金鑰。例如：
```
X-AnchorMailbox: UPN:alex@contoso.com
```
所有其他無特定郵箱目標的操作：根據情境使用以下鍵之一：
- 委託 (使用者) 流程：使用執行 API 管理員的路由金鑰。例如：
```
X-AnchorMailbox: UPN:admin@contoso.com
```
- 僅限應用程式的流程：使用組織系統信箱的路由金鑰。例如：
```
X-AnchorMailbox: APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com
```
  注意事項
  
  系統信箱 GUID 值在所有組織中相同，且為 bb558c35-97f1-4cb9-8ff7-d53741dc928c。

Pagination

部分Exchange Online 管理員 API 端點會回傳大量結果。支援分頁的端點會在個別端點文件中明確標示。分頁功能幫助你將結果分成較小的區塊，避免逾時或限速。

若要指定每頁項目數量，請在請求主體中使用 ResultSize 參數。
若有更多結果，回應會包含 @odata.nextLink 帶有延續網址的屬性。
要取得下一頁，請用相同的標頭和認證方式 POST 到 @odata.nextLink URL。

如果你不使用 ResultSize 參數，API 預設最多回傳 1,000 個項目。若要在單一請求中取得所有條目，若 ResultSize 參數支援，請使用該值Unlimited。

請使用以下方法來取得分頁的最佳實務：

保持各頁面請求的參數一致。
**生成 @odata.nextLink 的作品僅在產生時有效5-10分鐘內。如果你嘗試使用過期的連結，請求可能會失敗。為避免錯誤，收到物業後5分鐘 @odata.nextLink 內完成分頁通話。

範例請求：

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox
Authorization: Bearer <access_token>
Content-Type: application/json
X-AnchorMailbox: <Routing key>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "ResultSize": 50
    }
  }
}

後續頁面：

POST 到 @odata.nextLink 網址 (用同樣的方法) 。
不要在頁面間更改參數。

$select 物業選擇

Exchange Online 管理員 API 支援所有端點的$select查詢參數。只回 $select 傳回應有效載荷中你需要的屬性。此策略有助於縮小回應規模，並減少客戶的解析負擔。

若子句中 $select 指定的屬性無效，服務會跳過該屬性並回傳剩餘的有效屬性。

在端點網址上附加 $select 查詢參數。用逗號分隔多個物業：

POST https://<base-url>/adminapi/v2.0/<TenantID>/<EndpointName>?$select=Property1,Property2,...

例如，將 TenantID、access_token 和路由鍵>替換<成適當的值，只回傳顯示名稱和主要 SMTP 地址給信箱：<><>

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox?$select=DisplayName,PrimarySmtpAddress
Authorization: Bearer <access_token>
Content-Type: application/json
X-AnchorMailbox: <routing key>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox"
  }
}

常見問題及解決方法

本節說明您在使用 Exchange Online 管理員 API 時可能遇到的常見問題。

401 未經授權

原因：
- 缺少、無效或過期的 OAuth 代幣。
- 瞄準鏡錯誤。
修正方法：
- 確保您的應用程式已指定正確的範圍：
  - 委派： Exchange.ManageV2。
  - 僅限應用程式： Exchange.ManageAsAppV2。
- 如果原有的代幣過期，請取得新的代幣。
- 請確認申請中已傳達正確的 TenantID 和應用程式註冊資料。

403 禁忌

原因：缺少 RBAC 角色或試圖管理超出你範圍的物件。
修正方法：
- 將所需的 RBAC 角色指派給使用者 (委派的) 或服務主體 (僅) 。
- 確認該物件在你的管理範圍內。

400 個壞請求

原因：參數不支援或格式錯誤。
修正方法：
- 請查看 cmdlet 中端點與 cmdlet 組合的詳細資訊。
- 只在 REST 端點中包含 cmdlet 支援的參數。

錯誤的基礎網址

原因：你遇到的基地網址不適合你的環境。
解決方法：使用你組織的正確基礎網址。

頁碼問題

原因：在呼叫呼叫間改變參數或忽略 @odata.nextLink。
修正方法：
- 保持所有頁面的參數一致。
- 一定要貼網址 @odata.nextLink 。
- 如果你不使用 ResultSize 參數，API 預設每頁有 1,000 個項目。

路由錯誤

原因：郵箱範圍操作缺少或錯誤的 X-AnchorMailbox 標頭。
修正方法：
- 請將 X-AnchorMailbox 與郵箱 UPN (偏好的) 或 SMTP 位址一起加入。
- 在發送請求前先驗證該值。

最佳做法

請遵循本節指引，以確保 Exchange Online 管理員 API 的可靠且高效使用。

認證與安全性：
- 在生產工作負載中，使用僅有應用程式的認證，搭配憑證或受管理身份。
- 請只申請你需要的權限 (Exchange.ManageV2 或 Exchange.ManageAsAppV2) 。
- 指派最少的RBAC角色以降低風險。
需求設計：
- 所有操作都一定要用 POST，包括 Get-* 指令。
- 端點僅包含支援 cmdlet 的參數。
- 所有操作皆使用 X-AnchorMailbox 。
效能優化：
- 用於 $select 減少反應有效載荷大小。
- 對於大型資料集，可以搭配 $select 分頁。
- 使用 ResultSize 參數。否則，API 預設每頁有 1,000 個條目。
韌性與錯誤處理：
- 實作重試邏輯來限制 HTTP 429) (並尊重重試後。
- 從錯誤回應中記錄請求 ID，以便排查。
- 發送請求前先驗證參數，以避免 400 次錯誤請求。
路由與環境感知：
- 請使用您組織的正確基礎網址。
- 所有請求都包含 X-AnchorMailbox ，以避免路由錯誤。

後續步驟

Last updated on 2025-11-17

共用方式為