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
• path
• 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 sucesso ainda que os resultados de suas consultas de membros sejam uma combinação 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. O tempo necessário determina a conclusão de cada consulta individual. 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.
• Os objetos de solicitação individuais no lote estão sem as propriedades necessárias ou contêm IDs duplicadas.

Nessas condições, a forma da resposta será diferente do contêiner normal. Os objetos contidos dentro do objeto de lote podem falhar ou ser processados com sucesso individualmente. Veja os exemplos de erros a seguir.

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. Verifique se sua solicitação de token possui o recurso correto e se você concedeu as permissões necessárias 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 erro 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"
                  }
              }
          }
      ]
  }