Объединение нескольких запросов в один вызов HTTP с помощью пакетной обработки JSON

Статья
03/26/2023

Пакетная обработка JSON позволяет оптимизировать приложение путем объединения нескольких запросов (до 20) в один объект JSON. Например, клиенту может потребоваться создать представление несвязанных данных, например:

Изображение, хранящееся в OneDrive
Список задач Планировщика
Календарь группы

Объединение трех этих запросов в один может значительно снизить задержку в сети, ускорив работу приложения.

Microsoft Graph реализует сегмент пути URL-адреса OData $batch для поддержки пакетной обработки JSON.

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

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

POST https://graph.microsoft.com/v1.0/$batch
Accept: application/json
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "/me/drive/root:/{file}:/content"
    },
    {
      "id": "2",
      "method": "GET",
      "url": "/me/planner/tasks"
    },
    {
      "id": "3",
      "method": "GET",
      "url": "/groups/{id}/events"
    },
    {
      "id": "4",
      "url": "/me",
      "method": "PATCH",
      "body": {
        "city" : "Redmond"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "id": "5",
      "url": "users?$select=id,displayName,userPrincipalName&$filter=city eq null&$count=true",
      "method": "GET",
      "headers": {
        "ConsistencyLevel": "eventual"
      }
    }
  ]
}

Ответы на пакетные запросы могут отображаться в другом порядке. Свойство id можно использовать для корреляции отдельных запросов и ответов.

200 OK
Content-Type: application/json

{
  "responses": [
    {
      "id": "1",
      "status": 302,
      "headers": {
        "location": "https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi"
      }
    },
    {
      "id": "3",
      "status": 401,
      "body": {
        "error": {
          "code": "Forbidden",
          "message": "..."
        }
      }
    },
    {
      "id": "5",
      "status": 200,
      "headers": {
        "OData-Version": "4.0",
      },
      "body": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,userPrincipalName)",
        "@odata.count": 12,
        "value": [
          {
            "id": "071cc716-8147-4397-a5ba-b2105951cc0b",
            "displayName": "Adele Vance",
            "userPrincipalName": "AdeleV@Contoso.com"
          }
        ]
      }
    },
    {
      "id": "2",
      "status": 200,
      "body": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.plannerTask)",
        "value": []
      }
    },
    {
      "id": "4",
      "status": 204,
      "body": null
    }
  ]
}

Формат запроса

Пакетные запросы всегда отправляются с помощью метода POST в конечную точку /$batch.

Текст пакетного запроса JSON состоит из одного объекта JSON с одним обязательным свойством: requests. Свойство requests представляет собой коллекцию отдельных запросов. Для каждого отдельного запроса можно передать следующие свойства.

Свойство	Описание
id	Обязательно. Значение корреляции для связывания отдельных ответов с запросами. Это значение позволяет серверу обрабатывать запросы в пакете в наиболее эффективном порядке.
метод	Обязательный аргумент. Метод HTTP.
url	Обязательный аргумент. Относительный URL-адрес ресурса, на который обычно отправляется отдельный запрос. Таким образом, если абсолютный URL-адрес выглядит так: `https://graph.microsoft.com/v1.0/users`, то этот URL-адрес выглядит так: `/users`.
заголовки	Не является обязательным, но требуется, когда указан элементbody. Объект JSON с парой ключей и значений для заголовков. Например, если требуется заголовок ConsistencyLevel, это свойство будет представлено как `"headers": {"ConsistencyLevel": "eventual"}`. Если предоставлен элемент body, должен быть включен заголовок Content-Type.
body	Необязательно. Может быть объектом JSON или значением в кодировке URL Base64 (например, если элемент body является изображением). Когда элемент body включен в запрос, объект headers должен содержать значение для свойства Content-Type.

Формат ответа

Формат ответа для пакетных запросов JSON аналогичен формату запроса. Ниже перечислены основные различия.

Свойство в основном объекте JSON называется responses, а не requests.
Порядок отображения ответов и запросов может отличаться.
Вместо метода и URL-адреса отдельные ответы имеют свойство status . Значение состояния — это число, представляющее код состояния HTTP.
Свойство заголовков в каждом отдельном ответе представляет заголовки, возвращаемые сервером, например заголовки Cache-Control и Content-Type.

Пакетный ответ обычно содержит код состояния 200 или 400. Если пакетный запрос имеет неправильный формат, код состояния — 400. Если пакетный запрос пригоден для анализа, код состояния — 200. Код состояния 200 пакетного ответа не указывает на успешное выполнение отдельных запросов в пакете. Вот почему каждый отдельный ответ в свойстве responses имеет код состояния.

Выстраивание последовательности запросов с помощью свойства dependsOn

Отдельные запросы можно выполнять в указанном порядке с помощью свойства dependsOn . Это свойство представляет собой массив строк, ссылающийся на идентификатор другого отдельного запроса. По этой причине значения идентификатора должны быть уникальными. Например, в следующем запросе клиент указывает, что запросы должны выполняться в запросе порядка 1, затем запросе 2, затем запросе 4, а затем запросе 3.

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "..."
    },
    {
      "id": "2",
      "dependsOn": [ "1" ],
      "method": "GET",
      "url": "..."
    },
    {
      "id": "4",
      "dependsOn": [ "2" ],
      "method": "GET",
      "url": "..."
    },
    {
      "id": "3",
      "dependsOn": [ "4" ],
      "method": "GET",
      "url": "..."
    }
  ]
}

Если отдельный запрос не будет выполнен, то любой зависящий от него запрос также не будет выполнен с кодом состояния 424 (ошибка зависимости).

Совет

Пакет должен быть полностью последовательным или полностью параллельным.

Обход ограничения на длину URL-адреса с помощью пакетной обработки

Дополнительным вариантом использования пакетной обработки JSON является обход ограничений по длине URL-адресов. В случаях, когда предложение фильтра является сложным, длина URL-адреса может превышать ограничения, встроенные в браузеры или другие HTTP-клиенты. Пакетную обработку JSON можно использовать в качестве обходного решения для выполнения этих запросов, так как длинный URL-адрес просто становится частью полезных данных запроса.

Ограничения размера пакетов

Пакетные запросы JSON в настоящее время ограничены 20 отдельными запросами в дополнение к следующим ограничениям:

В зависимости от интерфейсов API, входящих в состав пакетного запроса, базовые службы налагают собственные ограничения регулирования, влияющие на приложения, которые используют Microsoft Graph для доступа к ним.
Запросы в пакете проверяются по отдельности на предмет ограничений регулирования. Если какой-либо запрос превышает ограничения, для него выдается ошибка с состоянием 429.

Дополнительные сведения см в статье Регулирование и пакетная обработка.

Известные проблемы

Список текущих ограничений, связанных с пакетной обработкой, см. в разделе Известные проблемы.

См. также

Дополнительные сведения о формате пакетных запросов и ответов JSON см. в спецификации формата JSON OData версии 4.01, раздел Пакетные запросы и ответы.