إصدار الرسائل أو رفضها على دفعات

عند الحاجة إلى اتخاذ إجراء بشأن العديد من الرسائل المعزولة في آنٍ واحد، استخدِم طرق الدفعات لمورد customers.quarantinedMessages في Mail Admin Quarantine API:

  • تتيح طريقة batchRelease إصدار ما يصل إلى 500 رسالة.
  • تؤدي طريقة batchDeny إلى رفض ما يصل إلى 500 رسالة.

كلتا الطريقتَين غير متزامنتَين. تقبل واجهة برمجة التطبيقات الطلب، وتعرض عملية طويلة الأمد، وتعالج الرسائل في الخلفية. بعد ذلك، يمكنك استطلاع طريقة get لمورد customers.operations إلى أن تكتمل العملية وقراءة النتائج لكل رسالة من الردّ.

مقارنةً باستدعاء طرق الرسالة الواحدة في حلقة، يتم احتساب طرق الدفعات كطلب كتابة واحد مقابل استخدام الحصة بغض النظر عن عدد الرسائل التي تحتوي عليها.

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

بدء عملية مجمّعة

لإصدار الرسائل بشكل مجمّع، أرسِل طلب POST إلى الطريقة المخصّصة :batchRelease في المورد customers.quarantinedMessages. تحتوي مصفوفة requests على عنصر واحد لكل رسالة، ولكل عنصر اسم المورد الخاص بالرسالة:

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

{
  "requests": [
    {"name": "customers/CUSTOMER_ID/quarantinedMessages/user1@example.com:18d3ef45a8b2c1d0"},
    {"name": "customers/CUSTOMER_ID/quarantinedMessages/user2@example.com:18d3ef45a8b2c1d1"}
  ]
}

لرفض الرسائل بشكل مجمّع، أرسِل نص الطلب نفسه إلى الطريقة المخصّصة :batchDeny في مورد customers.quarantinedMessages بدلاً من ذلك:

POST https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages:batchDeny

يجب أن يحتوي كل طلب على عدد يتراوح بين إدخال واحد و500 إدخال. يجب أن تنتمي كل رسالة إلى العميل في مسار الطلب. إذا كان الطلب يتضمّن أكثر من 500 إدخال، يظهر الخطأ 400 INVALID_ARGUMENT.

تستجيب واجهة برمجة التطبيقات على الفور باستخدام المورد Operation:

{
  "name": "customers/01abc23de/operations/7f1c2a0e-5b7d-4d3a-9c1e-2f4b6a8d0e13",
  "metadata": {
    "@type": "type.googleapis.com/google.gmail.mailadminquarantine.v1.BatchReleaseQuarantinedMessagesMetadata",
    "state": "PROCESSING",
    "processedCount": 0,
    "totalCount": 2
  },
  "done": false
}

يتم تخزين name العملية. ستحتاج إليه للتحقّق من مستوى تقدّم العملية.

الاطّلاع على حالة عملية مجمّعة

للاطّلاع على مستوى تقدّم عملية مجمّعة، أرسِل طلب GET إلى طريقة get على اسم مورد العملية:

GET https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/operations/OPERATION_ID
Authorization: Bearer ACCESS_TOKEN

تقبل طريقة get أيًا من نطاقَي Admin Quarantine API، وبالتالي يمكن لعملية دمج تتضمّن إذنًا بالقراءة فقط مراقبة العمليات التي بدأها نظام آخر.

أثناء تنفيذ العملية، يتم ضبط الحقل done على false ويعرض الحقل metadata مستوى التقدّم:

حقل البيانات الوصفية الوصف
state PROCESSING أثناء معالجة الرسائل، ثم SUCCEEDED أو FAILED.
processedCount عدد الرسائل التي تمت معالجتها حتى الآن
totalCount إجمالي عدد الرسائل في الدفعة

عند انتهاء العملية، يتم ضبط الحقل done على true ويحتوي الحقل response على نتيجة لكل رسالة في الدفعة:

{
  "name": "customers/01abc23de/operations/7f1c2a0e-5b7d-4d3a-9c1e-2f4b6a8d0e13",
  "metadata": {
    "@type": "type.googleapis.com/google.gmail.mailadminquarantine.v1.BatchReleaseQuarantinedMessagesMetadata",
    "state": "SUCCEEDED",
    "processedCount": 2,
    "totalCount": 2
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.gmail.mailadminquarantine.v1.BatchReleaseQuarantinedMessagesResponse",
    "results": [
      {
        "name": "customers/01abc23de/quarantinedMessages/user1@example.com:18d3ef45a8b2c1d0",
        "status": {},
        "quarantinedMessage": {
          "name": "customers/01abc23de/quarantinedMessages/user1@example.com:18d3ef45a8b2c1d0",
          "messageId": "18d3ef45a8b2c1d0",
          "messageOwner": "user1@example.com",
          "state": "RELEASED"
        }
      },
      {
        "name": "customers/01abc23de/quarantinedMessages/user2@example.com:18d3ef45a8b2c1d1",
        "status": {
          "code": 5,
          "message": "Quarantined message not found"
        }
      }
    ]
  }
}

يصف كل إدخال في results نتيجة رسالة واحدة:

حقل النتيجة الوصف
name اسم مورد الرسالة
status google.rpc.Status يعني العنصر الفارغ (الرمز 0، OK) أنّ الإجراء قد نجح. وإلا، يوضّح code وmessage سبب تخطّي الرسالة.
quarantinedMessage الرسالة المعدَّلة مع state الجديد يظهر فقط عندما تكون قيمة status هي OK.

تنجح العملية المجمّعة حتى في حال تعذُّر إرسال بعض الرسائل الفردية. يجب دائمًا فحص status لكل نتيجة بدلاً من الاعتماد على state للعملية فقط.

إذا تعذّر تنفيذ العملية بالكامل، على سبيل المثال بسبب عدم توفّر الخلفية، يتم ضبط الحقل done على true ويحتوي الحقل error على google.rpc.Status بدلاً من response.

مثال: إصدار الدفعة واستطلاع الرأي لإكمالها

يبدأ مثال Python التالي عملية إصدار مجمّع ويستطلع العملية كل بضع ثوانٍ إلى أن تكتمل:

import time
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',
}

# message_names is a list of up to 500 quarantined message resource names.
batch_url = f'{BASE_URL}/customers/{CUSTOMER_ID}/quarantinedMessages:batchRelease'
body = {'requests': [{'name': name} for name in message_names]}
operation = requests.post(batch_url, headers=headers, json=body)
operation.raise_for_status()
operation_name = operation.json()['name']

while True:
  status = requests.get(f'{BASE_URL}/{operation_name}', headers=headers)
  status.raise_for_status()
  operation = status.json()
  if operation.get('done'):
    break
  metadata = operation.get('metadata', {})
  print(f"Processed {metadata.get('processedCount', 0)} of "
        f"{metadata.get('totalCount', 0)} messages...")
  time.sleep(5)

if 'error' in operation:
  raise RuntimeError(f"Batch failed: {operation['error']}")

for result in operation['response'].get('results', []):
  if result.get('status', {}).get('code', 0) == 0:
    print(f"Released: {result['name']}")
  else:
    print(f"Skipped {result['name']}: {result['status'].get('message')}")

الخطوات التالية