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

เวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์: มีให้ใช้งานในโปรแกรมเวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ของ Google Workspace ซึ่งให้สิทธิ์ทดลองใช้ฟีเจอร์บางอย่างก่อนเปิดตัว

หากส่วนเสริม 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 ของ 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) โดยใช้บริการ 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 ได้
• คุณสามารถใช้ไวลด์การ์ด * 1 ตัวในช่อง 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 (ต้องใช้ไวลด์การ์ดเป็นคำนำหน้า)