運用ワークフローに直接対応するように、ドキュメントのナビゲーション構造を再編成しました。詳しくは、リリースノートとチュートリアル動画をご覧ください。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

非同期検索 API

以下でサポートされています。

Google SecOps SIEM

Google Security Operations の検索プラットフォームでは、最大 100 万件の結果を含む大規模な結果セットを返す長時間実行クエリに非同期 API を使用できます。これらの API を使用すると、アプリケーションをブロックすることなく、統合データモデル（UDM）イベント、検出、データテーブル、エンティティコンテキストグラフ（ECG）などのデータソース全体で検索を開始できます。長時間実行オペレーション（LRO）API を使用して検索クエリを実行すると、オペレーション ID が返されます。この ID を使用して、オペレーションのステータスをモニタリングし、結果をページごとに取得できます。

前提条件

長時間実行オペレーション API を使用するには、呼び出し元プリンシパルに特定の Identity and Access Management（IAM）権限が必要です。

次の操作を行うには、対応する IAM 権限が必要です。

検索を開始する: chronicle.searchSessions.search
結果を一覧表示する: SearchSession リソースに対する chronicle.searchedResults.list。

呼び出し元のプリンシパルに、これらの権限を付与するロール（Chronicle API 閲覧者、Chronicle API 編集者、Chronicle API 管理者など）があることを確認します。

LRO API を使用して検索を実行する

LRO API を使用して検索を実行する手順は次のとおりです。

検索を開始します。
オペレーションをモニタリングする。
結果を取得する。

検索を開始する

POST リクエストを Google SecOps インスタンスの search カスタムメソッドに送信します。

エンドポイント: POST /{$api_version}/projects/{project}/locations/{location}/instances/{instance}:search
メソッド: Search
リクエストの本文: SearchRequest

次の例は、SearchRequest オブジェクトを示しています。

{
  "parent": "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID",
  "query": "metadata.event_type = \"USER_LOGIN\"",
  "time_range": {},
  "start_time": "2026-03-16T14:40:13Z",
  "endTime": "2026-03-16T15:40:13Z",
  "dialect": "YL2"
}

リクエストには次のキーパラメータが必要です。

query: 検索クエリ文字列。
time_range: 検索の時間間隔。
dialect: 言語の言語を YL2 として指定します。
result_limit: 省略可。マテリアライズする行の最大数。デフォルト値は 10000、最大値は 1000000 です。

この呼び出しは google.longrunning.Operation オブジェクトを返します。

次の例は、オペレーションが成功した場合のレスポンスを示しています。

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "[type.googleapis.com/google.cloud.chronicle.v1main.SearchOperationMetadata](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchOperationMetadata)",
    "state": "RUNNING",
    "start_time": "2026-03-13T10:00:00Z"
  }
}

state: RUNNING フィールドは、検索が進行中であることを示します。

オペレーションを監視する

google.longrunning.Operations サービスの標準の GetOperation メソッドを使用して、LRO のステータスをポーリングします。前のレスポンスの name 値を使用します。

エンドポイント: GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}/operations/{operationID}

GetOperation レスポンスの done フィールドが true を返すまで、ポーリングを続行します。

オペレーションが成功すると、metadata.state フィールドは SUCCEEDED を返し、レスポンスフィールドには作成された SearchSession リソースが含まれます。
オペレーションが失敗した場合、done フィールドは true を返し、エラーフィールドには関連する失敗の詳細が含まれます。

次の例は、成功した GetOperation レスポンスを示しています。

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "[type.googleapis.com/google.cloud.chronicle.v1main.SearchOperation](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchOperation) Metadata",
    "state": "SUCCEEDED",
    "startTime": "2026-03-16T15:42:11.037506921Z"
  },
  "endTime": "2026-03-16T15:42:17.504730842Z",
  "expireTime": "2026-03-17T15:42:17.504731874Z",
  "progress": 100,
  "done": true,
  "response": {
    "@type": "[type.googleapis.com/google.cloud.chronicle.v1main.SearchSession](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchSession)",
    "name": "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/SEARCH_SESSION_ID",
    "query": "metadata.event_type = \"USER_LOGIN\"",
    "timeRange": {},
    "startTime": "2026-03-16T14:40:13Z",
    "endTime": "2026-03-16T15:40:13Z",
    "dialect": "YL2",
    "metadata": {
      "operationId": "OPERATION_ID",
      "startTime": "2026-03-16T15:42:11.037506921Z",
      "endTime": "2026-03-16T15:42:17.504730842Z",
      "expireTime": "2026-03-17T15:42:17.504731874Z",
      "resultRowCount": 10000,
      "moreDataAvailable": true
    }
  }
}

