Zatwierdzanie i odrzucanie wiadomości w grupach

Jeśli chcesz wykonać działania na wielu wiadomościach w kwarantannie jednocześnie, użyj metod zbiorczych zasobu customers.quarantinedMessages w interfejsie Mail Admin Quarantine API:

  • Metoda batchRelease zwalnia do 500 wiadomości.
  • Metoda batchDeny odrzuca maksymalnie 500 wiadomości.

Obie metody są asynchroniczne. Interfejs API akceptuje żądanie, zwraca długo trwającą operację i przetwarza wiadomości w tle. Następnie wywołujesz metodę get zasobu customers.operations, dopóki operacja nie zostanie zakończona, i odczytujesz wyniki dla poszczególnych wiadomości z odpowiedzi.

W porównaniu z wywoływaniem metod pojedynczych wiadomości w pętli metody zbiorcze są liczone jako jedno żądanie zapisu w ramach wykorzystania limitu, niezależnie od tego, ile wiadomości zawierają.

Wymagania wstępne

Rozpoczynanie operacji wsadowej

Aby zbiorczo zwolnić wiadomości, wyślij żądanie POST do metody niestandardowej :batchRelease w zasobie customers.quarantinedMessages. Tablica requests zawiera po 1 obiekcie na każdą wiadomość, a każdy z nich ma nazwę zasobu wiadomości:

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

Aby odrzucić wiadomości w ramach zbiorczego działania, wyślij tę samą treść żądania do metody niestandardowej :batchDeny w zasobie customers.quarantinedMessages:

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

Każde żądanie musi zawierać od 1 do 500 wpisów. Każda wiadomość musi należeć do klienta w ścieżce żądania. Żądanie zawierające więcej niż 500 wpisów zwraca błąd 400 INVALID_ARGUMENT.

Interfejs API natychmiast zwraca zasób 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
}

Zapisz name operacji. Będzie Ci potrzebny do sprawdzenia postępu operacji.

Sprawdzanie stanu operacji zbiorczej

Aby sprawdzić postęp operacji zbiorczej, wyślij żądanie GET do metody get w nazwie zasobu operacji:

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

Metoda get akceptuje zakres interfejsu Admin Quarantine API, więc integracja tylko do odczytu może monitorować operacje rozpoczęte przez inny system.

Podczas wykonywania operacji pole done ma wartość false, a pole metadata raportuje postęp:

Pole metadanych Opis
state PROCESSING podczas przetwarzania wiadomości, a następnie SUCCEEDED lub FAILED.
processedCount Liczba wiadomości przetworzonych do tej pory.
totalCount Łączna liczba wiadomości w grupie.

Po zakończeniu operacji pole done ma wartość true, a pole response zawiera wynik dla każdej wiadomości w partii:

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

Każdy wpis w results opisuje wynik dla jednej wiadomości:

Pole wyniku Opis
name Nazwa zasobu wiadomości.
status google.rpc.Status. Pusty obiekt (kod 0, OK) oznacza, że działanie się powiodło. W przeciwnym razie code i message wyjaśniają, dlaczego wiadomość została pominięta.
quarantinedMessage Zaktualizowana wiadomość z nowym state. Występuje tylko wtedy, gdy status ma wartość OK.

Operacja zbiorcza powiedzie się, nawet jeśli niektóre wiadomości nie zostaną wysłane. Zawsze sprawdzaj status każdego wyniku, zamiast polegać wyłącznie na state operacji.

Jeśli cała operacja się nie powiedzie, na przykład z powodu niedostępności backendu, pole done zostanie ustawione na true, a pole error będzie zawierać google.rpc.Status zamiast response.

Przykład: zbiorcze udostępnianie i sprawdzanie stanu ukończenia

Poniższy przykład w Pythonie rozpoczyna publikację zbiorczą i co kilka sekund sprawdza stan operacji, aż do jej zakończenia:

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

Dalsze kroki