分批发送 Outlook REST 请求（测试版）

适用于：Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

备注

本文档介绍测试版中的批处理 REST 请求。 测试版本中的功能通常会随时更改，恕不另行通知，并可能会破坏使用的代码。 正因为如此，一般而言，生产代码中只应使用生产版本的 API。 如果可用，2.0 版目前是首选版本。

批处理允许您将多个 Outlook REST 请求放入一个 HTTP 批处理请求中，从而减少 HTTP 连接数和开销。 批量请求访问登录用户的数据，由Office 365 中的 Azure Active Directory 或 Microsoft 帐户（Hotmail，Live.com，MSN.com，Outlook.com 或 Passport.com）保护。

备注

为简便起见，本文的其余部分使用 Outlook.com 来指代这些 Microsoft 帐户域。

对 API 的测试版不感兴趣？ 在左侧的目录中，转到 Office 365 REST API 引用部分，然后选择所需的版本。

概述

REST 请求需要客户端和服务器之间的 HTTP 连接，这会产生一定的开销。 通过批量处理，您可以通过将针对相同上下文的多个 REST API 调用合并到 $ batch 端点的单个 HTTP POST 请求中来减少连接开销。

例如，您可以针对 me 类似上下文结合使用 API​​ 调用：

POST https://outlook.office.com/api/beta/me/$batch

一个批量请求可以包含多达20个单独的 REST API 调用，这些调用可以是数据查询（例如 GET）或更改（例如 POST）操作。 您可以指定一个优选头文件，即使在一个或多个 REST 调用失败时也能继续批处理。

批处理在同步大量数据时特别有用。 同一批次的 API 调用可以访问属于同一个邮箱的不同资源，例如消息和事件。

如果您需要超过 20 项调用，或者完成调用的顺序很重要，请使用多个批量请求。

示例

一个最能说明批处理的简单例子。 针对me上下文，以下批量请求将 2 个 Outlook REST API 调用放在一个批处理中：

1. 获取登录用户的所有事件。
2. 发布并发送消息。

批量请求

POST https://outlook.office.com/api/beta/me/$batch HTTP/1.1

Authorization: Bearer aGFwcHlnQGRr==
Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_myBatchId

--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

GET /api/beta/me/events?$select=subject,organizer HTTP/1.1

--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /api/beta/me/sendmail HTTP/1.1
Content-Type: application/json

{
  "Message": {
    "Subject": "Meet for lunch?",
    "Body": {
      "ContentType": "Text",
      "Content": "The new cafeteria is open."
    },
    "ToRecipients": [
      {
        "EmailAddress": {
          "Address": "rufus@contoso.com"
        }
      }
    ]
  }
}

--batch_myBatchId--
 

备注

在上一个在批处理结束时有 POST 操作的示例中，当前在最后一个批处理分隔符 --batch_{batchId}--_后_需要一个新行。 查看关于批量请求正文的更多格式化备注。

批量响应

批处理响应包括单独的响应代码和正文，适用于批处理请求和单个调用。

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Length: 786

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Events(Subject,Organizer)",
    "value":[
        {
            "@odata.id":"https://outlook.office.com/api/beta/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAt9AHkAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALfZeSA==\"",
            "Id":"AAMkAGI1AAAt9AHkAAA=",
            "Subject":"Let's go for lunch",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id":"https://outlook.office.com/api/beta/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAtCq6LAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALQzodA==\"",
            "Id":"AAMkAGI1AAAtCq6LAAA=",
            "Subject":"Prep for customer visit",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        }
    ]
}
--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 202 Accepted

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a--

端点 URL

您可以在 2 个上下文之一的 $ batch 端点执行 POST：

• 对于登录用户 me：

  POST https://outlook.office.com/api/beta/me/$batch HTTP/1.1
  

• 对于特定的用户， 用户 _id 可以是用户 ID 或用户电子邮件地址：

  POST https://outlook.office.com/api/beta/users('{user_id}')/$batch
  

一旦在 $ batch 端点的 POST 请求中建立了上下文关联，则包含在同一批处理请求中的所有 REST API 调用都必须应用于相同的上下文。

重要

• 如果您的批量请求针对的是特定用户，请确保您在整批批处理请求中以一致的方式引用用户。 也就是说，只使用.../users('{user_id}')或 .../users/'{user_id}'而非同时使用两者。
• 使用根 URL 时 https://outlook.office.com，为获得最佳性能，请添加一个 X-AnchorMailbox 标头并将其设置为用户的电子邮件地址。
• 处理尚未为 Outlook REST API 启用的 Outlook.com 用户邮箱的情况；检查错误代码 MailboxNotEnabledForRESTAPI 和 MailboxNotSupportedForRESTAPI。 在这里查看更多信息。

备注

中国开发人员注意事项

• 如果您正在开发_面向中国的 Office 365_ 应用程序，您应该继续使用 Office 365 for China 的 API 端点。
• 如果您正在创建_面向中国的 Outlook.com_ 应用程序，您必须使用 v2 应用程序模型预览，以及以下Outlook REST 端点：

