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

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

// Sample configuration of the addOns section in a manifest file:
{
  "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"
      }
    },

    "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"
  ],
  "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 (ไวลด์การ์ดต้องใช้เป็นคํานําหน้า)