ไฟล์ 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 โดยเปิดใช้และ กำหนดค่า Google Chat API ในคอนโซล Google Cloud

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

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

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

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

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

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

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

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

  • การตั้งค่า Manifest ตัวอย่างจะเปิดใช้สิ่งต่อไปนี้

    • ทริกเกอร์ eventOpen และ eventUpdated ของปฏิทิน

    • (Apps Script เท่านั้น) โซลูชันการประชุม 2 รายการของปฏิทิน

    • การดำเนินการทั่วไป 2 รายการ

    • onItemsSelectedTrigger ของไดรฟ์

    • การดำเนินการเขียน Gmail และทริกเกอร์ตามบริบท

    • ออบเจ็กต์ linkPreviewTriggers ของเอกสาร ดูตัวอย่างลิงก์ด้วยชิปอัจฉริยะ

    • ออบเจ็กต์ createActionTriggers ของเอกสาร ดู สร้างแหล่งข้อมูลของบุคคลที่สามจากเมนู @

    • อินเทอร์เฟซเฉพาะไฟล์สำหรับเอกสาร ชีต และสไลด์

    • ตัวเลือก sidePanelUri และ addOnOrigins ของ Google Meet

    • (HTTP เท่านั้น) HttpOptions 2 รายการสำหรับส่งส่วนหัวการให้สิทธิ์และรองรับการขอความยินยอมแบบละเอียด

  • ช่อง oauthScopes จะกำหนดขอบเขตการให้สิทธิ์ของโปรเจ็กต์

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

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

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