กำหนดค่าข้อความ Push ใน Gmail API

เอกสารนี้อธิบายวิธีจัดการข้อความ Push ใน Gmail API

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

หมายเหตุ: สำหรับการแจ้งเตือนไปยังอุปกรณ์ของผู้ใช้ (เช่น แอปที่ติดตั้ง อุปกรณ์เคลื่อนที่ หรือเบราว์เซอร์) วิธีที่แนะนำในการดึงข้อมูลอัปเดตยังคงเป็นแนวทางซิงค์ไคลเอ็นต์กับ Gmail API ที่อิงตามการสำรวจ

การตั้งค่า Cloud Pub/Sub เริ่มต้น

Gmail API ใช้ Cloud Pub/Sub API เพื่อส่งการแจ้งเตือนแบบพุช ซึ่งจะช่วยให้ส่งการแจ้งเตือนได้โดยใช้วิธีต่างๆ รวมถึง Webhook และการสำรวจที่ปลายทางการสมัครใช้บริการเดียว

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

หากต้องการตั้งค่านี้ให้เสร็จสมบูรณ์ ให้ทำตามข้อกำหนดเบื้องต้นของ Cloud Pub/Sub แล้วตั้งค่าไคลเอ็นต์ Cloud Pub/Sub

สร้างหัวข้อ

