ข้อความ Push

ภาพรวม

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 Developers Console)

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

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

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

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

โดยคุณต้องให้สิทธิ์ publish แก่ gmail-api-push@system.gserviceaccount.com คุณทำได้โดยใช้อินเทอร์เฟซสิทธิ์ของ Cloud Pub/Sub Developer Console ตามวิธีการควบคุมการเข้าถึงระดับทรัพยากร

การรับข้อมูลอัปเดตกล่องจดหมาย 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 โปรดดูคำแนะนำในการซิงค์

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

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

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

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

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

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

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

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

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

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

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

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

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

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

หากต้องการหยุดรับข้อมูลอัปเดตในกล่องจดหมาย ให้โทรไปที่ stop และการแจ้งเตือนใหม่ทั้งหมด จะหยุดภายใน 2-3 นาที

ข้อจำกัด

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

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

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

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

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

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