ข้อความ Push

ภาพรวม

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

การตั้งค่า Cloud Pub/Sub เบื้องต้น

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

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

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

สร้างหัวข้อ

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

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

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

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

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

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

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

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

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

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

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

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

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

ข้อจำกัด

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

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

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

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

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

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