Tệp kê khai cho tiện ích bổ sung của Google Workspace

Tiện ích bổ sung sử dụng tệp manifest để định cấu hình một số thông tin chi tiết về ứng dụng và hoạt động của ứng dụng.

Tài liệu này trình bày chi tiết về cách định cấu hình tệp kê khai cho Tiện ích bổ sung của Google Workspace.

Cấu trúc tệp kê khai cho tiện ích bổ sung của Google Workspace

Tiện ích bổ sung của Google Workspace sử dụng tệp kê khai để xác định một số khía cạnh về giao diện và hành vi.

Các thuộc tính tệp kê khai cho tiện ích bổ sung của Google Workspace được sắp xếp trong phần addOns.

  • Để biết thông tin về tệp kê khai Google Apps Script, hãy tham khảo phần Cấu trúc tệp kê khai.

  • Để biết thông tin về tệp kê khai cho các tiện ích bổ sung được tạo bằng điểm cuối HTTP, hãy tham khảo projects.deployments.

Tệp kê khai cho Google Chat

Nếu tiện ích bổ sung Google Workspace của bạn mở rộng Google Chat, hãy định cấu hình ứng dụng Google Chat bằng cách bật và định cấu hình API Google Chat trong bảng điều khiển Cloud.

Các chế độ cài đặt cấu hình tệp kê khai thông thường (bao gồm cả addons.common) sẽ bị bỏ qua trong Chat. Sử dụng API Chat để định cấu hình các chế độ cài đặt Chat sau đây:

Nếu bạn tạo tiện ích bổ sung trong Apps Script, hãy thêm hoặc cập nhật các đối tượng sau trong tệp kê khai:

  • addons.chat (Bắt buộc)
  • oauthScopes (Bắt buộc nếu ứng dụng Google Chat của bạn sử dụng OAuth)

Để định cấu hình chế độ cài đặt Chat cho một tiện ích bổ sung, hãy xem phần Định cấu hình ứng dụng Google Chat.

Cấu hình tệp kê khai mẫu của tiện ích bổ sung Google Workspace

Các mẫu sau đây cho thấy phần của tệp kê khai xác định một tiện ích bổ sung Google Workspace, bao gồm cả những khía cạnh sau:

  • addOns.common xác định tên, biểu trưng, màu sắc và các chế độ cài đặt chung khác cho tiện ích bổ sung.

  • Tệp kê khai xác định một trang chủ chung, nhưng cũng xác định các trang chủ dành riêng cho Lịch Google, Google Drive, Google Tài liệu, Google Trang tính và Google Trang trình bày. Gmail sử dụng trang chủ mặc định.

  • Các chế độ cài đặt mẫu trong tệp kê khai cho phép những điều sau:

    • Sự kiện kích hoạt eventOpen và eventUpdated trên Lịch.

    • (Chỉ Apps Script) Hai giải pháp hội nghị trên Lịch.

    • Hai thao tác chung.

    • Ổ đĩa onItemsSelectedTrigger.

    • Thao tác soạn thư trong Gmail và điều kiện kích hoạt theo bối cảnh.

    • Một đối tượng linkPreviewTriggers trong Tài liệu. Xem phần Xem trước đường liên kết bằng khối thông minh.

    • Một đối tượng createActionTriggers trong Tài liệu. Xem phần Tạo tài nguyên bên thứ ba thông qua trình đơn @.

    • Giao diện dành riêng cho tệp đối với Tài liệu, Trang tính và Trang trình bày.

    • Tuỳ chọn sidePanelUri và addOnOrigins của Google Meet.

    • (Chỉ HTTP) Hai HttpOptions để gửi tiêu đề uỷ quyền và hỗ trợ sự đồng ý chi tiết.

  • Trường oauthScopes đặt phạm vi uỷ quyền của dự án.

  • (Chỉ Apps Script) urlFetchWhitelist đảm bảo các điểm cuối được tìm nạp khớp với tiền tố URL HTTPS đã chỉ định. Xem phần URL trong danh sách cho phép.

