Отправка запросов Outlook REST в пакетах (версия 2.0)

  • Статья

Область применения: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Пакетная обработка позволяет размещать несколько запросов Outlook REST в одном пакетном HTTP-запросе, уменьшая количество HTTP-соединений и накладные расходы. Запросы в пакете получают доступ к данным вошедшего пользователя под защитой Azure Active Directory в Office 365 или в учетной записи Microsoft (Hotmail.com, Live.com, MSN.com, Outlook.com или Passport.com).

Примечание

Для упрощения этой справки в остальной части этой статьи при упоминании Outlook.com также подразумеваются и эти домены учетной записи Майкрософт.

Не интересуетесь API версии 2.0? В оглавлении слева перейдите к разделу Справка по API Office 365 и выберите нужную версию.

Обзор

Для запроса REST требуется HTTP-соединение между клиентом и сервером, которое несет определенное количество накладных расходов. Пакетирование позволяет сократить расходы на соединение, объединив несколько вызовов API REST для одного и того же контекста в один HTTP-запрос ОПУБЛИКОВАТЬ для конечной точки $пакета.

Например, вы можете комбинировать вызовы API для контекста me следующим образом:

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

Пакетный запрос может включать до 20 отдельных вызовов API REST, которые могут представлять собой запрос данных (например, ПОЛУЧИТЬ) или операцию изменения (например, ОПУБЛИКОВАТЬ). Вы можете указать заголовок Предпочесть, чтобы пакет продолжался, даже если один или несколько вызовов REST завершились с ошибкой.

Пакетирование особенно полезно для синхронизации больших объемов данных. API-вызовы в одном пакете могут обращаться к различным ресурсам, таким как сообщения и события, которые принадлежат одному и тому же почтовому ящику.

Если вам нужно сделать более 20 вызовов, или если имеет значение порядок выполнения вызовов, используйте несколько пакетных запросов.

Пример

Простой пример лучше всего иллюстрирует пакетирование. Следующий пакетный запрос создает два вызова API Outlook REST в одном пакете для контекста me:

  1. Получить (GET) все события вошедшего пользователя.
  2. Опубликовать (POST) и отправить сообщение.

Пакетный запрос

POST https://outlook.office.com/api/v2.0/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/v2.0/me/events?$select=subject,organizer HTTP/1.1

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

POST /api/v2.0/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/v2.0/$metadata#Me/Events(Subject,Organizer)",
    "value":[
        {
            "@odata.id":"https://outlook.office.com/api/v2.0/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/v2.0/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 конечной точки

Вы можете сделать запрос ОПУБЛИКОВАТЬ конечной точке $пакета для одного из двух контекстов:

  • Для вошедшего пользователя me:

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

  • Для конкретного пользователя, где идентификатор_пользователя может быть идентификатором пользователя или адресом пользователя:

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

После того, как вы установили контекст в запросе ОПУБЛИКОВАТЬ для конечной точки $пакета, все вызовы API REST, включенные в один пакетный запрос, должны применяться к одному контексту.

Важно!

  • Если ваш пакетный запрос предназначен для определенного пользователя, убедитесь, что вы последовательно ссылаетесь на пользователя во всем наборе пакетных запросов. То есть, используйте только .../users('{user_id}') или .../users/'{user_id}', но не оба.
  • При использовании корневого URL-адреса https://outlook.office.com для обеспечения оптимальной производительности добавьте заголовок х-AnchorMailbox и установите его на адрес электронной почты пользователя
  • Кроме того, обработайте случай, когда почтовый ящик пользователя на Outlook.com еще не включен для API REST Outlook. Проверьте на наличие кодов ошибок MailboxNotEnabledForRESTAPI и MailboxNotSupportedForRESTAPI. Подробнее – здесь.

Примечание

Примечания для разработчиков в Китае

Версия API

Пакетирование было продвинуто с предварительного просмотра до статуса Общей доступности (General Availability или GA). Оно поддерживается в версиях v2.0 и бета-версиях API REST Outlook.

Вы должны указать тот же хост и версию в пакетном запросе, что и в REST-вызовах в пакете.

Целевой пользователь

Вы можете группировать вызовы API REST Outlook для одного и того же почтового ящика в пакете. Почтовый ящик может находиться в Office 365 или Outlook.com. Попытка доступа к нескольким почтовым ящикам в наборе пакетных запросов приводит к исключению.

Проверка подлинности

Подобно отправке вызовов Outlook API RESTкак индивидуальных запросов, вы должны включить действительный маркер доступа в заголовке запроса Авторизация. Если вы укажете этот заголовок для пакетного запроса, то маркер доступа должен предоставить необходимое разрешение для всех вызовов этого пакета. При необходимости вы можете указать маркер доступа для определенного вызова в пакете, если для этого вызова требуется другой маркер доступа.

Получение маркера доступа требует, чтобы вы зарегистрировались и идентифицировали свое приложение и получили соответствующее разрешение. Узнайте больше о некоторых упрощенных параметрах регистрации и авторизации. Помните об этом, когда вы узнаете больше о запросах пакетной обработки.

Заголовки пакетных запросов

Включите следующие заголовки для каждого пакетного запроса:

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 обработанные операции ПОЛУЧИТЬ.
  • В частности, если у вас есть запрос ОПУБЛИКОВАТЬ в конце партии, аналогичный пакетному запросу первого примера, убедитесь, что после самый последний разделителя партии --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-адреса полностью и указывать все заголовки для каждой операции в пакете, обязательно включите определенные заголовки и текст запроса, если они необходимы для операции.

Поддерживаемые форматы запросов в пакете

Как упоминалось выше, хост, версия и контекст должны оставаться согласованными в наборе пакетных запросов. Запросы, включенные в один пакет, могут содержать один или несколько из следующих трех форматов. В приведенных ниже примерах предположим, что запрос ОПУБЛИКОВАТЬ для конечной точки $пакета выглядит следующим образом:

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

Абсолютный URL-адрес

Включите хост, версию и контекст в URL. Примеры:

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

URL-адрес относительно хоста

Включите URL-адрес относительно хоста, указанного в пакетном запросе. Повторять хост в каждом пакетном запросе не требуется, но нужно включать версию и контекст. Примеры:

GET /api/v2.0/me/messages?$select=subject,sender HTTP/1.1

URL-адрес относительно пакета

В этом формате вам не нужно повторять хост, версию и контекст в пакетном запросе. Примеры:

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

Обработка пакетного запроса

Пакетный запрос обрабатывается как один отдельный запрос и возвращает свой собственный код ответа. Хорошо сформированный пакетный запрос с правильными заголовками дает ответ HTTP 200 OK. Это, однако, не означает, что все запросы в пакете были успешными.

Каждый запрос в тексте пакетного запроса обрабатывается отдельно и возвращает свой собственный код ответа, а также текст ответа и сообщение об ошибке.

Сервер может выполнять операции в пакете в любом порядке. Если вам требуется, чтобы операции выполнялись в определенном порядке, – не помещайте их в один пакетный запрос. Вместо этого отправляйте каждую операцию по отдельности, дожидаясь ответа перед отправкой следующей.

По умолчанию обработка останавливается при первой операции, возвратившей ошибку. Вы можете указать следующий заголовок, чтобы обработка проигнорировала ошибку и запустила следующую операцию в пакете:

Prefer: odata.continue-on-error

Дальнейшие действия

Независимо от того, готовы ли вы приступить к созданию приложения или хотите изучить больше материалов, у нас есть все необходимое.

Или узнайте больше об использовании платформы Office 365 здесь: