Invio di query in batch

L'API Log Analytics di Monitoraggio di Azure supporta l'invio in batch di query. Le query batch richiedono attualmente l'autenticazione Di Microsoft Entra.

Formato richiesta

Per eseguire query in batch, usare l'endpoint API, aggiungendo $batch alla fine dell'URL: https://api.loganalytics.azure.com/v1/$batch.

Se non è incluso alcun metodo, l'invio in batch viene impostato per impostazione predefinita sul metodo GET. Nelle richieste GET l'API ignora il parametro body dell'oggetto richiesta.

La richiesta batch include intestazioni regolari per altre operazioni:

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

Il corpo della richiesta è una matrice di oggetti contenente le proprietà seguenti:

• ID
• intestazioni
• corpo
• method
• path
• area di lavoro

Esempio:

    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 risposta

Il formato della risposta è una matrice simile di oggetti. Ogni oggetto contiene:

• The ID
• Codice di stato HTTP della query specifica
• Corpo della risposta restituita per la query.

Se una query non restituisce correttamente, il corpo della risposta contiene messaggi di errore. I messaggi di errore si applicano solo alle singole query nel batch; il batch stesso restituisce un codice di stato indipendentemente dai valori restituiti dei relativi membri. Il batch restituisce correttamente se il batch è:

• Ben formato e formattato correttamente
• Autenticato
• Autorizzato Il batch restituisce correttamente anche quando i risultati delle query membro possono essere una combinazione di operazioni riuscite ed errori.

Esempio

    {
        "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 ed errori

L'ordine delle risposte all'interno dell'oggetto restituito non è correlato all'ordine nella richiesta. È determinato dal tempo necessario per completare ogni singola query. Usare gli ID per eseguire il mapping degli oggetti di risposta della query alle richieste originali. Non presupporre che le risposte alle query siano in ordine.

Un'intera richiesta batch ha esito negativo solo se:

• Il formato JSON del payload esterno non è valido.
• Autenticazione non riuscita: l'utente non fornisce un token di autenticazione o il token non è valido.
• I singoli oggetti richiesta nel batch non hanno proprietà necessarie o sono presenti ID duplicati.

In queste condizioni, la forma della risposta sarà diversa dal contenitore normale. Gli oggetti contenuti nell'oggetto batch possono avere esito negativo o esito positivo in modo indipendente. Per un esempio, vedere di seguito.

Esempi di errori

Questo elenco è un elenco non esaustivo di esempi di possibili errori e dei relativi significati.

• 400 - Richiesta non valida. L'oggetto richiesta esterna non è valido 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 - Accesso negato. Il token fornito non ha accesso alla risorsa a cui si sta tentando di accedere. Assicurarsi che la richiesta di token abbia la risorsa corretta e che siano state concesse le autorizzazioni per l'applicazione 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 - Non posizionato. Non sono disponibili dati per l'API di cui eseguire il pull nell'archivio di backup. Come 2xx questa è tecnicamente una richiesta riuscita. Tuttavia, in un batch, è utile notare l'errore.

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

• 404 - Non trovato. Il percorso della query non esiste. Questo errore può verificarsi anche in un batch se si specifica un metodo HTTP non valido nella singola richiesta.

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

• 400 - Impossibile risolvere la risorsa. IL GUID che rappresenta l'area di lavoro non è corretto.

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