ไฟล์ 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เอกสาร ดูข้อมูลเกี่ยวกับทริกเกอร์นี้ได้ที่ดูตัวอย่างลิงก์ด้วยชิปอัจฉริยะ
  • ออบเจ็กต์ createActionTriggers ของเอกสาร หากต้องการเรียนรู้เกี่ยวกับทริกเกอร์นี้ โปรดดูที่สร้างทรัพยากรของบุคคลที่สามจากเมนู @
  • อินเทอร์เฟซเฉพาะไฟล์สำหรับเอกสาร ชีต และสไลด์
• ช่อง oauthScopes จะกำหนดขอบเขตการให้สิทธิ์สำหรับโปรเจ็กต์ (โดยปกติแล้วจำเป็นสำหรับส่วนเสริม)
• (สคริปต์ Apps เท่านั้น) ช่อง 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 หากต้องการเพิ่ม 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 ย่อยของคำนำหน้า แสดงว่าเป็นรายการที่ตรงกัน

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