Các đường liên kết trong mẫu sẽ chuyển hướng đến nội dung mô tả trường trong tài liệu tham khảo về tệp kê khai cho Apps Script và tiện ích bổ sung HTTP của Google Workspace.

Tệp kê khai bao gồm các thành phần khác. Các trường trong addOns liên quan trực tiếp đến tiện ích bổ sung của Google Workspace. Ví dụ này chỉ cho thấy một phần của tệp kê khai đầy đủ và không hoạt động độc lập.

Apps Script 

{
  "addOns": {
    "calendar": {
      "createSettingsUrlFunction": "getConferenceSettingsPageUrl",
      "conferenceSolution": [{
        "id": "my-video-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Video Conference",
        "onCreateFunction": "onCreateMyVideoConference"
      }, {
        "id": "my-streamed-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Streamed Conference",
        "onCreateFunction": "onCreateMyStreamedConference"
      }],
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "onDefaultHomePageOpen",
        "enabled": true
      },
      "layoutProperties": {
        "primaryColor": "#ff392b",
        "secondaryColor": "#d68617"
      },
      "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
      "name": "Demo Google Workspace add-on",
      "openLinkUrlPrefixes": [
        "https://mail.google.com/",
        "https://script.google.com/a/google.com/d/",
        "https://drive.google.com/a/google.com/file/d/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "selectActions": [
          {
            "text": "Add images to email",
            "runFunction": "getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
        "runFunction": "onLinkPreview",
        "patterns": [
            {
              "hostPattern": "example.com",
              "pathPrefix": "example-path"
            }
        ],
        "labelText": "Link preview",
        "localizedLabelText": {
          "es": "Link preview localized in Spanish"
        },
        "logoUrl": "https://www.example.com/images/smart-chip-icon.png"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "exampleFunction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/logoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
    },
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.locale",
    "https://www.googleapis.com/auth/script.scriptapp",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/documents.currentonly",
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/presentations.currentonly",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ]
}

HTTP

{
  "addOns": {
    "calendar": {
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDefaultHomePageOpen",
        "enabled": true
      },
      "layoutProperties": {
        "primaryColor": "#ff392b",
        "secondaryColor": "#d68617"
      },
      "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
      "name": "Demo Google Workspace add-on",
      "openLinkUrlPrefixes": [
        "https://mail.google.com/",
        "https://script.google.com/a/google.com/d/",
        "https://drive.google.com/a/google.com/file/d/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "actions": [
          {
            "label": "Add images to email",
            "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onLinkPreview",
          "patterns": [
              {
                "hostPattern": "example.com",
                "pathPrefix": "example-path"
              }
          ],
          "labelText": "Link preview",
          "localizedLabelText": {
            "es": "Link preview localized in Spanish"
          },
          "logoUrl": "https://www.example.com/images/smart-chip-icon.png"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
      ]
    },
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.locale",
    "https://www.googleapis.com/auth/script.scriptapp",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/documents.currentonly",
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/presentations.currentonly",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ]
}

URL trong danh sách cho phép

Bạn sử dụng danh sách cho phép để chỉ định các URL cụ thể được phê duyệt trước để tập lệnh hoặc tiện ích bổ sung của bạn truy cập. Danh sách cho phép giúp bảo vệ dữ liệu người dùng; khi bạn xác định danh sách cho phép, các dự án tập lệnh sẽ không thể truy cập vào những URL chưa được thêm vào danh sách cho phép.

Bạn không bắt buộc phải điền trường này khi cài đặt bản triển khai kiểm thử, nhưng bắt buộc phải điền khi tạo bản triển khai có phiên bản.

Bạn sử dụng danh sách cho phép khi tập lệnh hoặc tiện ích bổ sung của bạn thực hiện các thao tác sau:

  • Truy xuất hoặc tìm nạp thông tin từ một vị trí bên ngoài (chẳng hạn như các điểm cuối HTTPS) bằng dịch vụ UrlFetch của Apps Script. Để đưa các URL vào danh sách cho phép để tìm nạp, hãy thêm trường urlFetchWhitelist vào tệp kê khai.
  • Mở hoặc hiển thị một URL để phản hồi hành động của người dùng (Bắt buộc đối với những tiện ích bổ sung Google Workspace mở hoặc hiển thị các URL bên ngoài Google). Để đưa các URL vào danh sách cho phép để mở, hãy thêm trường addOns.common.openLinkUrlPrefixes vào tệp kê khai của bạn.

Thêm tiền tố vào danh sách cho phép

Khi chỉ định danh sách cho phép trong tệp kê khai (bằng cách thêm trường addOns.common.openLinkUrlPrefixes hoặc urlFetchWhitelist), bạn phải thêm danh sách tiền tố URL. Các tiền tố mà bạn thêm vào tệp kê khai phải đáp ứng các yêu cầu sau:

  • Mỗi tiền tố phải là một URL hợp lệ.
  • Mỗi tiền tố phải sử dụng https://, không phải http://.
  • Mỗi tiền tố phải có một miền đầy đủ.
  • Mỗi tiền tố phải có một đường dẫn không trống. Ví dụ: https://www.google.com/ là hợp lệ nhưng https://www.google.com thì không.
  • Bạn có thể sử dụng ký tự đại diện để so khớp tiền tố miền phụ của URL.
  • Bạn có thể dùng một ký tự đại diện * trong trường addOns.common.openLinkUrlPrefixes để so khớp tất cả các đường liên kết, nhưng bạn không nên làm như vậy vì việc này có thể khiến dữ liệu của người dùng gặp rủi ro và có thể kéo dài quy trình xem xét tiện ích bổ sung. Chỉ sử dụng ký tự đại diện nếu chức năng của tiện ích bổ sung yêu cầu bạn làm như vậy.

Khi xác định xem một URL có khớp với tiền tố trong danh sách cho phép hay không, các quy tắc sau sẽ được áp dụng:

  • Tính năng so khớp đường dẫn có phân biệt chữ hoa chữ thường.
  • Nếu tiền tố giống hệt với URL, thì đó là một kết quả trùng khớp.
  • Nếu URL giống với tiền tố hoặc là một phần của tiền tố, thì đó là một kết quả khớp.

Ví dụ: tiền tố https://example.com/foo khớp với các URL sau:

  • https://example.com/foo
  • https://example.com/foo/
  • https://example.com/foo/bar
  • https://example.com/foo?bar
  • https://example.com/foo#bar

Sử dụng ký tự đại diện

Bạn có thể sử dụng một ký tự đại diện (*) để so khớp một miền con cho cả trường urlFetchWhitelist và addOns.common.openLinkUrlPrefixes. Bạn không thể dùng nhiều ký tự đại diện để so khớp nhiều miền con và ký tự đại diện phải đại diện cho tiền tố đầu tiên của URL.

Ví dụ: tiền tố https://*.example.com/foo khớp với các URL sau:

  • https://subdomain.example.com/foo
  • https://any.number.of.subdomains.example.com/foo

Tiền tố https://*.example.com/foo không khớp với các URL sau:

  • https://subdomain.example.com/bar (hậu tố không khớp)
  • https://example.com/foo (phải có ít nhất một miền con)

Một số quy tắc về tiền tố sẽ được thực thi khi bạn cố gắng lưu tệp kê khai. Ví dụ: các tiền tố sau đây sẽ gây ra lỗi nếu có trong tệp kê khai khi bạn cố gắng lưu:

  • https://*.*.example.com/foo (không được dùng nhiều ký tự đại diện)
  • https://subdomain.*.example.com/foo (bạn phải sử dụng ký tự đại diện làm tiền tố chính)