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

เอกสารนี้จะอธิบายวิธีใช้ข้อความ 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 ต่อไปนี้

ส่วนหัว คำอธิบาย
แสดงเสมอ
X-Goog-Channel-ID UUID หรือสตริงที่ไม่ซ้ำกันอื่นๆ ที่คุณให้ไว้เพื่อระบุช่องทางการแจ้งเตือนนี้
X-Goog-Message-Number จำนวนเต็มที่ระบุข้อความนี้สำหรับช่องทางการแจ้งเตือนนี้ ค่าจะเป็น 1 เสมอสำหรับ sync ข้อความ จำนวนข้อความที่เพิ่มขึ้นสำหรับแต่ละข้อความที่ตามมาบนช่องทาง แต่จะไม่มีจำนวนเพิ่มขึ้นตามลำดับ
X-Goog-Resource-ID ค่าทึบที่ระบุทรัพยากรที่ดู รหัสนี้จะคงที่ใน API เวอร์ชันต่างๆ
X-Goog-Resource-State สถานะทรัพยากรใหม่ที่เรียกใช้การแจ้งเตือน ค่าที่เป็นไปได้ ได้แก่ sync, add, remove, update, trash, untrash หรือ change
X-Goog-Resource-URI ตัวระบุเฉพาะเวอร์ชัน API สำหรับทรัพยากรที่ดู
บางครั้งอาจมี
X-Goog-Changed รายละเอียดเพิ่มเติมเกี่ยวกับการเปลี่ยนแปลง ค่าที่เป็นไปได้ ได้แก่ content, parents, children หรือ permissions ไม่ได้ให้มาพร้อมกับ sync ข้อความ
X-Goog-Channel-Expiration วันที่และเวลาของช่องทางการแจ้งเตือนหมดอายุ ซึ่งแสดงในรูปแบบที่มนุษย์อ่านได้ แสดงเมื่อกำหนดไว้เท่านั้น
X-Goog-Channel-Token โทเค็นช่องทางการแจ้งเตือนที่แอปพลิเคชันตั้งค่า และคุณจะใช้เพื่อยืนยันแหล่งที่มาของการแจ้งเตือนได้ แสดงเมื่อกำหนดไว้เท่านั้น

ข้อความแจ้งเตือนสำหรับ 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

X-Goog-Resource-State ใช้กับ นำส่งเมื่อ
sync files changes สร้างแชแนลสำเร็จแล้ว คุณจะเริ่มได้รับการแจ้งเตือนเกี่ยวกับการโทร
add files มีการสร้างหรือแชร์ทรัพยากร
remove files ทรัพยากรที่มีอยู่ถูกลบหรือยกเลิกการแชร์แล้ว
update files มีการอัปเดตพร็อพเพอร์ตี้ (ข้อมูลเมตา) ของทรัพยากรอย่างน้อย 1 รายการ
trash files ย้ายแหล่งข้อมูลไปที่ถังขยะแล้ว
untrash files นำแหล่งข้อมูลออกจากถังขยะแล้ว
change 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"
}