ข้อความ Push

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

ภาพรวม

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

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

  • ตั้งค่า URL ฝั่งที่รับหรือตัวรับการเรียกกลับ "เว็บฮุค"

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

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

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

ปัจจุบัน Directory API รองรับการแจ้งเตือนการเปลี่ยนแปลงในทรัพยากร Users

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

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

ส่งคำขอรับนาฬิกา

ทรัพยากร Directory API ที่รับชมได้แต่ละรายการจะมีวิธีการ watch ที่เชื่อมโยงกันในรูปแบบ URI ต่อไปนี้

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

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

ช่องทางการแจ้งเตือนแต่ละช่องทางจะเชื่อมโยงทั้งกับผู้ใช้รายหนึ่งๆ และ ทรัพยากรที่เฉพาะเจาะจง (หรือชุดของทรัพยากร) คำขอwatch จะไม่สำเร็จ เว้นแต่ผู้ใช้ปัจจุบัน หรือบัญชีบริการ เป็นเจ้าของหรือมีสิทธิ์เข้าถึงแหล่งข้อมูลนี้

ตัวอย่าง

คำขอนาฬิกาทั้งหมดสำหรับทรัพยากร User สำหรับโดเมนเดียวจะมีแบบฟอร์มทั่วไปดังนี้

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
Authorization: Bearer auth_token_for_current_user
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 channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

ใช้พารามิเตอร์ domain และ event เพื่อระบุโดเมนและประเภทเหตุการณ์ที่คุณต้องการรับการแจ้งเตือน

คำขอดูทั้งหมดสำหรับทรัพยากรผู้ใช้ของลูกค้ามีรูปแบบทั่วไปดังนี้

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
Authorization: Bearer auth_token_for_current_user
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 channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

ใช้พารามิเตอร์ customer และ event เพื่อระบุรหัสที่ไม่ซ้ำกันของบัญชี Google ของลูกค้าและประเภทเหตุการณ์ที่คุณต้องการรับการแจ้งเตือน

ค่าที่เป็นไปได้สำหรับ event มีดังนี้

  • add: เหตุการณ์ที่ผู้ใช้สร้างขึ้น
  • delete: ผู้ใช้ลบกิจกรรม
  • makeAdmin: กิจกรรมการเปลี่ยนแปลงสถานะผู้ดูแลระบบที่เป็นผู้ใช้
  • undelete: ผู้ใช้ยกเลิกการนำออกกิจกรรม
  • update: เหตุการณ์ที่อัปเดตผู้ใช้

หมายเหตุ: ตัวอย่างต่อไปนี้ไม่มีเนื้อหาคําขอเพื่อความชัดเจน

เฝ้าดูเหตุการณ์ที่ผู้ใช้สร้างขึ้นสำหรับโดเมน mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

คอยดูเหตุการณ์ที่ผู้ใช้สร้างขึ้นสำหรับลูกค้า my_customer

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

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

ในคำขอ watch แต่ละรายการ คุณจะต้องกรอกข้อมูลในช่องต่อไปนี้

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

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

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

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

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

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

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

นอกจากนี้ คุณยังระบุช่องที่ไม่บังคับเหล่านี้ได้โดยใช้ คำขอwatch:

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

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

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

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

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

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

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

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

ดูการตอบกลับ

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

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

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

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

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

คุณไม่จำเป็นต้องสนใจการแจ้งเตือน sync แต่จะใช้ก็ได้ เช่น หากคุณตัดสินใจว่าไม่ต้องการเก็บ ช่องนั้น คุณจะสามารถใช้ X-Goog-Channel-ID และ X-Goog-Resource-ID ค่าในการเรียกไปยัง หยุดรับการแจ้งเตือน นอกจากนี้ คุณยังใช้การแจ้งเตือน sync เพื่อทำการเริ่มต้นใช้งานบางอย่างเพื่อเตรียมพร้อมสําหรับเหตุการณ์ในภายหลังได้ด้วย

รูปแบบของข้อความ sync ที่ Directory 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 เสมอ การแจ้งเตือนที่ตามมาแต่ละรายการสำหรับช่องนี้ หมายเลขข้อความที่มากกว่าหมายเลขก่อนหน้านี้ แม้ว่าข้อความ จะไม่เรียงตามลำดับ

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

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

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

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

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

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

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

ส่วนหัว

ข้อความการแจ้งเตือนที่ Directory API โพสต์ไปยัง URL ที่คุณรับจะมีส่วนหัว HTTP ต่อไปนี้

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

ข้อความแจ้งเตือนสําหรับผู้ใช้จะมีข้อมูลต่อไปนี้ในส่วนเนื้อหาของคําขอ

พร็อพเพอร์ตี้ คำอธิบาย
kind ระบุว่าเป็นทรัพยากรของผู้ใช้ ค่า: สตริงคงที่ "admin#directory#user"
id ตัวระบุที่ไม่ซ้ำกันของทรัพยากรผู้ใช้
etag ETag ของข้อความแจ้งเตือน แตกต่างจาก ETag ของทรัพยากรผู้ใช้
primaryEmail อีเมลหลักของผู้ใช้

ตัวอย่าง

ข้อความแจ้งเตือนสำหรับเหตุการณ์ทรัพยากร User จะมีรูปแบบทั่วไปดังนี้

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: 'https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

ตัวอย่างเหตุการณ์ที่ผู้ใช้ลบ

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

ตอบสนองต่อการแจ้งเตือนต่างๆ

เพื่อแสดงถึงความสำเร็จ คุณสามารถส่งรหัสสถานะต่อไปนี้ 200, 201, 202, 204 หรือ 102

หากบริการของคุณใช้ไลบรารีไคลเอ็นต์ API ของ Google และแสดงผลเป็น 500,502, 503 หรือ 504 ทาง Directory API จะลองอีกครั้งโดยใช้การถดถอยแบบเลขชี้กำลัง รหัสสถานะการคืนสินค้าอื่นๆ ทั้งหมดจะถือว่าเป็นข้อความล้มเหลว

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

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

https://www.googleapis.com/admin/directory_v1/channels/stop

วิธีนี้กำหนดให้คุณระบุพร็อพเพอร์ตี้ id และ resourceId ของช่องเป็นอย่างน้อย ดังที่แสดงในตัวอย่างด้านล่าง โปรดทราบว่าหาก Directory API มีประเภท ทรัพยากรที่มี watch เมธอด มีได้เพียง 1 วิธีเท่านั้น stop วิธี

เฉพาะผู้ใช้ที่มีสิทธิ์ที่ถูกต้องเท่านั้นที่จะหยุดช่องได้ โดยเฉพาะอย่างยิ่งฟีเจอร์ต่อไปนี้

  • หากบัญชีผู้ใช้ทั่วไปสร้างช่อง เฉพาะผู้ใช้รายเดียวกันจากไคลเอ็นต์เดียวกัน (ตามที่ระบุโดยรหัสไคลเอ็นต์ OAuth 2.0 จากโทเค็นการตรวจสอบสิทธิ์) ซึ่งสร้างช่องเท่านั้นที่จะหยุดช่องได้
  • หากช่องสร้างขึ้นโดยบัญชีบริการ ผู้ใช้จาก สามารถหยุดช่องได้

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีหยุดรับการแจ้งเตือน

POST https://www.googleapis.com/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}