เอกสารนี้จะอธิบายวิธีใช้ข้อความ Push ที่แจ้งแอปพลิเคชันของคุณเมื่อทรัพยากรมีการเปลี่ยนแปลง
ภาพรวม
Google Drive API แสดงข้อความ Push ที่ให้คุณตรวจสอบการเปลี่ยนแปลงในทรัพยากรได้ คุณใช้ฟีเจอร์นี้เพื่อปรับปรุงประสิทธิภาพของแอปพลิเคชันได้ ซึ่งช่วยให้คุณไม่ต้องใช้เครือข่ายเพิ่มเติมและคำนวณค่าใช้จ่ายที่เกี่ยวข้องกับทรัพยากรแบบสำรวจเพื่อพิจารณาว่ามีการเปลี่ยนแปลงหรือไม่ เมื่อใดก็ตามที่ทรัพยากรที่ดูมีการเปลี่ยนแปลง Google Drive API จะแจ้งเตือนแอปพลิเคชันของคุณ
หากต้องการใช้ข้อความ Push คุณต้องดำเนินการ 2 อย่างต่อไปนี้
ตั้งค่า URL รับหรือตัวรับ Callback "เว็บฮุค"
นี่คือเซิร์ฟเวอร์ HTTPS ที่จัดการข้อความแจ้งเตือน API ที่ทริกเกอร์เมื่อทรัพยากรเปลี่ยนแปลง
ตั้งค่า (ช่องทางการแจ้งเตือน) สำหรับปลายทางของทรัพยากรแต่ละรายการที่ต้องการดู
ช่องทางระบุข้อมูลการกำหนดเส้นทางสำหรับข้อความแจ้งเตือน ในการตั้งค่าช่อง คุณต้องระบุ URL ที่เจาะจงที่ต้องการรับการแจ้งเตือน เมื่อใดก็ตามที่ทรัพยากรของช่องมีการเปลี่ยนแปลง Google Drive API จะส่งข้อความแจ้งเตือนเป็นคำขอ
POST
ไปยัง URL นั้น
ปัจจุบัน API ของ Google ไดรฟ์รองรับการแจ้งเตือนการเปลี่ยนแปลงเมธอดของ files
และ changes
สร้างช่องทางการแจ้งเตือน
หากต้องการขอข้อความ Push คุณต้องตั้งค่าช่องทางการแจ้งเตือนสำหรับทรัพยากรแต่ละรายการที่ต้องการตรวจสอบ หลังจากตั้งค่าช่องทางการแจ้งเตือนแล้ว Google Drive 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 อักขระค่ารหัสที่คุณตั้งค่าไว้จะสะท้อนกลับในส่วนหัว HTTP
X-Goog-Channel-Id
ของข้อความแจ้งเตือนทุกข้อความที่คุณได้รับสำหรับแชแนลนี้ -
ตั้งค่าสตริงพร็อพเพอร์ตี้
type
เป็นค่าweb_hook
-
สตริงพร็อพเพอร์ตี้
address
ที่ตั้งค่าเป็น URL ที่ฟังและตอบสนองต่อการแจ้งเตือนสำหรับช่องทางการแจ้งเตือนนี้ นี่คือ URL เรียกกลับของเว็บฮุคและต้องใช้ HTTPSโปรดทราบว่า Google Drive API จะส่งการแจ้งเตือนไปยังที่อยู่ HTTPS นี้ได้ต่อเมื่อมีการติดตั้งใบรับรอง SSL ที่ถูกต้องในเว็บเซิร์ฟเวอร์ของคุณ ใบรับรองที่ไม่ถูกต้อง ได้แก่
- ใบรับรองแบบ Self-signed
- ใบรับรองที่ลงนามโดยแหล่งที่มาที่ไม่น่าเชื่อถือ
- ใบรับรองที่เพิกถอนไปแล้ว
- ใบรับรองที่มีเรื่องไม่ตรงกับชื่อโฮสต์เป้าหมาย
พร็อพเพอร์ตี้ที่ไม่บังคับ
นอกจากนี้ คุณยังระบุข้อมูลในช่องที่ไม่บังคับเหล่านี้ได้ด้วยคำขอ watch
-
พร็อพเพอร์ตี้
token
ที่ระบุค่าสตริงที่กําหนดเองเพื่อใช้เป็นโทเค็นแชแนล คุณใช้โทเค็นช่องทางการแจ้งเตือนเพื่อวัตถุประสงค์ต่างๆ ได้ ตัวอย่างเช่น คุณสามารถใช้โทเค็นเพื่อยืนยันว่าข้อความขาเข้าแต่ละรายการเป็นของช่องทางที่แอปพลิเคชันสร้างไว้ เพื่อให้มั่นใจว่าการแจ้งเตือนไม่ได้ถูกปลอมแปลง หรือเพื่อกำหนดเส้นทางข้อความไปยังปลายทางที่ถูกต้องภายในแอปพลิเคชันของคุณตามวัตถุประสงค์ของช่องทางนี้ ความยาวสูงสุด: 256 อักขระโทเค็นจะรวมอยู่ในส่วนหัว HTTP
X-Goog-Channel-Token
ในทุกข้อความแจ้งเตือนที่แอปพลิเคชันได้รับสำหรับแชแนลนี้หากใช้โทเค็นช่องทางการแจ้งเตือน เราขอแนะนำให้ทำดังนี้
ใช้รูปแบบการเข้ารหัสที่ขยายได้ เช่น พารามิเตอร์การค้นหาของ URL เช่น
forwardTo=hr&createdBy=mobile
อย่าใส่ข้อมูลที่ละเอียดอ่อน เช่น โทเค็น OAuth
-
ตั้งค่าสตริงพร็อพเพอร์ตี้
expiration
เป็นการประทับเวลา Unix (เป็นมิลลิวินาที) ของวันที่และเวลาที่คุณต้องการให้ Google Drive API หยุดส่งข้อความสำหรับช่องทางการแจ้งเตือนนี้หากแชแนลมีเวลาหมดอายุ แชแนลดังกล่าวจะรวมเป็นค่าของส่วนหัว HTTP
X-Goog-Channel-Expiration
(ในรูปแบบที่มนุษย์อ่านได้) ในข้อความแจ้งเตือนทุกรายการที่แอปพลิเคชันได้รับสำหรับแชแนลนี้
ดูรายละเอียดเพิ่มเติมเกี่ยวกับคําขอได้ที่เมธอด 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 Drive API จะส่งข้อความ sync
เพื่อระบุว่าการแจ้งเตือนกำลังเริ่มต้น ค่าส่วนหัว HTTP ของ X-Goog-Resource-State
สำหรับข้อความเหล่านี้คือ 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 Drive API (จะใช้ค่าที่มีการจำกัดมากกว่า) หากมีเวลาหมดอายุของแชแนล เวลาหมดอายุของแชแนลจะรวมอยู่ในการประทับเวลา Unix (เป็นมิลลิวินาที) ในข้อมูลที่แสดงผลโดยเมธอด watch
นอกจากนี้ ระบบยังระบุวันที่และเวลาหมดอายุ (ในรูปแบบที่มนุษย์อ่านได้) ในข้อความแจ้งเตือนทั้งหมดที่แอปพลิเคชันได้รับสำหรับช่องทางนี้ในส่วนหัว HTTP ของ X-Goog-Channel-Expiration
ด้วย
ปัจจุบันยังไม่มีวิธีต่ออายุช่องทางการแจ้งเตือนโดยอัตโนมัติ เมื่อแชแนลใกล้หมดอายุ คุณต้องแทนที่ด้วยแชแนลใหม่โดยเรียกใช้เมธอด watch
คุณต้องใช้ค่าที่ไม่ซ้ำกันสำหรับพร็อพเพอร์ตี้ id
ของแชแนลใหม่เหมือนเช่นเคย โปรดทราบว่าช่วงเวลาที่ช่องทางการแจ้งเตือน 2 ช่องทางสำหรับทรัพยากรเดียวกันทำงานอยู่อาจ "ซ้อนทับกัน"
รับการแจ้งเตือน
เมื่อใดก็ตามที่มีการเปลี่ยนแปลงทรัพยากรที่ดู แอปพลิเคชันจะได้รับข้อความแจ้งเตือนที่อธิบายการเปลี่ยนแปลงดังกล่าว Google Drive API จะส่งข้อความเหล่านี้เป็นคำขอ HTTPS POST
ไปยัง URL ที่คุณระบุเป็นพร็อพเพอร์ตี้ address
สำหรับช่องทางการแจ้งเตือนนี้
ตีความรูปแบบข้อความแจ้งเตือน
ข้อความแจ้งเตือนทั้งหมดจะมีชุดส่วนหัว HTTP ที่มีคำนำหน้า X-Goog-
การแจ้งเตือนบางประเภทอาจรวมเนื้อหาข้อความไว้ด้วย
ส่วนหัว
ข้อความแจ้งเตือนที่โพสต์โดย Google Drive API ไปยัง URL ผู้รับจะมีส่วนหัว HTTP ต่อไปนี้
ส่วนหัว | คำอธิบาย |
---|---|
แสดงเสมอ | |
|
UUID หรือสตริงที่ไม่ซ้ำกันอื่นๆ ที่คุณให้ไว้เพื่อระบุช่องทางการแจ้งเตือนนี้ |
|
จำนวนเต็มที่ระบุข้อความนี้สำหรับช่องทางการแจ้งเตือนนี้ ค่าจะเป็น 1 เสมอสำหรับ sync ข้อความ จำนวนข้อความที่เพิ่มขึ้นสำหรับแต่ละข้อความที่ตามมาบนช่องทาง แต่จะไม่มีจำนวนเพิ่มขึ้นตามลำดับ |
|
ค่าทึบที่ระบุทรัพยากรที่ดู รหัสนี้จะคงที่ใน 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 อีกครั้งโดยมี Exponential Backoff
รหัสสถานะการคืนสินค้าอื่นๆ ทั้งหมดจะถือว่าเป็นข้อความล้มเหลว
ทำความเข้าใจเหตุการณ์การแจ้งเตือน 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 Drive 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" }