SearchSession リソース名の形式は projects/{project}/locations/{location}/instances/{instance}/searchSessions/{search_session} です。

成功したレスポンスには、次のキーフィールドが含まれます。

done: true に設定すると、オペレーションは完了します。
state: SUCCEEDED に設定されている場合、検索は正常に完了しました。
response.name: SearchSession のリソース名。次のステップで、この値を親プロパティとして使用します。
response.metadata.resultRowCount: 検出された行の合計数を示します。
response.metadata.moreDataAvailable: 使用可能な結果の数が定義された戻り上限を超えていることを示します。

LRO オペレーションを一覧表示する

LRO オペレーションを一覧表示するには、google.longrunning.Operations サービスから ListOperations メソッドを使用します。前のレスポンスの name 値を使用します。

エンドポイント: GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}

過去 24 時間のすべての LRO オペレーションを一覧表示するには、フィルタ name: "operations/s-lro" を追加します。

次の例は、成功した ListOperations リクエストを示しています。

google.longrunning.ListOperationsRequest {
  name: "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID"
  filter: "name:\"operations/lro\""
  page_size: 100
}

次の例は、成功した ListOperations レスポンスを示しています。

{
  operations {
    name: "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/operations/OPERATION_ID_1"
    metadata {
      type_url: "[type.googleapis.com/google.cloud.chronicle.v1main.SearchOperation](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchOperation) Metadata"
      value: "\b\002\022\f\b\367\304\363\316\006\020\317\352\232\240\003\032\f\b\237\307\363\316\006\020\326\334\351\311\001\"\f\b\237\352\370\316\006\020\352\342\351\311\001(d"
    }
    done: true
    response {
      type_url: "[type.googleapis.com/google.cloud.chronicle.v1main.SearchSession](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchSession)"
      value: "\n\213\001projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/OPERATION_ID_11022\bip != \"\"\032\020\n\006\b\251\255\334\316\006\022\006\b\351\345\336\316\006\0012\\\n*OPERATION_ID_1\022\f\b\367\304\363\316\006\020\317\352\232\240\003\032\f\b\237\307\363\316\006\020\326\334\351\311\001\"\f\b\237\352\370\316\006\020\352\342\351\311\001(\300\204=0\001"
    }
  }
  operations {
    name: "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/operations/OPERATION_ID_2"
    metadata {
      type_url: "[type.googleapis.com/google.cloud.chronicle.v1main.SearchOperationMetadata](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchOperationMetadata)"
      value: "\b\002\022\f\b\200\305\363\316\006\020\324\262\367\225\001\032\v\b\241\307\363\316\006\020\321\261\333?\"\v\b\241\352\370\316\006\020\317\264\333?(d"
    }
    done: true
    response {
      type_url: "[type.googleapis.com/google.cloud.chronicle.v1main.SearchSession](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchSession)"
      value: "\n\213\001projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/OPERATION_ID_2\022\bip != \"\"\0321020\n\006\b\251\255\334\316\006\022\006\b\351\345\336\316\006\0012Z\n*OPERATION_ID_2\022\f\b\200\305\363\316\006\0201324\262\367\225\001\032\v\b\241\307\363\316\006\020\321\261\333?\"\v\b\241\352\370\316\006\020\317\264\333?(\300\204=0\001"
    }
  }
}

結果を取得する

オペレーションの状態が SUCCEEDED を返したら、ListSearchedResults() メソッドを使用して検索結果を取得します。

