ไฟล์ Manifest สำหรับส่วนเสริมของ Google Workspace

ส่วนเสริมใช้ไฟล์ manifest เพื่อกำหนดค่ารายละเอียดบางอย่างเกี่ยวกับแอปและการทำงานของแอป

เอกสารนี้ครอบคลุมรายละเอียดการกำหนดค่าไฟล์ Manifest สำหรับส่วนเสริมของ Google Workspace

โครงสร้างไฟล์ Manifest สำหรับส่วนเสริมของ Google Workspace

ส่วนเสริมของ Google Workspace ใช้ไฟล์ Manifest เพื่อกำหนดลักษณะที่ปรากฏ และลักษณะการทำงานหลายอย่าง

พร็อพเพอร์ตี้ของไฟล์ Manifest สำหรับส่วนเสริมของ Google Workspace จะจัดระเบียบไว้ในส่วน addOns

  • ดูข้อมูลเกี่ยวกับไฟล์ Manifest ของ Google Apps Script ได้ที่ โครงสร้าง Manifest

  • ดูข้อมูลเกี่ยวกับไฟล์ Manifest สำหรับส่วนเสริมที่สร้างด้วย ปลายทาง HTTP ได้ที่ projects.deployments

ไฟล์ Manifest สำหรับ Google Chat

หากส่วนเสริม Google Workspace ขยาย Google Chat ให้กำหนดค่า Google Chat API ในคอนโซล Google Cloud

ระบบจะละเว้นการตั้งค่าการกำหนดค่าไฟล์ Manifest ทั่วไป (รวมถึง addons.common) ใน Chat ใช้ Chat API เพื่อกำหนดค่าการตั้งค่า Chat ต่อไปนี้ การตั้งค่า Chat:

หากคุณสร้างส่วนเสริมใน Apps Script ให้เพิ่มหรืออัปเดตออบเจ็กต์ต่อไปนี้ในไฟล์ Manifest

  • addons.chat (ต้องระบุ)
  • oauthScopes (ต้องระบุ หากแอป Google Chat ใช้ OAuth)

หากต้องการกำหนดค่าการตั้งค่า Chat สำหรับส่วนเสริม โปรดดูใช้ Google Chat API

ตัวอย่างการกำหนดค่าไฟล์ Manifest ของส่วนเสริม Google Workspace

ตัวอย่างต่อไปนี้แสดงส่วนของไฟล์ Manifest ที่กำหนดส่วนเสริมของ Google Workspace ซึ่งรวมถึงแง่มุมต่อไปนี้

  • addOns.common กำหนดชื่อ โลโก้ สี และการตั้งค่าทั่วไปอื่นๆ สำหรับส่วนเสริม

  • ไฟล์ Manifest จะกำหนดหน้าแรกทั่วไป แต่ยังกำหนดหน้าแรกเฉพาะของ Google ปฏิทิน Google ไดรฟ์, Google เอกสาร, Google ชีต และ Google สไลด์ด้วย Gmail ใช้หน้าแรกเริ่มต้น

  • การตั้งค่าไฟล์ Manifest ตัวอย่างช่วยให้ทำสิ่งต่อไปนี้ได้

  • oauthScopes ฟิลด์จะตั้งค่าขอบเขตการให้สิทธิ์ของโปรเจ็กต์

  • (Apps Script เท่านั้น) urlFetchWhitelist ช่วยให้มั่นใจว่าปลายทางที่ดึงข้อมูลมาจะตรงกับคำนำหน้า HTTPS URL ที่ระบุ ดูURL ในรายการที่อนุญาต

ลิงก์ในตัวอย่างจะเปลี่ยนเส้นทางไปยังคำอธิบายฟิลด์ในข้อมูลอ้างอิง Manifest สำหรับส่วนเสริม Apps Script และ HTTP Google Workspace

ไฟล์ Manifest มีคอมโพเนนต์อื่นๆ ฟิลด์ในส่วน addOns เกี่ยวข้องโดยตรงกับ ส่วนเสริมของ Google Workspace ตัวอย่างนี้แสดงเฉพาะส่วนหนึ่งของไฟล์ Manifest แบบเต็มและ ไม่สามารถใช้งานได้ด้วยตัวเอง

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 ในรายการที่อนุญาต

คุณใช้รายการที่อนุญาตเพื่อกำหนด URL ที่เฉพาะเจาะจงซึ่งได้รับอนุมัติล่วงหน้าสำหรับการเข้าถึง โดยสคริปต์หรือส่วนเสริม รายการที่อนุญาตช่วยปกป้องข้อมูลผู้ใช้ เมื่อคุณกำหนดรายการที่อนุญาต โปรเจ็กต์สคริปต์จะเข้าถึง URL ที่ไม่ได้เพิ่มลงในรายการที่อนุญาตไม่ได้

ฟิลด์นี้ไม่บังคับเมื่อติดตั้งการติดตั้งใช้งานทดสอบ แต่ต้องระบุเมื่อ สร้างการติดตั้งใช้งานที่มีการควบคุมเวอร์ชัน

