Nous avons réorganisé la structure de navigation de notre documentation pour l'aligner directement sur vos workflows opérationnels. Pour en savoir plus, consultez les notes de version et la vidéo de présentation.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

API de recherche asynchrone

Compatible avec :

Google secops SIEM

La plate-forme de recherche de Google Security Operations vous permet d'utiliser des API asynchrones pour les requêtes de longue durée qui renvoient des ensembles de résultats volumineux (jusqu'à un million de résultats). Ces API vous permettent de lancer des recherches dans des sources de données, y compris les événements UDM (Unified Data Model), les détections, les tables de données et le graphique de contexte d'entité (ECG), sans bloquer votre application. Lorsque vous exécutez une requête de recherche à l'aide d'une API d'opération de longue durée (LRO), vous recevez un ID d'opération. Vous pouvez utiliser cet ID pour surveiller l'état de l'opération et obtenir les résultats page par page.

Prérequis

Pour utiliser les API d'opération de longue durée, le principal appelant doit disposer d'autorisations Identity and Access Management (IAM) spécifiques.

Pour effectuer les actions suivantes, vous devez disposer des autorisations IAM correspondantes :

Lancer une recherche : chronicle.searchSessions.search
Répertorier les résultats : chronicle.searchedResults.list sur la ressource SearchSession

Assurez-vous que le principal appelant dispose d'un rôle qui accorde ces autorisations, par exemple le rôle Lecteur de l'API Chronicle, Éditeur de l'API Chronicle ou Administrateur de l'API Chronicle.

Exécuter une recherche à l'aide des API LRO

Pour exécuter une recherche à l'aide des API LRO, procédez comme suit :

Lancez la recherche.
Surveillez l'opération.
Récupérez les résultats.

Lancer la recherche

Envoyez une requête POST à la méthode personnalisée search sur l'instance Google SecOps.

Point de terminaison : POST /{$api_version}/projects/{project}/locations/{location}/instances/{instance}:search
Méthode : Search
Corps de la requête : SearchRequest

L'exemple suivant montre un objet 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 requête nécessite les paramètres clés suivants :

query : chaîne de requête de recherche
time_range : intervalle de temps pour la recherche
dialect : spécifie le dialecte de la langue comme YL2
result_limit : facultatif. Nombre maximal de lignes à matérialiser. La valeur par défaut est 10000, et la valeur maximale est 1000000.

Cet appel renvoie un objet google.longrunning.Operation.

L'exemple suivant montre une réponse d'opération réussie :

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

Le champ state: RUNNING indique que la recherche est en cours.

Surveiller l'opération

Interrogez l'état de la LRO à l'aide de la méthode GetOperation standard du service google.longrunning.Operations. Utilisez la valeur name de la réponse précédente.

Point de terminaison : GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}/operations/{operationID}

Continuez à interroger jusqu'à ce que le champ done de la réponse GetOperation renvoie true.

Si l'opération réussit, le champ metadata.state renvoie SUCCEEDED, et le champ de réponse contient la ressource SearchSession créée.
Si l'opération échoue, le champ done renvoie true, et le champ d'erreur contient les détails de l'échec associé.

L'exemple suivant montre une réponse GetOperation réussie :

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

Le format du nom de la ressource SearchSession est projects/{project}/locations/{location}/instances/{instance}/searchSessions/{search_session}.

La réponse réussie contient les champs clés suivants :

done : lorsque la valeur est true, l'opération est terminée.
state : lorsque la valeur est SUCCEEDED, la recherche s'est terminée correctement.
response.name : nom de la ressource SearchSession. Utilisez cette valeur comme propriété parente à l'étape suivante.
response.metadata.resultRowCount : indique le nombre total de lignes trouvées.
response.metadata.moreDataAvailable: indique que le nombre de résultats disponibles dépasse la limite de retour définie.

Répertorier les opérations LRO

Pour répertorier les opérations LRO, utilisez la méthode ListOperations du service google.longrunning.Operations. Utilisez la valeur name de la réponse précédente.

Point de terminaison: GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}

Pour répertorier toutes les opérations LRO des dernières 24 heures, ajoutez le filtre name: "operations/s-lro".

L'exemple suivant montre une requête ListOperations réussie :

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

L'exemple suivant montre une réponse ListOperations réussie :

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

Récupérer les résultats

Une fois que l'état de l'opération renvoie SUCCEEDED, utilisez la méthode ListSearchedResults() pour récupérer les résultats de la recherche.

Point de terminaison: GET /{$api_version}/{parent=projects/*/locations/*/instances/*/searchSessions/*}/searchedResults
Méthode : ListSearchedResults
Paramètres de requête : ListSearchedResultsRequest

L'exemple suivant montre une ListSearchedResultsRequest qui récupère trois résultats et ignore les cinq premiers :

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

La requête accepte les paramètres de requête suivants :

page_size : nombre maximal de résultats à renvoyer par page. La valeur par défaut est 100, et la valeur maximale est 10 000.
page_token: jeton d'une ListSearchedResultsResponse précédente utilisé pour récupérer la page suivante.
order_by : facultatif. Le champ est utilisé pour trier les résultats.
- UDM events (eventRecord) : utilisez des chemins d'accès dans le champ udm, par exemple udm.metadata.timestamp desc ou udm.principal.hostname asc. Les noms de colonnes incluant hostname, user, process name et event type sont également acceptés.
  
  La valeur par défaut est udm.metadata.event_timestamp.
- Entities / ECG (entityContextRecord) : utilisez des chemins d'accès dans le champ entity, par exemple graph.entity.ip asc.
- data tables (dataTableRecord) : utilisez le format %<table_alias>.<column_name>. Par exemple, %dt.user desc.
  
  La valeur par défaut est la première colonne de la table de données.
- Detections (DetectionRecord) : utilisez le mot clé detection suivi du chemin d'accès, par exemple detection.id.
- Jointures : pour les événements et les entités, utilisez la variable d'espace réservé qui les définit. Pour toutes les autres sources, le format reste le même.
  
  Exemple :
  - ECG (jointure UDM-ECG) : entité : $e1.graph.entity.hostname
  - UDM (toutes les jointures avec UDM) : $e1.principal.ip
  - Table de données (jointure UDM-table de données) : %<table_alias>.<column_name>
  Les alias prédéfinis tels que hostname, user, process name et event type sont également acceptés. Pour ces alias, utilisez le format $e1.hostname.at.
- skip : facultatif. Nombre de résultats à ignorer. N'utilisez pas ce paramètre si vous utilisez page_token.

L'exemple suivant montre une réponse ListSearchedResultsResponse réussie :

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

Pour récupérer la page de résultats suivante, utilisez la valeur nextPageToken renvoyée dans le paramètre de requête page_token de votre prochaine requête ListSearchedResults. Le champ resultRow contient les données réelles.

Continuez à appeler ListSearchedResults avec la valeur next_page_token de chaque réponse. Lorsque next_page_token renvoie une valeur vide, tous les résultats ont été récupérés.

Étape suivante

Pour en savoir plus sur les méthodes, les champs de requête et de réponse, et les types, consultez la documentation de référence de l'API suivante :

Vous avez encore besoin d'aide ? Obtenez des réponses auprès des membres de la communauté et des professionnels Google SecOps.