Wyświetlanie i wyszukiwanie wiadomości w kwarantannie

Na tej stronie dowiesz się, jak znaleźć wiadomości przechowywane w kwarantannach administratora Google Workspace za pomocą interfejsu Mail Admin Quarantine API.

Interfejs API udostępnia 2 metody w zasobie customers.quarantinedMessages:

  • Metoda list zwraca wiadomości umieszczone w kwarantannie bez żadnego filtrowania. Użyj go, aby przeglądać wszystkie elementy w kwarantannach.
  • Metoda search zawęża wyniki za pomocą filtra uporządkowanego, zapytania w Gmailu lub obu tych elementów. Używaj go w przepływach pracy związanych z klasyfikacją, np. do pobierania tylko wiadomości przychodzących, które oczekują na sprawdzenie.

Obie metody zwracają wiadomości z ostatnich 30 dni i obie zwracają te same podstawowe metadane dla każdej wiadomości. Aby pobrać nagłówki, treść, załączniki lub nieprzetworzoną wiadomość, zapoznaj się z artykułem Uzyskiwanie szczegółowych informacji o wiadomości.

Wymagania wstępne

Wyświetlanie listy wiadomości poddanych kwarantannie

Aby wyświetlić listę wiadomości objętych kwarantanną, wyślij żądanie GET do metody list w zasobie customers.quarantinedMessages klienta:

GET https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages?pageSize=50
Authorization: Bearer ACCESS_TOKEN

Zastąp CUSTOMER_ID swoim identyfikatorem klienta.

Metoda list akceptuje te parametry zapytania:

Parametr Opis
pageSize Maksymalna liczba wiadomości do zwrócenia na stronę, od 1 do 300. Zawsze ustawiaj ten parametr bezpośrednio.
pageToken Wartość nextPageToken z poprzedniej odpowiedzi. Użyj go, aby pobrać następną stronę.

Aby wyszukać wiadomości umieszczone w kwarantannie, wyślij żądanie POST do metody niestandardowej :search w zasobie customers.quarantinedMessages z treścią w formacie JSON:

POST https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages:search
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "filter": "status = PENDING_TRIAGE AND direction = INBOUND",
  "query": "from:suspicious@example.com",
  "pageSize": 50
}

Treść żądania akceptuje te pola. Wszystkie pola są opcjonalne:

Pole Opis
filter Filtr strukturalny w składni AIP-160. Zobacz Składnia filtra.
query zapytanie w wyszukiwaniu w Gmailu, np. has:attachment lub from:suspicious@example.com; Zapytanie używa tych samych operatorów co pole wyszukiwania w Gmailu. Zobacz Operatory wyszukiwania dostępne w Gmailu.
pageSize Maksymalna liczba wiadomości do zwrócenia na stronę, od 1 do 300. Zawsze ustawiaj to pole bezpośrednio.
pageToken Wartość nextPageToken z poprzedniej odpowiedzi.

Jeśli ustawisz zarówno filter, jak i query, interfejs API zwróci tylko wiadomości, które pasują do obu tych parametrów.

Składnia filtra

Pole filter obsługuje te pola. Połącz je za pomocą operatora AND. Inne operatory, takie jak OR i NOT, nie są obsługiwane.

Pole Obsługiwane porównania Wartości
status = PENDING_TRIAGE, RELEASED lub DENIED.
direction =, != INBOUND lub OUTBOUND.
quarantine_name (lub quarantineName) = Wyświetlana nazwa kwarantanny widoczna w konsoli administracyjnej Google, na przykład "Default".

Poniższe przykłady pokazują prawidłowe filtry:

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

Nieprawidłowy filtr zwraca błąd 400 INVALID_ARGUMENT.

Odpowiedź

Obie metody zwracają listę zasobów QuarantinedMessage z podstawowymi metadanymi oraz nextPageToken, jeśli dostępnych jest więcej wyników:

{
  "quarantinedMessages": [
    {
      "name": "customers/01abc23de/quarantinedMessages/user@example.com:18d3ef45a8b2c1d0",
      "messageId": "18d3ef45a8b2c1d0",
      "messageOwner": "user@example.com",
      "quarantines": [
        "customers/01abc23de/quarantines/0"
      ],
      "receiveTime": "2026-09-22T10:15:30Z",
      "direction": "INBOUND",
      "state": "PENDING_TRIAGE",
      "retentionExpireTime": "2026-10-22T10:15:30Z",
      "triggeredRules": [
        {
          "policyId": "123",
          "ruleId": "456",
          "displayName": "Inbound phishing protection"
        }
      ]
    }
  ],
  "nextPageToken": "CAESBAgBEA..."
}
Pole Opis
name Nazwa zasobu wiadomości. Użyj go w kolejnych wywołaniach get, release i deny w zasobie customers.quarantinedMessages.
messageId Niezmienny identyfikator wiadomości w Gmailu.
messageOwner Adres e-mail skrzynki pocztowej, do której należy wiadomość.
quarantines Nazwy zasobów kwarantann, w których znajduje się wiadomość. Aby uzyskać wyświetlaną nazwę kwarantanny, wywołaj metodę get zasobu customers.quarantines.
receiveTime Kiedy Gmail otrzymał wiadomość.
direction INBOUND, jeśli użytkownik otrzymał wiadomość, lub OUTBOUND, jeśli użytkownik ją wysłał.
state PENDING_TRIAGE, RELEASED lub DENIED.
retentionExpireTime gdy kwarantanna przestanie przechowywać wiadomość.
triggeredRules reguły, które spowodowały umieszczenie wiadomości w kwarantannie;
unreachable Konta, dla których usługa nie mogła pobrać wiadomości poddanych kwarantannie. Jeśli tak, spróbuj ponownie później.

Przeglądanie wyników strona po stronie

Aby pobrać wszystkie pasujące wiadomości:

  1. Wyślij pierwsze żądanie z pageSize.
  2. Jeśli odpowiedź zawiera parametr nextPageToken, powtórz żądanie z tymi samymi parametrami i ustaw pageToken na tę wartość.
  3. Zatrzymaj, gdy odpowiedź nie zawiera nextPageToken.

Poniższy przykład w Pythonie pokazuje, jak przeglądać wszystkie wiadomości przychodzące, które oczekują na klasyfikację:

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',
}

search_url = f'{BASE_URL}/customers/{CUSTOMER_ID}/quarantinedMessages:search'
body = {
    'filter': 'status = PENDING_TRIAGE AND direction = INBOUND',
    'pageSize': 100,
}
messages = []
while True:
  response = requests.post(search_url, headers=headers, json=body)
  response.raise_for_status()
  result = response.json()
  messages.extend(result.get('quarantinedMessages', []))
  page_token = result.get('nextPageToken')
  if not page_token:
    break
  body['pageToken'] = page_token

print(f'Found {len(messages)} messages pending triage.')

Dalsze kroki