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,

  "driveOptions": {
    object (DriveOptions)
  }

  "userAuthority": string,
  "serviceAccountAuthority": string

  "expireTime": string,
  "ttl": string
}
ช่อง
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 และ Google ไดรฟ์
notificationEndpoint

object (NotificationEndpoint)

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

enum (State)

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

enum (ErrorType)

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

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

string

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

เมื่อผู้ใช้ให้สิทธิ์การสมัครใช้บริการ ฟิลด์นี้และฟิลด์ userAuthority จะมีค่าเดียวกันและมีรูปแบบดังนี้

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

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

เมื่อแอป Chat อนุญาตการสมัครใช้บริการ ระบบจะป้อนข้อมูลเฉพาะserviceAccountAuthority และช่องนี้จะว่างเปล่า
createTime

string (Timestamp format)

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

string (Timestamp format)

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

boolean

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

string

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

object (DriveOptions)

ไม่บังคับ ฟีเจอร์ที่รองรับเฉพาะการสมัครใช้บริการในทรัพยากรของไดรฟ์
ฟิลด์ Union authority_info ข้อมูลประจำตัวที่ให้สิทธิ์ในการสร้างการสมัครใช้บริการ authority_info ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
userAuthority

string

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

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

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

string

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

รูปแบบ: projects/{projectId}/serviceAccounts/{service_account_id}

ฟิลด์ 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 จะใช้ระยะเวลาสูงสุดที่เป็นไปได้

DriveOptions

ตัวเลือกเพิ่มเติมที่รองรับสำหรับการแสดงเหตุการณ์ในไดรฟ์

การแสดง JSON 
{
  "includeDescendants": boolean
}
ฟิลด์
includeDescendants

boolean

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

ฟิลด์นี้ต้องเป็น true สำหรับการสมัครใช้บริการในไดรฟ์ที่แชร์

  • หากเป็น false การสมัครใช้บริการจะได้รับเฉพาะเหตุการณ์เกี่ยวกับการเปลี่ยนแปลงโฟลเดอร์หรือไดรฟ์ที่แชร์ที่ระบุเป็น targetResource
  • หากเป็น true คุณต้องตั้งค่าฟิลด์ mimeType ของทรัพยากร file เป็น application/vnd.google-apps.folder

โปรดดูรายละเอียดที่ประเภทเหตุการณ์ใน Google ไดรฟ์

PayloadOptions

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

การแสดง JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
ฟิลด์
includeResource

boolean

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

string (FieldMask format)

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

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

NotificationEndpoint

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

การแสดง JSON 
{

  "pubsubTopic": string
}
ช่อง

ฟิลด์ Union endpoint

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

string

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

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

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

หมายเหตุ: Google 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
APP_SCOPE_REVOKED ผู้ดูแลระบบโดเมนได้เพิกถอนการให้สิทธิ์ขอบเขต OAuth อย่างน้อย 1 รายการสำหรับแอป
RESOURCE_DELETED ไม่มีทรัพยากรเป้าหมายสำหรับการสมัครใช้บริการอีกต่อไป
USER_AUTHORIZATION_FAILURE ผู้ใช้ที่ให้สิทธิ์สร้างการสมัครใช้บริการไม่มีสิทธิ์เข้าถึงทรัพยากรเป้าหมายของการสมัครใช้บริการอีกต่อไป
APP_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 ที่ถูกระงับอีกครั้ง