‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

فهرست کردن و جستجوی پیام‌های قرنطینه‌شده

این صفحه توضیح می‌دهد که چگونه بااستفاده از Mail Admin Quarantine API پیام‌هایی را که در قرنطینه‌های سرپرست Google Workspace شما نگهداری می‌شوند پیدا کنید.

این میانای برنامه‌سازی کاربردی دو روش در منبع customers.quarantinedMessages ارائه می‌دهد:

روش list پیام‌های قرنطینه‌شده را بدون هیچ فیلتری برمی‌گرداند. از آن برای ورق زدن همه موارد موجود در قرنطینه‌ها استفاده کنید.
روش search نتایج را با فیلتر ساختاریافته، پرسمان جستجوی Gmail، یا هر دو محدود می‌کند. از آن برای گردش‌های کاری تریاژ استفاده کنید، مثلاً فقط برای بازیابی پیام‌های ورودی که درانتظار بازبینی هستند.

هر دو روش پیام‌های ۳۰ روز گذشته را برمی‌گردانند و هر دو فراداده‌های پایه یکسانی را برای هر پیام برمی‌گردانند. برای بازیابی سرایندها، متن، پیوست‌ها، یا پیام خام، به دریافت جزئیات پیام مراجعه کنید.

پیش‌نیازها

مراحل را در راه‌اندازی API تکمیل کرده باشید.
یک کد دسترسی که خود را به‌جای سرپرستی با امتیاز قرنطینه سرپرست جا می‌زند و شامل دامنه https://www.googleapis.com/auth/gmail.admin.quarantine یا https://www.googleapis.com/auth/gmail.admin.quarantine.readonly است. مجاز کردن با واگذاری در سراسر دامنه را ببینید.

فهرست کردن پیام‌های قرنطینه‌شده

برای فهرست کردن پیام‌های قرنطینه‌شده، درخواست GET را به روش list در منبع customers.quarantinedMessages مشتری‌تان ارسال کنید:

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

CUSTOMER_ID را با شناسه مشتری خودتان جایگزین کنید.

روش list پارامترهای پُرسمان زیر را می‌پذیرد:

پارامتر	شرح
`pageSize`	حداکثر تعداد پیام‌هایی که در هر صفحه برگردانده می‌شود، از ۱ تا ۳۰۰. همیشه این پارامتر را به‌طور صریح تنظیم کنید.
`pageToken`	مقدار `nextPageToken` از پاسخ قبلی. از آن برای بازیابی صفحه بعدی استفاده کنید.

جستجوی پیام‌های قرنطینه‌شده

برای جستجوی پیام‌های قرنطینه‌شده، درخواست POST را به روش سفارشی :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`	حداکثر تعداد پیام‌هایی که در هر صفحه برگردانده می‌شود، از ۱ تا ۳۰۰. همیشه این فیلد را به‌طور صریح تنظیم کنید.
`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`	نام منابع قرنطینه‌ای که پیام را نگه می‌دارند. برای دریافت نام نمایشی قرنطینه، روش `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.')