Asynchrone Such-APIs

Unterstützt in:

Mit der Suchplattform in Google Security Operations können Sie asynchrone APIs für Abfragen mit langer Laufzeit verwenden, die große Ergebnismengen von bis zu 1 Million Ergebnissen zurückgeben. Mit diesen APIs können Sie Suchvorgänge in verschiedenen Datenquellen initiieren, einschließlich UDM-Ereignissen (Unified Data Model), Erkennungen, Datentabellen und ECG (Entity Context Graph), ohne Ihre Anwendung zu blockieren. Wenn Sie eine Suchanfrage mit einer API für Vorgänge mit langer Ausführungszeit ausführen, erhalten Sie eine Vorgangs-ID. Mit dieser ID können Sie den Vorgangsstatus überwachen und die Ergebnisse seitenweise abrufen.

Vorbereitung

Wenn Sie APIs für Vorgänge mit langer Ausführungszeit verwenden möchten, benötigt das aufrufende Hauptkonto bestimmte IAM-Berechtigungen (Identity and Access Management).

Für die folgenden Aktionen benötigen Sie die entsprechenden IAM-Berechtigungen:

  • Suche starten: chronicle.searchSessions.search
  • Ergebnisse auflisten: chronicle.searchedResults.list für die Ressource SearchSession.

Achten Sie darauf, dass das aufrufende Hauptkonto eine Rolle hat, die diese Berechtigungen gewährt, z. B. die Rolle „Chronicle API Viewer“, „Chronicle API Editor“ oder „Chronicle API Admin“.

Suche mit LRO APIs ausführen

So führen Sie eine Suche mit den LRO APIs aus:

  1. Suche starten:
  2. Vorgang überwachen
  3. Ergebnisse abrufen

Senden Sie eine POST-Anfrage an die benutzerdefinierte Methode search in der Google SecOps-Instanz.

  • Endpunkt: POST /{$api_version}/projects/{project}/locations/{location}/instances/{instance}:search
  • Methode: Search
  • Anfragetext: SearchRequest

Das folgende Beispiel zeigt ein SearchRequest-Objekt:

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

Für die Anfrage sind die folgenden Schlüsselparameter erforderlich:

  • query: Der Suchanfragestring.
  • time_range: Das Zeitintervall für die Suche.
  • dialect: Gibt den Sprachdialekt als YL2 an.
    • Der Dialekt SQL wird für den asynchronen Abruf von LRO-Ergebnissen mit ListSearchedResults (searchedResults.list) nicht unterstützt.
    • Der RAW_LOG-Dialekt befindet sich in der Vorabversion und gibt möglicherweise einen 501 UNIMPLEMENTED-Fehler zurück, wenn er für Ihre Instanz nicht aktiviert ist.
  • result_limit: Optional. Die maximale Anzahl der zu materialisierenden Zeilen. Der Standardwert ist 10000 und der Höchstwert 1000000.
  • simulated_data_visibility (oder simulatedDataVisibility in JSON): Optional. Steuert, ob Suchergebnisse simulierte Ereignisse enthalten. Legen Sie SIMULATED_DATA_INCLUDED fest, um simulierte Ereignisse in die Suchergebnisse aufzunehmen. Wenn dieser Parameter nicht angegeben ist, wird standardmäßig SIMULATED_DATA_EXCLUDED verwendet, wodurch simulierte Ereignisse ausgeschlossen werden.

Dieser Aufruf gibt ein google.longrunning.Operation-Objekt zurück.

Das folgende Beispiel zeigt eine erfolgreiche Antwort auf einen Vorgang:

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

Das Feld state: RUNNING gibt an, dass die Suche läuft.

Den Vorgang überwachen

Fragen Sie den Status des LRO mit der Standardmethode GetOperation aus dem Dienst google.longrunning.Operations ab. Verwenden Sie den Wert name aus der vorherigen Antwort.

  • Endpunkt: GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}/operations/{operationID}

Fragen Sie weiter ab, bis das Feld done in der Antwort GetOperation den Wert true zurückgibt.

  • Wenn der Vorgang erfolgreich ist, wird im Feld metadata.state der Wert SUCCEEDED zurückgegeben und das Antwortfeld enthält die erstellte SearchSession-Ressource.
  • Wenn der Vorgang fehlschlägt, gibt das Feld done den Wert true zurück und das Fehlerfeld enthält die entsprechenden Fehlerdetails.

Das folgende Beispiel zeigt eine erfolgreiche GetOperation-Antwort:

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

Das Format des Ressourcennamens für SearchSession ist projects/{project}/locations/{location}/instances/{instance}/searchSessions/{search_session}.

Die erfolgreiche Antwort enthält die folgenden Schlüsselfelder:

  • done: Wenn der Wert auf true gesetzt ist, ist der Vorgang abgeschlossen.
  • state: Wenn dieser Wert auf SUCCEEDED gesetzt ist, wurde die Suche erfolgreich abgeschlossen.
  • response.name: Der Ressourcenname des SearchSession. Verwenden Sie diesen Wert im nächsten Schritt als übergeordnete Property.
  • response.metadata.resultRowCount: Gibt die Gesamtzahl der gefundenen Zeilen an.
  • response.metadata.moreDataAvailable: Gibt an, dass die Anzahl der verfügbaren Ergebnisse das definierte Rückgabelimit überschreitet.

Vorgänge mit langer Ausführungszeit auflisten

Verwenden Sie zum Auflisten von LRO-Vorgängen die Methode ListOperations aus dem Dienst google.longrunning.Operations. Verwenden Sie den Wert name aus der vorherigen Antwort.

  • Endpunkt: GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}

