Sbloccare o rifiutare i messaggi in batch

Quando devi intervenire su molti messaggi in quarantena contemporaneamente, utilizza i metodi batch della risorsa customers.quarantinedMessages nell'API Mail Admin Quarantine:

Entrambi i metodi sono asincroni. L'API accetta la richiesta, restituisce un'operazione a lunga esecuzione ed elabora i messaggi in background. Poi esegui il polling del metodo get della risorsa customers.operations fino al completamento dell'operazione e leggi i risultati per messaggio dalla risposta.

Rispetto alla chiamata dei metodi per un singolo messaggio in un loop, i metodi batch vengono conteggiati come una singola richiesta di scrittura ai fini dell'utilizzo della quota, indipendentemente dal numero di messaggi che contengono.

Prerequisiti

Avvia un'operazione batch

Per rilasciare i messaggi in un batch, invia una richiesta POST al metodo personalizzato :batchRelease sulla risorsa customers.quarantinedMessages. L'array requests contiene un oggetto per messaggio, ciascuno con il nome della risorsa del messaggio:

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

Per rifiutare i messaggi in un batch, invia lo stesso corpo della richiesta al metodo personalizzato :batchDeny sulla risorsa customers.quarantinedMessages:

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

Ogni richiesta deve contenere da 1 a 500 voci. Ogni messaggio deve appartenere al cliente nel percorso della richiesta. Una richiesta con più di 500 voci restituisce un errore 400 INVALID_ARGUMENT.

L'API risponde immediatamente con una risorsa 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
}

Memorizza il valore name dell'operazione. Ti servirà per controllare l'avanzamento dell'operazione.

Controlla lo stato di un'operazione batch

Per controllare l'avanzamento di un'operazione batch, invia una richiesta GET al metodo get sul nome della risorsa dell'operazione:

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

Il metodo get accetta l'ambito dell'API Admin Quarantine, quindi un'integrazione di sola lettura può monitorare le operazioni avviate da un altro sistema.

Durante l'esecuzione dell'operazione, il campo done è impostato su false e il campo metadata segnala l'avanzamento:

Campo metadati Descrizione
state PROCESSING mentre i messaggi vengono elaborati, poi SUCCEEDED o FAILED.
processedCount Il numero di messaggi elaborati finora.
totalCount Il numero totale di messaggi nel batch.

Al termine dell'operazione, il campo done viene impostato su true e il campo response contiene un risultato per ogni messaggio nel 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"
        }
      }
    ]
  }
}

Ogni voce in results descrive il risultato per un messaggio:

Campo dei risultati Descrizione
name Il nome della risorsa del messaggio.
status google.rpc.Status. Un oggetto vuoto (codice 0, OK) indica che l'azione è riuscita. In caso contrario, code e message spiegano il motivo per cui il messaggio è stato ignorato.
quarantinedMessage Il messaggio aggiornato con il nuovo state. Presente solo quando status è OK.

Un'operazione batch va a buon fine anche se alcuni singoli messaggi non vengono inviati. Controlla sempre l'status di ogni risultato anziché fare affidamento solo sull'state dell'operazione.

Se l'intera operazione non va a buon fine, ad esempio perché il backend non è disponibile, il campo done viene impostato su true e il campo error contiene un google.rpc.Status anziché response.

Esempio: rilascio in batch e polling per il completamento

L'esempio Python seguente avvia un'operazione di rilascio in batch ed esegue il polling dell'operazione ogni pochi secondi fino al completamento:

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

Passaggi successivi