ข้อความ Push

เอกสารนี้อธิบายวิธีใช้ข้อความ Push ที่แจ้งให้แอปพลิเคชันทราบเมื่อมีการเปลี่ยนแปลงทรัพยากร

ภาพรวม

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

หากต้องการใช้ข้อความ Push คุณต้องดําเนินการ 2 อย่างต่อไปนี้

  • ตั้งค่า URL ผู้รับหรือ "Callback Receiver" ของเว็บฮุค

    ซึ่งเป็นเซิร์ฟเวอร์ HTTPS ที่จัดการข้อความแจ้งเตือน API ที่มีการเรียกใช้เมื่อทรัพยากรมีการเปลี่ยนแปลง

  • ตั้งค่าช่องทางการแจ้งเตือนสําหรับปลายทางทรัพยากรแต่ละรายการที่ต้องการดู

    ช่องทางระบุข้อมูลการกําหนดเส้นทางสําหรับข้อความแจ้งเตือน ในการตั้งค่าช่อง คุณจะระบุ URL เฉพาะที่ต้องการรับการแจ้งเตือน เมื่อใดก็ตามที่มีการเปลี่ยนแปลงทรัพยากรของช่อง Google Calendar API จะส่งการแจ้งเตือนเป็นคําขอ POST ไปยัง URL นั้น

ปัจจุบัน Google ปฏิทิน API สนับสนุนการแจ้งเตือนสําหรับการเปลี่ยนแปลงทรัพยากร Acl, CalendarList, Event และ Settings

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

หากต้องการขอข้อความ Push คุณจะต้องตั้งค่าช่องทางการแจ้งเตือนสําหรับทรัพยากรแต่ละรายการที่ต้องการดู หลังจากตั้งค่าช่องทางการแจ้งเตือนแล้ว Google Calendar API จะแจ้งแอปพลิเคชันของคุณเมื่อมีการเปลี่ยนแปลงทรัพยากรที่ดู

การสร้างคําขอนาฬิกา

ทรัพยากร API ของ Google ปฏิทินที่ดูได้แต่ละรายการจะมีเมธอด watch ที่เชื่อมโยงที่ URI ในรูปแบบต่อไปนี้

https://www.googleapis.com/apiName/apiVersion/resourcePath/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 Calendar 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, Event และ Settings ในการอ้างอิง 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, Event และ 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 ปฏิทิน 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 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 Calendar API จะส่งข้อความเหล่านี้เป็นคําขอ POST ของ HTTPS ไปยัง URL ที่คุณระบุว่าเป็น "ที่อยู่" สําหรับช่องทางการแจ้งเตือนนี้

ทําความเข้าใจรูปแบบข้อความแจ้งเตือน

ข้อความแจ้งเตือนทั้งหมดจะมีชุดส่วนหัว HTTP ที่มีคํานําหน้า X-Goog- การแจ้งเตือนบางประเภทอาจมีเนื้อหาข้อความด้วย

ส่วนหัว

ข้อความแจ้งเตือนที่โพสต์โดย Google ปฏิทิน API ไปยัง URL การรับของคุณมีส่วนหัว HTTP ต่อไปนี้:

ส่วนหัว คำอธิบาย
นําเสนอเสมอ
X-Goog-Channel-ID UUID หรือสตริงที่ไม่ซ้ํากันอื่นๆ ที่คุณระบุเพื่อระบุช่องทางการแจ้งเตือนนี้
X-Goog-Message-Number จํานวนเต็มที่ระบุข้อความนี้สําหรับช่องการแจ้งเตือนนี้ ค่า 1 สําหรับข้อความ sync เสมอ หมายเลขของข้อความแต่ละข้อความจะเพิ่มขึ้นตามลําดับในแชแนล แต่ไม่เรียงตามลําดับ
X-Goog-Resource-ID ค่าทึบแสงที่ระบุทรัพยากรที่ดู ซึ่งรหัสนี้จะคงที่ทั่วทุกเวอร์ชัน API
X-Goog-Resource-State สถานะทรัพยากรใหม่ที่จะเรียกใช้การแจ้งเตือน ค่าที่เป็นไปได้คือ sync, exists หรือ not_exists
X-Goog-Resource-URI ตัวระบุเฉพาะ API สําหรับทรัพยากรที่ดู
บางครั้งก็มี
X-Goog-Channel-Expiration วันที่และเวลาที่หมดอายุของช่องทางการแจ้งเตือน ซึ่งแสดงในรูปแบบที่มนุษย์อ่านได้ แสดงเมื่อกําหนดไว้เท่านั้น
X-Goog-Channel-Token โทเค็นช่องทางการแจ้งเตือนที่แอปพลิเคชันกําหนด และคุณจะใช้เพื่อยืนยันแหล่งที่มาของการแจ้งเตือนได้ แสดงเมื่อนิยามเท่านั้น

ข้อความแจ้งเตือนที่โพสต์โดย 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

X-Goog-Resource-State ใช้กับ นําส่งเมื่อ
sync ACL, รายการปฏิทิน, กิจกรรม, การตั้งค่า สร้างช่องใหม่เรียบร้อยแล้ว คุณน่าจะเริ่มได้รับการแจ้งเตือน
exists ACL, รายการปฏิทิน, กิจกรรม, การตั้งค่า มีการเปลี่ยนแปลงทรัพยากร การเปลี่ยนแปลงที่เป็นไปได้รวมถึงการสร้างทรัพยากรใหม่ หรือการแก้ไขหรือการลบทรัพยากรที่มีอยู่

กําลังหยุดการแจ้งเตือน

เวลาหมดอายุคือเวลาที่การแจ้งเตือนหยุดโดยอัตโนมัติ คุณเลือกหยุดรับการแจ้งเตือนสําหรับช่องใดช่องหนึ่งก่อนที่จะหมดอายุได้โดยเรียกใช้เมธอด 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 {auth_token_for_current_user}
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}