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

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
• заголовки
• текст
• метод
• path
• Рабочая область

Пример:

    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"
                    }
                }
            }
        ]
    }