שחרור או דחייה של הודעות בקבוצות

אם אתם צריכים לבצע פעולה על הרבה הודעות בהסגר בבת אחת, השתמשו בשיטות של משאב customers.quarantinedMessages ב-Mail Admin Quarantine API:

  • ה-method‏ batchRelease משחררת עד 500 הודעות.
  • השיטה batchDeny דוחה עד 500 הודעות.

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

בהשוואה להפעלת השיטות של הודעה בודדת בלולאה, שיטות באצווה נספרות כבקשת כתיבה אחת בניצול המכסה, בלי קשר למספר ההודעות שהן מכילות.

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

התחלת פעולה בכמות גדולה

כדי לשחרר הודעות באצווה, שולחים בקשת POST ל-method המותאם אישית :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"}
  ]
}

כדי לדחות הודעות בכמות גדולה, שולחים את אותו גוף בקשה ל-method המותאם אישית :batchDeny במשאב customers.quarantinedMessages:

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

כל בקשה חייבת להכיל בין רשומה אחת ל-500 רשומות. כל הודעה חייבת להיות שייכת ללקוח בנתיב הבקשה. בקשה עם יותר מ-500 רשומות מחזירה שגיאת 400 INVALID_ARGUMENT.

ה-API מגיב מיד עם משאב 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 ל-method‏ get בשם המשאב של הפעולה:

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

ה-method‏ 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 של הפעולה.

אם הפעולה כולה נכשלת, למשל כי ה-backend לא זמין, השדה 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')}")

השלבים הבאים