REST Resource: subscriptions

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

Một gói thuê bao để nhận các sự kiện về một tài nguyên Google Workspace. Để tìm hiểu thêm về các sự kiện được đăng ký nhận thông báo, hãy xem bài viết Tổng quan về Google Workspace Events API.

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 subscription_options can be only one of the following:
  "driveOptions": {
    object (DriveOptions)
  }
  // End of list of possible types for union field subscription_options.

  // 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

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 riêng biệt do hệ thống chỉ định cho gói thuê bao.
targetResource

string

Bắt buộc. Không thể thay đổi. Tài nguyên Google Workspace được giám sát để theo dõi các sự kiện, được định dạng dưới dạng 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ợ của Google Workspace.

Người dùng chỉ có thể cho phép ứng dụng của bạn tạo một gói thuê bao cho một tài nguyên đích 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 bằng thông tin đăng nhập của cùng một người dùng, thì yêu cầu sẽ trả về lỗi ALREADY_EXISTS.
eventTypes[]

string

Bắt buộc. Danh sách không theo thứ tự. Đầu vào để tạo gói thuê bao. Nếu không, chỉ có đầu ra. Một hoặc nhiều loại sự kiện sẽ nhận được về tài nguyên đích. Đượ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 phần Các sự kiện được hỗ trợ của Google Workspace.

Theo mặc định, bạn cũng nhận được các sự kiện về vòng đời của 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, thì yêu cầu sẽ trả về 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ỉ được hỗ trợ cho các sự kiện trên Google Chat và Google Drive.
notificationEndpoint

object (NotificationEndpoint)

Bắt buộc. Không thể thay đổi. Điểm cuối mà gói thuê bao gửi sự kiện đế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 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 khiến gói thuê bao bị tạm ngưng.

Để kích hoạt lại gói thuê bao, hãy giải quyết lỗi và gọi phương thức subscriptions.reactivate.
authority

string

Chỉ có đầu ra. Người dùng đã uỷ quyền 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 đây nhất gói thuê bao được cập nhật.
reconciling

boolean

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

string

Không bắt buộc. 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 các yêu cầu cập nhật để đảm bảo ứng dụng có giá trị mới nhất trước khi tiếp tục.
Trường nhóm subscription_options. Các lựa chọn đăng ký bổ sung được cung cấp cho một số tài nguyên mục tiêu cụ thể đối với gói thuê bao Google Workspace. subscription_options chỉ có thể là một trong những trạng thái sau:
driveOptions

object (DriveOptions)

Không bắt buộc. Các tính năng chỉ được hỗ trợ cho gói thuê bao đối với tài nguyên trên Drive.

Trường nhóm 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 tải trọng sự kiện (được chỉ định trong trường PayloadOptions) hay không:

  • Nếu tải trọng bỏ qua dữ liệu tài nguyên, tối đa 7 ngày.
  • Nếu tải trọng bao gồm dữ liệu tài nguyên, 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, bạn có thể kéo dài thời gian hết hạn của mã thông báo đăng ký tối đa 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 cho notification_endpoint 12 giờ và 1 giờ trước khi gói thuê bao hết hạn. Để biết thông tin chi tiết, hãy xem phần Nhận và phản hồi các sự kiện trong vòng đời.

Để ngăn gói thuê bao hết hạn, bạn có thể 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:
expireTime

string (Timestamp format)

Giá trị mặc định không được để 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ể bạn đã sử dụng giá trị nào trên đầu vào.
ttl

string (Duration format)

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

DriveOptions

Các lựa chọn được hỗ trợ khác để phân phát sự kiện trên Drive.

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

boolean

Không bắt buộc. Không thể thay đổi. Đối với các sự kiện trên Google Drive, cho biết có nhận các sự kiện về tệp trên Drive là tệp con của thư mục hoặc bộ nhớ dùng chung mục tiêu hay không.

  • Nếu false, thì thuê bao chỉ nhận được các sự kiện về những thay đổi đối với thư mục hoặc bộ nhớ dùng chung được chỉ định là targetResource.
  • Nếu true, bạn phải đặt trường mimeType của tài nguyên file thành application/vnd.google-apps.folder.

Để biết thông tin chi tiết, hãy xem bài viết Các loại sự kiện trên Google Drive.

PayloadOptions

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

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 mà tin nhắn trên Google Chat được tạo, 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, tải trọng sự kiện sẽ 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 includeResource được đặt thành true, danh sách các trường sẽ có trong tải trọng sự kiện. Phân tách các trường bằng dấu phẩy. Ví dụ: để thêm người gửi và thời gian tạo của một tin nhắn trên Google Chat, hãy nhập message.sender,message.createTime. Nếu bạn bỏ qua, 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 nơi gói thuê bao phân phối các 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 nhóm endpoint.

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

string

Không thể thay đổi. Chủ đề 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 nơi bạn tạo gói thuê bao này.

Lưu ý: Google Workspace Events API sử dụng khoá sắp xếp để mang lại lợi ích cho các sự kiện tuần tự. Nếu chủ đề Cloud Pub/Sub có chính sách lưu trữ tin nhắn được định cấu hình để loại trừ khu vực Google Cloud gần nhất, thì việc xuất bản các sự kiện bằng khoá sắp xếp sẽ không thành công.

Khi chủ đề nhận được các sự kiện, các sự kiện đó sẽ được mã hoá dưới dạng thông báo Pub/Sub. Để biết thông tin chi tiết, hãy xem Google Cloud Pub/Sub Protocol Binding for CloudEvents (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 không được dùng.
ACTIVE Gói thuê bao đ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.
SUSPENDED Do lỗi nên gói thuê bao không nhận được sự kiện. Để 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 đối với một gói thuê bao.

Enum
ERROR_TYPE_UNSPECIFIED Giá trị mặc định. Giá trị này không được 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 phần Định cấu hình màn hình đồng ý OAuth.
RESOURCE_DELETED Tài nguyên mục tiêu cho gói thuê bao không còn tồn tại.
USER_AUTHORIZATION_FAILURE Người dùng đã uỷ quyền tạo gói thuê bao không còn có 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.
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 về tốc độ.
OTHER Đã xảy ra lỗi không xác định.

Phương thức

create

 Tạo gói thuê bao Google Workspace.

delete

 Xoá gói thuê bao Google Workspace.

get

 Lấy thông tin chi tiết về một gói thuê bao Google Workspace.

list

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

patch

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

reactivate

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