Merilis atau menolak pesan dalam batch

Jika Anda perlu menindaklanjuti banyak pesan yang dikarantina sekaligus, gunakan metode batch resource customers.quarantinedMessages di Mail Admin Quarantine API:

Kedua metode tersebut bersifat asinkron. API menerima permintaan, menampilkan operasi yang berjalan lama, dan memproses pesan di latar belakang. Kemudian, Anda melakukan polling pada metode get dari resource customers.operations hingga operasi selesai dan membaca hasil per pesan dari respons.

Dibandingkan dengan memanggil metode pesan tunggal dalam loop, metode batch dihitung sebagai satu permintaan tulis terhadap penggunaan kuota Anda, terlepas dari jumlah pesan yang dimuat.

Prasyarat

Memulai operasi batch

Untuk merilis pesan dalam batch, kirim permintaan POST ke metode kustom :batchRelease pada resource customers.quarantinedMessages. Array requests berisi satu objek per pesan, masing-masing dengan nama resource pesan:

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"}
  ]
}

Untuk menolak pesan dalam batch, kirim isi permintaan yang sama ke metode kustom :batchDeny pada resource customers.quarantinedMessages:

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

Setiap permintaan harus berisi antara 1 dan 500 entri. Setiap pesan harus dimiliki oleh pelanggan di jalur permintaan. Permintaan dengan lebih dari 500 entri akan menampilkan error 400 INVALID_ARGUMENT.

API akan segera merespons dengan resource 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
}

Simpan name operasi. Anda memerlukannya untuk memeriksa progres operasi.

Memeriksa status operasi batch

Untuk memeriksa progres operasi batch, kirim permintaan GET ke metode get pada nama resource operasi:

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

Metode get menerima cakupan Admin Quarantine API, sehingga integrasi hanya baca dapat memantau operasi yang dimulai oleh sistem lain.

Saat operasi berjalan, kolom done ditetapkan ke false dan kolom metadata melaporkan progres:

Kolom metadata Deskripsi
state PROCESSING saat pesan sedang diproses, lalu SUCCEEDED atau FAILED.
processedCount Jumlah pesan yang diproses sejauh ini.
totalCount Jumlah total pesan dalam batch.

Setelah operasi selesai, kolom done ditetapkan ke true dan kolom response berisi hasil untuk setiap pesan dalam batch:

{
  "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"
        }
      }
    ]
  }
}

Setiap entri di results menjelaskan hasil untuk satu pesan:

Kolom hasil Deskripsi
name Nama resource pesan.
status google.rpc.Status. Objek kosong (kode 0, OK) berarti tindakan berhasil. Jika tidak, code dan message akan menjelaskan alasan pesan dilewati.
quarantinedMessage Pesan yang diperbarui dengan state barunya. Hanya ada jika status adalah OK.

Operasi batch berhasil meskipun beberapa pesan individual gagal. Selalu periksa status setiap hasil, bukan hanya mengandalkan state operasi.

Jika seluruh operasi gagal, misalnya karena backend tidak tersedia, kolom done ditetapkan ke true dan kolom error berisi google.rpc.Status, bukan response.

Contoh: Rilis batch dan polling untuk penyelesaian

Contoh Python berikut memulai rilis batch dan melakukan polling operasi setiap beberapa detik hingga selesai:

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

Langkah berikutnya