Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

แสดงรายการและค้นหาข้อความที่กักบริเวณไว้

หน้านี้อธิบายวิธีค้นหาข้อความที่เก็บไว้ในเขตกักบริเวณของผู้ดูแลระบบ Google Workspace โดยใช้ Mail Admin Quarantine API

API มี 2 เมธอดในทรัพยากร customers.quarantinedMessages ดังนี้

เมธอด list จะแสดงข้อความที่กักเก็บไว้โดยไม่มีการกรอง ใช้เพื่อเลื่อนดูทุกอย่างในเขตกักบริเวณ
เมธอด search จะจำกัดผลลัพธ์ให้แคบลงด้วยตัวกรองที่มีโครงสร้าง คำค้นหาใน Gmail หรือทั้ง 2 อย่าง ใช้สำหรับเวิร์กโฟลว์การคัดแยก เช่น การดึงข้อมูลเฉพาะข้อความขาเข้าที่รอดำเนินการตรวจสอบ

ทั้ง 2 วิธีจะแสดงข้อความจากช่วง 30 วันที่ผ่านมา และทั้ง 2 วิธีจะแสดงข้อมูลเมตาพื้นฐานเดียวกันสำหรับแต่ละข้อความ หากต้องการดึงข้อมูลส่วนหัว เนื้อหา ไฟล์แนบ หรือข้อความดิบ โปรดดูหัวข้อดูรายละเอียดข้อความ

ข้อกำหนดเบื้องต้น

คุณได้ทำตามขั้นตอนในหัวข้อตั้งค่า API แล้ว
โทเค็นเพื่อการเข้าถึงที่แอบอ้างเป็นผู้ดูแลระบบที่มีสิทธิ์เขตกักบริเวณของผู้ดูแลระบบและมีขอบเขต https://www.googleapis.com/auth/gmail.admin.quarantine หรือ https://www.googleapis.com/auth/gmail.admin.quarantine.readonly ดูหัวข้อให้สิทธิ์ด้วยการมอบสิทธิ์ทั่วทั้งโดเมน

แสดงรายการข้อความที่กักเก็บไว้

หากต้องการแสดงรายการข้อความที่กักเก็บไว้ ให้ส่งคำขอ GET ไปยังเมธอด list ในทรัพยากร customers.quarantinedMessages ของลูกค้า ดังนี้

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

แทนที่ CUSTOMER_ID ด้วยรหัสลูกค้า

เมธอด list ยอมรับพารามิเตอร์การค้นหาต่อไปนี้

พารามิเตอร์	คำอธิบาย
`pageSize`	จำนวนข้อความสูงสุดที่จะแสดงต่อหน้า ตั้งแต่ 1 ถึง 300 รายการ ตั้งค่าพารามิเตอร์นี้อย่างชัดเจนเสมอ
`pageToken`	ค่า `nextPageToken` จากการตอบกลับก่อนหน้า ใช้เพื่อเรียกข้อมูลหน้าถัดไป

ค้นหาข้อความที่กักเก็บไว้

หากต้องการค้นหาข้อความที่กักเก็บไว้ ให้ส่งคำขอ POST ไปยังเมธอดที่กำหนดเอง :search ในทรัพยากร customers.quarantinedMessages พร้อมเนื้อหา 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
}

เนื้อหาคำขอยอมรับฟิลด์ต่อไปนี้ ไม่จำเป็นต้องกรอกข้อมูลครบทุกช่อง

ช่อง	คำอธิบาย
`filter`	ตัวกรองที่มีโครงสร้างในไวยากรณ์ AIP-160 ดูไวยากรณ์ของตัวกรอง
`query`	คำค้นหาใน Gmail เช่น `has:attachment` หรือ `from:suspicious@example.com` โดยคำค้นหาจะใช้โอเปอเรเตอร์เดียวกันกับช่องค้นหาของ Gmail โปรดดูหัวข้อโอเปอเรเตอร์การค้นหาที่ใช้กับ Gmail ได้
`pageSize`	จำนวนข้อความสูงสุดที่จะแสดงต่อหน้า ตั้งแต่ 1 ถึง 300 รายการ ตั้งค่าช่องนี้อย่างชัดเจนเสมอ
`pageToken`	ค่า `nextPageToken` จากการตอบกลับก่อนหน้า

