İletileri toplu olarak serbest bırakma veya reddetme

Karantinaya alınmış birçok ileti üzerinde aynı anda işlem yapmanız gerektiğinde Mail Admin Quarantine API'deki customers.quarantinedMessages kaynağının toplu yöntemlerini kullanın:

  • batchRelease yöntemi, 500'e kadar iletiyi serbest bırakır.
  • batchDeny yöntemi, en fazla 500 mesajı reddeder.

Her iki yöntem de eşzamansızdır. API, isteği kabul eder, uzun süreli işlem döndürür ve mesajları arka planda işler. Ardından, işlem tamamlanana kadar customers.operations kaynağının get yöntemini yoklar ve yanıttan mesaj başına sonuçları okursunuz.

Tek mesaj yöntemlerini bir döngüde çağırmaya kıyasla toplu yöntemler, içerdikleri mesaj sayısından bağımsız olarak kota kullanımınız için bir yazma isteği olarak sayılır.

Ön koşullar

  • API'yi ayarlama başlıklı makaledeki adımları tamamlamış olmanız gerekir.
  • Yönetici karantinası ayrıcalığına sahip bir yönetici kimliğine bürünen ve https://www.googleapis.com/auth/gmail.admin.quarantine kapsamını içeren bir erişim jetonu. Alan genelinde yetkiyle yetkilendirme başlıklı makaleyi inceleyin.
  • PENDING_TRIAGE durumunda olan ve Karantinaya alınan iletileri listeleme ve arama bölümünden aldığınız, karantinaya alınmış en fazla 500 iletinin kaynak adları.

Toplu işlem başlatma

İletileri toplu olarak serbest bırakmak için customers.quarantinedMessages kaynağındaki :batchRelease özel yöntemine bir POST isteği gönderin. requests dizisi, her mesaj için bir nesne içerir ve her nesne, mesajın kaynak adını taşır:

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

Mesajları toplu olarak reddetmek için aynı istek gövdesini customers.quarantinedMessages kaynağındaki :batchDeny özel yöntemine gönderin:

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

Her istekte 1 ila 500 giriş bulunmalıdır. Her mesaj, istek yolundaki müşteriye ait olmalıdır. 500'den fazla giriş içeren istekler 400 INVALID_ARGUMENT hatası döndürür.

API, hemen bir Operation kaynağıyla yanıt verir:

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

İşlemin name değerini saklayın. İşlemin ilerleme durumunu kontrol etmek için bu kimliğe ihtiyacınız vardır.

Toplu işlemin durumunu kontrol etme

Toplu işlemin ilerleme durumunu kontrol etmek için işlemin kaynak adındaki get yöntemine bir GET isteği gönderin:

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

get yöntemi, her iki Yönetici Karantinası API kapsamını da kabul eder. Bu sayede, salt okunur bir entegrasyon başka bir sistemin başlattığı işlemleri izleyebilir.

İşlem çalışırken done alanı false olarak ayarlanır ve metadata alanı ilerleme durumunu bildirir:

Meta veri alanı Açıklama
state Mesajlar işlenirken PROCESSING, ardından SUCCEEDED veya FAILED.
processedCount Şu ana kadar işlenen mesaj sayısı.
totalCount Gruptaki toplam mesaj sayısı.

İşlem tamamlandığında done alanı true olarak ayarlanır ve response alanı, gruptaki her mesaj için bir sonuç içerir:

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

results içindeki her giriş, bir mesajın sonucunu açıklar:

Sonuç alanı Açıklama
name Mesajın kaynak adı.
status google.rpc.Status. Boş bir nesne (kod 0, OK) işlemin başarılı olduğu anlamına gelir. Aksi takdirde, code ve message iletinin neden atlandığını açıklar.
quarantinedMessage Yeni state ile güncellenen mesaj. Yalnızca status, OK olduğunda gösterilir.

Bazı iletiler başarısız olsa bile toplu işlem başarılı olur. Yalnızca işlemin state değerine güvenmek yerine her zaman her sonucun status değerini inceleyin.

Arka ucun kullanılamaması gibi nedenlerle işlemin tamamı başarısız olursa done alanı true olarak ayarlanır ve error alanı response yerine google.rpc.Status içerir.

Örnek: Toplu yayınlama ve tamamlanma için anket yapma

Aşağıdaki Python örneği, bir toplu sürüm başlatır ve tamamlanana kadar her birkaç saniyede bir işlemi sorgular:

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

Sonraki adımlar