Trang này được dịch bởi Cloud Translation API.

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

Dự án Apps Script sử dụng tệp tệp kê khai để định cấu hình một số chi tiết nhất định về tập lệnh và hoạt động của tập lệnh đó. Để tìm hiểu cách xem và chỉnh sửa tệp kê khai, hãy xem phần Tệp kê khai.

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 của dự án Apps Script để xác định một số khía cạnh của giao diện và hành vi của tiện ích bổ sung. 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 của cấu trúc đối tượng tệp kê khai.

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

Mẫu tệp kê khai bên dưới cho thấy phần của tệp kê khai xác định Tiện ích bổ sung của Google Workspace, bao gồm các khía cạnh sau:

Phần addOns.common của tệp kê khai xác định tên, URL biểu trưng, màu sắc và các chế độ cài đặt khác, độc lập với máy chủ cho tiện ích bổ sung.
Tệp kê khai xác định trang chủ phổ biến, nhưng cũng xác định trang chủ dành riêng cho Lịch, Drive, Tài liệu, Trang tính và Trang trình bày. Gmail sử dụng trang chủ mặc định.
Chế độ cài đặt tệp kê khai mẫu cho phép các mục sau:
- Trình kích hoạt Lịch eventOpen và eventUpdated cùng hai giải pháp hội nghị Lịch.
- Hai hành động chung.
- Lái xe onItemsSelectedTrigger.
- Một hành động soạn Gmail và trình kích hoạt theo ngữ cảnh.
- Giao diện dành riêng cho tệp trên Tài liệu, Trang tính và Trang trình bày.
Trường oauthScopes đặt phạm vi uỷ quyền cho dự án (Thường bắt buộc đối với các tiện ích bổ sung).
Trường urlFetchWhitelist đặt tiền tố URL loại HTTPS để đảm bảo rằng mọi điểm cuối được tìm nạp đều khớp với tiền tố đó (thường được yêu cầu đối với các tiện ích bổ sung). Để biết thêm thông tin, hãy xem bài viết URL danh sách cho phép.

Các đường liên kết trong mẫu sẽ dẫn trực tiếp đến phần mô tả của trường đó trong tài liệu tham khảo về tệp kê khai.

// Sample configuration of the addOns section in a manifest file:
{
  "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://en.wikipedia.org/wiki/",
        "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"
      }
    },

    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },

    "slides": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
  "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"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ],
}

URL danh sách cho phép

Đôi khi, bạn có thể muốn tập lệnh hoặc tiện ích bổ sung của mình mở URL để phản hồi lại hành động của người dùng. Cũng có lúc bạn muốn tập lệnh hoặc tiện ích bổ sung của mình truy xuất thông tin của một vị trí bên ngoài bằng dịch vụ Apps Script UrlFetch. Trong cả hai trường hợp, bạn phải cho phép các URL mà bạn mở hoặc tìm nạp trong tệp kê khai dự án.

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

Bạn có thể đưa một URL vào danh sách cho phép để tìm nạp bằng cách thêm URL đó hoặc tiền tố phù hợp vào trường tệp kê khai urlFetchWhitelist. Đối với các dự án bổ sung Google Workspace, bạn có thể đưa một URL vào danh sách cho phép để mở bằng cách thêm URL đó hoặc một tiền tố phù hợp vào trường tệp kê khai addOns.common.openLinkUrlPrefixes.

Tiền tố 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 được dùng 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/ hợp lệ nhưng https://www.google.com thì không hợp lệ.
Bạn có thể dùng ký tự đại diện để khớp với các tiền tố miền con của URL.
Bạn có thể sử dụng một ký tự đại diện * trong trường addOns.common.openLinkUrlPrefixes để khớp với tất cả đường liên kết. Tuy nhiên, bạn không nên làm 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 quá 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 tiện ích bổ sung của bạn yêu cầu.

Khi xác định xem một URL có khớp với tiền tố có trong danh sách cho phép hay không, các quy tắc sau sẽ á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ì URL đó phải khớp.
Nếu URL giống hoặc con của tiền tố, thì URL đó phải 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 (*) duy nhất để so khớp với một miền con cho cả trường urlFetchWhitelist và addOns.common.openLinkUrlPrefixes. Bạn không được sử dụng nhiều ký tự đại diện để so khớp với nhiều miền con và ký tự đại diện phải đại diện cho tiền tố hàng đầu 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#39 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ố đượ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ác tiền tố này xuất hiện trong tệp kê khai khi bạn cố gắng lưu:

https://*.*.example.com/foo (nhiều ký tự đại diện bị cấm)
https://subdomain.*.example.com/foo (phải sử dụng ký tự đại diện làm tiền tố hàng đầu)