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

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

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

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

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

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

• ดูข้อมูลเกี่ยวกับไฟล์ Manifest ของ 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 ต่อไปนี้แทนการใช้ไฟล์ Manifest ของส่วนเสริม

• ชื่อ โลโก้ และคำอธิบายของแอป Chat ซึ่งจะปรากฏใน UI ของ Chat เท่านั้น
• ทริกเกอร์ของแอป Chat

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

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

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

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

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

• ส่วน addOns.common ของไฟล์ Manifest จะกำหนดชื่อ, URL ของโลโก้, สี และการตั้งค่าทั่วไปอื่นๆ ที่ไม่ขึ้นอยู่กับโฮสต์สำหรับ ส่วนเสริม

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

• การตั้งค่าไฟล์ Manifest ตัวอย่างช่วยให้ทำสิ่งต่อไปนี้ได้

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

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

  • การดำเนินการสากล 2 รายการ

  • ไดรฟ์ onItemsSelectedTrigger

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

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

  • ออบเจ็กต์ createActionTriggers ของเอกสาร ดูข้อมูลเกี่ยวกับทริกเกอร์นี้ได้ที่สร้างทรัพยากรของบุคคลที่สามจากเมนู @

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

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

• ฟิลด์ oauthScopes จะตั้งค่าขอบเขตการให้สิทธิ์สำหรับโปรเจ็กต์ (โดยปกติแล้วต้องระบุสำหรับส่วนเสริม)

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

ลิงก์ในตัวอย่างไฟล์ Manifest จะเปลี่ยนเส้นทางไปยังคำอธิบายของฟิลด์นั้นใน เอกสารอ้างอิงไฟล์ 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"
      }
    }
    "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

หมายเหตุ: รายการที่อนุญาตพิเศษตามที่ใช้ใน 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 (ต้องใช้ไวลด์การ์ดเป็นตัวอักษรขึ้นต้น)