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

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

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

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

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

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

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

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

  • ส่วน addOns.common ของไฟล์ Manifest จะกำหนดชื่อ, URL ของโลโก้, สี และการตั้งค่าทั่วไปอื่นๆ ที่ไม่ขึ้นอยู่กับโฮสต์สำหรับส่วนเสริม
  • ไฟล์ Manifest ให้คำจำกัดความของหน้าแรกที่ใช้กันทั่วไป แต่ยังรวมถึง ปฏิทิน ไดรฟ์ เอกสาร หน้าแรกสำหรับชีต และสไลด์โดยเฉพาะ Gmail ใช้หน้าแรกเริ่มต้น
  • การตั้งค่าไฟล์ Manifest ตัวอย่างจะเปิดใช้สิ่งต่อไปนี้
  • ช่อง oauthScopes ตั้งค่าขอบเขตการให้สิทธิ์สำหรับโครงการ (โดยทั่วไปแล้วจำเป็นต้องใช้ บริการเสริม)
  • (Apps Script เท่านั้น) ช่อง urlFetchWhitelist เป็นช่องที่ช่วยให้ปลายทางที่ดึงข้อมูลตรงกับรายการส่วนนำหน้า HTTPS URL ที่ระบุ สำหรับข้อมูลเพิ่มเติม โปรดดู URL ในรายการที่อนุญาต

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

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

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

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

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

  • ดึงหรือดึงข้อมูลจากตำแหน่งภายนอก (เช่น HTTPS ปลายทาง) โดยใช้ Apps Script UrlFetch service. หากต้องการเพิ่ม 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 ย่อยของคำนำหน้า แสดงว่าตรงกัน

เช่น Prefix 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 (ต้องใช้ไวลด์การ์ดเป็นคำนำหน้านำหน้า)