ข้อความ Push

ภาพรวม

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

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

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

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

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

สร้างหัวข้อ

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

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

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

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

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

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 แอปพลิเคชันของคุณจะได้รับข้อความแจ้งเตือนที่อธิบายการเปลี่ยนแปลง

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

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

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

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

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

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

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

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

ข้อจำกัด

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

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

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

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

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

นอกจากนี้ Cloud Pub/Sub API ยังมีข้อจำกัดของตนเอง โดยเฉพาะในกรณีที่มีรายละเอียดอยู่ในเอกสารประกอบเกี่ยวกับpricingและquotas