Wenn Sie Suchvorgänge mit langer Ausführungszeit der letzten 24 Stunden auflisten möchten, geben Sie den Filter name:"operations/s-lro-" an, einschließlich des abschließenden Bindestrichs.

Das folgende Beispiel zeigt eine erfolgreiche ListOperations-Anfrage:

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

Das folgende Beispiel zeigt eine erfolgreiche ListOperations-Antwort:

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

Ergebnisse abrufen

Wenn der Vorgangsstatus SUCCEEDED zurückgibt, rufen Sie die Suchergebnisse mit der Methode ListSearchedResults() ab.

  • Endpunkt: GET /{$api_version}/{parent=projects/*/locations/*/instances/*/searchSessions/*}/searchedResults
  • Methode: ListSearchedResults
  • Anfrageparameter: ListSearchedResultsRequest

Das folgende Beispiel zeigt eine ListSearchedResultsRequest, die drei Ergebnisse abruft und die ersten fünf überspringt:

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

Die Anfrage unterstützt die folgenden Abfrageparameter:

  • page_size: Die maximale Anzahl von Ergebnissen, die pro Seite zurückgegeben werden sollen. Der Standardwert ist 100 und der Höchstwert 10.000.
  • page_token: Das Token aus einem vorherigen ListSearchedResultsResponse, das zum Abrufen der nächsten Seite verwendet wird.

  • order_by (oder orderBy in JSON): Optional. Das Feld, das zum Sortieren der Ergebnisse verwendet wird. Wenn Sie order_by weglassen, werden die UDM-Ereignisergebnisse standardmäßig nach udm.metadata.event_timestamp in absteigender Reihenfolge sortiert, wobei die neuesten Ereignisse zuerst zurückgegeben werden. Wenn Sie in order_by einen Feldpfad ohne Richtungssuffix angeben, z. B. udm.principal.hostname, werden die Ergebnisse standardmäßig in aufsteigender Reihenfolge sortiert. Hängen Sie nicht asc an, da das Suffix asc nicht unterstützt wird und den Fehler 400 INVALID_ARGUMENT zurückgibt. Wenn Sie die Ergebnisse in absteigender Reihenfolge sortieren möchten, hängen Sie das Suffix desc an den Feldpfad an, z. B. udm.metadata.event_timestamp desc. Das Sortieren nach mehreren Spalten wird nicht unterstützt.

    • UDM events (eventRecord): Verwenden Sie im Feld udm vollständig qualifizierte Pfade, z. B. udm.metadata.event_timestamp desc oder udm.principal.hostname. Spaltennamen wie hostname, user, process name und event type werden ebenfalls unterstützt.

      Die Standardsortierreihenfolge ist udm.metadata.event_timestamp in absteigender Reihenfolge, wobei die neuesten Ereignisse zuerst zurückgegeben werden.

    • Entities / ECG (entityContextRecord): Verwenden Sie Pfade im Feld entity, z. B. graph.entity.ip oder graph.entity.ip desc.

    • data tables (dataTableRecord): Verwenden Sie das Format %<table_alias>.<column_name>. Beispiel: %dt.user desc

      Der Standardwert ist die erste Spalte der Datentabelle.

    • Detections (DetectionRecord): Verwenden Sie das Keyword detection gefolgt vom Pfad, z. B. detection.id.

    • Joins: Verwenden Sie für Ereignisse und Entitäten die Platzhaltervariable, die sie definiert. Für alle anderen Quellen bleibt das Format unverändert.

      Beispiel:

      • ECG (UDM-ECG-Join): Entität: $e1.graph.entity.hostname
      • UDM (alle Joins mit UDM): $e1.principal.ip
      • Datentabelle (UDM-Datentabellen-Join): %<table_alias>.<column_name>

      Vordefinierte Aliase wie hostname, user, process name und event type werden ebenfalls unterstützt. Verwenden Sie dafür das Format $e1.hostname.at.

  • skip: Optional. Die Anzahl der zu überspringenden Ergebnisse. Verwenden Sie diesen Parameter nicht mit page_token.

    • Die Standardsortierung (udm.metadata.event_timestamp) ist für Ereignisse mit demselben Zeitstempel nicht eindeutig. Außerdem wird die Sortierreihenfolge für die Suchergebnisse beim ersten ListSearchedResults-Aufruf (searchedResults.list) festgelegt.
    • Wenn Sie die Paginierung mit skip verwenden, insbesondere bei parallelen Anfragen, geben Sie im Parameter order_by ein eindeutiges Sortierfeld wie udm.metadata.id an. Alternativ können Sie die erste Seite abrufen, bevor Sie parallele skip-Anfragen senden, damit die Sortierreihenfolge bereits festgelegt ist.

Das folgende Beispiel zeigt eine erfolgreiche ListSearchedResultsResponse-Antwort:

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

Wenn Sie die nächste Ergebnisseite abrufen möchten, verwenden Sie den zurückgegebenen nextPageToken-Wert im Suchparameter page_token Ihrer nächsten ListSearchedResults-Anfrage. Das Feld resultRow enthält die eigentlichen Daten.

Rufen Sie ListSearchedResults weiterhin mit dem Wert next_page_token aus jeder Antwort auf. Wenn next_page_token leer ist, wurden alle Ergebnisse abgerufen.

Nächste Schritte

Weitere Informationen zu Methoden, Anfrage- und Antwortfeldern sowie Typen finden Sie in der folgenden API-Referenzdokumentation:

Benötigen Sie weitere Hilfe? Antworten von Community-Mitgliedern und Google SecOps-Experten erhalten