Consultas de lote

Artigo
10/18/2023

A API do Azure Monitor Log Analytics dá suporte a consultas em lote. Atualmente, as consultas em lote exigem autenticação do Microsoft Entra.

Formato do pedido

Para consultas em lote, use o ponto de extremidade da API, adicionando $batch no final da URL: https://api.loganalytics.azure.com/v1/$batch.

Se nenhum método for incluído, o padrão de envio em lote será o método GET. Em solicitações GET, a API ignora o parâmetro body do objeto de solicitação.

A solicitação de lote inclui cabeçalhos regulares para outras operações:

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

O corpo da solicitação é uma matriz de objetos que contém as seguintes propriedades:

ID
cabeçalhos
corpo
método
path
área de trabalho

Exemplo:

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

Formato da resposta

O formato de resposta é uma matriz semelhante de objetos. Cada objeto contém:

O ID
O código de status HTTP da consulta específica
O corpo da resposta retornada para essa consulta.

Se uma consulta não retornar com êxito, o corpo da resposta conterá mensagens de erro. As mensagens de erro só se aplicam às consultas individuais no lote; O lote em si retorna um código de status independente dos valores de retorno de seus membros. O lote retorna com êxito se o lote for:

Bem formado e devidamente formatado
Autenticado
Autorizado O lote retorna com êxito mesmo quando os resultados de suas consultas de membros podem ser uma mistura de sucessos e falhas.

Exemplo

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

Comportamento e erros

A ordem das respostas dentro do objeto retornado não está relacionada à ordem na solicitação. Ele é determinado pelo tempo que cada consulta individual leva para ser concluída. Use IDs para mapear os objetos de resposta de consulta para as solicitações originais. Não assuma que as respostas da consulta estão em ordem.

Uma solicitação de lote inteiro só falhará se:

O formato JSON da carga externa não é válido.
Falha na autenticação: o usuário não fornece um token de autenticação ou o token é inválido.
Os objetos de solicitação individuais no lote não têm propriedades necessárias ou há IDs duplicados.

Nestas condições, a forma da resposta será diferente do recipiente normal. Os objetos contidos no objeto em lote podem falhar ou ter êxito independentemente. Veja um exemplo abaixo.

Erros de exemplo

Esta lista é uma lista não exaustiva de exemplos de possíveis erros e seus significados.

400 - Pedido indeferido. O objeto de solicitação externa não era JSON válido.

    {
        "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 - Proibido. O token fornecido não tem acesso ao recurso que você está tentando acessar. Verifique se sua solicitação de token tem o recurso correto e se você concedeu permissões para seu aplicativo 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 - Não colocado. Você não tem dados para a API puxar no armazenamento de backup. Como um 2xx este é tecnicamente um pedido bem-sucedido. No entanto, em um lote, é útil observar o erro.

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

404 - Não encontrado. O caminho da consulta não existe. Esse erro também pode ocorrer em um lote se você especificar um método HTTP inválido na solicitação individual.

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

400 - Falha ao resolver recurso. O GUID que representa o espaço de trabalho está incorreto.

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

Partilhar via