Nachrichten im Batch freigeben oder ablehnen

Wenn Sie viele Nachrichten in der Quarantäne gleichzeitig bearbeiten müssen, verwenden Sie die Batch-Methoden der Ressource customers.quarantinedMessages in der Mail Admin Quarantine API:

  • Mit der Methode batchRelease werden bis zu 500 Nachrichten freigegeben.
  • Mit der Methode batchDeny werden bis zu 500 Nachrichten abgelehnt.

Beide Methoden sind asynchron. Die API akzeptiert die Anfrage, gibt einen Vorgang mit langer Ausführungszeit zurück und verarbeitet die Nachrichten im Hintergrund. Anschließend rufen Sie die Methode get der Ressource customers.operations ab, bis der Vorgang abgeschlossen ist, und lesen die Ergebnisse pro Nachricht aus der Antwort.

Im Vergleich zum Aufrufen der Methoden für einzelne Nachrichten in einer Schleife werden Batchmethoden unabhängig von der Anzahl der enthaltenen Nachrichten als eine Schreibanfrage auf Ihre Kontingentnutzung angerechnet.

Vorbereitung

Batchvorgang starten

Wenn Sie Nachrichten in einem Batch freigeben möchten, senden Sie eine POST-Anfrage an die benutzerdefinierte Methode :batchRelease für die Ressource customers.quarantinedMessages. Das Array requests enthält ein Objekt pro Nachricht, jeweils mit dem Ressourcennamen der Nachricht:

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

Wenn Sie Nachrichten in einem Batch ablehnen möchten, senden Sie stattdessen denselben Anfragetext an die benutzerdefinierte Methode :batchDeny für die Ressource customers.quarantinedMessages:

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

Jede Anfrage muss zwischen 1 und 500 Einträge enthalten. Jede Nachricht muss dem Kunden im Anfragepfad gehören. Eine Anfrage mit mehr als 500 Einträgen gibt den Fehler 400 INVALID_ARGUMENT zurück.

Die API antwortet sofort mit einer Operation-Ressource:

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

Speichern Sie den name des Vorgangs. Sie benötigen ihn, um den Fortschritt des Vorgangs zu prüfen.

Status eines Batchvorgangs prüfen

Wenn Sie den Fortschritt eines Batchvorgangs prüfen möchten, senden Sie eine GET-Anfrage an die Methode get für den Ressourcennamen des Vorgangs:

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

Die Methode get akzeptiert beide Admin Quarantine API-Bereiche, sodass eine schreibgeschützte Integration Vorgänge überwachen kann, die von einem anderen System gestartet wurden.

Während der Vorgang ausgeführt wird, ist das Feld done auf false gesetzt und das Feld metadata meldet den Fortschritt:

Metadatenfeld Beschreibung
state PROCESSING, während Nachrichten verarbeitet werden, dann SUCCEEDED oder FAILED.
processedCount Die Anzahl der bisher verarbeiteten Nachrichten.
totalCount Die Gesamtzahl der Nachrichten im Batch.

Wenn der Vorgang abgeschlossen ist, wird das Feld done auf true gesetzt und das Feld response enthält ein Ergebnis für jede Nachricht im Batch:

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

Jeder Eintrag in results beschreibt das Ergebnis für eine Nachricht:

Ergebnisfeld Beschreibung
name Der Ressourcenname der Nachricht.
status Ein google.rpc.Status. Ein leeres Objekt (Code 0, OK) bedeutet, dass die Aktion erfolgreich war. Andernfalls wird in code und message erläutert, warum die Nachricht übersprungen wurde.
quarantinedMessage Die aktualisierte Nachricht mit dem neuen state. Nur vorhanden, wenn status OK ist.

Ein Batchvorgang ist auch dann erfolgreich, wenn einige einzelne Nachrichten fehlschlagen. Prüfen Sie immer den status jedes Ergebnisses, anstatt sich nur auf den state des Vorgangs zu verlassen.

Wenn der gesamte Vorgang fehlschlägt, z. B. weil das Backend nicht verfügbar ist, wird das Feld done auf true gesetzt und das Feld error enthält google.rpc.Status anstelle von response.

Beispiel: Batch-Release und Abfrage des Abschlusses

Im folgenden Python-Beispiel wird eine Batchfreigabe gestartet und der Vorgang alle paar Sekunden abgefragt, bis er abgeschlossen ist:

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

Nächste Schritte