Giao diện điểm cuối của tiện ích bổ sung Google Workspace


Tổng quan về dịch vụ

Khi người dùng kích hoạt một hoạt động tương tác trong một ứng dụng lưu trữ được hỗ trợ (Gmail, Lịch Google, Google Drive, Google Chat, Google Tài liệu, Google Trang tính, Google Trang trình bày hoặc Workspace Studio), máy chủ lưu trữ sẽ gửi một tải trọng sự kiện HTTP POST đến URL gọi lại của tiện ích bổ sung mà bạn đã định cấu hình (/*).

Điểm cuối của tiện ích bổ sung phải nhận được tải trọng yêu cầu EventObject và trả về một trong 5 loại phản hồi JSON hợp lệ được ghi lại trong Phản hồi: HandleEventResponse.


Hợp đồng điểm cuối webhook

Phương thức Đường dẫn điểm cuối Nội dung yêu cầu Nội dung phản hồi
POST /* (hoặc đường dẫn gọi lại đã định cấu hình) EventObject Một trong 5 loại phản hồi

Yêu cầu: EventObject

EventObject chứa siêu dữ liệu cấp cao nhất, các trường sự kiện phổ biến và thông tin chi tiết theo bối cảnh của ứng dụng lưu trữ:

Bối cảnh chung và bối cảnh uỷ quyền

  • commonEventObject: Ngôn ngữ của người dùng, enum ứng dụng lưu trữ (GMAIL, CALENDAR, DRIVE, CHAT, DOCS, SHEETS, SLIDES, WORKFLOW), nền tảng của người dùng, múi giờ, giá trị đầu vào của biểu mẫu tiện ích (formInputs) và tham số tuỳ chỉnh. Xem CommonEventObject.
  • authorizationEventObject: Mã truy cập OAuth của người dùng, mã nhận dạng người dùng và phạm vi được hệ thống uỷ quyền. Xem AuthorizationEventObject.

Đối tượng sự kiện của ứng dụng lưu trữ

Tuỳ thuộc vào ứng dụng gọi lệnh gọi lại, một trong các đối tượng lưu trữ sau sẽ xuất hiện:

  • Gmail: Mã nhận dạng thư, mã nhận dạng chuỗi thư, mã truy cập tạm thời và danh sách người nhận thư (toRecipients, ccRecipients, bccRecipients). Xem GmailEventObject.
  • Lịch: Mã sự kiện, mã sự kiện định kỳ, mã lịch, thông tin về người tổ chức, người tham dự, dữ liệu hội nghị và điểm truy cập. Xem CalendarEventObject.
  • Drive: Các tệp hoặc thư mục đã chọn (selectedItems) và siêu dữ liệu của mục hiện tại mà con trỏ đang trỏ đến (activeCursorItem). Xem DriveEventObject.
  • Chat: Loại sự kiện (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), siêu dữ liệu của không gian, thông tin chi tiết về người dùng và dữ liệu tải trọng. Xem ChatEventObject.
  • Workspace Studio: Lời gọi hành động, sự kiện trong vòng đời của trình kích hoạt, cấu hình phần tử, truy xuất tài nguyên và liên kết dữ liệu biến. Xem WorkflowEventObject.
  • Tài liệu: Mã tài liệu, tiêu đề, cờ quyền trong phạm vi tệp và mẫu URL trùng khớp. Xem DocsEventObject.
  • Trang tính: Mã nhận dạng bảng tính, tiêu đề, cờ quyền trong phạm vi tệp và mẫu URL trùng khớp. Xem SheetsEventObject.
  • Trang trình bày: Mã nhận dạng bản trình bày, tiêu đề, cờ cấp quyền trong phạm vi tệp và mẫu URL trùng khớp. Xem SlidesEventObject.

Phản hồi: HandleEventResponse

Phản hồi HTTP do điểm cuối webhook trả về là một đối tượng JSON gốc không được gắn thẻ. Đối tượng này phải là một thực thể của một trong năm loại phản hồi sau:

  1. RenderActions: Hiển thị thẻ mới, di chuyển ngăn xếp thẻ hoặc thực thi các thao tác trên giao diện người dùng (ví dụ: {"action": {"navigations": [...]}} hoặc {"renderActions": ...}).
  2. SubmitFormResponse: Phản hồi hành động gửi biểu mẫu của người dùng bằng hướng dẫn hiển thị thẻ và chỉ báo cập nhật trạng thái không bắt buộc (ví dụ: {"renderActions": {...}, "stateChanged": true}).
  3. GetAutocompletionResponse: Cung cấp các đề xuất văn bản động cho các trường tự động hoàn thành của tiện ích (ví dụ: {"autoComplete": {"items": [...]}}).
  4. DataActions: Thực hiện các thay đổi đối với tài liệu hoặc các hành động trong phòng Chat được kích hoạt bởi lệnh gọi lại (ví dụ: {"hostAppDataAction": {...}}).
  5. AuthorizationError: Nhắc người dùng uỷ quyền thông tin xác thực bên ngoài của bên thứ ba hoặc yêu cầu phạm vi OAuth bổ sung của Google (ví dụ: {"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).

Thông số kỹ thuật OpenAPI 3.0 độc lập và Giản đồ JSON

Để tự động tạo mã giả lập máy chủ, thư viện ứng dụng SDK hoặc giản đồ xác thực tải trọng cho điểm cuối gọi lại, hãy tham khảo các tệp thông số kỹ thuật sau:

  • Quy cách OpenAPI 3.0.3: addon_callback_openapi.json
  • Định nghĩa giản đồ JSON: endpoint_interface.schema.json
    • Mảnh giản đồ yêu cầu: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • Đoạn giản đồ phản hồi: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse