REST Resource: subscriptions

แหล่งข้อมูล: การสมัครใช้บริการ

การสมัครใช้บริการเพื่อรับเหตุการณ์เกี่ยวกับทรัพยากร Google Workspace ดูข้อมูลเพิ่มเติมเกี่ยวกับการสมัครใช้บริการได้ที่ภาพรวมของ Google Workspace Events API

การแสดง JSON 
{
  "name": string,
  "uid": string,
  "targetResource": string,
  "eventTypes": [
    string
  ],
  "payloadOptions": {
    object (PayloadOptions)
  },
  "notificationEndpoint": {
    object (NotificationEndpoint)
  },
  "state": enum (State),
  "suspensionReason": enum (ErrorType),
  "authority": string,
  "createTime": string,
  "updateTime": string,
  "reconciling": boolean,
  "etag": string,

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
ช่อง
name

string

ตัวระบุ ชื่อทรัพยากรของการสมัครใช้บริการ

รูปแบบ: subscriptions/{subscription}
uid

string

เอาต์พุตเท่านั้น ตัวระบุที่ไม่ซ้ำกันที่ระบบกำหนดให้สำหรับการสมัครใช้บริการ
targetResource

string

ต้องระบุ เปลี่ยนแปลงไม่ได้ ทรัพยากร Google Workspace ที่ตรวจสอบหาเหตุการณ์ ซึ่งจัดรูปแบบเป็นชื่อทรัพยากรแบบเต็ม ดูข้อมูลเกี่ยวกับทรัพยากรเป้าหมายและกิจกรรมที่รองรับได้ที่กิจกรรม Google Workspace ที่รองรับ

ผู้ใช้จะให้สิทธิ์แอปของคุณสร้างการสมัครใช้บริการสำหรับทรัพยากรเป้าหมายที่กำหนดได้เพียงรายการเดียวเท่านั้น หากแอปพยายามสร้างการสมัครใช้บริการอีกรายการด้วยข้อมูลเข้าสู่ระบบของผู้ใช้เดียวกัน คำขอจะแสดงALREADY_EXISTSข้อผิดพลาด
eventTypes[]

string

ต้องระบุ รายการที่ไม่เรียงลำดับ ข้อมูลสำหรับการสร้างการสมัครใช้บริการ หรือหากมีการตั้งค่า ระบบจะแสดงผลเท่านั้น ประเภทเหตุการณ์อย่างน้อย 1 ประเภทที่จะรับเกี่ยวกับทรัพยากรเป้าหมาย จัดรูปแบบตามข้อกำหนดของ CloudEvents

ประเภทกิจกรรมที่รองรับจะขึ้นอยู่กับทรัพยากรเป้าหมายของการสมัครใช้บริการ โปรดดูรายละเอียดที่หัวข้อกิจกรรม Google Workspace ที่รองรับ

โดยค่าเริ่มต้น คุณจะได้รับเหตุการณ์เกี่ยวกับวงจรการสมัครใช้บริการด้วย คุณไม่จำเป็นต้องระบุเหตุการณ์วงจรลูกค้าสำหรับฟิลด์นี้

หากคุณระบุประเภทเหตุการณ์ที่ไม่มีสำหรับทรัพยากรเป้าหมาย คำขอจะแสดงรหัสสถานะ HTTP 400 Bad Request
payloadOptions

object (PayloadOptions)

ไม่บังคับ ตัวเลือกเกี่ยวกับข้อมูลที่จะรวมไว้ในเพย์โหลดของเหตุการณ์ รองรับเฉพาะกิจกรรมใน Google Chat
notificationEndpoint

object (NotificationEndpoint)

ต้องระบุ เปลี่ยนแปลงไม่ได้ ปลายทางที่การสมัครใช้บริการส่งเหตุการณ์ เช่น หัวข้อ Pub/Sub
state

enum (State)

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

enum (ErrorType)

เอาต์พุตเท่านั้น ข้อผิดพลาดที่ระงับการสมัครใช้บริการ

หากต้องการเปิดใช้งานการสมัครใช้บริการอีกครั้ง ให้แก้ไขข้อผิดพลาดและเรียกใช้เมธอด subscriptions.reactivate
authority

string

เอาต์พุตเท่านั้น ผู้ใช้ที่ให้สิทธิ์ในการสร้างการสมัครใช้บริการ

รูปแบบ: users/{user}

สำหรับผู้ใช้ Google Workspace ค่า {user} คือฟิลด์ user.id จาก Directory API
createTime

string (Timestamp format)

เอาต์พุตเท่านั้น เวลาที่สร้างการสมัครใช้บริการ
updateTime

string (Timestamp format)

เอาต์พุตเท่านั้น เวลาล่าสุดที่มีการอัปเดตการสมัครใช้บริการ
reconciling

boolean

เอาต์พุตเท่านั้น หาก true แสดงว่าระบบกำลังอัปเดตการสมัครใช้บริการ
etag

string

ไม่บังคับ เซิร์ฟเวอร์จะคำนวณผลรวมตรวจสอบนี้ตามค่าของช่องอื่นๆ และอาจส่งในคำขออัปเดตเพื่อให้แน่ใจว่าไคลเอ็นต์มีค่าล่าสุดก่อนดำเนินการต่อ

ฟิลด์ Union expiration เวลาที่การสมัครใช้บริการหมดอายุ

เวลาหมดอายุสูงสุดจะขึ้นอยู่กับว่าการสมัครใช้บริการของคุณมีข้อมูลทรัพยากรในเพย์โหลดของเหตุการณ์หรือไม่ (ระบุในฟิลด์ PayloadOptions)

  • หากเพย์โหลดไม่มีข้อมูลทรัพยากร จะใช้เวลาสูงสุด 7 วัน
  • หากเพย์โหลดมีข้อมูลทรัพยากร จะใช้เวลาสูงสุด 4 ชั่วโมง หากองค์กร Google Workspace ให้สิทธิ์เข้าถึงทรัพยากรผ่านการมอบสิทธิ์ระดับโดเมน คุณจะขยายเวลาหมดอายุของการสมัครใช้บริการได้สูงสุด 24 ชั่วโมง

หลังจากที่การสมัครใช้บริการหมดอายุ ระบบจะลบการสมัครใช้บริการโดยอัตโนมัติ คุณจะได้รับเหตุการณ์วงจรลูกค้า notification_endpoint 12 ชั่วโมงและ 1 ชั่วโมงก่อนที่การสมัครใช้บริการจะหมดอายุ โปรดดูรายละเอียดที่หัวข้อรับและตอบสนองต่อเหตุการณ์วงจรของลูกค้า

หากไม่ต้องการให้การสมัครใช้บริการหมดอายุ คุณสามารถใช้วิธีUpdateSubscriptionเพื่อขยายวันที่หมดอายุได้ โปรดดูรายละเอียดที่หัวข้ออัปเดตหรือต่ออายุการสมัครใช้บริการ expiration ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
expireTime

string (Timestamp format)

ค่าเริ่มต้นที่ไม่ว่างเปล่า การประทับเวลาใน UTC เมื่อการสมัครใช้บริการหมดอายุ แสดงในเอาต์พุตเสมอ ไม่ว่าจะใช้อะไรในอินพุตก็ตาม
ttl

string (Duration format)

อินพุตเท่านั้น Time to Live (TTL) หรือระยะเวลาของการสมัครใช้บริการ หากไม่ได้ระบุหรือตั้งค่าเป็น 0 จะใช้ระยะเวลาสูงสุดที่เป็นไปได้

PayloadOptions

ตัวเลือกเกี่ยวกับข้อมูลที่จะรวมไว้ในเพย์โหลดของเหตุการณ์ รองรับเฉพาะกิจกรรมใน Google Chat

การแสดง JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
ช่อง
includeResource

boolean

ไม่บังคับ ไม่ว่าเพย์โหลดของเหตุการณ์จะมีข้อมูลเกี่ยวกับทรัพยากรที่เปลี่ยนแปลงหรือไม่ เช่น สำหรับเหตุการณ์ที่มีการสร้างข้อความ Google Chat เพย์โหลดจะมีข้อมูลเกี่ยวกับทรัพยากร Message หรือไม่ หากเป็นเท็จ เพย์โหลดของเหตุการณ์จะมีเฉพาะชื่อของทรัพยากรที่เปลี่ยนแปลง
fieldMask

string (FieldMask format)

ไม่บังคับ หากตั้งค่า includeResource เป็น true รายการช่องที่จะรวมไว้ในเพย์โหลดของเหตุการณ์ คั่นฟิลด์ด้วยคอมมา เช่น หากต้องการรวมผู้ส่งและเวลาสร้างข้อความ Google Chat ให้ป้อน message.sender,message.createTime หากละไว้ เพย์โหลดจะมีช่องทั้งหมดสำหรับทรัพยากร

หากคุณระบุฟิลด์ที่ไม่มีอยู่สำหรับทรัพยากร ระบบจะละเว้นฟิลด์นั้น

NotificationEndpoint

ปลายทางที่การสมัครใช้บริการส่งเหตุการณ์

การแสดง JSON 
{

  // Union field endpoint can be only one of the following:
  "pubsubTopic": string
  // End of list of possible types for union field endpoint.
}
ช่อง

ฟิลด์ Union endpoint

endpoint ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
pubsubTopic

string

เปลี่ยนแปลงไม่ได้ หัวข้อ Pub/Sub ที่รับเหตุการณ์สำหรับการสมัครใช้บริการ

รูปแบบ: projects/{project}/topics/{topic}

คุณต้องสร้างหัวข้อในโปรเจ็กต์ Google Cloud เดียวกันกับที่สร้างการสมัครใช้บริการนี้

หมายเหตุ: Workspace Events API ใช้คีย์การจัดลำดับเพื่อประโยชน์ของเหตุการณ์ตามลำดับ หากหัวข้อ Cloud Pub/Sub มีนโยบายการจัดเก็บข้อความที่กำหนดค่าให้ยกเว้นภูมิภาค Google Cloud ที่ใกล้ที่สุด การเผยแพร่เหตุการณ์ที่มีคีย์การจัดลำดับจะล้มเหลว

เมื่อหัวข้อได้รับเหตุการณ์ ระบบจะเข้ารหัสเหตุการณ์เป็นข้อความ Pub/Sub โปรดดูรายละเอียดที่การเชื่อมโยงโปรโตคอล Google Cloud Pub/Sub สำหรับ CloudEvents

รัฐ

สถานะที่เป็นไปได้ของการสมัครใช้บริการ

Enum
STATE_UNSPECIFIED ค่าเริ่มต้น ค่านี้ไม่ได้ใช้
ACTIVE การสมัครใช้บริการใช้งานอยู่ และรับและส่งเหตุการณ์ไปยังปลายทางการแจ้งเตือนได้
SUSPENDED การติดตามรับข้อมูลไม่สามารถรับเหตุการณ์ได้เนื่องจากมีข้อผิดพลาด หากต้องการระบุข้อผิดพลาด ให้ดูช่อง suspensionReason
DELETED ระบบจะลบการสมัครใช้บริการ

ErrorType

ข้อผิดพลาดที่อาจเกิดขึ้นสำหรับการสมัครใช้บริการ

Enum
ERROR_TYPE_UNSPECIFIED ค่าเริ่มต้น ค่านี้ไม่ได้ใช้
USER_SCOPE_REVOKED ผู้ใช้ที่ให้สิทธิ์ได้เพิกถอนการให้สิทธิ์ขอบเขต OAuth อย่างน้อย 1 รายการ ดูข้อมูลเพิ่มเติมเกี่ยวกับการให้สิทธิ์สำหรับ Google Workspace ได้ที่กำหนดค่าหน้าจอขอความยินยอม OAuth
RESOURCE_DELETED ไม่มีทรัพยากรเป้าหมายสำหรับการสมัครใช้บริการอีกต่อไป
USER_AUTHORIZATION_FAILURE ผู้ใช้ที่ให้สิทธิ์สร้างการสมัครใช้บริการไม่มีสิทธิ์เข้าถึงทรัพยากรเป้าหมายของการสมัครใช้บริการอีกต่อไป
ENDPOINT_PERMISSION_DENIED แอปพลิเคชัน Google Workspace ไม่มีสิทธิ์เข้าถึงเพื่อส่งกิจกรรมไปยังปลายทางการแจ้งเตือนของการสมัครใช้บริการ
ENDPOINT_NOT_FOUND ไม่มีปลายทางการแจ้งเตือนของการสมัครใช้บริการ หรือไม่พบปลายทางในโปรเจ็กต์ Google Cloud ที่คุณสร้างการสมัครใช้บริการ
ENDPOINT_RESOURCE_EXHAUSTED ปลายทางการแจ้งเตือนของการสมัครใช้บริการรับกิจกรรมไม่สำเร็จเนื่องจากโควต้าไม่เพียงพอหรือถึงการจำกัดอัตรา
OTHER เกิดข้อผิดพลาดที่ไม่รู้จัก

เมธอด

create

 สร้างการสมัครใช้บริการ Google Workspace

delete

 ลบการสมัครใช้บริการ Google Workspace

get

 รับรายละเอียดเกี่ยวกับการสมัครใช้บริการ Google Workspace

list

 แสดงรายการการสมัครใช้บริการ Google Workspace

patch

 อัปเดตหรือต่ออายุการสมัครใช้บริการ Google Workspace

reactivate

 เปิดใช้งานการสมัครใช้บริการ Google Workspace ที่ถูกระงับอีกครั้ง