通过

Exchange Online 管理员 API 入门

注意

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

本文介绍了如何成功进行第一次Exchange Online 管理员 API 调用，并说明跨所有终结点应用的关键行为和模式。

本文可帮助你完成以下任务：

  • 如何 (标头和正文) 形成请求以调用Exchange Online 管理员 API。
  • 要用于每个环境的支持的环境和基 URL。
  • 分页和属性选择的工作原理。
  • 何时以及如何使用 X-AnchorMailbox 进行路由。
  • 常见问题和最佳做法。

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

先决条件：设置身份验证和权限

在首次调用 Exchange Online 管理员 API 之前，需要设置身份验证和权限，以便应用或脚本可以安全地访问组织。 有关完整说明，请参阅 Exchange Online 管理员 API 的身份验证和授权。

下面是汇总的步骤：

  1. 在 Microsoft Entra ID 中注册应用：为委派或仅限应用的访问权限创建应用注册。
  2. 授予 API 权限：
    • 委托： Exchange.ManageV2。
    • 仅限应用： Exchange.ManageAsAppV2。
  3. 获取管理员同意：确保在组织级别同意权限。
  4. 分配 RBAC 角色：将角色分配给 (委派) 或服务主体 (涵盖所管理对象的仅限应用) 的用户。
  5. 获取访问令牌：使用委托流或仅限应用的流获取有效的 OAuth 令牌。
  6. 了解组织上下文：确定你的 TenantID (GUID) 和基 URL。

支持的环境和基 URL

Exchange Online 管理员 API 在所有Exchange Online环境中都可用。 每个环境对请求使用不同的基 URL，因此请确保为环境使用正确的 URL，如下表所述：

环境 基 URL
Microsoft 365 或 Microsoft 365 GCC https://outlook.office365.com
由世纪互联（中国）运营的 Office 365 https://outlook.office365.cn
Microsoft 365 GCC High https://outlook.office365.us
Microsoft 365 DoD https://outlook-dod.office365.us

最终请求 URL 取决于你的环境，并使用以下语法包括 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 信封，该信封指定所选 REST 终结点中的 cmdlet 名称和支持的参数。

有关支持的 cmdlet 和参数的详细信息，请参阅 Exchange Online 管理员 API 终结点参考。

  • 所需的标头：

    • 授权： Bearer <access_token>。
    • Content-Type： application/json
    • X-AnchorMailbox：如即将发布的 X-AnchorMailbox 路由提示 部分中所述的路由键值。

  • 正文：

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

注意

为终结点传递不支持的 cmdlet 或参数会导致错误： 400 错误请求。 始终检查终结点的特定文档，以获取允许的 cmdlet 和参数。

首次调用示例

现在你已了解请求结构和标头，接下来让我们进行第一次成功的调用。 此示例使用 Microsoft 365 基 URL 并检索组织配置。

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 正常 ，JSON 有效负载包含组织级别属性 (例如， MailTipsAllTipsEnabledMailTipsExternalRecipientsTipsEnabled) 。

X-AnchorMailbox 路由提示

所有 v2.0 管理员 API 调用都必须使用X-AnchorMailbox 标头。 它提供将请求定向到正确的后端服务器的路由提示。 如果没有路由提示，请求的路由可能会效率低下或完全失败。 提供正确的邮箱标识符可确保请求到达邮箱的主服务器，减少延迟，避免不必要的跃点，并提高一致性。

若要将 标头添加到请求，请使用以下语法：

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。

分页

某些Exchange Online 管理员 API 终结点返回大型结果。 各个终结点文档中明确标识了支持分页的终结点。 分页有助于检索较小区块中的结果，并避免超时或限制。

  • 若要指定每页的项数，请在请求正文中使用 ResultSize 参数。
  • 如果有更多结果可用，则响应将包含具有 @odata.nextLink 延续 URL 的属性。
  • 若要获取下一页，请使用相同的标头和身份验证发布到 @odata.nextLink URL。

如果不使用 ResultSize 参数，API 默认最多返回 1,000 个条目。 若要检索单个请求中的所有条目，请使用 ResultSize 参数的值Unlimited（如果支持该值）。

使用以下方法获取分页的最佳做法：

  • 使跨页面的请求的参数保持一致。
  • **生成的 @odata.nextLink 仅在生成时 5-10 分钟内有效。 如果尝试使用过期的链接，请求可能会失败。 为避免错误，请在收到 @odata.nextLink 属性后的 5 分钟内完成分页调用。

示例请求：

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 URL (使用相同的方法) 。
  • 不要在页面之间更改参数。

使用$select选择属性

Exchange Online 管理员 API 支持$select所有终结点上的查询参数。 使用 $select 仅返回响应有效负载中所需的属性。 此策略有助于减小响应大小，并最大程度地减少客户端上的分析开销。

如果 子句中指定的 $select 属性无效，则服务将跳过该属性并返回剩余的有效属性。

将 作为查询参数追加 $select 到终结点 URL。 使用逗号分隔多个属性：

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 支持的参数。

错误的基 URL

分页问题

  • 原因：更改分页调用之间的参数或忽略 @odata.nextLink。
  • 修复：
    • 使参数在所有页面中保持一致。
    • 始终 POST 到 @odata.nextLink URL。
    • 如果不使用 ResultSize 参数，则 API 默认为每页 1,000 个条目。

路由错误

  • 原因：邮箱范围作的 X-AnchorMailbox 标头缺失或不正确。
  • 修复：
    • 将 X-AnchorMailbox 与邮箱 UPN (首选) 或 SMTP 地址包含在内。
    • 在发送请求之前验证值。

最佳做法

遵循本部分中的准则，确保可靠高效地使用 Exchange Online 管理员 API。

  • 身份验证和安全性：

    • 将仅限应用的身份验证与证书或托管标识一起使用，用于生产工作负荷。
    • 仅请求 (Exchange.ManageV2 或 Exchange.ManageAsAppV2) 所需的权限。
    • 分配最小 RBAC 角色以降低风险。

  • 请求设计：

    • 始终对所有作使用 POST，包括 Get-* cmdlet。
    • 在终结点中仅包含 cmdlet 支持的参数。
    • 对所有作使用 X-AnchorMailbox 。

  • 性能优化：

    • 使用 $select 减小响应有效负载大小。
    • 与大型数据集的分页结合使用 $select 。
    • 使用 ResultSize 参数。 否则，API 默认为每页 1,000 个条目。

  • 复原能力和错误处理：

    • 实现重试逻辑以限制 (HTTP 429) ，并遵循重试后。
    • 记录错误响应中的请求 ID，以便进行故障排除。
    • 在发送请求之前验证参数，以避免 400 个错误的请求。

  • 路由和环境意识：

    • 为组织使用正确的基 URL。
    • 为所有请求包括 X-AnchorMailbox 以避免路由错误。

后续步骤

  • Last updated on