ממשקי API אסינכרוניים של חיפוש

נתמך ב:

Google secops SIEM

פלטפורמת החיפוש ב-Google Security Operations מאפשרת להשתמש בממשקי API אסינכרוניים לשאילתות ממושכות שמחזירות מערכי תוצאות גדולים של עד מיליון תוצאות. ממשקי ה-API האלה מאפשרים להתחיל חיפושים במקורות נתונים, כולל אירועים של Unified Data Model‏ (UDM), זיהויים, טבלאות נתונים ו-Entity Context Graph‏ (ECG), בלי לחסום את האפליקציה. כשמריצים שאילתת חיפוש באמצעות API של פעולה ממושכת (LRO), מקבלים מזהה פעולה. אפשר להשתמש במזהה הזה כדי לעקוב אחרי סטטוס הפעולה ולקבל את התוצאות דף אחרי דף.

דרישות מוקדמות

כדי להשתמש בממשקי API של פעולות ממושכות, לחשבון המשתמש שקורא ל-API נדרשות הרשאות ספציפיות לניהול זהויות והרשאות גישה (IAM).

כדי לבצע את הפעולות הבאות, אתם צריכים את הרשאות ה-IAM המתאימות:

• מפעילים חיפוש: chronicle.searchSessions.search
• רשימת התוצאות: chronicle.searchedResults.list במשאב SearchSession.

מוודאים שלחשבון המשתמש שקורא ל-API יש תפקיד שמעניק את ההרשאות האלה, למשל התפקיד 'צפייה ב-Chronicle API', 'עריכת Chronicle API' או 'אדמין של Chronicle API'.

הפעלת חיפוש באמצעות ממשקי LRO API

כדי להריץ חיפוש באמצעות ממשקי ה-API של LRO:

1. מתחילים את החיפוש.
2. מעקב אחר הפעולה.
3. אחזור התוצאות.

הפעלת החיפוש

שליחת בקשת POST ל-method המותאם אישית search במכונת Google SecOps.

• נקודת קצה (endpoint)‏: POST /{$api_version}/projects/{project}/locations/{location}/instances/{instance}:search
• שיטה: Search
• גוף הבקשה: SearchRequest

בדוגמה הבאה מוצג אובייקט 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"
}

הבקשה צריכה לכלול את הפרמטרים העיקריים הבאים:

• ‫query: מחרוזת שאילתת החיפוש.
• ‫time_range: מרווח הזמן לחיפוש.
• ‫dialect: מציינים את הניב של השפה כ-YL2.
• ‫result_limit: אופציונלי. מספר השורות המקסימלי שיוצגו. ערך ברירת המחדל הוא 10000, והערך המקסימלי הוא 1000000.

הקריאה הזו מחזירה אובייקט google.longrunning.Operation.

בדוגמה הבאה מוצגת תשובה של פעולה שבוצעה בהצלחה:

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

השדה state: RUNNING מציין שהחיפוש מתבצע.

מעקב אחר הפעולה

בודקים את הסטטוס של ה-LRO באמצעות השיטה הרגילה GetOperation מהשירות google.longrunning.Operations. משתמשים בערך name מהתשובה הקודמת.

• נקודת קצה: GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}/operations/{operationID}

ממשיכים לשלוח בקשות עד שהשדה done בתשובה GetOperation מחזיר את הערך true.

• אם הפעולה מצליחה, השדה metadata.state מחזיר SUCCEEDED, ושדה התגובה מכיל את משאב SearchSession שנוצר.
• אם הפעולה נכשלת, השדה done מחזיר true, ושדה השגיאה מכיל את פרטי הכשל הרלוונטיים.

בדוגמה הבאה מוצגת תגובה מוצלחת של GetOperation:

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

הפורמט של שם המשאב SearchSession הוא projects/{project}/locations/{location}/instances/{instance}/searchSessions/{search_session}.

התגובה שמתקבלת אחרי פעולה מוצלחת מכילה את שדות המפתח הבאים:

• ‫done: כשהערך מוגדר כ-true, הפעולה הושלמה.
• ‫state: כשמוגדר ל-SUCCEEDED, החיפוש הסתיים בהצלחה.
• ‫response.name: שם המשאב של SearchSession. משתמשים בערך הזה כמאפיין האב בשלב הבא.
• ‫response.metadata.resultRowCount: מציין את המספר הכולל של השורות שנמצאו.
• ‫response.metadata.moreDataAvailable: מציין שמספר התוצאות הזמינות חורג ממגבלת ההחזרה שהוגדרה.

