‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

הצגה וחיפוש של הודעות בהסגר

בדף הזה מוסבר איך למצוא את ההודעות שמוחזקות בהסגרים של האדמין ב-Google Workspace באמצעות Mail Admin Quarantine API.

ה-API מציע שתי שיטות במשאב customers.quarantinedMessages:

השיטה list מחזירה הודעות בהסגר בלי סינון. אפשר להשתמש בו כדי לדפדף בין כל הפריטים בהסגר.
השיטה search מצמצמת את התוצאות באמצעות מסנן מובנה, שאילתת חיפוש ב-Gmail או שניהם. אפשר להשתמש בו לתהליכי עבודה של מיון, כמו אחזור של הודעות נכנסות בלבד שממתינות לבדיקה.

שתי השיטות מחזירות הודעות מ-30 הימים האחרונים, ושתיהן מחזירות את אותם מטא-נתונים בסיסיים לכל הודעה. כדי לאחזר כותרות, גוף, קבצים מצורפים או את ההודעה הגולמית, ראו קבלת פרטי ההודעה.

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

השלמתם את השלבים שמפורטים בקטע הגדרת ה-API.
אסימון גישה שמתחזה לאדמין עם הרשאת הסגר של אדמין, וכולל את ההיקף https://www.googleapis.com/auth/gmail.admin.quarantine או https://www.googleapis.com/auth/gmail.admin.quarantine.readonly. מידע נוסף זמין במאמר אישור באמצעות הענקת גישה ברמת הדומיין.

הצגת רשימה של הודעות בהסגר

כדי להציג רשימה של הודעות בהסגר, שולחים בקשת GET ל-method‏ list במשאב customers.quarantinedMessages של הלקוח:

GET https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages?pageSize=50
Authorization: Bearer ACCESS_TOKEN

מחליפים את CUSTOMER_ID במספר הלקוח.

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

פרמטר	תיאור
`pageSize`	המספר המקסימלי של הודעות שיוחזרו בכל דף, מ-1 עד 300. תמיד צריך להגדיר את הפרמטר הזה באופן מפורש.
`pageToken`	הערך `nextPageToken` מתגובה קודמת. אפשר להשתמש בו כדי לאחזר את הדף הבא.

חיפוש הודעות בהסגר

כדי לחפש הודעות בהסגר, שולחים בקשת POST ל-method המותאם אישית :search במשאב customers.quarantinedMessages עם גוף JSON:

POST https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages:search
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "filter": "status = PENDING_TRIAGE AND direction = INBOUND",
  "query": "from:suspicious@example.com",
  "pageSize": 50
}

גוף הבקשה מקבל את השדות הבאים. כל השדות הם אופציונליים:

שדה	תיאור
`filter`	מסנן מובנה בתחביר AIP-160. תחביר של מסננים
`query`	שאילתת חיפוש ב-Gmail, כמו `has:attachment` או `from:suspicious@example.com`. השאילתה משתמשת באותם אופרטורים כמו חיפוש ב-Gmail. סימנים או מילים למיקוד החיפוש ב-Gmail
`pageSize`	המספר המקסימלי של הודעות שיוחזרו בכל דף, מ-1 עד 300. תמיד צריך להגדיר את השדה הזה באופן מפורש.
`pageToken`	הערך `nextPageToken` מתגובה קודמת.

כשמגדירים גם את filter וגם את query, ה-API מחזיר רק הודעות שתואמות לשניהם.

תחביר המסנן

השדה filter תומך בשדות הבאים. אפשר לשלב אותם עם האופרטור AND. אין תמיכה באופרטורים אחרים, כמו OR ו-NOT.

שדה	השוואות נתמכות	ערכים
`status`	`=`	‫`PENDING_TRIAGE`, `RELEASED` או `DENIED`.
`direction`	`=`, `!=`	‫`INBOUND` או `OUTBOUND`.
`quarantine_name` (או `quarantineName`)	`=`	השם המוצג של הסגר כפי שהוא מופיע במסוף Google Admin, לדוגמה `"Default"`.

הדוגמאות הבאות מציגות מסננים תקינים:

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

מסנן לא תקין מחזיר שגיאת 400 INVALID_ARGUMENT.

תשובה

שתי השיטות מחזירות רשימה של משאבי QuarantinedMessage עם מטא-נתונים בסיסיים, וגם nextPageToken אם יש עוד תוצאות זמינות:

{
  "quarantinedMessages": [
    {
      "name": "customers/01abc23de/quarantinedMessages/user@example.com:18d3ef45a8b2c1d0",
      "messageId": "18d3ef45a8b2c1d0",
      "messageOwner": "user@example.com",
      "quarantines": [
        "customers/01abc23de/quarantines/0"
      ],
      "receiveTime": "2026-09-22T10:15:30Z",
      "direction": "INBOUND",
      "state": "PENDING_TRIAGE",
      "retentionExpireTime": "2026-10-22T10:15:30Z",
      "triggeredRules": [
        {
          "policyId": "123",
          "ruleId": "456",
          "displayName": "Inbound phishing protection"
        }
      ]
    }
  ],
  "nextPageToken": "CAESBAgBEA..."
}

שדה	תיאור
`name`	שם המשאב של ההודעה. משתמשים בו בקריאות הבאות ל-`get`, ל-`release` ול-`deny` במשאב `customers.quarantinedMessages`.
`messageId`	המזהה הקבוע של ההודעה ב-Gmail.
`messageOwner`	כתובת האימייל של תיבת הדואר שההודעה שייכת לה.
`quarantines`	שמות המשאבים של ההסגרים שבהם נמצאת ההודעה. קוראים ל-method‏ `get` של המשאב `customers.quarantines` כדי לקבל את השם המוצג של ההסגר.
`receiveTime`	מתי ההודעה התקבלה ב-Gmail.
`direction`	`INBOUND` אם המשתמש קיבל את ההודעה, או `OUTBOUND` אם המשתמש שלח אותה.
`state`	‫`PENDING_TRIAGE`, `RELEASED` או `DENIED`.
`retentionExpireTime`	כשההודעה מוסרת מההסגר.
`triggeredRules`	הכללים שגרמו להעברת ההודעה להסגר.
`unreachable`	חשבונות שהשירות לא הצליח לאחזר מהם הודעות שהועברו להסגר. אם יש בעיה, נסו שוב מאוחר יותר.

מעבר בין דפי התוצאות

כדי לאחזר את כל ההודעות התואמות:

שולחים את הבקשה הראשונה עם pageSize.
אם התשובה מכילה nextPageToken, חוזרים על הבקשה עם אותם פרמטרים ומגדירים את pageToken לערך הזה.
עוצרים כשהתשובה לא מכילה nextPageToken.

בדוגמה הבאה ב-Python, עוברים על כל ההודעות הנכנסות שממתינות למיון:

import requests

BASE_URL = 'https://mailadminquarantine.googleapis.com/v1'
CUSTOMER_ID = '01abc23de'  # Your customer ID without the leading 'C'.
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',
}

search_url = f'{BASE_URL}/customers/{CUSTOMER_ID}/quarantinedMessages:search'
body = {
    'filter': 'status = PENDING_TRIAGE AND direction = INBOUND',
    'pageSize': 100,
}
messages = []
while True:
  response = requests.post(search_url, headers=headers, json=body)
  response.raise_for_status()
  result = response.json()
  messages.extend(result.get('quarantinedMessages', []))
  page_token = result.get('nextPageToken')
  if not page_token:
    break
  body['pageToken'] = page_token

print(f'Found {len(messages)} messages pending triage.')