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

เอกสารนี้อธิบายวิธีจัดการการแจ้งเตือนแบบพุชด้วย Gmail API

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

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

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

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

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

โดยให้สิทธิ์ publish แก่ gmail-api-push@system.gserviceaccount.com คุณทำได้โดยใช้คอนโซลสิทธิ์ 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

นอกจากนี้ การเรียกใช้ 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": "user@example.com", "historyId": "9876543210"}

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

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

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

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

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

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

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

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

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

ข้อจำกัด

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

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

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

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

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

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

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