مانیفست‌های برافزاهای Google Workspace

برافزایی از فایل مانیفست برای پیکربندی جزئیات خاصی درباره برنامه و عملکرد آن استفاده می‌کند.

این سند جزئیات پیکربندی مانیفست برای «برافزای Google Workspace» را پوشش می‌دهد.

ساختار مانیفست برای برافزاهای Google Workspace

برافزاهای Google Workspace از فایل مانیفست برای تعریف چندین جنبه از ظاهر و رفتار استفاده می‌کنند.

دارایی‌های مانیفست برای برافزاهای Google Workspace در بخش addOns سازمان‌دهی شده است.

• برای کسب اطلاعات درباره فایل‌های مانیفست Google Apps Script، به ساختار مانیفست مراجعه کنید.

• برای کسب اطلاعات درباره فایل‌های مانیفست برای برافزاهای ساخته‌شده با نقطه‌های پایانی HTTP، به projects.deployments مراجعه کنید.

مانیفست‌های Google Chat

اگر برافزای Google Workspace شما Google Chat را گسترش می‌دهد، «میانای برنامه‌سازی کاربردی Google Chat» را در کنسول Google Cloud پیکربندی کنید.

تنظیمات پیکربندی مانیفست رایج (ازجمله addons.common) در Chat نادیده گرفته می‌شود. از Chat API برای پیکربندی تنظیمات Chat زیر استفاده کنید:

• نام، نشان‌واره، و شرح برنامه Chat برای واسط کاربر Chat.
• برنامه Chat راه‌اندازی می‌کند.

اگر برافزا را در Apps Script ساخته‌اید، اشیای زیر را در مانیفست خود اضافه یا به‌روزرسانی کنید:

• addons.chat (ضروری)
• oauthScopes (درصورتی‌که برنامه Google Chat شما از OAuth استفاده می‌کند، الزامی است)

برای پیکربندی تنظیمات Chat برای برافزا، به استفاده از Google Chat API مراجعه کنید.

پیکربندی مانیفست برافزای Google Workspace نمونه

نمونه‌های زیر بخشی از مانیفستی را نشان می‌دهد که یک برافزای Google Workspace را تعریف می‌کند، ازجمله این جنبه‌ها:

• addOns.common نام، نشان‌واره، رنگ‌ها، و دیگر تنظیمات کلی برافزا را تعریف می‌کند.

• مانیفست صفحه اصلی مشترکی را تعریف می‌کند، اما صفحه‌های اصلی ویژه «تقویم Google»، ‫Google Drive، «سندنگار Google»، «کاربرگ‌نگار Google»، و «اسلایدنگار Google» را نیز تعریف می‌کند. ‫Gmail از صفحه اصلی پیش‌فرض استفاده می‌کند.

• تنظیمات مانیفست نمونه موارد زیر را فعال می‌کند:

  • ‫eventOpen تقویم و eventUpdated راه‌انداز.

  • (فقط Apps Script) دو راهکار کنفرانس «تقویم».

  • دو کنش جهانی.

  • ‫Drive onItemsSelectedTrigger.

  • کنش نوشتن Gmail و راه‌انداز زمینه‌ای.

  • شیء linkPreviewTriggers «سندنگار». پیش‌نمایش پیوندها با تراشه‌های هوشمند را ببینید.

  • شیء createActionTriggers «سندنگار». به ایجاد منابع طرف سوم از منو @ مراجعه کنید.

  • میاناهای مختص فایل برای «سندنگار»، «کاربرگ‌نگار»، و «اسلایدنگار».

  • گزینه Google Meet sidePanelUri و addOnOrigins.

  • (فقط HTTP) دو HttpOptions برای ارسال سرایند مجوز و پشتیبانی از رضایت جزئی.

• فیلد oauthScopes محدوده‌های مجوز پروژه را تنظیم می‌کند.

• (فقط Apps Script) urlFetchWhitelist تضمین می‌کند که نقاط پایانی واکشی‌شده با پیشوندهای نشانی وب HTTPS مشخص‌شده مطابقت داشته باشند. فهرست مجاز نشانی‌های وب را ببینید.

پیوندهای موجود در نمونه‌ها به شرح فیلدها در مرجع مانیفست برای Apps Script و HTTP برافزاهای Google Workspace هدایت می‌شوند.

مانیفست‌ها شامل اجزای دیگر هستند. فیلدهای زیر addOns مستقیماً به برافزاهای Google Workspace مربوط می‌شود. این مثال فقط بخشی از فایل مانیفست کامل را نشان می‌دهد و به‌تنهایی کار نمی‌کند.

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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/logoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
    },
  },
  "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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
      ]
    },
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "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"
  ]
}

نشانی‌های وب فهرست مجازها

