Traitement par lot des requêtes

L’API Log Analytics d’Azure Monitor prend en charge le traitement par lot des requêtes. Les requêtes Batch nécessitent actuellement l’authentification Microsoft Entra.

Format de la demande

Pour traiter les requêtes par lots, utilisez le point de terminaison d’API, en ajoutant $batch à la fin de l’URL : https://api.loganalytics.azure.com/v1/$batch

Si aucune méthode n’est incluse, le traitement par lot par défaut est la méthode GET. Sur les demandes GET, l’API ignore le paramètre de corps de l’objet de demande.

La demande de lots inclut des en-têtes normaux pour d’autres opérations :

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

Le corps de la demande est un tableau d’objets contenant les propriétés suivantes :

• id
• headers
• body
• method
• path
• espace de travail

Exemple :

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

Format de la réponse

Le format de réponse est un tableau similaire d’objets. Chaque objet contient les éléments suivants :

• ID
• Code d’état HTTP de la requête particulière
• Corps de la réponse retournée pour cette requête.

Si une requête ne retourne pas correctement, le corps de la réponse contient des messages d’erreur. Les messages d’erreur ne s’appliquent qu’aux requêtes individuelles dans le lot. Le traitement lui-même retourne un code d’état indépendant des valeurs de retour de ses membres. Le traitement retourne correctement si le lot est :

• Bien formé et correctement mis en forme
• Authentifié
• Autorisé. Le traitement retourne correctement même si les résultats de ses requêtes membres peuvent être une combinaison de réussites et d’échecs.

Exemple

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

Comportement et erreurs

L’ordre des réponses à l’intérieur de l’objet retourné n’est pas lié à l’ordre dans la demande. Il est déterminé par le temps nécessaire à l’exécution de chaque requête. Utilisez des ID pour mapper les objets de réponse de requête aux demandes d’origine. Ne présumez pas que les réponses aux requêtes sont ordonnées.

L’intégralité d’une demande de lots n’échoue que dans les conditions suivantes :

• Le format JSON de la charge utile externe n’est pas valide.
• L’authentification échoue : l’utilisateur ne fournit pas de jeton d’authentification, ou le jeton n’est pas valide.
• Les objets de demande individuels dans le lot n’ont pas de propriétés requises ou il existe des ID en double.

Dans ces conditions, la forme de la réponse sera différente du conteneur normal. Chacun des objets contenus dans l’objet lot peut échouer ou réussir indépendamment. Voir l’exemple ci-dessous.

Exemples d’erreurs

Voici une liste non exhaustive d’exemples d’erreurs possibles et de leurs significations.

• 400 - Demande malformée. L’objet de demande externe n’était pas un JSON valide.

    {
        "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 - Interdit. Le jeton fourni n’a pas accès à la ressource à laquelle vous essayez d’accéder. Assurez-vous que votre demande de jeton dispose de la ressource correcte et que vous avez accordé des autorisations pour votre application 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 placé. Vous n’avez aucune donnée pour l’API à extraire dans le magasin de stockage. En tant que 2xx, il s’agit techniquement d’une demande réussie. Toutefois, dans un lot, il est utile de noter l’erreur.

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

• 404 - Introuvable. Le chemin d’accès de la requête n’existe pas. Cette erreur peut également se produire dans un lot si vous spécifiez une méthode HTTP non valide dans la demande individuelle.

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

• 400 - Échec de résolution de la ressource. Le GUID représentant l’espace de travail est incorrect.

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