คุณใช้รายการที่อนุญาตเมื่อสคริปต์หรือส่วนเสริมดำเนินการต่อไปนี้

  • ดึงข้อมูลจากตำแหน่งภายนอก (เช่น ปลายทาง HTTPS) โดยใช้บริการ UrlFetch ของ Apps Script หากต้องการเพิ่ม URL ลงในรายการที่อนุญาตสำหรับการดึงข้อมูล ให้ใส่ช่อง urlFetchWhitelist ในไฟล์ Manifest
  • เปิดหรือแสดง URL เพื่อตอบสนองต่อการกระทําของผู้ใช้ (ต้องระบุสําหรับส่วนเสริมของ Google Workspace ที่เปิดหรือแสดง URL ที่อยู่นอก Google) หากต้องการเพิ่ม URL ในรายการที่อนุญาตสำหรับการเปิด ให้ใส่ฟิลด์ addOns.common.openLinkUrlPrefixes ในไฟล์ Manifest

การเพิ่มคำนำหน้าลงในรายการที่อนุญาต

เมื่อระบุรายการที่อนุญาตในไฟล์ Manifest (โดยรวมฟิลด์ addOns.common.openLinkUrlPrefixes หรือ urlFetchWhitelist) คุณต้อง รวมรายการคำนำหน้า URL คำนำหน้าที่คุณเพิ่มลงในไฟล์ Manifest ต้องเป็นไปตามข้อกำหนดต่อไปนี้

  • คำนำหน้าแต่ละรายการต้องเป็น URL ที่ถูกต้อง
  • คำนำหน้าแต่ละรายการต้องใช้ https:// ไม่ใช่ http://
  • คำนำหน้าแต่ละรายการต้องมีโดเมนแบบเต็ม
  • คำนำหน้าแต่ละรายการต้องมีเส้นทางที่ไม่ว่างเปล่า เช่น https://www.google.com/ ใช้ได้ แต่ https://www.google.com ใช้ไม่ได้
  • คุณสามารถใช้ไวลด์การ์ดเพื่อจับคู่คำนำหน้าโดเมนย่อยของ URL ได้
  • คุณใช้ไวลด์การ์ด * รายการเดียวในฟิลด์ addOns.common.openLinkUrlPrefixes เพื่อจับคู่ลิงก์ทั้งหมดได้ แต่เราไม่แนะนำให้ทำเช่นนี้เนื่องจากอาจทำให้ข้อมูลของผู้ใช้มีความเสี่ยงและอาจทำให้กระบวนการตรวจสอบส่วนเสริมนานขึ้น ใช้ไวลด์การ์ดเฉพาะในกรณีที่ฟังก์ชันการทำงานของส่วนเสริมจำเป็นต้องใช้

เมื่อพิจารณาว่า URL ตรงกับคำนำหน้าในรายการที่อนุญาตหรือไม่ ให้ใช้กฎต่อไปนี้

  • การจับคู่เส้นทางจะคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
  • หากคำนำหน้าเหมือนกับ URL ก็ถือว่าตรงกัน
  • หาก URL เหมือนกันหรือเป็น URL ย่อยของคำนำหน้า จะถือว่าตรงกัน

ตัวอย่างเช่น คำนำหน้า https://example.com/foo จะตรงกับ URL ต่อไปนี้

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

การใช้ไวลด์การ์ด

คุณสามารถใช้อักขระไวลด์การ์ดเดียว (*) เพื่อจับคู่โดเมนย่อยสำหรับทั้งฟิลด์ urlFetchWhitelist และ addOns.common.openLinkUrlPrefixes คุณใช้ไวลด์การ์ดมากกว่า 1 รายการเพื่อจับคู่โดเมนย่อยหลายรายการไม่ได้ และไวลด์การ์ดต้องแสดงคำนำหน้า URL

ตัวอย่างเช่น คำนำหน้า https://*.example.com/foo จะตรงกับ URL ต่อไปนี้

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

คำนำหน้า https://*.example.com/foo ไม่ตรงกับ URL ต่อไปนี้

  • https://subdomain.example.com/bar (คำต่อท้ายไม่ตรงกัน)
  • https://example.com/foo (ต้องมีโดเมนย่อยอย่างน้อย 1 รายการ)

ระบบจะบังคับใช้กฎคำนำหน้าบางอย่างเมื่อคุณพยายามบันทึกไฟล์ Manifest ตัวอย่างเช่น คำนำหน้าต่อไปนี้จะทำให้เกิดข้อผิดพลาดหากอยู่ใน ไฟล์ Manifest เมื่อคุณพยายามบันทึก

  • https://*.*.example.com/foo (ไม่อนุญาตให้ใช้ไวลด์การ์ดหลายรายการ)
  • https://subdomain.*.example.com/foo (ต้องใช้ไวลด์การ์ดเป็นคำนำหน้า)