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

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

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

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

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

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

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

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

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

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

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

หมายเหตุ: ไฟล์ Manifest จะมีคอมโพเนนต์อื่นๆ รวมอยู่ด้วย ช่องต่างๆ ใต้ช่อง addOns เกี่ยวข้องกับส่วนเสริมของ Google Workspace โดยตรง ตัวอย่างนี้เป็นเพียงส่วนหนึ่งของไฟล์ Manifest แบบเต็มและไม่ใช่ไฟล์ 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"
      }
    }
  },
  "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

หมายเหตุ: รายการที่อนุญาตตามที่ใช้ใน urlFetchWhitelist เป็นคําที่เลิกใช้งานแล้วซึ่งมีความหมายเหมือนกับรายการที่อนุญาต ดูข้อมูลเพิ่มเติมได้ที่การเขียนเอกสารที่ครอบคลุม

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

เมื่อคุณระบุรายการที่อนุญาตในไฟล์ 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 (ต้องใช้ไวลด์การ์ดเป็นคำนำหน้านำหน้า)