از فهرست‌های مجاز برای تعیین نشانی‌های وب خاصی استفاده می‌کنید که ازقبل برای دسترسی توسط افزونه یا نوشتار شما تأیید شده‌اند. فهرست‌های مجاز به محافظت از داده‌های کاربر کمک می‌کنند؛ وقتی فهرست مجاز تعریف می‌کنید، پروژه‌های نوشتاری نمی‌توانند به نشانی‌های وبی که به فهرست مجاز اضافه نشده‌اند دسترسی پیدا کنند.

این فیلد هنگام نصب استقرار آزمایشی اختیاری است، اما هنگام ایجاد استقرار نسخه‌دار الزامی است.

وقتی دستورگان یا برافزای شما کنش‌های زیر را انجام می‌دهد، از فهرست‌های مجاز استفاده می‌کنید:

• بااستفاده از سرویس Apps Script UrlFetch اطلاعات را از مکان خارجی (مثل نقاط پایانی HTTPS) بازیابی یا واکشی می‌کند. برای افزودن نشانی‌های وب به فهرست مجاز برای واکشی، فیلد urlFetchWhitelist را در فایل مانیفست خود اضافه کنید.
• نشانی وبی را در پاسخ به کنش کاربر باز یا نمایش می‌دهد (برای برافزاهای Google Workspace که نشانی‌های وب خارجی از Google را باز یا نمایش می‌دهند الزامی است). برای افزودن نشانی‌های وب به فهرست مجاز برای باز کردن، فیلد addOns.common.openLinkUrlPrefixes را در فایل مانیفست خود اضافه کنید.

توجه: فهرست سفید، همان‌گونه که در urlFetchWhitelist استفاده می‌شود، اصطلاحی منسوخ است که مترادف با فهرست مجاز است و جایگزین آن شده است. برای کسب اطلاعات بیشتر، نوشتن مستندات فراگیر را ببینید.

افزودن پیشوند به فهرست مجاز شما

وقتی فهرست‌های مجاز را در فایل مانیفست خود مشخص می‌کنید (با افزودن فیلد addOns.common.openLinkUrlPrefixes یا urlFetchWhitelist)، باید فهرستی از پیشوندهای نشانی وب را اضافه کنید. پیشوندهایی که به مانیفست اضافه می‌کنید باید الزامات زیر را برآورده کنند:

• هر پیشوند باید نشانی وب معتبری باشد.
• هر پیشوندی باید از https:// استفاده کند، نه http://.
• هر پیشوند باید دامنه کامل داشته باشد.
• هر پیشوندی باید مسیر غیرخالی داشته باشد. برای مثال، https://www.google.com/ معتبر است اما https://www.google.com معتبر نیست.
• می‌توانید از نویسه‌های عام برای مطابقت دادن پیشوندهای زیردامنه نشانی وب استفاده کنید.
• از یک کارت عام * می‌توان در فیلد addOns.common.openLinkUrlPrefixes استفاده کرد تا با همه پیوندها مطابقت پیدا کند، اما این کار توصیه نمی‌شود زیرا می‌تواند داده‌های کاربر را درمعرض خطر قرار دهد و فرایند مرور برافزا را طولانی کند. فقط اگر عملکرد برافزای شما به آن نیاز دارد از کارت جوکر استفاده کنید.

هنگام تعیین اینکه آیا نشانی وب با پیشوندی در فهرست مجاز مطابقت دارد یا نه، قوانین زیر اعمال می‌شود:

• تطابق مسیر حروف‌حساس است.
• اگر پیشوند با نشانی وب یکسان باشد، مطابقت دارد.
• اگر نشانی وب یکسان باشد یا فرزند پیشوند باشد، مطابقت دارد.

برای مثال، پیشوند https://example.com/foo با نشانی‌های وب زیر مطابقت دارد:

• 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 استفاده کنید. نمی‌توانید از بیش‌از یک نویسه عام برای مطابقت با چند زیردامنه استفاده کنید، و نویسه عام باید نشان‌دهنده پیشوند ابتدایی نشانی وب باشد.

برای مثال، پیشوند https://*.example.com/foo با نشانی‌های وب زیر مطابقت دارد:

• https://subdomain.example.com/foo
• https://any.number.of.subdomains.example.com/foo

پیشوند https://*.example.com/foo با نشانی‌های وب زیر مطابقت ندارد:

• ‫https://subdomain.example.com/bar (عدم تطابق پسوند)
• ‫https://example.com/foo (حداقل یک زیردامنه باید وجود داشته باشد)

وقتی می‌خواهید مانیفست خود را ذخیره کنید، برخی‌از قوانین پیشوند اعمال می‌شوند. برای مثال، پیشوندهای زیر درصورت وجود در مانیفست شما هنگام تلاش برای ذخیره کردن باعث بروز خطا می‌شوند:

• ‫https://*.*.example.com/foo (استفاده از چند نویسه عام ممنوع است)
• ‫https://subdomain.*.example.com/foo (کارت‌های جوکر باید به‌عنوان پیشوند پیشرو استفاده شوند)