메시지를 일괄적으로 해제 또는 거부하기

한 번에 여러 격리된 메일에 대해 조치를 취해야 하는 경우 Mail Admin Quarantine API에서 customers.quarantinedMessages 리소스의 일괄 메서드를 사용하세요.

  • batchRelease 메서드는 최대 500개의 메시지를 해제합니다.
  • batchDeny 메서드는 최대 500개의 메시지를 거부합니다.

두 메서드 모두 비동기식입니다. 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 메서드는 관리 격리 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인 경우에만 표시됩니다.

일부 개별 메시지가 실패하더라도 일괄 작업은 성공합니다. 작업의 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')}")

다음 단계