Abbiamo riorganizzato la struttura di navigazione della documentazione per allinearla direttamente ai tuoi flussi di lavoro operativi. Per ulteriori informazioni, consulta le note di rilascio e il video dimostrativo.

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

API di ricerca asincrona

Supportato in:

Google secops SIEM

La piattaforma di ricerca in Google Security Operations ti consente di utilizzare le API asincrone per le 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 nelle origini dati, inclusi eventi UDM (Unified Data Model), rilevamenti, tabelle dati e ECG (Entity Context Graph), senza bloccare l'applicazione. Quando esegui una query di ricerca utilizzando un'API di operazioni a lunga esecuzione (LRO), ricevi un ID operazione. Puoi utilizzare questo ID per monitorare lo stato dell'operazione e ottenere i risultati pagina per pagina.

Prerequisiti

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

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

Avviare una ricerca: chronicle.searchSessions.search
Elencare i risultati: chronicle.searchedResults.list sulla risorsa SearchSession.

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

Eseguire una ricerca utilizzando le API LRO

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

Avvia la ricerca.
Monitora l'operazione.
Recupera i risultati.

Avviare la ricerca

Invia una richiesta POST al metodo personalizzato search sull'istanza di 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 di query.
time_range: l'intervallo di tempo per la ricerca.
dialect: specifica il dialetto della lingua come YL2.
result_limit: (facoltativo) Il numero massimo di righe da materializzare. Il valore predefinito è 10000 e il valore massimo è 1000000.

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.

Monitorare l'operazione

Esegui il polling dello stato dell'operazione a lunga esecuzione utilizzando il metodo standard GetOperation 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 a eseguire 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 riesce, il campo done restituisce true e il campo error contiene i dettagli dell'errore correlati.

L'esempio seguente mostra una risposta GetOperation riuscita:

{
  "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: quando è impostato su true, l'operazione è completata.
state: quando è 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.

Elencare 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 tutte le operazioni LRO delle ultime 24 ore, aggiungi il filtro name: "operations/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/lro\""
  page_size: 100
}

L'esempio seguente mostra una risposta ListOperations riuscita:

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

Recuperare i risultati

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

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

L'esempio seguente mostra una 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 è 10000.
page_token: il token di una ListSearchedResultsResponse precedente utilizzato per recuperare la pagina successiva.
order_by: (facoltativo) Il campo viene utilizzato per ordinare i risultati.
- UDM events (eventRecord): utilizza i percorsi all'interno del campo udm, ad esempio, udm.metadata.timestamp desc o udm.principal.hostname asc. Sono supportati anche i nomi delle colonne che includono hostname, user, process name e event type.
  
  Il valore predefinito è udm.metadata.event_timestamp.
- Entities / ECG (entityContextRecord): utilizza i percorsi all'interno del campo entity, ad esempio, graph.entity.ip asc.
- data tables (dataTableRecord): utilizza 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 eventi ed entità, utilizza la variabile segnaposto che li definisce. Per tutte le altre origini, il formato rimane lo stesso.
  
  Ad esempio:
  - ECG (join UDM-ECG): Entity: $e1.graph.entity.hostname
  - UDM (tutti i join con UDM): $e1.principal.ip
  - Tabella dati (join UDM-tabella dati): %<table_alias>.<column_name>
  Sono supportati anche gli 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 se utilizzi page_token.

L'esempio seguente mostra una risposta ListSearchedResultsResponse riuscita:

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

Per recuperare la pagina successiva dei risultati, 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, tutti i risultati sono stati recuperati.

Passaggi successivi

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

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