非同步搜尋 API

支援的國家/地區：

Google Security Operations 的搜尋平台可讓您使用非同步 API，執行長時間查詢，並傳回最多 100 萬筆結果的大型結果集。這些 API 可讓您在資料來源中啟動搜尋，包括統一資料模型 (UDM) 事件、偵測項目、資料表和實體內容圖表 (ECG)，而不會封鎖應用程式。使用長時間執行作業 (LRO) API 執行搜尋查詢時，您會收到作業 ID。您可以使用這個 ID 監控作業狀態，並逐頁取得結果。

必要條件

如要使用長時間執行的作業 API，呼叫主體必須具備特定的 Identity and Access Management (IAM) 權限。

如要執行下列動作，您必須具備相應的 IAM 權限：

  • 開始搜尋：chronicle.searchSessions.search
  • 列出結果：chronicle.searchedResults.list資源的 SearchSession。

請確認呼叫主體具備可授予這些權限的角色，例如 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。
  • 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

以下範例顯示的 ListSearchedResultsRequest 會擷取三項結果，並略過前五項：

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

要求支援下列查詢參數：

  • page_size：每頁要傳回的結果數量上限。預設值為 100，最大值為 10000。
  • 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"
}

如要擷取下一頁結果，請在下一個 ListSearchedResults 要求的 page_token 查詢參數中使用傳回的 nextPageToken 值。resultRow 欄位包含實際資料。

繼續使用每個回應中的 next_page_token 值呼叫 ListSearchedResults。當 next_page_token 傳回空白時，表示已擷取所有結果。

後續步驟

如要進一步瞭解方法、要求和回應欄位，以及類型，請參閱下列 API 參考文件：

還有其他問題嗎？向社群成員和 Google SecOps 專業人員尋求答案。