Consultas em lote

A API do Log Analytics do Azure Monitor oferece suporte ao envio em lote das consultas. Atualmente, as consultas em lote exigem a autenticação do Microsoft Entra.

Formato de solicitação

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

Se nenhum método for incluído, o envio em lote seguirá o método GET. Nas solicitações GET, a API ignora o parâmetro corpo do objeto da solicitação.

A solicitação em lote inclui os cabeçalhos regulares das demais 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
• headers
• body
• method
• caminho
• workspace

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 de objetos similar. Cada objeto contém:

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

Se uma consulta não for retornada com êxito, o corpo da resposta conterá mensagens de erro. As mensagens de erro se aplicam somente à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 retornará com êxito se o lote for:

• Bem formado e formatado corretamente
• Autenticada
• Autorizado O lote retorna com êxito ainda que os resultados de suas consultas de membros sejam uma combinação de êxitos 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. Ela é determinada pelo tempo que cada consulta individual leva para ser concluída. Use IDs para mapear os objetos de resposta da consulta às solicitações originais. Não suponha que as respostas das consultas estejam em ordem.

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

• O formato JSON do payload externo não for válido.
• Falha na autenticação: o usuário não forneceu um token de autenticação ou o token é inválido.
• Alguns objetos de solicitação individuais do lote não têm as propriedades necessárias ou há IDs duplicadas.

Nessas condições, a forma da resposta será diferente do contêiner normal. Os objetos contidos no objeto de lote podem falhar ou ter êxito de maneira independente. Veja um exemplo abaixo.

Erros de exemplo

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

• 400 - Solicitação malformada. O objeto de solicitação externa não era um 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. Certifique-se de que sua solicitação de token tem o recurso correto e de que você concedeu permissões ao seu aplicativo do 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 que a API faça pull no repositório de backup. Assim como um 2xx, essa é tecnicamente uma solicitação bem-sucedida. No entanto, em um lote, convém 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 - Não é possível resolver o recurso. O GUID que representa o workspace está incorreto.

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