เมื่อคุณตั้งค่าทั้ง filter และ query, API จะแสดงเฉพาะข้อความที่ตรงกับทั้ง 2 รายการ

ไวยากรณ์ของตัวกรอง

ช่อง filter รองรับช่องต่อไปนี้ รวมเข้าด้วยกันโดยใช้โอเปอเรเตอร์ AND ระบบไม่รองรับโอเปอเรเตอร์อื่นๆ เช่น OR และ NOT

ช่อง	การเปรียบเทียบที่รองรับ	ค่า
`status`	`=`	`PENDING_TRIAGE`, `RELEASED` หรือ `DENIED`
`direction`	`=`, `!=`	`INBOUND` หรือ `OUTBOUND`
`quarantine_name` (หรือ `quarantineName`)	`=`	ชื่อที่แสดงของเขตกักบริเวณตามที่แสดงในคอนโซลผู้ดูแลระบบของ Google เช่น `"Default"`

ตัวอย่างต่อไปนี้แสดงตัวกรองที่ถูกต้อง

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

ตัวกรองที่ไม่ถูกต้องจะแสดงข้อผิดพลาด 400 INVALID_ARGUMENT

คำตอบ

ทั้ง 2 วิธีจะแสดงรายการทรัพยากร QuarantinedMessage พร้อมข้อมูลเมตาพื้นฐาน และ nextPageToken หากมีผลการค้นหาเพิ่มเติม ดังนี้

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

ช่อง	คำอธิบาย
`name`	ชื่อทรัพยากรของข้อความ ใช้โทเค็นนี้ในการเรียก `get`, `release` และ `deny` ครั้งถัดไปในทรัพยากร `customers.quarantinedMessages`
`messageId`	รหัสข้อความ Gmail ที่เปลี่ยนแปลงไม่ได้
`messageOwner`	อีเมลของกล่องจดหมายที่เป็นเจ้าของข้อความ
`quarantines`	ชื่อทรัพยากรของเขตกักเก็บที่มีข้อความอยู่ เรียกใช้เมธอด `get` ของทรัพยากร `customers.quarantines` เพื่อรับชื่อที่แสดงของเขตกักบริเวณ
`receiveTime`	เมื่อ Gmail ได้รับข้อความ
`direction`	`INBOUND` หากผู้ใช้ได้รับข้อความ หรือ `OUTBOUND` หากผู้ใช้ส่งข้อความ
`state`	`PENDING_TRIAGE`, `RELEASED` หรือ `DENIED`
`retentionExpireTime`	เมื่อเขตกักเก็บหยุดเก็บรักษาข้อความ
`triggeredRules`	กฎที่ทำให้ข้อความถูกกักบริเวณ
`unreachable`	บัญชีที่บริการไม่สามารถเรียกข้อความที่กักเก็บไว้ได้ หากมี ให้ลองส่งคำขออีกครั้งในภายหลัง

เลื่อนดูผลการค้นหาทีละหน้า

วิธีดึงข้อมูลข้อความที่ตรงกันทั้งหมด

ส่งคำขอแรกด้วย pageSize
หากการตอบกลับมี nextPageToken ให้ส่งคำขอซ้ำโดยใช้พารามิเตอร์เดียวกันและตั้งค่า pageToken เป็นค่านั้น
หยุดเมื่อการตอบกลับไม่มี nextPageToken

ตัวอย่าง Python ต่อไปนี้จะไปยังหน้าต่างๆ ของข้อความขาเข้าทั้งหมดที่รอดำเนินการคัดแยก

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.')