ข้อความ Push

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

ภาพรวม

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

หากต้องการใช้ข้อความ Push คุณต้องทำ 2 สิ่งต่อไปนี้

  • ตั้งค่า URL ที่รับหรือเครื่องรับการเรียกกลับ "Webhook"

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

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

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

ปัจจุบัน Google Calendar API รองรับการแจ้งเตือนการเปลี่ยนแปลงทรัพยากร Acl, CalendarList, Events และ Settings

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

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

ส่งคำขอให้ดู

ทรัพยากร Google ปฏิทิน API ที่ดูได้แต่ละรายการจะมีเมธอด 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

ในเนื้อหาของคำขอ ให้ระบุช่อง id ของคุณ type เป็น web_hook และ URL ที่รับใน address นอกจากนี้ คุณยังระบุข้อมูลต่อไปนี้ได้ด้วย (ไม่บังคับ)

  • token เพื่อใช้เป็นโทเค็นของช่อง
  • expiration เวลาเป็นมิลลิวินาทีสำหรับเวลาหมดอายุของช่องที่คุณขอ

พร็อพเพอร์ตี้ที่จำเป็น

คุณต้องระบุฟิลด์ต่อไปนี้ในคำขอ watch แต่ละรายการ

  • id สตริงพร็อพเพอร์ตี้ที่ระบุช่องทางการแจ้งเตือนใหม่นี้ได้อย่างไม่ซ้ำกัน ภายในโปรเจ็กต์ เราขอแนะนำให้ใช้ ตัวระบุที่ไม่ซ้ำกับผู้อื่น (UUID) หรือสตริงที่ไม่ซ้ำ ที่คล้ายกัน ความยาวสูงสุด 64 อักขระ

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

  • สตริงพร็อพเพอร์ตี้ type ที่ตั้งค่าเป็น web_hook

  • addressสตริงพร็อพเพอร์ตี้ที่ตั้งค่าเป็น URL ที่รับฟัง และตอบกลับการแจ้งเตือนสำหรับช่องการแจ้งเตือนนี้ นี่คือ URL การเรียกกลับของ Webhook และต้องใช้ HTTPS

    โปรดทราบว่า Google Calendar API จะส่งการแจ้งเตือนไปยังที่อยู่ HTTPS นี้ได้ก็ต่อเมื่อมีการติดตั้งใบรับรอง SSL ที่ถูกต้องในเว็บเซิร์ฟเวอร์ ใบรับรองที่ไม่ถูกต้องมีดังนี้

    • ใบรับรองแบบ Self-signed
    • ใบรับรองที่ลงนามโดยแหล่งที่มาที่ไม่น่าเชื่อถือ
    • ใบรับรองที่เพิกถอนไปแล้ว
    • ใบรับรองที่มีเรื่องที่ไม่ตรงกับชื่อโฮสต์เป้าหมาย

พร็อพเพอร์ตี้ที่ไม่บังคับ

นอกจากนี้ คุณยังระบุฟิลด์ที่ไม่บังคับเหล่านี้พร้อมกับ watch คำขอได้ด้วย

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

    โทเค็นจะรวมอยู่ใน X-Goog-Channel-Token ส่วนหัว HTTP ในข้อความแจ้งเตือนทุกข้อความ ที่แอปพลิเคชันของคุณได้รับสำหรับช่องนี้

    หากใช้โทเค็นแชแนลการแจ้งเตือน เราขอแนะนำให้คุณทำดังนี้

    • ใช้รูปแบบการเข้ารหัสที่ขยายได้ เช่น พารามิเตอร์การค้นหาของ URL ตัวอย่าง: forwardTo=hr&createdBy=mobile

    • อย่าใส่ข้อมูลที่ละเอียดอ่อน เช่น โทเค็น OAuth

  • สตริงพร็อพเพอร์ตี้ expiration ที่ตั้งค่าเป็น การประทับเวลา Unix (เป็นมิลลิวินาที) ของวันที่และเวลาที่คุณต้องการให้ Google Calendar API หยุดส่งข้อความสำหรับช่องทางการแจ้งเตือนนี้

    หากช่องมีเวลาหมดอายุ ระบบจะรวมเวลาดังกล่าวเป็นค่า ของX-Goog-Channel-Expirationส่วนหัว HTTP (ในรูปแบบที่มนุษย์อ่านได้ ) ในข้อความแจ้งเตือนทุกข้อความที่แอปพลิเคชัน ของคุณได้รับสำหรับช่องนี้

ดูรายละเอียดเพิ่มเติมเกี่ยวกับคำขอได้ที่เมธอด watch สำหรับทรัพยากร Acl, CalendarList, Events และ Settings ในข้อมูลอ้างอิง API

ดูคำตอบ

หากคำขอ watch สร้างช่องการแจ้งเตือนสำเร็จ ระบบจะแสดงรหัสสถานะ 200 OK HTTP

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

