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

// 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"
      },
      "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) โดยใช้บริการ UrlFetch ของ Apps Script หากต้องการเพิ่ม 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 เดียวกันหรือเป็น 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 (ต้องใช้ไวลด์การ์ดเป็นคำนำหน้าที่นำหน้า)