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

API Log Analytics в Azure Monitor поддерживает объединение запросов в пакеты. Пакетные запросы в настоящее время требуют проверки подлинности Microsoft Entra.

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

Для пакетных запросов используйте конечную точку API, добавив $batch в конце URL-адреса: https://api.loganalytics.azure.com/v1/$batch.

Если метод не указан, пакетная обработка по умолчанию применяется к методу GET. В запросах GET API игнорирует параметр body объекта request.

Пакетный запрос содержит обычные заголовки для других операций:

Content-Type: application/json
Authorization: Bearer <user token>

Тело запроса — это массив объектов, содержащий следующие свойства:

• id
• headers
• body
• method
• path
• workspace

Пример:

POST https://api.loganalytics.azure.com/v1/$batch
Content-Type: application/json
Authorization: Bearer <user token>
Cache-Control: no-cache
{
    "requests": 
    [
        {
            "id": "1",
            "headers": {
                "Content-Type": "application/json"
            },
            "body": {
                "query": "AzureActivity | summarize count()",
                "timespan": "PT1H"
            },
            "method": "POST",
            "path": "/query",
            "workspace": "workspace-1"
        },
        {
            "id": "2",
            "headers": {
                "Content-Type": "application/json"
            },
            "body": {
                "query": "ApplicationInsights | limit 10",
                "timespan": "PT1H"
            },
            "method": "POST",
            "path": "/fakePath",
            "workspace": "workspace-2"
        }
    ]
}

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

Формат ответа представляет собой аналогичный массив объектов. Каждый объект содержит следующие элементы:

• Идентификатор
• Код состояния HTTP конкретного запроса.
• Текст ответа, возвращаемого для этого запроса.

Если запрос не возвращается, текст ответа содержит сообщения об ошибках. Сообщения об ошибках относятся только к отдельным запросам в пакете; сам пакет возвращает код состояния, не зависящий от значений, возвращаемых его элементами. Пакетная обработка выполняется успешно, если пакет:

• Задан в правильной форме и формате
• Проверка подлинности выполнена
• Авторизован

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

Пример:

{
    "responses":
    [
        {
            "id": "2",
            "status": 404,
            "body": {
                "error": {
                    "message": "The requested path does not exist",
                    "code": "PathNotFoundError"
                }
            }
        },
        {
            "id": "1",
            "status": 200,
            "body": {
                "tables": [
                    {
                        "name": "PrimaryResult",
                        "columns": [
                            {
                                "name": "Count",
                                "type": "long"
                            }
                        ],
                        "rows": [
                            [
                                7240
                            ]
                        ]
                    }
                ]
            }
        }
    ]
}

Поведение и ошибки

Порядок ответов в возвращенном объекте не связан с порядком элементов в запросе. Время, затраченное на выполнение каждого отдельного запроса. Для сопоставления объектов ответов с исходными запросами используются идентификаторы. Не следует рассчитывать, что ответы будут следовать в том же порядке, что и запросы.

Весь пакетный запрос завершается ошибкой только в следующих случаях:

• Формат JSON внешних полезных данных недопустим.
• Проверка подлинности завершилась сбоем: пользователь не предоставил маркер проверки подлинности или этот маркер недействителен.
• Отдельные объекты запроса в пакете не имеют необходимых свойств или имеют повторяющиеся идентификаторы.

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

Примеры ошибок

Этот список представляет собой неисчерпаемый список примеров возможных ошибок и их значений.

• 400 — неправильно оформленный запрос. Внешний объект запроса не был допустимым JSON.

  {
      "error": {
          "message": "The request had some invalid properties",
          "code": "BadArgumentError",
          "innererror": {
              "code": "QueryValidationError",
              "message": "Failed parsing the query",
              "details": [
                  {
                      "code": "InvalidJsonBody",
                      "message": "Unexpected end of JSON input",
                      "target": null
                  }
              ]
          }
      }
  }
  

• 403 — запрет. Предоставленный маркер не имеет доступа к ресурсу, к который вы пытаетесь получить доступ. Убедитесь, что ваш запрос токена имеет правильный ресурс, и вы предоставили разрешения для приложения Microsoft Entra.

  {
      "error": {
          "message": "The provided authentication is not valid for this resource",
          "code": "InvalidTokenError",
          "innererror": {
              "code": "SignatureVerificationFailed",
              "message": "Could not validate the request"
          }
      }
  }
  

• 204 — не размещено. У вас нет данных, которые вызов API должен разместить в резервном хранилище. Как ошибка 2xx, это технически успешный запрос. Однако в рамках пакета такие ответы следует обрабатывать как ошибки.

  {
      "responses": [
          {
              "id": "2",
              "status": 204,
              "body": {
                  "error": {
                      "code": "WorkspaceNotPlacedError"
                  }
              }
          }
      ]
  }
  

• 404 — не найдено. Путь запроса не существует. Эта ошибка также может возникать в пакете, если в отдельном запросе указан недопустимый метод HTTP.

  {
      "responses": [
          {
              "id": "1",
              "status": 404,
              "body": {
                  "error": {
                      "message": "The requested path does not exist",
                      "code": "PathNotFoundError"
                  }
              }
          }
      ]
  }
  

• 400 — не удается разрешить ресурс Неверное значение GUID, представляющее рабочую область.

  {
      "responses": [
          {
              "id": "1",
              "status": 400,
              "body": {
                  "error": {
                      "code": "FailedToResolveResource",
                      "message": "Resource identity could not be resovled"
                  }
              }
          }
      ]
  }