เอกสารนี้อธิบายวิธีใช้ Push Notification ที่แจ้งให้แอปพลิเคชันทราบเมื่อมีการเปลี่ยนแปลงทรัพยากร
ภาพรวม
Google ไดรฟ์ API มีข้อความ Push ที่ช่วยให้คุณตรวจสอบการเปลี่ยนแปลงในทรัพยากรได้ คุณสามารถใช้ฟีเจอร์นี้เพื่อปรับปรุงประสิทธิภาพของแอปพลิเคชันได้ ซึ่งช่วยให้คุณประหยัดค่าใช้จ่ายเครือข่ายและค่าประมวลผลเพิ่มเติมที่เกี่ยวข้องกับการสำรวจทรัพยากรเพื่อดูว่ามีการเปลี่ยนแปลงหรือไม่ เมื่อใดก็ตามที่ทรัพยากรที่ดูมีการเปลี่ยนแปลง Google Drive API จะแจ้งเตือนแอปพลิเคชันของคุณ
หากต้องการใช้ข้อความ Push คุณต้องดำเนินการ 2 อย่างต่อไปนี้
ตั้งค่า URL ฝั่งที่รับหรือตัวรับการเรียกกลับ "เว็บฮุค"
นี่คือเซิร์ฟเวอร์ HTTPS ที่จัดการข้อความการแจ้งเตือน API ที่ทริกเกอร์เมื่อทรัพยากรมีการเปลี่ยนแปลง
ตั้งค่า (ช่องทางการแจ้งเตือน) สําหรับปลายทางทรัพยากรแต่ละรายการที่ต้องการติดตาม
ช่องทางระบุข้อมูลการกำหนดเส้นทางสำหรับข้อความแจ้งเตือน ในการตั้งค่าช่อง คุณต้องระบุ URL ที่เจาะจงที่ต้องการรับการแจ้งเตือน เมื่อใดก็ตามที่มีการเปลี่ยนแปลงทรัพยากรของช่อง Google ไดรฟ์ API จะส่งข้อความแจ้งเป็น
POST
คำขอไปยัง URL นั้น
ปัจจุบัน Google ไดรฟ์ API รองรับการแจ้งเตือนการเปลี่ยนแปลงในวิธีการ files
และ changes
สร้างช่องทางการแจ้งเตือน
หากต้องการขอรับข้อความ Push คุณต้องตั้งค่าช่องทางการแจ้งเตือนสำหรับแต่ละทรัพยากรที่ต้องการตรวจสอบ หลังจากตั้งค่าช่องทางการแจ้งเตือนแล้ว Google ไดรฟ์ API จะแจ้งให้แอปพลิเคชันทราบเมื่อทรัพยากรที่ตรวจสอบมีการเปลี่ยนแปลง
ส่งคำขอรับนาฬิกา
ทรัพยากร API ของ Google ไดรฟ์ที่ดูได้แต่ละรายการมีเมธอด watch
ที่เชื่อมโยงที่ URI ของแบบฟอร์มต่อไปนี้
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
หากต้องการตั้งค่าช่องทางการแจ้งเตือนสำหรับข้อความเกี่ยวกับการเปลี่ยนแปลงไปยังทรัพยากรใดทรัพยากรหนึ่ง ให้ส่งคำขอ POST
ไปยังเมธอด watch
สำหรับทรัพยากรดังกล่าว
ช่องทางการแจ้งเตือนแต่ละช่องทางจะเชื่อมโยงกับผู้ใช้และทรัพยากร (หรือชุดทรัพยากร) ที่เฉพาะเจาะจง คำขอ watch
จะไม่สำเร็จ เว้นแต่ผู้ใช้
หรือบัญชีบริการ
ปัจจุบันเป็นเจ้าของหรือมีสิทธิ์เข้าถึงทรัพยากรนี้
ตัวอย่าง
ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้ทรัพยากร channels
เพื่อเริ่มเฝ้าติดตามการเปลี่ยนแปลงทรัพยากร files
รายการเดียวโดยใช้เมธอด files.watch
POST https://www.googleapis.com/drive/v3/files/fileId/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN 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-myFilesChannelDest", // (Optional) Your files channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้ทรัพยากร channels
เพื่อเริ่มรับชม changes
ทั้งหมดโดยใช้เมธอด changes.watch
POST https://www.googleapis.com/drive/v3/changes/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
พร็อพเพอร์ตี้ที่จำเป็น
คุณต้องกรอกข้อมูลในช่องต่อไปนี้สำหรับคำขอ watch
แต่ละรายการ
-
สตริงพร็อพเพอร์ตี้
id
ที่ระบุช่องทางการแจ้งเตือนใหม่นี้ภายในโปรเจ็กต์ของคุณโดยไม่ซ้ำกัน เราขอแนะนำให้ใช้ตัวระบุที่ไม่ซ้ำกับผู้อื่น (UUID) หรือสตริงที่ไม่ซ้ำกันแบบอื่นๆ ที่คล้ายกัน จำกัดความยาวสูงสุด 64 อักขระระบบจะแสดงค่ารหัสที่คุณตั้งไว้ใน
X-Goog-Channel-Id
ส่วนหัว HTTP ของข้อความการแจ้งเตือนทุกข้อความที่คุณได้รับสำหรับช่องนี้ -
ตั้งค่าสตริงพร็อพเพอร์ตี้
type
เป็นค่าweb_hook
-
สตริงพร็อพเพอร์ตี้
address
ที่ตั้งค่าเป็น URL ที่คอยฟังและตอบสนองต่อการแจ้งเตือนสําหรับช่องทางการแจ้งเตือนนี้ นี่คือ URL การเรียกกลับของ Webhook ของคุณ และต้องใช้ 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 หยุดส่งข้อความสำหรับช่องทางการแจ้งเตือนนี้หากช่องมีเวลาหมดอายุ ระบบจะรวมเวลาดังกล่าวเป็นค่าของ
X-Goog-Channel-Expiration
ส่วนหัว HTTP (ในรูปแบบที่มนุษย์อ่านได้) ในข้อความแจ้งเตือนทุกข้อความที่แอปพลิเคชันของคุณได้รับสำหรับช่องนี้
ดูรายละเอียดเพิ่มเติมเกี่ยวกับคำขอได้ที่เมธอด watch
สำหรับเมธอด files
และ changes
ในข้อมูลอ้างอิง 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/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable. }
นอกเหนือจากพร็อพเพอร์ตี้ที่คุณส่งมาเป็นส่วนหนึ่งของคำขอแล้ว ข้อมูลที่แสดงผลจะมี resourceId
และ resourceUri
เพื่อระบุแหล่งข้อมูลที่รับชมในแชแนลการแจ้งเตือนนี้ด้วย
คุณสามารถส่งข้อมูลที่แสดงผลไปยังการดำเนินการอื่นๆ ของช่องทางการแจ้งเตือนได้ เช่น เมื่อต้องการหยุดรับการแจ้งเตือน
ดูรายละเอียดเพิ่มเติมเกี่ยวกับการตอบกลับได้ที่เมธอด watch
สำหรับเมธอด files
และ changes
ในข้อมูลอ้างอิง API
ซิงค์ข้อความ
หลังจากสร้างช่องทางการแจ้งเตือนเพื่อเฝ้าดูทรัพยากรแล้ว Google ไดรฟ์ API จะส่งข้อความ sync
เพื่อระบุว่าการแจ้งเตือนกำลังจะเริ่มขึ้น ค่าส่วนหัว X-Goog-Resource-State
HTTP สำหรับข้อความเหล่านี้คือ sync
เนื่องจากปัญหาด้านเวลาของเครือข่าย คุณจึงอาจได้รับข้อความ sync
ก่อนที่จะได้รับการตอบกลับของเมธอด watch
คุณไม่จำเป็นต้องสนใจการแจ้งเตือน sync
แต่จะใช้ก็ได้ ตัวอย่างเช่น หากตัดสินใจว่าไม่ต้องการเก็บแชแนลไว้ คุณสามารถใช้ค่า X-Goog-Channel-ID
และ X-Goog-Resource-ID
ในการเรียกใช้เพื่อหยุดรับการแจ้งเตือน คุณยังใช้การแจ้งเตือน sync
เพื่อการเริ่มต้นบางส่วนเพื่อเตรียมพร้อมสำหรับกิจกรรมในภายหลังได้ด้วย
รูปแบบของข้อความ sync
ที่ Google Drive 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
นอกจากนี้ ระบบจะระบุวันที่และเวลาหมดอายุ (ในรูปแบบที่มนุษย์อ่านได้) ไว้ในข้อความแจ้งเตือนทุกข้อความที่แอปพลิเคชันของคุณได้รับสำหรับแชแนลนี้ในส่วนX-Goog-Channel-Expiration
ส่วนหัว HTTP
ปัจจุบันยังไม่มีวิธีต่ออายุช่องทางการแจ้งเตือนอัตโนมัติ เมื่อช่องใกล้จะหมดอายุ คุณต้องแทนที่ด้วยช่องใหม่โดยเรียกใช้เมธอด watch
คุณต้องระบุค่าที่ไม่ซ้ำกันสำหรับพร็อพเพอร์ตี้ id
ของแชแนลใหม่ ดังเช่นเคย โปรดทราบว่าอาจมีระยะเวลาที่ "ทับซ้อนกัน" เมื่อช่องทางการแจ้งเตือน 2 ช่องทางสำหรับทรัพยากรเดียวกันทำงานอยู่
รับการแจ้งเตือน
เมื่อใดก็ตามที่มีการเปลี่ยนแปลงทรัพยากรที่ดู แอปพลิเคชันจะได้รับข้อความแจ้งเตือนที่อธิบายการเปลี่ยนแปลงดังกล่าว Google ไดรฟ์ API จะส่งข้อความเหล่านี้เป็นคำขอ POST
ผ่าน HTTPS ไปยัง URL ที่คุณระบุเป็นพร็อพเพอร์ตี้ address
สำหรับช่องทางการแจ้งเตือนนี้
ตีความรูปแบบข้อความแจ้งเตือน
ข้อความแจ้งเตือนทั้งหมดจะมีชุดส่วนหัว HTTP ที่มีคำนำหน้า X-Goog-
การแจ้งเตือนบางประเภทอาจมีเนื้อหาข้อความด้วย
ส่วนหัว
ข้อความการแจ้งเตือนที่ Google Drive API โพสต์ไปยัง URL ที่คุณรับจะมีส่วนหัว HTTP ต่อไปนี้
ส่วนหัว | คำอธิบาย |
---|---|
แสดงอยู่เสมอ | |
|
UUID หรือสตริงที่ไม่ซ้ำกันอื่นๆ ที่คุณให้ไว้เพื่อระบุช่องทางการแจ้งเตือนนี้ |
|
จำนวนเต็มที่ระบุข้อความนี้สำหรับช่องทางการแจ้งเตือนนี้ ค่าสำหรับข้อความ sync คือ 1 เสมอ หมายเลขข้อความจะเพิ่มขึ้นสำหรับข้อความแต่ละรายการในช่อง แต่จะไม่เรียงตามลำดับ |
|
ค่าทึบที่ระบุทรัพยากรที่ดู รหัสนี้มีความเสถียรในทุกเวอร์ชันของ API |
|
สถานะทรัพยากรใหม่ซึ่งทริกเกอร์การแจ้งเตือน
ค่าที่เป็นไปได้มีดังนี้
sync , add , remove , update ,
trash , untrash หรือ change
|
|
ตัวระบุเฉพาะเวอร์ชัน API สําหรับทรัพยากรที่ดูอยู่ |
บางครั้งมี | |
|
รายละเอียดเพิ่มเติมเกี่ยวกับการเปลี่ยนแปลง
ค่าที่เป็นไปได้มีดังนี้
content ,
parents ,
children หรือ
permissions
ไม่มีข้อความ sync |
|
วันที่และเวลาหมดอายุของช่องทางการแจ้งเตือน ซึ่งแสดงในรูปแบบที่มนุษย์อ่านได้ แสดงเฉพาะในกรณีที่มีการกําหนด |
|
โทเค็นช่องทางการแจ้งเตือนที่แอปพลิเคชันของคุณตั้งค่าไว้และคุณใช้เพื่อยืนยันแหล่งที่มาของการแจ้งเตือนได้ แสดงเฉพาะในกรณีที่มีการกําหนด |
ข้อความแจ้งเตือนสำหรับ files
และ changes
ว่างเปล่า
ตัวอย่าง
เปลี่ยนข้อความแจ้งเตือนสำหรับทรัพยากร files
ซึ่งไม่มีส่วนเนื้อหาของคำขอ:
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/drive/v3/files/ret08u3rv24htgh289g X-Goog-Resource-State: update X-Goog-Changed: content,properties X-Goog-Message-Number: 10
เปลี่ยนข้อความแจ้งเตือนสำหรับทรัพยากร changes
ซึ่งรวมถึงเนื้อหาของคำขอ:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 118 X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43 X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes X-Goog-Resource-State: changed X-Goog-Message-Number: 23 { "kind": "drive#changes" }
ตอบสนองต่อการแจ้งเตือนต่างๆ
เพื่อแสดงถึงความสำเร็จ คุณสามารถส่งรหัสสถานะต่อไปนี้ 200
, 201
, 202
, 204
หรือ 102
หากบริการของคุณใช้ไลบรารีไคลเอ็นต์ API ของ Google และแสดงผลเป็น 500
,502
, 503
หรือ 504
ทาง Google Drive API จะลองอีกครั้งโดยใช้การถดถอยแบบเลขชี้กำลัง
รหัสสถานะการคืนสินค้าอื่นๆ ทั้งหมดจะถือว่าเป็นข้อความล้มเหลว
ทำความเข้าใจเหตุการณ์การแจ้งเตือน Google Drive API
ส่วนนี้แสดงรายละเอียดเกี่ยวกับข้อความแจ้งเตือนที่คุณจะได้รับเมื่อใช้ข้อความ Push กับ Google Drive API
นำส่งเมื่อ | ||
---|---|---|
sync |
files changes |
สร้างแชแนลเรียบร้อยแล้ว คุณจะได้รับแจ้งเกี่ยวกับเรื่องนี้ |
add |
files |
มีการสร้างหรือแชร์ทรัพยากร |
|
files |
ทรัพยากรที่มีอยู่ถูกลบหรือยกเลิกการแชร์แล้ว |
|
files |
มีการอัปเดตพร็อพเพอร์ตี้ (ข้อมูลเมตา) ของทรัพยากรอย่างน้อย 1 รายการ |
|
files |
ย้ายแหล่งข้อมูลไปที่ถังขยะแล้ว |
|
files |
นําทรัพยากรออกจากถังขยะแล้ว |
|
changes |
เพิ่มรายการบันทึกการเปลี่ยนแปลงแล้วอย่างน้อย 1 รายการ |
อาจมีการระบุส่วนหัว HTTP X-Goog-Changed
สำหรับเหตุการณ์ update
ส่วนหัวดังกล่าวมีรายการที่คั่นด้วยคอมมาซึ่งอธิบายประเภทการเปลี่ยนแปลงที่เกิดขึ้น
ประเภทการเปลี่ยนแปลง | บ่งชี้ |
---|---|
content |
อัปเดตเนื้อหาทรัพยากรแล้ว |
properties |
อัปเดตพร็อพเพอร์ตี้ทรัพยากรอย่างน้อย 1 รายการแล้ว |
parents |
มีการเพิ่มหรือนำทรัพยากรหลักอย่างน้อย 1 รายการออกแล้ว |
children |
มีการเพิ่มหรือนำทรัพยากรย่อยอย่างน้อย 1 รายการออกแล้ว |
permissions |
อัปเดตสิทธิ์สำหรับทรัพยากรแล้ว |
ตัวอย่างที่มีส่วนหัว X-Goog-Changed
X-Goog-Resource-State: update X-Goog-Changed: content, permissions
ปิดการแจ้งเตือน
พร็อพเพอร์ตี้ expiration
จะควบคุมเมื่อการแจ้งเตือนหยุดโดยอัตโนมัติ คุณสามารถเลือกหยุดรับการแจ้งเตือนสำหรับบางช่องก่อนที่ช่องจะหมดอายุได้โดยเรียกใช้เมธอด stop
ที่ URI ต่อไปนี้
https://www.googleapis.com/drive/v3/channels/stop
คุณต้องระบุ id
ของช่องและพร็อพเพอร์ตี้ resourceId
เป็นอย่างน้อยดังที่แสดงในตัวอย่างด้านล่าง โปรดทราบว่าหาก Google ไดรฟ์ API มีทรัพยากรหลายประเภทที่มีเมธอด watch
จะมีเมธอด stop
เพียงเมธอดเดียว
เฉพาะผู้ใช้ที่มีสิทธิ์เท่านั้นที่จะหยุดช่องได้ โดยเฉพาะอย่างยิ่งฟีเจอร์ต่อไปนี้
- หากบัญชีผู้ใช้ทั่วไปสร้างช่อง เฉพาะผู้ใช้รายเดียวกันจากไคลเอ็นต์เดียวกัน (ตามที่ระบุโดยรหัสไคลเอ็นต์ OAuth 2.0 จากโทเค็นการตรวจสอบสิทธิ์) ที่สร้างช่องเท่านั้นที่จะหยุดช่องได้
- หากช่องสร้างขึ้นโดยบัญชีบริการ ผู้ใช้ทุกคนจากไคลเอ็นต์เดียวกันจะหยุดช่องได้
ตัวอย่างโค้ดต่อไปนี้แสดงวิธีหยุดรับการแจ้งเตือน
POST https://www.googleapis.com/drive/v3/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }