非同期 Search 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 を使用して検索を実行する手順は次のとおりです。

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

検索を開始する

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

• エンドポイント: 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 として指定します。
  • SQL 言語は、ListSearchedResults（searchedResults.list）を使用した非同期 LRO 結果の取得ではサポートされていません。
  • RAW_LOG 言語はプレビュー版です。インスタンスで有効になっていない場合、501 UNIMPLEMENTED エラーが返されることがあります。
• result_limit: 省略可。実体化する行の最大数。デフォルト値は 10000、最大値は 1000000 です。
• simulated_data_visibility（JSON では simulatedDataVisibility）: 省略可。検索結果にシミュレートされたイベントを含めるかどうかを制御します。検索結果にシミュレートされたイベントを含めるには、SIMULATED_DATA_INCLUDED に設定します。指定しない場合、このパラメータはデフォルトで SIMULATED_DATA_EXCLUDED になり、シミュレートされたイベントは除外されます。

この呼び出しは 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 を返し、error フィールドには関連する失敗の詳細が含まれます。

次の例は、正常な 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（operations.list）を呼び出して検索オペレーションを取得する場合に必要です。このフィルタを指定せずに ListOperations を呼び出すと、レスポンスには retrohunt オペレーションのみが返され、検索オペレーションは省略されます。また、s-lro- 検索オペレーションでは、CancelOperation（operations.cancel）メソッドと DeleteOperation（operations.delete）メソッドはサポートされていません。

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

google.longrunning.ListOperationsRequest {
  name: "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID"
  filter: "name:\"operations/s-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（JSON では orderBy）: 省略可。結果の並べ替えに使用されるフィールド。order_by を省略すると、UDM イベントの結果はデフォルトで udm.metadata.event_timestamp の降順で並べ替えられ、最新のイベントが最初に返されます。order_by で方向接尾辞なしでフィールドパス（udm.principal.hostname など）を指定すると、結果はデフォルトで昇順に並べ替えられます。asc は追加しないでください。asc サフィックスはサポートされていないため、400 INVALID_ARGUMENT エラーが返されます。結果を降順で並べ替えるには、フィールドパスに desc 接尾辞を追加します（例: udm.metadata.event_timestamp desc）。複数列の並べ替えはサポートされていません。

  • UDM events (eventRecord): udm フィールド内で完全修飾パス（udm.metadata.event_timestamp desc や udm.principal.hostname など）を使用します。hostname、user、process name、event type などの列名もサポートされています。

    デフォルトの並べ替え順序は udm.metadata.event_timestamp の降順です。これにより、最新のイベントが最初に返されます。

  • Entities / ECG (entityContextRecord): entity フィールド内のパス（graph.entity.ip、graph.entity.ip desc など）を使用します。

  • data tables (dataTableRecord): %<table_alias>.<column_name> 形式を使用します。例: %dt.user desc

    デフォルト値は、最初のデータテーブル列です。

  • Detections (DetectionRecord): キーワード detection の後にパスを指定します（例: detection.id）。

  • 結合: イベントとエンティティの場合は、それらを定義するプレースホルダ変数を使用します。他のすべてのソースの形式は変更されません。

    次に例を示します。

    • ECG（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 と一緒に使用しないでください。

  • デフォルトの並べ替え（udm.metadata.event_timestamp）は、同じタイムスタンプを共有するイベント間で一意ではありません。また、検索結果の並べ替え順序は、最初の ListSearchedResults（searchedResults.list）呼び出しで設定されます。
  • skip を使用してページ分けを行う場合、特に並列リクエスト間でページ分けを行う場合は、order_by パラメータに udm.metadata.id などの一意の並べ替えフィールドを指定します。または、並列 skip リクエストを送信する前に最初のページを取得して、並べ替え順序がすでに設定されているようにします。

次の例は、正常な 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</span>
/searchSessions/SEARCH_SESSION_ID/searchedResults/RESULT_ID", "resultRow": {
"eventRecord": {
//... Similar UDM event structure...
}
}
},
{
""name": "projects/PROJECT_NUMBER/locations/
LOCATION/instances/INSTANCE_ID</span>
/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 REST API リファレンス
• search メソッド
• ListSearchedResults メソッド

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