API 版本

此 API 已从预览版本升级到正式发布 (GA) 状态。 Outlook REST API 的 v2.0 和 beta 版本中均予以支持。

您必须在批处理请求中指定与批处理中的REST调用相同的主机和版本。

目标用户

您可以将批量中同一邮箱的 Outlook REST API 调用分组。 邮箱可以为 Office 365 或 Outlook.com。 尝试访问一组批处理请求中的多个邮箱会导致异常。

身份验证

与发送 Outlook REST API 调用作为单个请求相类似，您应该在授权请求标头中包含一个有效的访问令牌。 如果您为批处理请求指定了标头，则访问令牌应为该批处理中的所有调用提供必要的权限。 或者，如果该调用要求不同的访问令牌，则可以为该批次中的特定调用指定访问令牌。

获取访问令牌需要注册和识别应用，并获得相应的授权。 了解更多有关简化注册和授权选项的信息。 在您了解更多有关批处理请求的信息时请记住这一点。

批量请求标头

为每个批量请求包含以下标头：

Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_<batchId> 

标识批次并用于批次内分隔请求的位置。{batchId} 它可以是一个 GUID 或任何区分字符串。

您可以在适当的地方添加其他标头。 除了与内容相关的标头如内容类型，批处理请求中的标头通常适用于批处理中的每个操作。 如果您在批处理请求和批处理中的特定操作中都指定了标头，则后者优先并适用于该操作。

批量请求正文

使用以下标头行开始批处理中的每个操作：

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

使用以下命令结束批处理中的最后一个操作：

--batch_{batchId}--
 

格式化批量请求正文

请注意以下格式要求，否则您的批处理请求可能会失败或不会返回预期的响应：

• 确保在批处理边界定界符之前有一个额外的新行，如以下具有 2 个批处理GET操作的请求正文所示。
• 特别是，如果您在与第一个示例批量请求相似的批处理结尾有 POST 请求时，确保_在_最后一个批处理分隔符 --batch_{batchId}--后有新的一行。

您可以在 批处理（OData版本3.0）中查看更多批处理请求正文的示例。

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/messages    HTTP/1.1

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/events    HTTP/1.1

--batch_{batchId}--
 

批量操作

您可以在一个批量请求中最多指定 20 个操作。

批处理操作可以是数据查询、修改、操作或函数调用请求。 虽然您不必重复完整URL并在批处理中为每个操作声明所有标头，但确保在操作需要时包含特定标头和请求正文。

批处理中支持的请求格式

如上所述，主机、版本和上下文在整个批处理请求中必须保持一致。 包含在同一批处理中的请求可以是以下三种格式中的任何一种格式的组合。 在下面的示例中，假设对 $ batch 端点的 POST 请求如下所示：

POST https://outlook.office.com/api/beta/me/$batch HTTP/1.1

绝对 URL

在 URL 中包含主机、版本和上下文。 例如：

GET https://outlook.office.com/api/beta/me/messages?$select=subject,sender HTTP/1.1 

相对于主机的 URL

包含一个与批处理请求中指定的主机相对 URL。 虽然您不会在每个批处理请求中重复主机，但您确有包含版本和上下文。 例如：

GET /api/beta/me/messages?$select=subject,sender HTTP/1.1

批处理相对网址

在此格式中，您不会在批处理请求中重复主机、版本和上下文。 例如：

GET messages?$select=subject,sender HTTP/1.1

例如：

批处理请求作为一个请求自行处理并返回其自有的响应代码。 具有正确标头且格式良好的批处理请求将返回 HTTP 200 OK。 但这并不意味着批处理中的所有请求都是成功的。

批处理请求正文中的每个请求都会单独处理，并返回其自有的响应代码以及任何响应正文和错误消息。

服务器可以按任何顺序在批处理中执行操作。 如果您必须按特定顺序执行操作，则不应将它们置于同一批处理请求中。 而是自行发送一个操作，并在发送下一个操作之前等待响应。

默认情况下，在返回错误的第一个操作后停止处理。 您可以指定以下标头以使处理忽略错误并继续批处理中的下一个操作：

Prefer: odata.continue-on-error

后续步骤

无论你准备开始构建应用还是只想了解更多信息，我们都已为你考虑周全。

• 开始使用邮件、日历和联系人 REST API。
• 想要查看一些示例吗？ 我们就有。

或者，了解有关使用 Office 365 平台的更多信息：

• Outlook 开发人员中心的 Outlook REST API
• Office 365 平台开发概述
• Office 365 应用验证和资源授权
• 将应用手动注册到 Azure AD，以便访问 Office 365 API
• 邮件 REST API 参考
• 日历 REST API 参考
• 联系人 REST API 参考
• 任务 REST API（预览）
• 邮件、日历、联系人和任务 REST API 的资源参考
• Office 365 数据扩展 REST API 参考
• 人员 API 参考 （预览）
• 通知 REST API 参考
• 用户照片 REST API 参考