ממשקי 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 לשיטה המותאמת אישית 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
/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"
}

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

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

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

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

• הפניית Google SecOps API בארכיטקטורת REST גרסה v1alpha
• search method
• ListSearchedResults method

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