REST Resource: subscriptions

Tài nguyên: Gói thuê bao

Gói thuê bao nhận sự kiện về một tài nguyên trên Google Workspace. Để tìm hiểu thêm về các gói thuê bao, hãy xem bài viết Tổng quan về API Sự kiện của Google Workspace.

Biểu diễn dưới dạng 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.
}
Trường
name

string

Không bắt buộc. Bất biến. Giá trị nhận dạng. Tên tài nguyên của gói thuê bao.

Định dạng subscriptions/{subscription}

uid

string

Chỉ có đầu ra. Giá trị nhận dạng duy nhất do hệ thống chỉ định cho gói thuê bao này.

targetResource

string

Bắt buộc. Bất biến. Tài nguyên trên Google Workspace có chức năng giám sát các sự kiện, có định dạng là tên tài nguyên đầy đủ. Để tìm hiểu về các tài nguyên mục tiêu và những sự kiện mà các tài nguyên đó hỗ trợ, hãy xem bài viết Các sự kiện được hỗ trợ trong Google Workspace.

Người dùng chỉ có thể cho phép ứng dụng tạo một gói thuê bao cho một tài nguyên mục tiêu nhất định. Nếu ứng dụng của bạn cố gắng tạo một gói thuê bao khác có cùng thông tin đăng nhập người dùng, thì yêu cầu sẽ trả về lỗi ALREADY_EXISTS.

eventTypes[]

string

Bắt buộc. Bất biến. Danh sách không theo thứ tự. Thông tin đầu vào để tạo gói thuê bao. Nếu không, chỉ có thể xuất đầu ra. Một hoặc nhiều loại sự kiện cần nhận về tài nguyên mục tiêu. Được định dạng theo quy cách CloudEvents.

Các loại sự kiện được hỗ trợ phụ thuộc vào tài nguyên mục tiêu của gói thuê bao. Để biết thông tin chi tiết, hãy xem bài viết Các sự kiện được hỗ trợ trong Google Workspace.

Theo mặc định, bạn cũng nhận được các sự kiện về vòng đời gói thuê bao. Bạn không cần chỉ định các sự kiện trong vòng đời cho trường này.

Nếu bạn chỉ định một loại sự kiện không tồn tại cho tài nguyên mục tiêu, yêu cầu sẽ trả về một mã trạng thái HTTP 400 Bad Request.

payloadOptions

object (PayloadOptions)

Không bắt buộc. Các lựa chọn về dữ liệu cần đưa vào tải trọng sự kiện. Chỉ hỗ trợ cho các sự kiện trong Google Chat.

notificationEndpoint

object (NotificationEndpoint)

Bắt buộc. Bất biến. Điểm cuối mà gói thuê bao phân phối các sự kiện, chẳng hạn như một chủ đề Pub/Sub.

state

enum (State)

Chỉ có đầu ra. Trạng thái của gói thuê bao. Xác định xem gói thuê bao có thể nhận sự kiện và gửi sự kiện đó đến điểm cuối thông báo hay không.

suspensionReason

enum (ErrorType)

Chỉ có đầu ra. Lỗi đã tạm ngưng gói thuê bao.

Để kích hoạt lại gói thuê bao, hãy khắc phục lỗi rồi gọi phương thức subscriptions.reactivate.

authority

string

Chỉ có đầu ra. Người dùng đã cho phép tạo gói thuê bao.

Định dạng users/{user}

Đối với người dùng Google Workspace, giá trị {user} là trường user.id trong Directory API.

createTime

string (Timestamp format)

Chỉ có đầu ra. Thời điểm tạo gói thuê bao.

updateTime

string (Timestamp format)

Chỉ có đầu ra. Lần gần nhất mà gói thuê bao được cập nhật.

reconciling

boolean

Chỉ có đầu ra. Nếu giá trị là true, tức là gói thuê bao đang trong quá trình cập nhật.

etag

string

Không bắt buộc. Giá trị tổng kiểm này được máy chủ tính toán dựa trên giá trị của các trường khác và có thể được gửi trong yêu cầu cập nhật để đảm bảo máy khách có giá trị đã cập nhật trước khi tiếp tục.

Trường kết hợp expiration. Thời điểm gói thuê bao hết hạn.

Thời gian hết hạn tối đa phụ thuộc vào việc gói thuê bao của bạn có bao gồm dữ liệu tài nguyên trong các gói dữ liệu sự kiện hay không (được chỉ định trong trường PayloadOptions):

  • Nếu tải trọng bỏ qua dữ liệu tài nguyên, thì tối đa 7 ngày.
  • Nếu tải trọng bao gồm dữ liệu tài nguyên thì tối đa 4 giờ. Nếu tổ chức Google Workspace của bạn cấp quyền truy cập vào tài nguyên thông qua tính năng uỷ quyền trên toàn miền, thì bạn có thể kéo dài thời gian hết hạn của gói thuê bao lên tới 24 giờ.

Sau khi hết hạn, gói thuê bao sẽ tự động bị xoá. Bạn sẽ nhận được các sự kiện trong vòng đời đến notification_endpoint 12 giờ và một giờ trước khi gói thuê bao hết hạn. Để biết thông tin chi tiết, hãy xem bài viết Nhận và phản hồi các sự kiện trong vòng đời.

Để gói thuê bao không hết hạn, bạn có thể sử dụng phương thức UpdateSubscription để gia hạn ngày hết hạn. Để biết thông tin chi tiết, hãy xem bài viết Cập nhật hoặc gia hạn gói thuê bao. expiration chỉ có thể là một trong những trạng thái sau đây:

