انتشار یا رد کردن پیام‌ها به‌صورت دسته‌ای

وقتی لازم است روی تعداد زیادی پیام قرنطینه‌شده به‌طور هم‌زمان اقدام کنید، از روش‌های دسته‌ای منبع customers.quarantinedMessages در Mail Admin Quarantine API استفاده کنید:

  • روش batchRelease حداکثر ۵۰۰ پیام را منتشر می‌کند.
  • روش batchDeny حداکثر ۵۰۰ پیام را رد می‌کند.

هر دو روش ناهمگام هستند. ‫API درخواست را می‌پذیرد، یک عملیات طولانی‌مدت برمی‌گرداند، و پیام‌ها را در پس‌زمینه پردازش می‌کند. سپس روش 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

هر درخواست باید بین ۱ تا ۵۰۰ ورودی داشته باشد. هر پیام باید به مشتری در مسیر درخواست تعلق داشته باشد. درخواست با بیش‌از ۵۰۰ ورودی خطای 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 به‌جای response حاوی google.rpc.Status است.

مثال: انتشار دسته‌ای و نظرسنجی برای تکمیل

نمونه 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')}")

مراحل بعدی