Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

นำส่งหรือปฏิเสธข้อความหลายรายการพร้อมกัน

เมื่อต้องการดำเนินการกับข้อความที่กักเก็บไว้หลายข้อความพร้อมกัน ให้ใช้วิธีการแบบกลุ่มของทรัพยากร customers.quarantinedMessages ใน Mail Admin Quarantine API ดังนี้

เมธอด batchRelease จะปล่อยข้อความได้สูงสุด 500 ข้อความ
เมธอด batchDeny จะปฏิเสธข้อความได้สูงสุด 500 ข้อความ

ทั้ง 2 วิธีเป็นแบบอะซิงโครนัส API จะยอมรับคำขอ แสดงผลการดำเนินการที่ใช้เวลานาน และประมวลผลข้อความในเบื้องหลัง จากนั้นคุณจะสำรวจเมธอด get ของทรัพยากร customers.operations จนกว่าการดำเนินการจะเสร็จสิ้น และอ่านผลลัพธ์ต่อข้อความจากการตอบกลับ

เมื่อเทียบกับการเรียกใช้เมธอดข้อความเดียวในลูป เมธอดแบบกลุ่มจะนับเป็นคำขอเขียน 1 รายการสำหรับการใช้โควต้าของคุณ ไม่ว่าจะมีข้อความกี่รายการก็ตาม

ข้อกำหนดเบื้องต้น

คุณได้ทำตามขั้นตอนในหัวข้อตั้งค่า API แล้ว
โทเค็นเพื่อการเข้าถึงที่แอบอ้างเป็นผู้ดูแลระบบที่มีสิทธิ์เขตกักบริเวณของผู้ดูแลระบบและรวมขอบเขต https://www.googleapis.com/auth/gmail.admin.quarantine ดูหัวข้อให้สิทธิ์ด้วยการมอบสิทธิ์ทั่วทั้งโดเมน
ชื่อทรัพยากรของข้อความที่ถูกกักบริเวณสูงสุด 500 ข้อความในสถานะ PENDING_TRIAGE ซึ่งคุณได้รับจากแสดงรายการและค้นหาข้อความที่ถูกกักบริเวณ

เริ่มการดำเนินการแบบกลุ่ม

หากต้องการปล่อยข้อความเป็นกลุ่ม ให้ส่งคำขอ POST ไปยังเมธอดที่กำหนดเอง :batchRelease ในทรัพยากร customers.quarantinedMessages อาร์เรย์ requests มีออบเจ็กต์ 1 รายการต่อข้อความ โดยแต่ละรายการจะมีชื่อทรัพยากรของข้อความดังนี้

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

คำขอแต่ละรายการต้องมีระหว่าง 1 ถึง 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 ไปยังเมธอด 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 จะอธิบายผลลัพธ์ของข้อความ 1 รายการ ดังนี้

ฟิลด์ผลลัพธ์	คำอธิบาย
`name`	ชื่อทรัพยากรของข้อความ
`status`	`google.rpc.Status` ออบเจ็กต์ว่างเปล่า (รหัส `0`, `OK`) หมายความว่าการดำเนินการสำเร็จ มิฉะนั้น `code` และ `message` จะอธิบายสาเหตุที่ข้ามข้อความ
`quarantinedMessage`	ข้อความที่อัปเดตพร้อม `state` ใหม่ แสดงเฉพาะเมื่อ `status` เป็น `OK`

การดำเนินการแบบกลุ่มจะสำเร็จแม้ว่าข้อความบางรายการจะดำเนินการไม่สำเร็จก็ตาม ตรวจสอบ status ของผลลัพธ์แต่ละรายการเสมอ แทนที่จะอาศัย state ของการดำเนินการเพียงอย่างเดียว

หากการดำเนินการทั้งหมดล้มเหลว เช่น เนื่องจากแบ็กเอนด์ไม่พร้อมใช้งาน ระบบจะตั้งค่าช่อง done เป็น true และช่อง error จะมี google.rpc.Status แทน response

ตัวอย่าง: การเผยแพร่แบบกลุ่มและการสำรวจเพื่อความสมบูรณ์

ตัวอย่าง Python ต่อไปนี้จะเริ่มการเผยแพร่แบบกลุ่มและสํารวจการดําเนินการทุกๆ 2-3 วินาทีจนกว่าจะเสร็จสมบูรณ์

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')}")

ขั้นตอนถัดไป

โควต้าการใช้งาน Mail Admin Quarantine API