ไฟล์ 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 เพื่อตอบสนองต่อการดําเนินการของผู้ใช้ ในบางครั้ง คุณอาจต้องการเรียกใช้สคริปต์หรือส่วนเสริมเพื่อดึงข้อมูลจากตําแหน่งภายนอกโดยใช้บริการ Apps Script UrlFetch ในทั้ง 2 กรณี คุณต้องอนุญาต URL ที่เปิดหรือดึงข้อมูลในไฟล์ Manifest ของโปรเจ็กต์

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

คุณอนุญาต URL สําหรับการดึงข้อมูลได้โดยเพิ่ม URL นําหน้าหรือคํานําหน้าในช่อง urlFetchWhitelist ไฟล์ Manifest สําหรับโปรเจ็กต์ Google Workspace ส่วนเสริม คุณสามารถเพิ่ม URL สําหรับเปิด โดยเพิ่ม URL หรือเพิ่มคํานําหน้าลงในช่อง addOns.common.openLinkUrlPrefixes ไฟล์ Manifest

คํานําหน้าที่คุณเพิ่มลงในไฟล์ 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 ไม่'t ตรงกับ URL ต่อไปนี้

  • https://subdomain.example.com/bar (ค่าต่อท้ายไม่ตรงกัน)
  • https://example.com/foo (ต้องมีโดเมนย่อยอย่างน้อย 1 รายการ)

ระบบจะบังคับใช้กฎคํานําหน้าบางส่วนเมื่อคุณพยายามบันทึกไฟล์ Manifest เช่น คํานําหน้าต่อไปนี้จะทําให้เกิดข้อผิดพลาดหากมีอยู่ในไฟล์ Manifest เมื่อพยายามบันทึก

  • https://*.*.example.com/foo (ไม่อนุญาตให้ใช้ไวลด์การ์ดหลายอัน)
  • https://subdomain.*.example.com/foo (ไวลด์การ์ดต้องใช้เป็นคํานําหน้านําหน้า)