เอกสารนี้จะอธิบายวิธีใช้ข้อความ Push ที่จะให้ข้อมูล เมื่อมีการเปลี่ยนแปลงทรัพยากร
ภาพรวม
Google Drive API จะแสดงข้อความ Push ที่ให้คุณตรวจสอบ ความเปลี่ยนแปลงในทรัพยากร คุณสามารถใช้ฟีเจอร์นี้เพื่อปรับปรุงประสิทธิภาพของ แอปพลิเคชันของคุณ ช่วยให้คุณกำจัดเครือข่ายและการประมวลผลเพิ่มเติม ค่าใช้จ่ายที่เกี่ยวข้องกับทรัพยากรที่ใช้ในการสำรวจเพื่อพิจารณาว่ามีการเปลี่ยนแปลงหรือไม่ เมื่อใดก็ตามที่ทรัพยากรที่ดูมีการเปลี่ยนแปลง Google ไดรฟ์ API จะแจ้ง แอปพลิเคชัน
หากต้องการใช้ข้อความ Push คุณต้องดำเนินการ 2 อย่างต่อไปนี้
ตั้งค่า URL การรับหรือ "เว็บฮุค" Callback Receiver
ช่วงเวลานี้ เป็นเซิร์ฟเวอร์ HTTPS ที่จัดการข้อความแจ้งเตือน API ที่ ทริกเกอร์เมื่อทรัพยากรเปลี่ยนแปลง
ตั้งค่า (ช่องทางการแจ้งเตือน) สำหรับปลายทางของทรัพยากรแต่ละรายการที่ต้องการ ดู
ช่องทางระบุข้อมูลการกำหนดเส้นทางสำหรับการแจ้งเตือน ข้อความ ในการตั้งค่าช่อง คุณต้องระบุ URL ที่เจาะจงซึ่ง ที่ต้องการรับการแจ้งเตือน เมื่อใดก็ตามที่ทรัพยากรของช่องมีการเปลี่ยนแปลง Google Drive API จะส่งข้อความแจ้งเตือนเป็น
POST
ไปยัง URL นั้น
ขณะนี้ Google Drive API รองรับการแจ้งเตือนเมื่อมีการเปลี่ยนแปลงกับ
เมธอด files
และ changes
สร้างช่องทางการแจ้งเตือน
หากต้องการขอข้อความ Push คุณต้องตั้งค่าช่องทางการแจ้งเตือน สำหรับทรัพยากรแต่ละรายการที่ต้องการตรวจสอบ หลังจากตั้งค่าช่องทางการแจ้งเตือนแล้ว API ของ Google ไดรฟ์จะแจ้งให้แอปพลิเคชันทราบเมื่อทรัพยากรที่มีการรับชม การเปลี่ยนแปลง
สร้างคำขอดูนาฬิกา
ทรัพยากร 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
ข้อความที่ซิงค์จะมี X-Goog-Message-Number
HTTP เสมอ
ค่าส่วนหัว 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
ที่ใช้เวลาเพียง 2 นาที
|
|
ตัวระบุเฉพาะเวอร์ชัน API สำหรับทรัพยากรที่ดู |
บางครั้งอาจมี | |
|
รายละเอียดเพิ่มเติมเกี่ยวกับการเปลี่ยนแปลง
ค่าที่เป็นไปได้มีดังนี้
content ,
parents ,
children หรือ
permissions
ที่ใช้เวลาเพียง 2 นาที
ไม่ได้ให้มาพร้อมกับ 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
เมธอด มีได้เพียง 1 วิธีเท่านั้น
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" }