Batch-query's

De Azure Monitor Log Analytics-API ondersteunt batchverwerkingsquery's samen. Voor Batch-query's is momenteel Microsoft Entra-verificatie vereist.

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
• hoofdtekst
• methode
• path
• werkruimte

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 wordt geretourneerd, bevat de hoofdtekst van het antwoord foutbericht. 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 geretourneerd als de batch het volgende is:

• Goed opgemaakt en goed opgemaakt
• Geverifieerd
• Geautoriseerd De batch retourneert succesvol, zelfs wanneer de resultaten van de ledenquery's een combinatie van geslaagde 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. Dit wordt bepaald door de tijd die nodig is voor elke afzonderlijke query. 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 nettolading is niet geldig.
• Verificatie mislukt: de gebruiker geeft geen verificatietoken op of het token is ongeldig.
• Afzonderlijke aanvraagobjecten in de batch hebben geen vereiste eigenschappen of er zijn dubbele id's.

Onder deze omstandigheden is de vorm van het antwoord anders dan de normale container. De objecten in het batchobject kunnen elk afzonderlijk mislukken of slagen. Hieronder vindt u een voorbeeld.

Voorbeeldfouten

Deze lijst is een niet-volledige lijst met voorbeelden van mogelijke fouten en hun betekenis.

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