ภาพรวม
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