เนื้อหาการตอบกลับจะแสดงรายละเอียดช่อง เช่น

  • kind: ระบุว่านี่คือทรัพยากรช่อง API
  • id: รหัสที่คุณระบุสำหรับช่องนี้
  • resourceId: รหัสของทรัพยากรที่ดู
  • resourceUri: รหัสเฉพาะเวอร์ชันของทรัพยากรที่ดู
  • token: โทเค็นที่ระบุในเนื้อหาคำขอ
  • expiration: เวลาหมดอายุของช่องเป็น Unix Timestamp ในหน่วยมิลลิวินาที

นอกจากพร็อพเพอร์ตี้ที่คุณส่งเป็นส่วนหนึ่งของคำขอแล้ว ข้อมูลที่ส่งคืนยังรวมถึง resourceId และ resourceUri เพื่อระบุแหล่งข้อมูลที่กำลังรับชมในช่องทางการแจ้งเตือนนี้ด้วย

คุณสามารถส่งข้อมูลที่ได้รับไปยังการดำเนินการช่องทางการแจ้งเตือนอื่นๆ ได้ เช่น เมื่อต้องการหยุดรับการแจ้งเตือน

ดูรายละเอียดเพิ่มเติมเกี่ยวกับคำตอบได้ที่เมธอด watch สำหรับทรัพยากร Acl, CalendarList, Events และ Settings ในข้อมูลอ้างอิง API

ซิงค์ข้อความ

หลังจากสร้างช่องการแจ้งเตือนเพื่อดูทรัพยากรแล้ว Google Calendar API จะส่งsyncเพื่อระบุว่า การแจ้งเตือนกำลังจะเริ่มขึ้น ค่าส่วนหัว HTTP ของ X-Goog-Resource-State สำหรับข้อความเหล่านี้คือ sync เนื่องจากปัญหาด้านเวลาของเครือข่าย คุณอาจได้รับsyncข้อความwatchก่อนที่จะได้รับการตอบกลับจากวิธีการ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 เสมอ การแจ้งเตือนครั้งต่อๆ ไปสำหรับช่องนี้จะมีหมายเลขข้อความที่มากกว่าครั้งก่อนหน้า แต่หมายเลขข้อความจะไม่เรียงตามลำดับ

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

แชแนลการแจ้งเตือนอาจมีเวลาหมดอายุ โดยมีค่า ที่กำหนดโดยคำขอของคุณหรือขีดจำกัดภายในของ API ของ Google ปฏิทิน หรือค่าเริ่มต้น (จะใช้ค่าที่จำกัดมากกว่า) เวลาหมดอายุของแชแนล (หากมี) จะรวมอยู่ในรูปแบบการประทับเวลา Unix (เป็นมิลลิวินาที) ในข้อมูลที่ส่งคืนโดยเมธอด watch นอกจากนี้ วันที่และเวลาหมดอายุ (ในรูปแบบที่มนุษย์อ่านได้) จะรวมอยู่ในข้อความแจ้งเตือนทุกข้อความที่แอปพลิเคชันของคุณได้รับสำหรับช่องนี้ในX-Goog-Channel-Expirationส่วนหัว HTTP

ปัจจุบันยังไม่มีวิธีต่ออายุช่องทางการแจ้งเตือนโดยอัตโนมัติ เมื่อ ช่องใกล้หมดอายุ คุณต้องแทนที่ด้วยช่องใหม่โดยเรียกใช้ เมธอด watch คุณต้องใช้ค่าที่ไม่ซ้ำกันสำหรับพร็อพเพอร์ตี้ id ของช่องใหม่เสมอ โปรดทราบว่าอาจมีช่วงเวลาที่ "ทับซ้อนกัน" เมื่อช่องทางการแจ้งเตือน 2 ช่องสำหรับทรัพยากรเดียวกันทำงานอยู่

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

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

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

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

ส่วนหัว

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

ทำความเข้าใจเหตุการณ์การแจ้งเตือนของ Google Calendar API

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

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

ปิดการแจ้งเตือน

พร็อพเพอร์ตี้ expiration จะควบคุมเวลาที่การแจ้งเตือนจะหยุดโดยอัตโนมัติ คุณสามารถ เลือกหยุดรับการแจ้งเตือนสำหรับช่องหนึ่งๆ ก่อนที่การแจ้งเตือนนั้นจะหมดอายุได้ โดยการเรียกใช้เมธอด stop ที่ URI ต่อไปนี้

https://www.googleapis.com/calendar/v3/channels/stop

วิธีนี้กำหนดให้คุณต้องระบุพร็อพเพอร์ตี้ id และ resourceId ของช่องเป็นอย่างน้อย ดังที่แสดงในตัวอย่างด้านล่าง โปรดทราบว่าหาก Google Calendar 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"
}