エンドポイント: GET /{$api_version}/{parent=projects/*/locations/*/instances/*/searchSessions/*}/searchedResults
メソッド: ListSearchedResults
リクエストパラメータ: ListSearchedResultsRequest

次の例は、3 つの結果を取得し、最初の 5 つをスキップする ListSearchedResultsRequest を示しています。

// GET
/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/SEARCH_SESSION_ID/searchedResults?page_size=3&skip=5

リクエストは、次のクエリパラメータをサポートしています。

page_size: ページごとに返す結果の最大数。デフォルト値は 100、最大値は 10, 000 です。
page_token: 次のページを取得するために使用される、前の ListSearchedResultsResponse からのトークン。
order_by: 省略可。このフィールドは結果の並べ替えに使用されます。
- UDM events (eventRecord): udm フィールド内のパスを使用します（udm.metadata.timestamp desc、udm.principal.hostname asc など）。hostname、user、process name、event type などの列名もサポートされています。
  
  デフォルト値は udm.metadata.event_timestamp です。
- Entities / ECG (entityContextRecord): entity フィールド内のパスを使用します（例: graph.entity.ip asc）。
- data tables (dataTableRecord): %<table_alias>.<column_name> 形式を使用します。例: %dt.user desc
  
  デフォルト値はデータテーブルの最初の列です。
- Detections (DetectionRecord): detection キーワードの後にパスを指定します（例: detection.id）。
- 結合: イベントとエンティティの場合は、それらを定義するプレースホルダ変数を使用します。その他のソースについては、形式は変更されません。
  
  次に例を示します。
  - 心電図（UDM-ECG 結合）: エンティティ: $e1.graph.entity.hostname
  - UDM（UDM とのすべての結合）: $e1.principal.ip
  - データテーブル（UDM-データテーブル結合）: %<table_alias>.<column_name>
  hostname、user、process name、event type などの事前定義されたエイリアスもサポートされています。これらには、$e1.hostname.at の形式を使用します。
- skip: 省略可。スキップする結果の数。page_token を使用している場合は使用しないでください。

次の例は、成功した ListSearchedResultsResponse レスポンスを示しています。

{
"searchedResults": [
{
"name":
"projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/SEARCH_SESSION_ID/searchedResults/
RESULT_ID",
"resultRow": {
"eventRecord": {
"event": {
"name":
"projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/events/EVENT_ID",
"udm": {
"metadata": {
"eventTimestamp": "2026-03-16T14:45:18Z",
"eventType": "USER_LOGIN",
"vendorName": "Microsoft",
"productName": "Azure AD"
}
},
//... other UDM fields
}
//... other UDM fields
"eventLogToken":
"EVENT_LOG_TOKEN"
}
},
{ }
},
{
"name": "projects/PROJECT_NUMBER/locations/
LOCATION/instances/INSTANCE_ID
/searchSessions/SEARCH_SESSION_ID/searchedResults/RESULT_ID", "resultRow": {
"eventRecord": {
//... Similar UDM event structure...
}
}
},
{
""name": "projects/PROJECT_NUMBER/locations/
LOCATION/instances/INSTANCE_ID
/searchSessions/SEARCH_SESSION_ID/searchedResults/RESULT_ID", "resultRow": {
"eventRecord": {
//... Similar UDM event structure...
}
}
}
],
"totalSize": 10000,
"columnNames": [],
"columnSchema": {},
"nextPageToken": "CAKYASAB"
}

結果の次のページを取得するには、返された nextPageToken 値を次の ListSearchedResults リクエストの page_token クエリパラメータで使用します。resultRow フィールドには実際のデータが含まれます。

各レスポンスの next_page_token 値を使用して ListSearchedResults の呼び出しを続けます。next_page_token が空を返すと、すべての結果が取得されます。

次のステップ

メソッド、リクエストフィールドとレスポンスフィールド、型について詳しくは、次の API リファレンスドキュメントをご覧ください。

さらにサポートが必要な場合 コミュニティメンバーや Google SecOps のプロフェッショナルから回答を得ることができます。