ข้อความ Push

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

ภาพรวม

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

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

  • ตั้งค่าผู้รับสายเรียกกลับของ URL ที่รับข้อความหรือ "เว็บฮุค"

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

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

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

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

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

หากต้องการขอข้อความ Push คุณต้องตั้งค่าช่องทางการแจ้งเตือนสำหรับแหล่งข้อมูลแต่ละรายการที่ต้องการดู หลังจากตั้งค่าช่องทางการแจ้งเตือนแล้ว Google ปฏิทิน 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 ปฏิทิน 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, Events และ การตั้งค่า ในการอ้างอิง 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 และการตั้งค่าในการอ้างอิง 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 ปฏิทิน API จะส่งข้อความเหล่านี้เป็นคำขอ HTTPS POST ไปยัง URL ที่คุณระบุเป็น "ที่อยู่" สำหรับช่องทางการแจ้งเตือนนี้

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

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

ส่วนหัว

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

ข้อความแจ้งเตือนที่โพสต์โดย API Google ปฏิทินไปยัง 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 Calendar 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"
}