ใช้ไคลเอ็นต์ Cloud Pub/Sub เพื่อสร้างหัวข้อที่ Gmail API ควรส่งการแจ้งเตือนไปให้ ชื่อหัวข้อจะเป็นชื่อใดก็ได้ ที่คุณเลือกภายใต้โปรเจ็กต์ (เช่น matching projects/myproject/topics/* โดยที่ myproject คือรหัสโปรเจ็กต์ที่แสดงสำหรับ โปรเจ็กต์ของคุณใน Google Cloud Console)

สร้างการสมัครใช้บริการ

หากต้องการตั้งค่าการสมัครใช้บริการหัวข้อที่คุณสร้างขึ้น ให้ทำตามคำแนะนำประเภทการสมัครใช้บริการ Cloud Pub/Sub กำหนดค่าประเภทการสมัครใช้บริการให้เป็นแบบพุชของ Webhook (นั่นคือการเรียกกลับ HTTP POST) หรือแบบดึง (นั่นคือแอปของคุณเป็นผู้เริ่ม) แอปพลิเคชันของคุณจะได้รับการแจ้งเตือนเกี่ยวกับข้อมูลอัปเดตด้วยวิธีนี้

ให้สิทธิ์ในการเผยแพร่ในหัวข้อของคุณ

Cloud Pub/Sub กำหนดให้คุณต้องให้สิทธิ์แก่ Gmail ในการเผยแพร่ การแจ้งเตือนไปยังหัวข้อของคุณ

โดยให้สิทธิ์ระดับ publish แก่ [e-mail] คุณทำได้โดยใช้คอนโซล สิทธิ์ Cloud Pub/Sub ใน คอนโซล Google Cloud โดยทำตามวิธีการควบคุมการเข้าถึงเหล่านี้

การกำหนดค่าการแชร์ที่จำกัดโดเมน ขององค์กรอาจทำให้คุณไม่สามารถให้สิทธิ์เผยแพร่ได้ หากต้องการแก้ไขปัญหานี้ คุณสามารถกำหนดค่าข้อยกเว้นสำหรับบัญชีบริการนี้ได้

รับข้อมูลอัปเดตกล่องจดหมาย Gmail

หลังจากตั้งค่า Cloud Pub/Sub เริ่มต้นเสร็จแล้ว ให้กำหนดค่าบัญชี Gmail เพื่อส่งการแจ้งเตือนการอัปเดตกล่องจดหมาย

คำขอรับชม

หากต้องการกำหนดค่าบัญชี Gmail ให้ส่งการแจ้งเตือนไปยังหัวข้อ Cloud Pub/Sub ให้ใช้ไคลเอ็นต์ Gmail API เพื่อเรียกใช้เมธอด watch ในกล่องจดหมายของผู้ใช้ Gmail ซึ่งคล้ายกับการเรียก Gmail API อื่นๆ ระบุชื่อหัวข้อที่สร้างขึ้นและตัวเลือกอื่นๆ ในคำขอ watch เช่น labels เพื่อกรอง เช่น ใช้คำขอต่อไปนี้เพื่อรับการแจ้งเตือนทุกครั้งที่มีการเปลี่ยนแปลงกล่องจดหมาย

โปรโตคอล

POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json

{
  topicName: "projects/myproject/topics/mytopic",
  labelIds: ["INBOX"],
  labelFilterBehavior: "INCLUDE",
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic',
  'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()

ดูคำตอบ

หากคำขอ watch สำเร็จ คุณจะได้รับการตอบกลับดังต่อไปนี้

{ historyId: 1234567890 expiration: 1431990098200 }

การตอบกลับมีกล่องจดหมายปัจจุบัน historyId สำหรับผู้ใช้ ไคลเอ็นต์ของคุณ จะได้รับการแจ้งเตือนสำหรับการเปลี่ยนแปลงทั้งหมดหลังจากวันที่ historyId หากต้องการ ประมวลผลการเปลี่ยนแปลงก่อนวันที่ historyId โปรดดูซิงค์ไคลเอ็นต์ กับ Gmail API

นอกจากนี้ การเรียกใช้ watch ที่สำเร็จจะทำให้ระบบส่งการแจ้งเตือนไปยังหัวข้อ Cloud Pub/Sub ของคุณทันที

หากได้รับข้อผิดพลาดจากwatch รายละเอียดควรจะอธิบายถึง แหล่งที่มาของปัญหา โดยปกติแล้วปัญหานี้เกิดจากการตั้งค่าหัวข้อและการสมัครใช้บริการ Cloud Pub/Sub โปรดดูเอกสารประกอบของ Cloud Pub/Sub เพื่อยืนยันว่าการตั้งค่า ถูกต้อง และขอรับความช่วยเหลือในการแก้ไขข้อบกพร่องเกี่ยวกับปัญหาของหัวข้อและการสมัครใช้บริการ

ต่ออายุการดูกล่องจดหมาย

คุณต้องเรียกใช้ watch อย่างน้อย 1 ครั้งทุก 7 วัน มิฉะนั้นคุณจะหยุดรับข้อมูลอัปเดตสำหรับผู้ใช้ เราขอแนะนำให้โทรหา watch วันละครั้ง การตอบกลับเมธอด watch ยังมีฟิลด์ expiration พร้อมการประทับเวลาสำหรับการหมดอายุของ watch ด้วย

รับการแจ้งเตือน

เมื่อใดก็ตามที่มีการอัปเดตกล่องจดหมายที่ตรงกับ watch แอปพลิเคชันของคุณ จะได้รับการแจ้งเตือนที่อธิบายการเปลี่ยนแปลง

หากกำหนดค่าการสมัครรับข้อมูลแบบพุช การแจ้งเตือนเว็บฮุคไปยังเซิร์ฟเวอร์ จะเป็นไปตาม PubsubMessage

POST https://yourserver.example.com/yourUrl
Content-type: application/json

{
  message:
  {
    // This is the actual notification data, as Base64URL-encoded JSON.
    data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",

    // This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
    "messageId": "2070443601311540",

    // This is the publish time of the message.
    "publishTime": "2021-02-26T19:13:55.749Z",
  }

  subscription: "projects/myproject/subscriptions/mysubscription"
}

เนื้อหาของ HTTP POST เป็น JSON และเพย์โหลดการแจ้งเตือน Gmail จริงจะอยู่ในฟิลด์ message.data ฟิลด์ message.data คือสตริงที่เข้ารหัส Base64URL ซึ่งถอดรหัสเป็นออบเจ็กต์ JSON ที่มีอีเมล และรหัสประวัติกล่องจดหมายใหม่สำหรับผู้ใช้

{"emailAddress": "[e-mail]", "historyId": "9876543210"}

จากนั้นคุณจะใช้เมธอด history.list เพื่อดูรายละเอียดการเปลี่ยนแปลงของผู้ใช้ตั้งแต่ครั้งล่าสุดที่ทราบ historyIdได้ตามที่อธิบายไว้ในซิงค์ไคลเอ็นต์กับ Gmail API

เช่น ใช้เมธอด history.list เพื่อระบุการเปลี่ยนแปลงที่เกิดขึ้นระหว่างคำขอ watchเริ่มต้นกับการรับข้อความแจ้งเตือนที่แชร์ในตัวอย่างก่อนหน้า ส่ง 1234567890 เป็น startHistoryId ไปยัง history.list หลังจากนั้น คุณจะ บันทึก 9876543210 เป็น historyId ที่ทราบล่าสุดเพื่อใช้ในกรณีการใช้งานในอนาคตได้

หากกำหนดค่าการสมัครใช้บริการแบบดึงแทน โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับการรับข้อความในตัวอย่างโค้ดในคำแนะนำเกี่ยวกับการสมัครใช้บริการแบบดึงของ Cloud Pub/Sub

ตอบสนองต่อการแจ้งเตือนต่างๆ

ต้องรับทราบการแจ้งเตือนทั้งหมด หากคุณใช้ push delivery ของ Webhook การตอบกลับ สำเร็จ (เช่น HTTP 200) จะเป็นการรับทราบการแจ้งเตือน

หากใช้การนำส่งแบบดึง (REST Pull, RPC Pull หรือ RPC StreamingPull) คุณต้องติดตามด้วยการเรียกการรับทราบ (REST หรือ RPC) ดูรายละเอียดเพิ่มเติมเกี่ยวกับการรับทราบข้อความแบบไม่พร้อมกันหรือแบบพร้อมกันโดยใช้ไลบรารีไคลเอ็นต์อย่างเป็นทางการที่อิงตาม RPC ได้ในตัวอย่างโค้ดในคู่มือการสมัครใช้บริการแบบดึงของ Cloud Pub/Sub

หากคุณไม่รับทราบการแจ้งเตือน (เช่น หาก Webhook Callback แสดงข้อผิดพลาดหรือหมดเวลา) Cloud Pub/Sub จะลองส่งการแจ้งเตือนอีกครั้ง ในภายหลัง

หยุดการอัปเดตกล่องจดหมาย

หากต้องการหยุดรับข้อมูลอัปเดตในกล่องจดหมาย ให้เรียกใช้เมธอด stop การแจ้งเตือนใหม่ทั้งหมดควรหยุดภายในไม่กี่นาที

ข้อจำกัด

ข้อจำกัดในการทำงานกับข้อความ Push จากเซิร์ฟเวอร์มีดังนี้

อัตราการแจ้งเตือนสูงสุด

ผู้ใช้ Gmail แต่ละรายที่กำลังดูอยู่จะมีการแจ้งเตือนสูงสุด 1 เหตุการณ์ต่อวินาที ระบบจะทิ้งการแจ้งเตือนของผู้ใช้ที่เกินอัตราดังกล่าว เมื่อจัดการการแจ้งเตือน ให้ระมัดระวังอย่าทริกเกอร์การแจ้งเตือนอื่น ซึ่งอาจทำให้เกิดลูปการแจ้งเตือน

ความน่าเชื่อถือ

โดยปกติแล้ว ระบบจะส่งการแจ้งเตือนทั้งหมดอย่างน่าเชื่อถือภายในไม่กี่วินาที อย่างไรก็ตาม ในบางสถานการณ์ที่รุนแรง การแจ้งเตือนอาจล่าช้าหรือถูกทิ้ง จัดการความเป็นไปได้นี้อย่างเหมาะสมเพื่อให้แอปพลิเคชันยังคงซิงค์ได้แม้ว่าจะไม่ได้รับข้อความพุช เช่น กลับไปเรียกใช้เมธอด history.list เป็นระยะๆ หลังจากที่ไม่มีการแจ้งเตือนสำหรับผู้ใช้ในช่วงระยะเวลาหนึ่ง

ข้อจำกัดของ Cloud Pub/Sub

นอกจากนี้ Cloud Pub/Sub API ยังมีข้อจำกัดของตัวเอง ซึ่งมีรายละเอียดอยู่ในเอกสารประกอบราคาและโควต้า