API di ricerca asincrona

Supportata in:

Google SecOps SIEM

La piattaforma di ricerca di Google Security Operations ti consente di utilizzare API asincrone per query a lunga esecuzione che restituiscono set di risultati di grandi dimensioni, fino a 1 milione di risultati. Queste API ti consentono di avviare ricerche in diverse origini dati, tra cui eventi UDM (Unified Data Model), rilevamenti, tabelle di dati ed ECG (Entity Context Graph), senza bloccare l'applicazione. Quando esegui una query di ricerca utilizzando un'API per operazioni a lunga esecuzione (LRO), ricevi un ID operazione. Puoi utilizzare questo ID per monitorare lo stato di attività dell'operazione e ottenere i risultati pagina per pagina.

Prerequisiti

Per utilizzare le API per operazione a lunga esecuzione, l'entità chiamante deve disporre di autorizzazioni Identity and Access Management (IAM) specifiche.

Per eseguire le seguenti azioni, devi disporre delle autorizzazioni IAM corrispondenti:

• Avvia una ricerca: chronicle.searchSessions.search
• Risultati dell'elenco: chronicle.searchedResults.list sulla risorsa SearchSession.

Assicurati che l'entità chiamante disponga di un ruolo che conceda queste autorizzazioni, ad esempio il ruolo Visualizzatore API Chronicle, Editor API Chronicle o Amministratore API Chronicle.

Esegui una ricerca utilizzando le API LRO

Segui questi passaggi per eseguire una ricerca utilizzando le API LRO:

1. Avvia la ricerca.
2. Monitora l'operazione.
3. Recupera i risultati.

Avvia la ricerca

Invia una richiesta POST al metodo personalizzato search nell'istanza Google SecOps.

• Endpoint: POST /{$api_version}/projects/{project}/locations/{location}/instances/{instance}:search
• Metodo: Search
• Corpo della richiesta: SearchRequest

L'esempio seguente mostra un oggetto 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"
}

La richiesta richiede i seguenti parametri chiave:

• query: la stringa della query di ricerca.
• time_range: l'intervallo di tempo per la ricerca.
• dialect: specifica il dialetto della lingua come YL2.
  • Il dialetto SQL non è supportato per il recupero asincrono dei risultati LRO utilizzando ListSearchedResults (searchedResults.list).
  • Il dialetto RAW_LOG è in anteprima e potrebbe restituire un errore 501 UNIMPLEMENTED se non è abilitato per la tua istanza.
• result_limit: (Facoltativo) Il numero massimo di righe da materializzare. Il valore predefinito è 10000 e il valore massimo è 1000000.
• simulated_data_visibility (o simulatedDataVisibility in JSON): facoltativo. Controlla se i risultati di ricerca includono eventi simulati. Imposta su SIMULATED_DATA_INCLUDED per includere gli eventi simulati nei risultati di ricerca. Se non viene specificato, questo parametro viene impostato per impostazione predefinita su SIMULATED_DATA_EXCLUDED, che esclude gli eventi simulati.

Questa chiamata restituisce un oggetto google.longrunning.Operation.

L'esempio seguente mostra una risposta di operazione riuscita:

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

Il campo state: RUNNING indica che la ricerca è in corso.

Monitora l'operazione

Esegui il polling dello stato dell'LRO utilizzando il metodo GetOperation standard del servizio google.longrunning.Operations. Utilizza il valore name della risposta precedente.

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

Continua il polling finché il campo done nella risposta GetOperation non restituisce true.

• Se l'operazione ha esito positivo, il campo metadata.state restituisce SUCCEEDED e il campo della risposta contiene la risorsa SearchSession creata.
• Se l'operazione non va a buon fine, il campo done restituisce true e il campo di errore contiene i dettagli dell'errore correlato.

L'esempio seguente mostra una risposta GetOperation corretta:

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

Il formato del nome della risorsa SearchSession è projects/{project}/locations/{location}/instances/{instance}/searchSessions/{search_session}.

La risposta corretta contiene i seguenti campi chiave:

• done: se impostato su true, l'operazione è completata.
• state: se impostato su SUCCEEDED, la ricerca è stata completata correttamente.
• response.name: il nome della risorsa SearchSession. Utilizza questo valore come proprietà principale nel passaggio successivo.
• response.metadata.resultRowCount: indica il numero totale di righe trovate.
• response.metadata.moreDataAvailable: indica che il numero di risultati disponibili supera il limite di restituzione definito.

Elenca le operazioni LRO

Per elencare le operazioni LRO, utilizza il metodo ListOperations del servizio google.longrunning.Operations. Utilizza il valore name della risposta precedente.

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

Per elencare le operazioni LRO di ricerca delle ultime 24 ore, specifica il filtro name:"operations/s-lro-", incluso il trattino finale.

