ไฟล์ 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

ไฟล์ 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 ได้
  • คุณใช้*ไวลด์การ์ด 1 ตัวในช่อง 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 (ต้องใช้ไวลด์การ์ดเป็นตัวอักษรขึ้นต้น)