メッセージを一括で解放または拒否する

複数の検疫済みメッセージに対して一度に操作を行う必要がある場合は、Mail Admin Quarantine API の customers.quarantinedMessages リソースのバッチメソッドを使用します。

  • batchRelease メソッドは、最大 500 件のメッセージを解放します。
  • batchDeny メソッドは、最大 500 件のメッセージを拒否します。

どちらのメソッドも非同期です。API はリクエストを受け入れ、長時間実行オペレーションを返し、バックグラウンドでメッセージを処理します。次に、オペレーションが完了するまで customers.operations リソースの get メソッドをポーリングし、レスポンスからメッセージごとの結果を読み取ります。

ループ内で単一メッセージ メソッドを呼び出す場合と比較して、バッチ メソッドは、含まれるメッセージの数に関係なく、割り当て使用量に対して 1 つの書き込みリクエストとしてカウントされます。

前提条件

バッチ オペレーションを開始する

メッセージをバッチで解放するには、customers.quarantinedMessages リソースの :batchRelease カスタム メソッドに POST リクエストを送信します。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"}
  ]
}

バッチ内のメッセージを拒否するには、代わりに 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 を保存します。これは、オペレーションの進行状況を確認するために必要です。

バッチ オペレーションのステータスを確認する

バッチ オペレーションの進行状況を確認するには、オペレーションのリソース名で 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 の場合にのみ存在します。

バッチ オペレーションは、個々のメッセージが失敗した場合でも成功します。オペレーションの state のみに依存するのではなく、各結果の status を常に確認してください。

バックエンドが使用できないなどの理由でオペレーション全体が失敗した場合、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')}")

次のステップ