Phát hành hoặc từ chối thư theo lô

Khi bạn cần xử lý nhiều thư bị cách ly cùng một lúc, hãy sử dụng các phương thức theo lô của tài nguyên customers.quarantinedMessages trong Mail Admin Quarantine API:

  • Phương thức batchRelease sẽ phát hành tối đa 500 thông báo.
  • Phương thức batchDeny từ chối tối đa 500 thư.

Cả hai phương thức đều không đồng bộ. API chấp nhận yêu cầu, trả về một thao tác chạy trong thời gian dài và xử lý các thông báo trong nền. Sau đó, bạn thăm dò phương thức get của tài nguyên customers.operations cho đến khi thao tác hoàn tất và đọc kết quả theo từng tin nhắn trong phản hồi.

So với việc gọi các phương thức một thông báo trong một vòng lặp, các phương thức theo lô được tính là một yêu cầu ghi đối với mức sử dụng hạn mức của bạn, bất kể chúng chứa bao nhiêu thông báo.

Điều kiện tiên quyết

Bắt đầu một thao tác hàng loạt

Để phát hành thư theo lô, hãy gửi yêu cầu POST đến phương thức tuỳ chỉnh :batchRelease trên tài nguyên customers.quarantinedMessages. Mảng requests chứa một đối tượng cho mỗi tin nhắn, mỗi đối tượng có tên tài nguyên của tin nhắn:

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

Để từ chối tin nhắn theo lô, hãy gửi cùng một nội dung yêu cầu đến phương thức tuỳ chỉnh :batchDeny trên tài nguyên customers.quarantinedMessages:

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

Mỗi yêu cầu phải chứa từ 1 đến 500 mục nhập. Mỗi thông báo phải thuộc về khách hàng trong đường dẫn yêu cầu. Yêu cầu có hơn 500 mục nhập sẽ trả về lỗi 400 INVALID_ARGUMENT.

API phản hồi ngay lập tức bằng tài nguyên 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
}

Lưu trữ name của thao tác. Bạn cần có mã này để kiểm tra tiến trình của thao tác.

Kiểm tra trạng thái của một thao tác hàng loạt

Để kiểm tra tiến trình của một thao tác theo lô, hãy gửi yêu cầu GET đến phương thức get trên tên tài nguyên của thao tác:

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

Phương thức get chấp nhận phạm vi API Khu vực cách ly của quản trị viên, vì vậy, một công cụ tích hợp chỉ có thể đọc có thể giám sát các hoạt động mà một hệ thống khác đã bắt đầu.

Trong khi thao tác chạy, trường done được đặt thành false và trường metadata báo cáo tiến trình:

Trường siêu dữ liệu Mô tả
state PROCESSING trong khi thư đang được xử lý, sau đó là SUCCEEDED hoặc FAILED.
processedCount Số lượng thư đã được xử lý cho đến nay.
totalCount Tổng số tin nhắn trong lô.

Khi thao tác kết thúc, trường done được đặt thành true và trường response chứa kết quả cho mọi thông báo trong lô:

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

Mỗi mục trong results mô tả kết quả cho một thông báo:

Trường kết quả Mô tả
name Tên tài nguyên của thông báo.
status google.rpc.Status. Một đối tượng trống (mã 0, OK) có nghĩa là hành động đã thành công. Nếu không, code và message sẽ giải thích lý do thư bị bỏ qua.
quarantinedMessage Thông báo mới với state mới. Chỉ xuất hiện khi status là OK.

Thao tác hàng loạt sẽ thành công ngay cả khi một số thông báo riêng lẻ không thành công. Luôn kiểm tra status của từng kết quả thay vì chỉ dựa vào state của thao tác.

Nếu toàn bộ thao tác không thành công, ví dụ: do phần phụ trợ không hoạt động, thì trường done sẽ được đặt thành true và trường error sẽ chứa google.rpc.Status thay vì response.

Ví dụ: Phát hành theo lô và thăm dò ý kiến để hoàn tất

Ví dụ về Python sau đây bắt đầu một bản phát hành theo lô và thăm dò ý kiến về hoạt động vài giây một lần cho đến khi hoàn tất:

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

Các bước tiếp theo