Wir haben die Navigationsstruktur unserer Dokumentation neu organisiert, um sie direkt an Ihre betrieblichen Arbeitsabläufe anzupassen. Weitere Informationen finden Sie in den Versionshinweisen und im Video zur Anleitung.

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

Asynchrone Search APIs

Unterstützt in:

Google SecOps SIEM

Mit der Suchplattform in Google Security Operations können Sie asynchrone APIs für zeitaufwendige Abfragen verwenden, die große Ergebnismengen von bis zu 1 Million Ergebnissen zurückgeben. Mit diesen APIs können Sie Suchvorgänge in Datenquellen starten, darunter UDM-Ereignisse (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 (LRO) ausführen, erhalten Sie eine Vorgangs-ID. Mit dieser ID können Sie den Status des Vorgangs überwachen und die Ergebnisse seitenweise abrufen.

Vorbereitung

Für die Verwendung von APIs für Vorgänge mit langer Ausführungszeit sind für das aufrufende Hauptkonto bestimmte IAM-Berechtigungen (Identity and Access Management) erforderlich.

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 SearchSession-Ressource.

Prüfen Sie, ob 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:

Suche starten:
Vorgang überwachen
Ergebnisse abrufen:

Suche starten

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 wichtigen Parameter erforderlich:

query: Der Suchanfragestring.
time_range: Das Zeitintervall für die Suche.
dialect: Gibt den Sprachdialekt als YL2 an.
result_limit: Optional. Die maximale Anzahl der zu materialisierenden Zeilen. Der Standardwert ist 10000 und der Höchstwert 1000000.

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

Das folgende Beispiel zeigt eine Antwort auf einen erfolgreichen 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 des Dienstes 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 den Vorgang so lange ab, bis das Feld done in der GetOperation-Antwort 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, wird im Feld done der Wert true zurückgegeben und das Fehlerfeld enthält die zugehörigen 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 SearchSession ist projects/{project}/locations/{location}/instances/{instance}/searchSessions/{search_session}.

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

done: Wenn auf true festgelegt, 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.

LRO-Vorgänge 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 alle LRO-Vorgänge der letzten 24 Stunden auflisten möchten, fügen Sie den Filter name: "operations/s-lro" hinzu.

Das folgende Beispiel zeigt eine erfolgreiche ListOperations-Anfrage:

google.longrunning.ListOperationsRequest {
  name: "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID"
  filter: "name:\"operations/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

Nachdem der Vorgangsstatus SUCCEEDED zurückgegeben wurde, 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, mit der drei Ergebnisse abgerufen und die ersten fünf übersprungen werden:

// 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 der Ergebnisse, 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 zum Abrufen der nächsten Seite.
order_by: Optional. Das Feld wird zum Sortieren der Ergebnisse verwendet.
- UDM events (eventRecord): Verwenden Sie Pfade im Feld udm, z. B. udm.metadata.timestamp desc oder udm.principal.hostname asc. Spaltennamen wie hostname, user, process name und event type werden ebenfalls unterstützt.
  
  Der Standardwert ist udm.metadata.event_timestamp.
- Entities / ECG (entityContextRecord): Verwenden Sie Pfade im Feld entity, z. B. graph.entity.ip asc.
- 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. Bei allen anderen Quellen bleibt das Format unverändert.
  
  Beispiel:
  - EKG (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 für diese das Format $e1.hostname.at.
- skip: Optional. Die Anzahl der zu überspringenden Ergebnisse. Nicht verwenden, wenn page_token verwendet wird.

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

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

Rufen Sie ListSearchedResults weiterhin mit dem Wert next_page_token aus jeder Antwort auf. Wenn next_page_token leer zurückgegeben wird, 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