Nota: questo filtro è obbligatorio quando chiami ListOperations (operations.list) per recuperare le operazioni di ricerca. Se chiami ListOperations senza questo filtro, la risposta restituisce solo le operazioni di retrohunt e omette le operazioni di ricerca. Inoltre, i metodi CancelOperation (operations.cancel) e DeleteOperation (operations.delete) non sono supportati per le operazioni di ricerca s-lro-.

L'esempio seguente mostra una richiesta ListOperations riuscita:

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

L'esempio seguente mostra una risposta ListOperations corretta:

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

Recupera i risultati

Dopo che lo stato dell'operazione restituisce SUCCEEDED, utilizza il metodo ListSearchedResults() per recuperare i risultati di ricerca.

• Endpoint: GET /{$api_version}/{parent=projects/*/locations/*/instances/*/searchSessions/*}/searchedResults
• Metodo: ListSearchedResults
• Parametri della richiesta: ListSearchedResultsRequest

L'esempio seguente mostra un ListSearchedResultsRequest che recupera tre risultati e salta i primi cinque:

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

La richiesta supporta i seguenti parametri di ricerca:

• page_size: il numero massimo di risultati da restituire per pagina. Il valore predefinito è 100 e il valore massimo è 10.000.
• page_token: il token di un ListSearchedResultsResponse precedente utilizzato per recuperare la pagina successiva.

• order_by (o orderBy in JSON): facoltativo. Il campo utilizzato per ordinare i risultati. Se ometti order_by, i risultati degli eventi UDM vengono ordinati per udm.metadata.event_timestamp in ordine decrescente per impostazione predefinita, restituendo prima gli eventi più recenti. Quando specifichi un percorso del campo in order_by senza un suffisso di direzione, ad esempio udm.principal.hostname, i risultati vengono ordinati in ordine crescente per impostazione predefinita. Non aggiungere asc, perché il suffisso asc non è supportato e restituisce un errore 400 INVALID_ARGUMENT. Per ordinare i risultati in ordine decrescente, aggiungi il suffisso desc al percorso del campo, ad esempio udm.metadata.event_timestamp desc. L'ordinamento su più colonne non è supportato.

  • UDM events (eventRecord): utilizza i percorsi completi nel campo udm, ad esempio udm.metadata.event_timestamp desc o udm.principal.hostname. Sono supportati anche i nomi delle colonne, come hostname, user, process name e event type.

    L'ordinamento predefinito è udm.metadata.event_timestamp in ordine decrescente, che restituisce prima gli eventi più recenti.

  • Entities / ECG (entityContextRecord): utilizza i percorsi all'interno del campo entity, ad esempio graph.entity.ip o graph.entity.ip desc.

  • data tables (dataTableRecord): Utilizzare il formato %<table_alias>.<column_name>. Ad esempio: %dt.user desc.

    Il valore predefinito è la prima colonna della tabella dati.

  • Detections (DetectionRecord): utilizza la parola chiave detection seguita dal percorso, ad esempio detection.id.

  • Join: per gli eventi e le entità, utilizza la variabile segnaposto che li definisce. Per tutte le altre origini, il formato rimane invariato.

    Ad esempio:

    • ECG (join UDM-ECG): entità: $e1.graph.entity.hostname
    • UDM (tutti i join con UDM): $e1.principal.ip
    • Tabella dati (join tabella dati-UDM): %<table_alias>.<column_name>

    Sono supportati anche alias predefiniti come hostname, user, process name e event type. Per questi, utilizza il formato $e1.hostname.at.

• skip: (Facoltativo) Il numero di risultati da saltare. Non utilizzare questo parametro con page_token.

  • L'ordinamento predefinito (udm.metadata.event_timestamp) non è univoco per gli eventi che condividono lo stesso timestamp. Inoltre, l'ordinamento dei risultati di ricerca viene impostato alla prima chiamata ListSearchedResults (searchedResults.list).
  • Quando esegui l'impaginazione con skip, in particolare tra richieste parallele, specifica un campo di ordinamento univoco come udm.metadata.id nel parametro order_by. In alternativa, recupera la prima pagina prima di inviare richieste skip parallele in modo che l'ordinamento sia già impostato.

L'esempio seguente mostra una risposta ListSearchedResultsResponse corretta:

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

Per recuperare la pagina di risultati successiva, utilizza il valore nextPageToken restituito nel parametro di query page_token della richiesta ListSearchedResults successiva. Il campo resultRow contiene i dati effettivi.

Continua a chiamare ListSearchedResults con il valore next_page_token di ogni risposta. Quando next_page_token restituisce un valore vuoto, significa che sono stati recuperati tutti i risultati.

Passaggi successivi

Per ulteriori informazioni su metodi, campi di richiesta e risposta e tipi, consulta la seguente documentazione di riferimento dell'API:

• Riferimento API REST di Google SecOps
• Metodo search
• Metodo ListSearchedResults

Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.