เอกสารนี้จะอธิบายวิธีใช้ข้อความ Push ที่จะแจ้งใบสมัครเมื่อทรัพยากรมีการเปลี่ยนแปลง
ภาพรวม
Google ปฏิทิน API ส่งข้อความ Push ที่ช่วยให้คุณตรวจสอบการเปลี่ยนแปลงในทรัพยากรได้ คุณใช้ฟีเจอร์นี้เพื่อปรับปรุงประสิทธิภาพของแอปพลิเคชันได้ ซึ่งช่วยให้คุณตัดค่าใช้จ่ายของเครือข่ายและการประมวลผลเพิ่มเติมที่เกี่ยวข้องกับทรัพยากรการสำรวจเพื่อดูว่ามีการเปลี่ยนแปลงหรือไม่ เมื่อใดก็ตามที่มีการเปลี่ยนแปลงทรัพยากรที่ดูแล้ว Google Calendar API จะแจ้งแอปพลิเคชันของคุณ
หากต้องการใช้ข้อความ Push คุณต้องดำเนินการ 2 อย่างต่อไปนี้
ตั้งค่าผู้รับติดต่อกลับสำหรับ URL หรือ "เว็บฮุค"
ซึ่งเป็นเซิร์ฟเวอร์ HTTPS ที่จัดการข้อความแจ้งเตือน API ที่ทริกเกอร์เมื่อมีการเปลี่ยนแปลงทรัพยากร
ตั้งค่า (ช่องทางการแจ้งเตือน) สำหรับปลายทางของทรัพยากรแต่ละแห่งที่ต้องการดู
แชแนลระบุข้อมูลการกำหนดเส้นทางสำหรับข้อความแจ้งเตือน ในการตั้งค่าช่อง คุณต้องระบุ URL เฉพาะที่ต้องการรับการแจ้งเตือน เมื่อใดก็ตามที่มีการเปลี่ยนแปลงทรัพยากรของช่อง Google Calendar API จะส่งข้อความแจ้งเตือนเป็นคำขอ
POST
ไปยัง URL นั้น
ขณะนี้ Google ปฏิทิน API รองรับการแจ้งเตือนสำหรับการเปลี่ยนแปลงทรัพยากร Acl, CalendarList, กิจกรรม และการตั้งค่า
สร้างช่องทางการแจ้งเตือน
หากต้องการขอข้อความ Push คุณต้องตั้งค่าช่องทางการแจ้งเตือนสำหรับทรัพยากรแต่ละรายการที่ต้องการตรวจสอบ หลังจากตั้งค่าช่องทางการแจ้งเตือนแล้ว Google Calendar API จะแจ้งแอปพลิเคชันเมื่อทรัพยากรที่ดูมีการเปลี่ยนแปลง
สร้างคำขอเป็นนาฬิกา
ทรัพยากร API ของ Google ปฏิทินที่ดูได้แต่ละรายการจะมีเมธอด watch
ที่เชื่อมโยงที่ URI ของรูปแบบต่อไปนี้
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
หากต้องการตั้งค่าช่องทางการแจ้งเตือนสำหรับข้อความเกี่ยวกับการเปลี่ยนแปลงในทรัพยากรหนึ่งๆ ให้ส่งคำขอ POST
ไปยังเมธอด watch
สำหรับทรัพยากรดังกล่าว
ช่องทางการแจ้งเตือนแต่ละช่องทางจะเชื่อมโยงกับทั้งผู้ใช้รายหนึ่งๆ และทรัพยากรที่เฉพาะเจาะจง (หรือชุดทรัพยากร) คำขอ watch
จะไม่สำเร็จ เว้นแต่ผู้ใช้ปัจจุบันจะเป็นเจ้าของหรือมีสิทธิ์เข้าถึงทรัพยากรนี้
ตัวอย่าง
เริ่มดูการเปลี่ยนแปลงของคอลเล็กชันกิจกรรมในปฏิทินที่ระบุ
POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch Authorization: Bearer auth_token_for_current_user Content-Type: application/json { "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration time. }
พร็อพเพอร์ตี้ที่จำเป็น
ในคำขอ watch
แต่ละรายการ คุณต้องระบุข้อมูลในช่องต่อไปนี้
-
สตริงพร็อพเพอร์ตี้
id
ที่ระบุช่องทางการแจ้งเตือนใหม่นี้ภายในโปรเจ็กต์ได้โดยไม่ซ้ำกัน เราขอแนะนำให้ใช้ตัวระบุที่ไม่ซ้ำกันทั่วโลก (UUID) หรือสตริงที่ไม่ซ้ำกันซึ่งมีค่าคล้ายกัน ความยาวสูงสุด: 64 อักขระค่ารหัสที่คุณกำหนดจะสะท้อนกลับในส่วนหัว HTTP
X-Goog-Channel-Id
ของข้อความแจ้งเตือนทั้งหมดที่คุณได้รับสำหรับช่องนี้ -
ตั้งค่าสตริงพร็อพเพอร์ตี้
type
เป็นค่าweb_hook
-
สตริงพร็อพเพอร์ตี้
address
ที่ตั้งค่าเป็น URL ที่รอฟังและตอบสนองต่อการแจ้งเตือนสำหรับช่องทางการแจ้งเตือนนี้ นี่คือ URL เรียกกลับของเว็บฮุคและต้องใช้ HTTPSโปรดทราบว่า Google ปฏิทิน API จะส่งการแจ้งเตือนไปยังที่อยู่ HTTPS นี้ได้เฉพาะในกรณีที่มีการติดตั้งใบรับรอง SSL ที่ถูกต้องในเว็บเซิร์ฟเวอร์ของคุณเท่านั้น ใบรับรองที่ไม่ถูกต้อง ได้แก่
- ใบรับรองแบบ Self-signed
- ใบรับรองที่ลงนามโดยแหล่งที่มาที่ไม่น่าเชื่อถือ
- ใบรับรองที่เพิกถอนไปแล้ว
- ใบรับรองที่มีเรื่องที่ไม่ตรงกับชื่อโฮสต์เป้าหมาย
พร็อพเพอร์ตี้ที่ไม่บังคับ
คุณยังระบุช่องที่ไม่บังคับเหล่านี้ด้วยคำขอ watch
ได้อีกด้วย
-
พร็อพเพอร์ตี้
token
ที่ระบุค่าสตริงที่กำหนดเองเพื่อใช้เป็นโทเค็นแชแนล คุณใช้โทเค็นช่องทางการแจ้งเตือนเพื่อวัตถุประสงค์ต่างๆ ได้ เช่น คุณสามารถใช้โทเค็นเพื่อยืนยันว่าข้อความขาเข้าแต่ละข้อความมีไว้สำหรับช่องที่แอปพลิเคชันสร้างขึ้น เพื่อให้มั่นใจว่าการแจ้งเตือนไม่ได้ถูกปลอมแปลง หรือเพื่อกำหนดเส้นทางข้อความไปยังปลายทางที่ถูกต้องภายในแอปพลิเคชันตามวัตถุประสงค์ของช่องนี้ ความยาวสูงสุด: 256 อักขระโทเค็นนี้จะรวมอยู่ในส่วนหัว HTTP ของ
X-Goog-Channel-Token
ในข้อความแจ้งเตือนทั้งหมดที่แอปพลิเคชันได้รับสำหรับช่องนี้หากคุณใช้โทเค็นช่องทางการแจ้งเตือน เราขอแนะนำให้คุณทำดังนี้
ใช้รูปแบบการเข้ารหัสที่ขยายได้ เช่น พารามิเตอร์การค้นหาของ URL เช่น
forwardTo=hr&createdBy=mobile
อย่าใส่ข้อมูลที่ละเอียดอ่อน เช่น โทเค็น OAuth
-
สตริงพร็อพเพอร์ตี้
expiration
ที่ตั้งค่าเป็นการประทับเวลา Unix (เป็นมิลลิวินาที) ของวันที่และเวลาที่คุณต้องการให้ Google ปฏิทิน API หยุดส่งข้อความสำหรับช่องทางการแจ้งเตือนนี้หากแชแนลมีเวลาหมดอายุ เวลาดังกล่าวจะรวมไว้เป็นค่าของส่วนหัว HTTP ของ
X-Goog-Channel-Expiration
(ในรูปแบบที่มนุษย์อ่านได้) ในข้อความแจ้งเตือนทั้งหมดที่แอปพลิเคชันได้รับสำหรับช่องนี้
โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับคําขอที่เมธอด watch
สําหรับทรัพยากร Acl, CalendarList, เหตุการณ์ และการตั้งค่าในการอ้างอิง API
ดูการตอบสนอง
หากคำขอ watch
สร้างช่องทางการแจ้งเตือนสำเร็จ คำขอจะแสดงรหัสสถานะ HTTP 200 OK
ส่วนเนื้อหาข้อความการตอบกลับของนาฬิกาจะให้ข้อมูลเกี่ยวกับช่องทางการแจ้งเตือนที่คุณเพิ่งสร้างขึ้นดังที่แสดงในตัวอย่างด้านล่าง
{ "kind": "api#channel", "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource. "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable. }
นอกเหนือจากพร็อพเพอร์ตี้ที่คุณส่งมาในคําขอแล้ว ข้อมูลที่แสดงผลยังมี resourceId
และ resourceUri
เพื่อระบุทรัพยากรที่กําลังดูในช่องการแจ้งเตือนนี้ด้วย
คุณส่งต่อข้อมูลที่ส่งคืนไปยังการดำเนินการอื่นๆ ของช่องทางการแจ้งเตือนได้ เช่น เมื่อคุณต้องการหยุดรับการแจ้งเตือน
ดูรายละเอียดเพิ่มเติมเกี่ยวกับการตอบกลับได้ที่เมธอด watch
สำหรับทรัพยากร Acl, CalendarList, Events และ Settings ในการอ้างอิง API
ซิงค์ข้อความ
หลังจากสร้างช่องทางการแจ้งเตือนสำหรับการดูทรัพยากรแล้ว Google Calendar API จะส่งข้อความ sync
เพื่อระบุว่าการแจ้งเตือนกำลังจะเริ่มขึ้น ค่าส่วนหัว HTTP ของ X-Goog-Resource-State
สำหรับข้อความเหล่านี้คือ sync
เนื่องจากปัญหาด้านเวลาของเครือข่าย คุณจึงอาจได้รับข้อความ sync
ก่อนที่จะได้รับการตอบกลับโดยใช้เมธอด watch
ไม่ต้องสนใจการแจ้งเตือน sync
แต่คุณก็ใช้การแจ้งเตือนนี้ได้เช่นกัน เช่น หากตัดสินใจว่าไม่ต้องการเก็บช่องทางไว้ คุณสามารถใช้ค่า X-Goog-Channel-ID
และ X-Goog-Resource-ID
ในการโทรเพื่อหยุดรับการแจ้งเตือนได้ นอกจากนี้ คุณยังใช้การแจ้งเตือน sync
ในการเริ่มต้นใช้งานเพื่อเตรียมพร้อมสำหรับเหตุการณ์ในอนาคตได้ด้วย
รูปแบบของข้อความ sync
ที่ Google Calendar API ส่งไปยัง URL ที่รับจะปรากฏด้านล่าง
POST https://mydomain.com/notifications // Your receiving URL. X-Goog-Channel-ID: channel-ID-value X-Goog-Channel-Token: channel-token-value X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires. X-Goog-Resource-ID: identifier-for-the-watched-resource X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource X-Goog-Resource-State: sync X-Goog-Message-Number: 1
ข้อความที่ซิงค์จะมีค่าส่วนหัว HTTP X-Goog-Message-Number
เป็น 1
เสมอ การแจ้งเตือนที่ตามมาสำหรับช่องนี้แต่ละครั้งจะมีหมายเลขข้อความที่มากกว่าจำนวนก่อนหน้า แม้ว่าจำนวนข้อความจะไม่เรียงตามลำดับก็ตาม
ต่ออายุช่องทางการแจ้งเตือน
ช่องทางการแจ้งเตือนอาจมีเวลาหมดอายุ ซึ่งเป็นค่าที่จะกำหนดตามคำขอของคุณหรือจากขีดจำกัดภายในหรือค่าเริ่มต้นของ Google ปฏิทิน API (ใช้ค่าที่จำกัดมากกว่า) เวลาหมดอายุของช่อง (หากมี) จะรวมเป็นการประทับเวลา Unix (หน่วยเป็นมิลลิวินาที) ในข้อมูลที่แสดงผลโดยเมธอด watch
นอกจากนี้ ยังระบุวันที่และเวลาหมดอายุ (ในรูปแบบที่มนุษย์อ่านได้) ในข้อความแจ้งเตือนทั้งหมดที่แอปพลิเคชันได้รับสำหรับแชแนลนี้ในส่วนหัว HTTP ของ X-Goog-Channel-Expiration
ปัจจุบันยังไม่มีวิธีต่ออายุช่องทางการแจ้งเตือนโดยอัตโนมัติ เมื่อแชแนลใกล้หมดอายุ คุณต้องแทนที่ด้วยแชแนลใหม่โดยเรียกใช้เมธอด watch
และเช่นเคย คุณต้องใช้ค่าที่ไม่ซ้ำกันสำหรับพร็อพเพอร์ตี้ id
ของแชแนลใหม่ โปรดทราบว่าอาจมีช่วงเวลา "ทับซ้อนกัน" เมื่อมีการใช้งานช่องทางการแจ้งเตือน 2 ช่องทางสำหรับทรัพยากรเดียวกัน
รับการแจ้งเตือน
เมื่อใดก็ตามที่มีการเปลี่ยนแปลงของทรัพยากรที่ดู แอปพลิเคชันของคุณจะได้รับข้อความแจ้งเตือนที่อธิบายการเปลี่ยนแปลงดังกล่าว Google ปฏิทิน API จะส่งข้อความเหล่านี้เป็นคำขอ HTTPS POST
ไปยัง URL ที่คุณระบุเป็นพร็อพเพอร์ตี้ address
สำหรับช่องทางการแจ้งเตือนนี้
ตีความรูปแบบข้อความแจ้งเตือน
ข้อความแจ้งเตือนทั้งหมดจะมีชุดส่วนหัว HTTP ที่มีคำนำหน้า X-Goog-
การแจ้งเตือนบางประเภทใส่เนื้อหาข้อความได้ด้วย
ส่วนหัว
ข้อความแจ้งเตือนที่โพสต์โดย Google Calendar API ไปยัง URL ที่คุณรับจะมีส่วนหัว HTTP ต่อไปนี้
ส่วนหัว | คำอธิบาย |
---|---|
แสดงตัวเสมอ | |
|
UUID หรือสตริงที่ไม่ซ้ำกันอื่นๆ ที่คุณระบุเพื่อระบุช่องทางการแจ้งเตือนนี้ |
|
จำนวนเต็มที่ระบุข้อความนี้สำหรับช่องทางการแจ้งเตือนนี้ ค่าจะเป็น 1 เสมอสำหรับ sync ข้อความ จำนวนข้อความที่เพิ่มขึ้นสําหรับข้อความต่อๆ มาในแชแนลแต่ละรายการจะไม่เรียงตามลำดับ |
|
ค่าทึบที่ระบุทรัพยากรที่ดู รหัสนี้เสถียรใน API เวอร์ชันต่างๆ |
|
สถานะทรัพยากรใหม่ที่ทริกเกอร์การแจ้งเตือน
ค่าที่เป็นไปได้ ได้แก่ sync , exists หรือ not_exists
|
|
ตัวระบุเฉพาะเวอร์ชัน API สำหรับทรัพยากรที่ดู |
บางครั้ง | |
|
วันที่และเวลาที่ช่องทางการแจ้งเตือนหมดอายุ แสดงในรูปแบบที่มนุษย์อ่านได้ แสดงเมื่อกำหนดไว้เท่านั้น |
|
โทเค็นช่องทางการแจ้งเตือนที่แอปพลิเคชันตั้งค่าไว้ ซึ่งคุณใช้เพื่อยืนยันแหล่งที่มาของการแจ้งเตือนได้ แสดงเมื่อกำหนดไว้เท่านั้น |
ข้อความแจ้งเตือนที่โพสต์โดย Google Calendar API ไปยัง URL ที่คุณรับจะไม่มีเนื้อหาของข้อความ ข้อความเหล่านี้ไม่มีข้อมูลที่เฉพาะเจาะจงเกี่ยวกับทรัพยากรที่อัปเดต คุณจะต้องเรียก API อีกครั้งเพื่อดูรายละเอียดการเปลี่ยนแปลงทั้งหมด
ตัวอย่าง
เปลี่ยนข้อความแจ้งเตือนสำหรับคอลเล็กชันเหตุการณ์ที่แก้ไข:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66 X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events X-Goog-Resource-State: exists X-Goog-Message-Number: 10
ตอบสนองต่อการแจ้งเตือนต่างๆ
คุณแสดงผลรหัสสถานะ 200
, 201
, 202
, 204
หรือ 102
เพื่อแสดงถึงความสําเร็จ
หากบริการของคุณใช้ไลบรารีของไคลเอ็นต์ API ของ Google และแสดงผล 500
,502
, 503
หรือ 504
ระบบของ Google ปฏิทิน API จะลองใหม่โดยใช้การย้อนกลับแบบเอ็กซ์โปเนนเชียล
รหัสสถานะการคืนสินค้าอื่นๆ ทั้งหมดจะถือว่าเป็นข้อความล้มเหลว
ทำความเข้าใจกิจกรรมการแจ้งเตือนของ Google Calendar API
ส่วนนี้แสดงรายละเอียดเกี่ยวกับข้อความแจ้งเตือนที่คุณได้รับเมื่อใช้ข้อความ Push กับ Google ปฏิทิน API
ส่งเมื่อ | ||
---|---|---|
sync |
ACL, รายการปฏิทิน, กิจกรรม, การตั้งค่า | สร้างช่องใหม่เรียบร้อยแล้ว โดยจะเริ่มได้รับการแจ้งเตือนเกี่ยวกับการดำเนินการดังกล่าว |
exists |
ACL, รายการปฏิทิน, กิจกรรม, การตั้งค่า | มีการเปลี่ยนแปลงในทรัพยากร การเปลี่ยนแปลงที่เป็นไปได้ ได้แก่ การสร้างทรัพยากรใหม่ การแก้ไข หรือการลบทรัพยากรที่มีอยู่ |
ปิดการแจ้งเตือน
พร็อพเพอร์ตี้ expiration
จะควบคุมเวลาที่การแจ้งเตือนหยุดโดยอัตโนมัติ คุณเลือกหยุดรับการแจ้งเตือนสำหรับช่องใดช่องหนึ่งก่อนที่ช่องจะหมดอายุได้โดยเรียกใช้เมธอด stop
ที่ URI ต่อไปนี้
https://www.googleapis.com/calendar/v3/channels/stop
วิธีนี้กำหนดให้คุณต้องระบุ id
ของช่องและพร็อพเพอร์ตี้ resourceId
เป็นอย่างน้อย ดังที่แสดงในตัวอย่างด้านล่าง โปรดทราบว่าหาก Google ปฏิทิน API มีทรัพยากรหลายประเภทที่มีเมธอด watch
จะมีเมธอด stop
เพียงเมธอดเดียวเท่านั้น
มีเพียงผู้ใช้ที่มีสิทธิ์ที่เหมาะสมเท่านั้นที่จะหยุดช่องได้ โดยเฉพาะอย่างยิ่งฟีเจอร์ต่อไปนี้
- หากแชแนลสร้างโดยบัญชีผู้ใช้ทั่วไป จะมีเพียงผู้ใช้รายเดียวกันจากไคลเอ็นต์เดียวกัน (ที่ระบุโดยรหัสไคลเอ็นต์ OAuth 2.0 จากโทเค็นการตรวจสอบสิทธิ์) ที่สร้างแชแนลเท่านั้นที่หยุดแชแนลได้
- หากบัญชีบริการสร้างแชแนล ผู้ใช้จากไคลเอ็นต์เดียวกันจะหยุดใช้แชแนลได้
ตัวอย่างโค้ดต่อไปนี้แสดงวิธีหยุดรับการแจ้งเตือน
POST https://www.googleapis.com/calendar/v3/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }