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

Tiện ích bổ sung sử dụng tệp tệp kê khai để định cấu hình một số thông tin nhất định 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 một Tiện ích bổ sung của Google Workspace.

Cấu trúc tệp kê khai cho các 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ủa tiện ích bổ sung.

Thuộc tính tệp kê khai cho Tiện ích bổ sung của Google Workspace là được sắp xếp trong phần addOns của cấu trúc đối tượng tệp kê khai.

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

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

Tệp kê khai mẫu sau đây hiển thị phần của tệp kê khai xác định một 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 chung, độc lập với máy chủ lưu trữ 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 Lịch, Drive, Tài liệu Trang chủ dành riêng cho 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:
  • Trình kích hoạt eventOpen và eventUpdated của Lịch.
  • (Chỉ dành cho Apps Script) Hai giải pháp hội nghị trên Lịch.
  • Hai thao tác chung.
  • Một onItemsSelectedTrigger của Drive.
  • Một hành động soạn thư trên Gmail và điều kiện kích hoạt theo bối cảnh.
  • Đối tượng linkPreviewTriggers của 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.
  • Đối tượng createActionTriggers của 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 Tạo tài nguyên của bên thứ ba từ trình đơn @.
  • 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 đặt phạm vi uỷ quyền cho dự án (Thường bắt buộc đối với tiện ích bổ sung).
• (Chỉ dành cho Apps Script) 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 loại HTTPS. Để biết thêm thông tin, hãy xem URL của danh sách cho phép.

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

Lưu ý: Tệp kê khai bao gồm các thành phần khác. Các trường trong trường addOns liên quan trực tiếp đến Tiện ích bổ sung của Google Workspace. Ví dụ này chỉ là một phần của tệp kê khai đầy đủ và không phải là tệp kê khai có đầy đủ chức năng.

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"
      }
    }
  },
  "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"
      }
    }
  },
  "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 để truy cập bằng tập lệnh hoặc tiện ích bổ sung. Danh sách cho phép giúp bảo vệ dữ liệu của 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 các URL chưa được thêm vào danh sách cho phép.

Trường này là không bắt buộc khi bạn cài đặt một bản triển khai thử nghiệm, nhưng là bắt buộc khi bạn tạo một 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 hoạt động 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 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ị URL để phản hồi hành động của người dùng (Bắt buộc đối với các tiện ích Google Workspace mở hoặc hiển thị URL bên ngoài Google). Để thêm 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.

Lưu ý: Danh sách trắng (như được dùng trong urlFetchWhitelist) là một thuật ngữ không còn được dùng nữa, đồng nghĩa với và được thay thế bằng danh sách cho phép. Để biết thêm thông tin, hãy xem phần Tài liệu hướng dẫn viết dành cho tất cả mọi người.

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

Khi bạn chỉ định danh sách cho phép trong tệp kê khai (bằng cách thêm addOns.common.openLinkUrlPrefixes hoặc urlFetchWhitelist), bạn phải thêm 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 sử dụng https://, chứ 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ó đườ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 con của URL.
• Bạn có thể sử dụng một ký tự đại diện * trong trường addOns.common.openLinkUrlPrefixes để so khớp tất cả đường liên kết, nhưng 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 bổ sung của bạn yêu cầu.

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

• Kiểu 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ì tức là tiền tố đó khớp.
• Nếu URL giống nhau hoặc là phần tử con của tiền tố, thì URL đó 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 miền con cho cả hai urlFetchWhitelist và addOns.common.openLinkUrlPrefixes mới. Bạn không thể sử 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ố đứ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 tiền tố sau URL:

• 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 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 chúng xuất hiện trong khi bạn cố gắng lưu:

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