expireTime

string (Timestamp format)

Giá trị mặc định không trống. Dấu thời gian theo giờ UTC khi gói thuê bao hết hạn. Luôn hiển thị trên đầu ra, bất kể nội dung nào được sử dụng trên đầu vào.

ttl

string (Duration format)

Chỉ nhập. Thời gian tồn tại (TTL) hoặc khoảng thời gian của gói thuê bao. Nếu bạn không chỉ định hoặc đặt thành 0, hãy sử dụng thời lượng tối đa có thể.

PayloadOptions

Các lựa chọn về dữ liệu cần đưa vào tải trọng sự kiện. Chỉ hỗ trợ cho các sự kiện trong Google Chat.

Biểu diễn dưới dạng JSON
{
  "includeResource": boolean,
  "fieldMask": string
}
Trường
includeResource

boolean

Không bắt buộc. Liệu tải trọng sự kiện có bao gồm dữ liệu về tài nguyên đã thay đổi hay không. Ví dụ: đối với một sự kiện tạo tin nhắn trong Google Chat, liệu tải trọng có chứa dữ liệu về tài nguyên Message hay không. Nếu là false, thì tải trọng sự kiện chỉ bao gồm tên của tài nguyên đã thay đổi.

fieldMask

string (FieldMask format)

Không bắt buộc. Nếu bạn đặt includeResource thành true, danh sách các trường cần đưa vào tải trọng sự kiện. Tách các trường bằng dấu phẩy. Ví dụ: Để thêm người gửi tin nhắn trong Google Chat và thời gian tạo, hãy nhập message.sender,message.createTime. Nếu bỏ qua, thì tải trọng sẽ bao gồm tất cả các trường cho tài nguyên.

Nếu bạn chỉ định một trường không tồn tại cho tài nguyên, hệ thống sẽ bỏ qua trường đó.

NotificationEndpoint

Điểm cuối mà gói thuê bao phân phối sự kiện.

Biểu diễn dưới dạng JSON
{

  // Union field endpoint can be only one of the following:
  "pubsubTopic": string
  // End of list of possible types for union field endpoint.
}
Trường

Trường kết hợp endpoint.

endpoint chỉ có thể là một trong những trạng thái sau đây:

pubsubTopic

string

Bất biến. Chủ đề Cloud Pub/Sub nhận các sự kiện cho gói thuê bao.

Định dạng projects/{project}/topics/{topic}

Bạn phải tạo chủ đề trong cùng một dự án trên Google Cloud mà bạn dùng để tạo gói thuê bao này.

Khi chủ đề nhận được sự kiện, các sự kiện đó sẽ được mã hoá dưới dạng thông báo trên Cloud Pub/Sub. Để biết thông tin chi tiết, vui lòng xem bài viết Liên kết giao thức Google Cloud Pub/Sub cho CloudEvents.

Tiểu bang

Các trạng thái có thể có của gói thuê bao.

Enum
STATE_UNSPECIFIED Giá trị mặc định. Giá trị này chưa được sử dụng.
ACTIVE Gói thuê bao này đang hoạt động và có thể nhận cũng như gửi các sự kiện đến điểm cuối thông báo của gói thuê bao đó.
SUSPENDED Gói thuê bao không thể nhận sự kiện do xảy ra lỗi. Để xác định lỗi, hãy xem trường suspensionReason.
DELETED Gói thuê bao đã bị xoá.

ErrorType

Các lỗi có thể xảy ra với gói thuê bao.

Enum
ERROR_TYPE_UNSPECIFIED Giá trị mặc định. Giá trị này chưa được sử dụng.
USER_SCOPE_REVOKED Người dùng uỷ quyền đã thu hồi quyền cấp một hoặc nhiều phạm vi OAuth. Để tìm hiểu thêm về việc uỷ quyền cho Google Workspace, hãy xem bài viết Định cấu hình màn hình xin phép bằng OAuth.
RESOURCE_DELETED Tài nguyên đích cho gói thuê bao này không còn tồn tại.
USER_AUTHORIZATION_FAILURE Người dùng đã uỷ quyền tạo gói thuê bao sẽ không còn quyền truy cập vào tài nguyên đích của gói thuê bao đó nữa.
ENDPOINT_PERMISSION_DENIED Ứng dụng Google Workspace không có quyền truy cập để gửi sự kiện đến điểm cuối thông báo của gói thuê bao của bạn.
ENDPOINT_NOT_FOUND Điểm cuối thông báo của gói thuê bao không tồn tại hoặc không tìm thấy điểm cuối trong dự án Google Cloud mà bạn đã tạo gói thuê bao.
ENDPOINT_RESOURCE_EXHAUSTED Điểm cuối thông báo của gói thuê bao không nhận được sự kiện do không đủ hạn mức hoặc đạt đến giới hạn số lượng yêu cầu.
OTHER Đã xảy ra lỗi không xác định.

Phương thức

create

Tạo một gói thuê bao của Google Workspace.

delete

Xoá một gói thuê bao của Google Workspace.

get

Xem thông tin chi tiết về một gói thuê bao của Google Workspace.

list

Liệt kê các gói thuê bao của Google Workspace.

patch

Cập nhật hoặc gia hạn gói thuê bao của Google Workspace.

reactivate

Kích hoạt lại một gói thuê bao bị tạm ngưng của Google Workspace.