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

Dự án Apps Script sử dụng một tệp tệp kê khai để định cấu hình một số thông tin chi tiết 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 thông tin 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 về 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 của tệp kê khai.

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

Mẫu tệp kê khai sau đây 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 của biểu trưng, màu sắc và các chế độ cài đặt chung, độc lập với máy chủ lưu trữ khác của 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, 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 những tính năng sau:
    • Các điều kiện kích hoạt lịch eventOpeneventUpdated cùng với 2 giải pháp hội nghị Lịch.
    • Hai hành động chung.
    • Ổ đĩa onItemsSelectedTrigger.
    • Thao tác soạn thư trong Gmail và điều kiện kích hoạt theo ngữ cảnh.
    • linkPreviewTrigger Tài liệu. Để tìm hiểu về điều kiện kích hoạt này, hãy xem bài viết Xem trước đường liên kết bằng khối thông minh.
    • Các giao diện dành riêng cho tệp dành cho Tài liệu, Trang tính và Trang trình bày.
  • Trường oauthScopes thiết lập phạm vi uỷ quyền cho dự án (Thường là bắt buộc đối với tiện ích bổ sung).
  • Trường urlFetchWhitelist là một trường đảm bảo rằng mọi điểm cuối được tìm nạp đều khớp với danh sách tiền tố URL HTTPS đã chỉ định. Để biết thêm thông tin, hãy xem bài viết URL có trong danh sách cho phép.

Các đường liên kết trong mẫu này chuyển hướng đến phần mô tả của trường đó trong tài liệu tham khảo về tệp kê khai.

{
  "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"
      },
      "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"
        }
      ]
    },
    "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",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ]
}

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 tập lệnh hoặc tiện ích bổ sung của bạn phê duyệt trước để 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 không thể truy cập vào các URL chưa có trong danh sách cho phép.

Trường này là trường không bắt buộc khi bạn cài đặt một quá trình triển khai thử nghiệm. Tuy nhiên, trường này bắt buộc phải có khi bạn tạo một phương thức triển khai có nhiều phiên bản.

Bạn sẽ 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 hành động 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ư điểm cuối HTTPS) bằng dịch vụ UrlFetch của Apps Script. Để đưa 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 một hành động của người dùng (Bắt buộc đối với các tiện ích bổ sung của Google Workspace mở hoặc hiển thị 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.

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

Khi chỉ định các danh sách cho phép trong tệp kê khai (bằng cách bao gồm trường addOns.common.openLinkUrlPrefixes hoặc urlFetchWhitelist), bạn phải đưa vào danh sách các 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 dùng https://, không phải http://.
  • Mỗi tiền tố phải có miền đầy đủ.
  • Mỗi tiền tố phải có một đường dẫn không được trống. Ví dụ: https://www.google.com/ là hợp lệ nhưng https://www.google.com không hợp lệ.
  • Bạn có thể sử dụng ký tự đại diện để so khớp các tiền tố miền con URL.
  • Bạn có thể dùng một ký tự đại diện * trong trường addOns.common.openLinkUrlPrefixes để so khớp mọi đường liên kết. Tuy nhiên, bạn không nên làm như vậy vì 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 ký tự đó.

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ẽ áp dụng:

  • Việc 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à kết quả trùng khớp.
  • Nếu URL giống nhau hoặc là con của tiền tố thì URL đó là 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à trường addOns.common.openLinkUrlPrefixes. Bạn không thể 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ố đứ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 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ác tiền tố này có 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 (ký tự đại diện phải được dùng làm tiền tố đứng đầu)