הצגת פעולות LRO

כדי להציג רשימה של פעולות LRO, משתמשים בשיטה ListOperations מהשירות google.longrunning.Operations. משתמשים בערך name מהתשובה הקודמת.

• נקודת קצה: GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}

כדי להציג רשימה של כל פעולות ה-LRO מ-24 השעות האחרונות, מוסיפים את המסנן name: "operations/s-lro".

בדוגמה הבאה מוצגת בקשת ListOperations שבוצעה בהצלחה:

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

בדוגמה הבאה מוצגת תגובה מוצלחת של ListOperations:

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

אחזור התוצאות

אחרי שסטטוס הפעולה מחזיר SUCCEEDED, משתמשים בשיטה ListSearchedResults() כדי לאחזר את תוצאות החיפוש.

• נקודת קצה: GET /{$api_version}/{parent=projects/*/locations/*/instances/*/searchSessions/*}/searchedResults
• שיטה: ListSearchedResults
• פרמטרים של הבקשה: ListSearchedResultsRequest

בדוגמה הבאה מוצג ListSearchedResultsRequest שמחזיר שלוש תוצאות ומדלג על חמש הראשונות:

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

הבקשה תומכת בפרמטרים הבאים של השאילתה:

• ‫page_size: המספר המקסימלי של התוצאות שיוחזרו בכל דף. ערך ברירת המחדל הוא 100, והערך המקסימלי הוא 10,000.
• ‫page_token: הטוקן מקריאה קודמת של ListSearchedResultsResponse שמשמש לאחזור הדף הבא.

• ‫order_by: אופציונלי. השדה משמש למיון התוצאות.

  • ‫UDM events (eventRecord): משתמשים בנתיבים בשדה udm, לדוגמה, udm.metadata.timestamp desc או udm.principal.hostname asc. יש תמיכה גם בשמות עמודות, כולל hostname, ‏ user, ‏ process name ו-event type.

    ערך ברירת המחדל הוא udm.metadata.event_timestamp.

  • ‫Entities / ECG (entityContextRecord): משתמשים בנתיבים בשדה entity. לדוגמה, graph.entity.ip asc.

  • ‫data tables (dataTableRecord): צריך להשתמש בפורמט %<table_alias>.<column_name>. לדוגמה, %dt.user desc.

    ערך ברירת המחדל הוא העמודה הראשונה בטבלת הנתונים.

  • ‫Detections (DetectionRecord): משתמשים במילת המפתח detection ואחריה בנתיב, לדוגמה, detection.id.

  • צירופים: לאירועים ולרכיבים, משתמשים במשתנה placeholder שמגדיר אותם. בכל המקורות האחרים, הפורמט נשאר זהה.

    לדוגמה:

    • ECG (UDM-ECG join): Entity: $e1.graph.entity.hostname
    • ‫UDM (כל ההצטרפות ל-UDM): $e1.principal.ip
    • טבלת נתונים (UDM-Data table join): %<table_alias>.<column_name>

    יש גם תמיכה בכינויים מוגדרים מראש כמו hostname,‏ user,‏ process name ו-event type. לכן, צריך להשתמש בפורמט $e1.hostname.at.

  • ‫skip: אופציונלי. מספר התוצאות שיש לדלג עליהן. אין להשתמש אם משתמשים ב-page_token.

בדוגמה הבאה מוצגת תגובה מוצלחת של ListSearchedResultsResponse:

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

כדי לאחזר את דף התוצאות הבא, צריך להשתמש בערך nextPageToken שהוחזר בפרמטר השאילתה page_token של בקשת ListSearchedResults הבאה. השדה resultRow מכיל את הנתונים בפועל.

ממשיכים להתקשר אל ListSearchedResults עם הערך next_page_token מכל תגובה. כשמחזירים ערך ריק של next_page_token, כל התוצאות אוחזרו.

המאמרים הבאים

מידע נוסף על שיטות, שדות של בקשות ותגובות וסוגים זמין במאמרי העזרה הבאים בנושא API:

• הפניית Google SecOps REST API
• שיטת search
• שיטת ListSearchedResults

הבעיה עדיין לא נפתרה? קבלת תשובות מחברי הקהילה וממומחי Google SecOps.