批处理查询

项目
12/18/2024

Azure Monitor Log Analytics API 支持将查询一起进行批处理。批处理查询目前需要 Microsoft Entra 身份验证。

请求格式

若要批处理查询，请使用 API 终结点，并在 URL 的末尾添加 $batch：https://api.loganalytics.azure.cn/v1/$batch。

如果不包含任何方法，则批处理默认将使用 GET 方法。在 GET 请求中，API 会忽略请求对象的正文参数。

批处理请求包括其他操作的常规标头：

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

请求的正文是包含以下属性的对象数组：

id
headers
body
method
path
workspace

示例：

POST https://api.loganalytics.azure.cn/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"
        }
    ]
}

响应格式

响应格式是类似的对象数组。每个对象包含：

ID
特定查询的 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
                            ]
                        ]
                    }
                ]
            }
        }
    ]
}

行为和错误

返回对象内部的响应顺序与请求中的顺序无关。该响应顺序由完成每个查询所需的时间决定。使用 ID 可将查询响应对象映射到原始请求。不要假设查询响应是有序的。

仅当在以下情况下，整个批处理请求才会失败：

外部有效负载的 JSON 格式无效。
身份验证失败：用户未提供身份验证令牌，或令牌无效。
批处理中的单个请求对象没有必需的属性，或存在重复 ID。

在这些情况下，响应的形状将与普通容器不同。批处理对象中包含的对象可能各自独立地失败或成功，请参阅以下示例错误。

示例错误

此列表是可能的错误示例及其含义的非详尽列表。

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

通过

批处理查询

请求格式

响应格式

行为和错误

示例错误

其他资源