تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

عرض الرسائل المعزولة والبحث عنها

توضّح هذه الصفحة كيفية العثور على الرسائل المحتجَزة في وحدات عزل مشرفي حسابات Google Workspace باستخدام Mail Admin Quarantine API.

توفّر واجهة برمجة التطبيقات طريقتَين في المورد customers.quarantinedMessages:

تُنتج الطريقة list الرسائل المعزولة بدون أي فلترة. يمكنك استخدامها للتصفّح بين كل العناصر في وحدات العزل.
تضيّق الطريقة search النتائج باستخدام فلتر منظَّم أو طلب بحث في Gmail أو كليهما. يمكنك استخدامها في سير عمل الفرز، مثل استرداد الرسائل الواردة التي تنتظر المراجعة فقط.

تعرض كلتا الطريقتين الرسائل من آخر 30 يومًا، وتعرض كلتاهما البيانات الوصفية الأساسية نفسها لكل رسالة. لاسترداد الرؤوس أو النص أو المرفقات أو الرسالة الأولية، يُرجى الاطّلاع على الحصول على تفاصيل الرسالة.

المتطلبات الأساسية

أكملت الخطوات الواردة في مقالة إعداد واجهة برمجة التطبيقات.
رمز الدخول الذي ينتحل هوية مشرف لديه إذن مميّز لعزل المشرف ويتضمّن نطاق 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`	الحد الأقصى لعدد الرسائل التي يتم عرضها في كل صفحة، من 1 إلى 300. اضبط هذه المَعلمة دائمًا بشكل صريح.
`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`	الحد الأقصى لعدد الرسائل التي يتم عرضها في كل صفحة، من 1 إلى 300. يجب ضبط هذا الحقل دائمًا بشكل صريح.
`pageToken`	قيمة `nextPageToken` من ردّ سابق

عند ضبط كل من filter وquery، تعرض واجهة برمجة التطبيقات الرسائل التي تتطابق مع كليهما فقط.

بنية الفلتر

يتيح الحقل filter استخدام الحقول التالية. اجمعها مع عامل التشغيل AND. لا يمكن استخدام عوامل تشغيل أخرى، مثل OR وNOT.

الحقل	المقارنات المتوافقة	القيم
`status`	`=`	`PENDING_TRIAGE` أو `RELEASED` أو `DENIED`
`direction`	‫`=`، `!=`	‫`INBOUND` أو `OUTBOUND`
‫`quarantine_name` (أو `quarantineName`)	`=`	الاسم المعروض لوحدة العزل كما يظهر في "وحدة تحكّم المشرف في Google"، على سبيل المثال `"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.')