Liberar ou recusar mensagens em lote

Quando você precisar agir em muitas mensagens em quarentena de uma só vez, use os métodos em lote do recurso customers.quarantinedMessages na API Mail Admin Quarantine:

Os dois métodos são assíncronos. A API aceita a solicitação, retorna uma operação de longa duração e processa as mensagens em segundo plano. Em seguida, pesquise o método get do recurso customers.operations até que a operação seja concluída e leia os resultados por mensagem da resposta.

Em comparação com a chamada dos métodos de mensagem única em um loop, os métodos em lote contam como uma solicitação de gravação em relação ao uso da cota, independentemente de quantas mensagens eles contêm.

Pré-requisitos

Iniciar uma operação em lote

Para liberar mensagens em um lote, envie uma solicitação POST ao método personalizado :batchRelease no recurso customers.quarantinedMessages. A matriz requests contém um objeto por mensagem, cada um com o nome do recurso da mensagem:

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

Para negar mensagens em um lote, envie o mesmo corpo de solicitação para o método personalizado :batchDeny no recurso customers.quarantinedMessages:

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

Cada solicitação precisa conter entre 1 e 500 entradas. Cada mensagem precisa pertencer ao cliente no caminho da solicitação. Uma solicitação com mais de 500 entradas retorna um erro 400 INVALID_ARGUMENT.

A API responde imediatamente com um recurso 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
}

Armazene o name da operação. Você precisa dele para verificar o progresso da operação.

Verificar o status de uma operação em lote

Para verificar o progresso de uma operação em lote, envie uma solicitação GET ao método get no nome do recurso da operação:

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

O método get aceita qualquer escopo da API Admin Quarantine, então uma integração somente leitura pode monitorar operações iniciadas por outro sistema.

Enquanto a operação é executada, o campo done é definido como false, e o campo metadata informa o progresso:

Campo de metadados Descrição
state PROCESSING enquanto as mensagens estão sendo processadas, depois SUCCEEDED ou FAILED.
processedCount O número de mensagens processadas até o momento.
totalCount O número total de mensagens no lote.

Quando a operação é concluída, o campo done é definido como true, e o campo response contém um resultado para cada mensagem no lote:

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

Cada entrada em results descreve o resultado de uma mensagem:

Campo de resultado Descrição
name O nome do recurso da mensagem.
status Uma google.rpc.Status. Um objeto vazio (código 0, OK) significa que a ação foi bem-sucedida. Caso contrário, code e message explicam por que a mensagem foi ignorada.
quarantinedMessage A mensagem atualizada com o novo state. Presente somente quando status é OK.

Uma operação em lote é bem-sucedida mesmo que algumas mensagens individuais falhem. Sempre inspecione o status de cada resultado em vez de confiar apenas no state da operação.

Se toda a operação falhar, por exemplo, porque o back-end está indisponível, o campo done será definido como true e o campo error conterá um google.rpc.Status em vez de response.

Exemplo: liberação em lote e sondagem para conclusão

O exemplo em Python a seguir inicia uma versão em lote e pesquisa a operação a cada poucos segundos até que ela seja concluída:

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

Próximas etapas