Batch-Abfragen

Die Azure Monitor Log Analytics-API unterstützt die Batchverarbeitung von Abfragen. Batchabfragen erfordern derzeit die Microsoft Entra-Authentifizierung.

Anforderungsformat

Verwenden Sie für die Batchverarbeitung von Abfragen den API-Endpunkt, und fügen Sie ans Ende der URL „$batch“ an: https://api.loganalytics.azure.com/v1/$batch.

Ist keine Methode enthalten, wird bei der Batchverarbeitung standardmäßig die GET-Methode verwendet. Bei GET-Anforderungen ignoriert die API den Textkörperparameter des Anforderungsobjekts.

Die Batchanforderung enthält reguläre Header für andere Vorgänge:

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

Der Text der Anforderung ist ein Array von Objekten, das die folgenden Eigenschaften enthält:

• id
• headers
• body
• Methode
• path
• Arbeitsbereich

Beispiel:

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

Antwortformat

Das Antwortformat ist ein ähnliches Array von Objekten. Jedes Objekt enthält Folgendes:

• Die ID
• Den HTTP-Statuscode der jeweiligen Abfrage
• Den Text der zurückgegebenen Antwort für diese Abfrage

Wurde eine Abfrage nicht erfolgreich ausgeführt, enthält der Antworttext Fehlermeldungen. Die Fehlermeldungen gelten nur für die einzelnen Abfragen im Batch. Der Batch selbst gibt einen Statuscode unabhängig von den Rückgabewerten seiner Mitglieder zurück. Der Batch wurde erfolgreich ausgeführt, wenn er folgende Eigenschaften aufweist:

• Wohlgeformt und ordnungsgemäß formatiert
• Authentifiziert
• Autorisiert. Der Batch wurde erfolgreich ausgeführt, auch wenn die Ergebnisse seiner Mitgliedabfragen teilweise erfolgreich und teilweise fehlerhaft waren.

Beispiel

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

Verhalten und Fehler

Die Reihenfolge der Antworten innerhalb des zurückgegebenen Objekts ist unabhängig von der Reihenfolge in der Anforderung. Sie wird durch die Zeit bestimmt, die für den Abschluss der einzelnen Abfragen benötigt wird. Verwenden Sie IDs, um die Abfrageantwortobjekte den ursprünglichen Anforderungen zuzuordnen. Gehen Sie nicht davon aus, dass die Abfrageantworten in der richtigen Reihenfolge vorliegen.

Eine gesamte Batchanforderung ist nur in den folgenden Fällen nicht erfolgreich:

• Das JSON-Format der äußeren Nutzlast ist ungültig.
• Fehler bei der Authentifizierung: Der Benutzer stellt kein Authentifizierungstoken zur Verfügung, oder das Token ist ungültig.
• Einzelne Anforderungsobjekte im Batch verfügen nicht über erforderliche Eigenschaften, oder es sind doppelte IDs vorhanden.

Unter diesen Bedingungen unterscheidet sich die Form der Antwort vom normalen Container. Die im Batchobjekt enthaltenen Objekte können unabhängig voneinander erfolgreich oder nicht erfolgreich sein. Ein Beispiel finden Sie weiter unten.

Fehlerbeispiele

Im Anschluss finden Sie eine nicht vollständige Liste mit Beispielen für mögliche Fehler und deren Bedeutung.

• 400: Falsch formatierte Anforderung. Das äußere Anforderungsobjekt war kein gültiger JSON-Code.

    {
        "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: Unzulässig. Das bereitgestellte Token hat keinen Zugriff auf die Ressource, auf die Sie zugreifen möchten. Stellen Sie sicher, dass Ihre Tokenanforderung über die richtige Ressource verfügt und Sie Berechtigungen für Ihre Microsoft Entra-Anwendung erteilt haben.

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

• 204 - Not Placed (204: Nicht platziert). Sie haben keine Daten, die von der API im Sicherungsspeicher gepullt werden können. Als 2xx-Code ist dies technisch gesehen eine erfolgreiche Anforderung. In einem Batch ist es jedoch hilfreich, den Fehler zu notieren.

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

• 404: Nicht gefunden. Der Abfragepfad ist nicht vorhanden. Dieser Fehler kann auch in einem Batch auftreten, wenn Sie eine ungültige HTTP-Methode in der einzelnen Anforderung angeben.

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

• 400: Die Ressource kann nicht aufgelöst werden. Die GUID, die den Arbeitsbereich darstellt, ist falsch.

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