Batchquery's

De Azure Monitor Log Analytics-API ondersteunt het samenvoegen van queries in batches. Voor Batch-query's is momenteel Microsoft Entra-verificatie vereist.

Opmerking

De batch API is afgeschaft. Voor meer informatie, zie Migrate from using batch and beta query APIs.

Aanvraagindeling

Als u query's wilt batcheren, gebruikt u het API-eindpunt en voegt u $batch toe aan het einde van de URL: https://api.loganalytics.azure.com/v1/$batch.

Als er geen methode is opgenomen, wordt batchverwerking standaard ingesteld op de GET-methode. Bij GET-aanvragen negeert de API de hoofdtekstparameter van het aanvraagobject.

De batchaanvraag bevat reguliere headers voor andere bewerkingen:

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

De hoofdtekst van de aanvraag is een matrix met objecten met de volgende eigenschappen:

• id
• headers
• body
• method
• path
• workspace

Voorbeeld:

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

Antwoordindeling

De antwoordindeling is een vergelijkbare matrix met objecten. Elk object bevat:

• De ID
• De HTTP-statuscode van de specifieke query
• De hoofdtekst van het geretourneerde antwoord voor die query.

Als een query niet succesvol is, bevat de hoofdtekst van het antwoord foutberichten. De foutberichten zijn alleen van toepassing op de afzonderlijke query's in de batch; de batch zelf retourneert een statuscode onafhankelijk van de retourwaarden van de leden. De batch wordt succesvol geretourneerd als de batch aan het volgende voldoet:

• Goed gevormd en correct opgemaakt
• Geverifieerd
• Bevoegd

De batch retourneert met succes, zelfs als de resultaten van de query's van de leden een mix van succesvolle en mislukte resultaten kunnen zijn.

Voorbeeld:

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

Gedrag en fouten

De volgorde van antwoorden in het geretourneerde object is niet gerelateerd aan de volgorde in de aanvraag. De tijd die nodig is, bepaalt elke afzonderlijke query om te voltooien. Gebruik id's om de queryantwoordobjecten toe te wijzen aan de oorspronkelijke aanvragen. Stel niet dat de queryantwoorden in volgorde zijn.

Een volledige batchaanvraag mislukt alleen als:

• De JSON-indeling van de buitenste gegevensset is niet geldig.
• Verificatie mislukt: de gebruiker geeft geen verificatietoken op of het token is ongeldig.
• Afzonderlijke aanvraagobjecten in de batch hebben niet de vereiste eigenschappen of er zijn dubbele id's.

Onder deze omstandigheden verschilt de vorm van het antwoord van de normale container. De objecten in het batchobject kunnen elk afzonderlijk mislukken of slagen. Zie de volgende voorbeeldfouten.

Voorbeeldfouten

Deze lijst is een niet-uitputtende lijst met voorbeelden van mogelijke fouten en hun betekenissen.

• 400 - Onjuiste aanvraag. Het buitenste aanvraagobject was geen geldige 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 - Verboden. Het opgegeven token heeft geen toegang tot de resource die u probeert te openen. Zorg ervoor dat uw tokenaanvraag de juiste resource heeft en dat u machtigingen hebt verleend voor uw Microsoft Entra-toepassing.

  {
      "error": {
          "message": "The provided authentication is not valid for this resource",
          "code": "InvalidTokenError",
          "innererror": {
              "code": "SignatureVerificationFailed",
              "message": "Could not validate the request"
          }
      }
  }
  

• 204 - Niet geplaatst. U hebt geen gegevens voor de API om de back-upopslag op te halen. Als 2xx-fout is dit technisch een geslaagde aanvraag. In een batch is het echter handig om de fout op te merken.

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

• 404 - Niet gevonden. Het querypad bestaat niet. Deze fout kan ook optreden in een batch als u een ongeldige HTTP-methode opgeeft in de afzonderlijke aanvraag.

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

• 400 - Kan de resource niet oplossen. De GUID die de werkruimte vertegenwoordigt, is onjuist.

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