バッチ クエリ
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
- メソッド
- path
- ワークスペース
例:
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"
}
}
}
]
}