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

โปรเจ็กต์ Apps Script ใช้ไฟล์ไฟล์ Manifest เพื่อกำหนดค่ารายละเอียดบางอย่างเกี่ยวกับสคริปต์และการดำเนินการ หากต้องการดูวิธีดูและแก้ไขไฟล์ Manifest โปรดดูไฟล์ Manifest

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

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

ส่วนเสริมของ Google Workspace ใช้ไฟล์ Manifest ของโปรเจ็กต์ Apps Script เพื่อกำหนดลักษณะและการทำงานของส่วนเสริมในหลายๆ ด้าน พร็อพเพอร์ตี้ไฟล์ Manifest สำหรับส่วนเสริมของ Google Workspace จัดระเบียบอยู่ภายใต้ส่วน addOns ของโครงสร้างออบเจ็กต์ไฟล์ Manifest

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

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

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

ลิงก์ในตัวอย่างจะนำไปยังคำอธิบายของช่องดังกล่าวในเอกสารอ้างอิงไฟล์ Manifest

{
  "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://en.wikipedia.org/wiki/",
        "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"
        }
      ]
    },
    "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/"
  ]
}

URL ในรายการที่อนุญาต

คุณใช้รายการที่อนุญาตเพื่อกำหนด URL เฉพาะซึ่งสคริปต์หรือส่วนเสริมได้รับอนุมัติล่วงหน้าให้เข้าถึงได้ รายการที่อนุญาตจะช่วยปกป้องข้อมูลผู้ใช้ เมื่อคุณกำหนดรายการที่อนุญาต โปรเจ็กต์สคริปต์จะเข้าถึง URL ที่ไม่ได้อยู่ในรายการที่อนุญาตไม่ได้

ช่องนี้เป็นช่องที่ไม่บังคับเมื่อคุณติดตั้งการทำให้ใช้งานได้ทดสอบ แต่ต้องระบุเมื่อคุณสร้างการทำให้ใช้งานได้ที่มีเวอร์ชัน

คุณจะใช้รายการที่อนุญาตเมื่อสคริปต์หรือส่วนเสริมดำเนินการต่อไปนี้ได้

  • เรียกหรือดึงข้อมูลจากตำแหน่งภายนอก (เช่น ปลายทาง HTTPS) โดยใช้บริการ Apps Script UrlFetch หากต้องการเพิ่ม 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 ได้
  • ไวลด์การ์ด * รายการเดียวจะใช้ในช่อง 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 (ต้องใช้ไวลด์การ์ดเป็นคำนำหน้าที่นำหน้า)