バッチクエリ

[アーティクル]
10/31/2024

Azure Monitor Log Analytics API では、クエリのバッチ処理をサポートしています。現在、バッチクエリには Microsoft Entra 認証が必要です。

要求の形式

クエリをバッチ処理するには、API エンドポイントを使用して、URL の末尾に $batch を追加します: https://api.loganalytics.azure.com/v1/$batch。

メソッドが含まれていない場合、バッチ処理は既定で GET メソッドになります。 GET 要求では、API は要求オブジェクトの body パラメーターを無視します。

バッチ要求には、他の操作用の通常のヘッダーが含まれています。

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

要求の本文は、次のプロパティを含むオブジェクトの配列です。

id
headers
body
method
path
workspace

例:

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

応答形式

応答形式は、類似したオブジェクトの配列です。各オブジェクトには、次の情報が含まれます。

ID
特定のクエリの HTTP 状態コード
そのクエリに対して返される応答の本文。

クエリから正常に返されない場合、応答本文にはエラーメッセージが含まれます。エラーメッセージは、バッチ内の個々のクエリに対してのみ適用されます。バッチ自体からは、そのメンバーの戻り値と無関係の状態コードが返されます。バッチが次の場合、バッチは正常に返されます。

整形式で適切な形式
認証済み
承認済

バッチは、そのメンバークエリの結果に成功と失敗が混在している可能性がある場合でも正常に返されます。

例:

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

動作とエラー

返されたオブジェクト内の応答の順序は、要求内の順序とは関係ありません。処理時間に応じて個々のクエリは完了します。クエリ応答オブジェクトを元の要求にマップするには、ID を使用します。クエリ応答が順番どおりであると想定しないでください。

バッチ要求全体は、次の場合にのみ失敗します。

外部ペイロードの JSON 形式が無効である。
認証に失敗する: ユーザーが認証トークンを提供していないか、トークンが無効です。
バッチ内の個々の要求オブジェクトに必要なプロパティがない、または ID が重複している。

このような状況下では、応答の形状は通常のコンテナーとは異なります。バッチオブジェクト内に含まれるオブジェクトは、それぞれ個別に失敗または成功する可能性があります。次のエラーの例を参照してください。

エラーの例

この一覧は、発生する可能性のあるエラーの例とその意味の一覧です (すべてを網羅しているわけではありません)。

400 - 要求の形式が正しくありません 外部要求オブジェクトが有効な 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 - 許可されていません。 指定されたトークンは、アクセスしようとしているリソースにアクセスできません。トークン要求に正しいリソースがあり、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 - 配置されていません。 API に、バッキングストアにプルするデータがありません。 2xx エラーとして、これは技術的には正常な要求です。ただし、バッチでは、エラーに注意することが有益です。
```
{
    "responses": [
        {
            "id": "2",
            "status": 204,
            "body": {
                "error": {
                    "code": "WorkspaceNotPlacedError"
                }
            }
        }
    ]
}
```

404 - 見つかりません。クエリパスが存在しません。 このエラーは、個々の要求で無効な HTTP メソッドを指定した場合にもバッチで発生する可能性があります。

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

400 - リソースを解決できません。 ワークスペースを表す GUID が正しくありません。

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

次の方法で共有

バッチクエリ

要求の形式

応答形式

動作とエラー

エラーの例

フィードバック

その他のリソース

次の方法で共有

バッチ クエリ

要求の形式

応答形式

動作とエラー

エラーの例

フィードバック

その他のリソース

バッチクエリ