批次放行或拒絕郵件

如要一次處理多封隔離郵件，請使用 Mail Admin Quarantine API 中 customers.quarantinedMessages 資源的批次方法：

這兩種方法都是非同步。API 會接受要求、傳回長時間執行的作業，並在背景處理訊息。接著，您會輪詢 customers.operations 資源的 get 方法，直到作業完成，並從回應中讀取每則訊息的結果。

與在迴圈中呼叫單一訊息方法相比，無論包含多少訊息，批次方法都會計為一項寫入要求，計入配額用量。

必要條件

啟動批次作業

如要批次釋出訊息，請向 customers.quarantinedMessages 資源上的 :batchRelease 自訂方法傳送 POST 要求。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"}
  ]
}

如要拒絕批次中的訊息，請改為將相同的要求主體傳送至 customers.quarantinedMessages 資源上的 :batchDeny 自訂方法：

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。您需要使用這個 ID 來查看作業進度。

查看批次作業狀態

如要查看批次作業的進度，請對作業的資源名稱，傳送 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')}")

後續步驟