تستخدم الإضافة ملف بيان لضبط تفاصيل معيّنة حول التطبيق وطريقة عمله.
تتضمّن هذه المستندات تفاصيل حول كيفية إعداد ملف بيان لإضافة Google Workspace.
بنية ملف البيان لإضافات Google Workspace
تستخدم إضافات Google Workspace ملف البيان لتحديد العديد من جوانب مظهر الإضافة وسلوكها.
يتم تنظيم خصائص ملف البيان لإضافات Google Workspace ضمن القسم addOns
من بنية عنصر ملف البيان.
للحصول على معلومات حول ملفات بيان Apps Script، يُرجى الرجوع إلى بنية البيان.
للحصول على معلومات حول ملفات البيان الخاصة بالإضافات التي تم إنشاؤها باستخدام نقاط نهاية HTTP، يُرجى الرجوع إلى المرجع
projects.deployments
.
ملفات البيان لتطبيق Google Chat
إذا كانت إضافة Google Workspace توسّع نطاق Google Chat، عليك إعداد تطبيق Google Chat من خلال تفعيل واجهة برمجة التطبيقات Google Chat API وإعدادها في Google Cloud Console.
يتم تجاهل إعدادات الضبط الشائعة لملف البيان (بما في ذلك addons.common
) في Chat. بدلاً من استخدام بيان الإضافة، يمكنك استخدام Chat API لضبط إعدادات Chat التالية:
- اسم تطبيق Chat وشعاره ووصفه، التي تظهر فقط في واجهة مستخدم Chat
- مشغّلات تطبيق Chat
إذا أنشأت الإضافة في Apps Script، عليك أيضًا إضافة الكائنات التالية أو تعديلها في ملف البيان:
addons.chat
(مطلوب)oauthScopes
(مطلوب إذا كان تطبيق Google Chat يستخدم نطاقات OAuth)
للاطّلاع على خطوات ضبط إعدادات Chat لإحدى الإضافات، يُرجى الاطّلاع على ضبط تطبيق Google Chat.
مثال على إعداد بيان إضافة Google Workspace
تعرض نماذج ملفات البيان التالية قسمًا من ملف بيان يحدّد إضافة Google Workspace، بما في ذلك الجوانب التالية:
يحدّد القسم
addOns.common
من البيان الاسم وعنوان URL الخاص بالشعار والألوان والإعدادات العامة الأخرى التي لا تعتمد على المضيف للإضافة.يحدّد ملف البيان صفحة رئيسية مشتركة، بالإضافة إلى صفحات رئيسية خاصة بـ "تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google". يستخدم Gmail الصفحة الرئيسية التلقائية.
تتيح إعدادات بيان العيّنة ما يلي:
مشغّلات "تقويم Google"
eventOpen
وeventUpdated
(في "برمجة تطبيقات Google" فقط) حلّان لعقد المؤتمرات في "تقويم Google".
إجراءان عامّان
Drive
onItemsSelectedTrigger
إجراء إنشاء رسالة في Gmail ومشغّل سياقي
كائن
linkPreviewTriggers
في "مستندات Google" لمعرفة المزيد عن هذا المشغّل، اطّلِع على معاينة الروابط باستخدام الشرائح الذكية.عنصر
createActionTriggers
في "مستندات Google" لمعرفة المزيد عن هذا المشغّل، يمكنك الاطّلاع على إنشاء مراجع خارجية من قائمة @.واجهات خاصة بالملفات في "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google"
(بروتوكول HTTP فقط)
HttpOptions
لإرسال عنوان منح الأذونات وإتاحة الموافقة التفصيلية.
يضبط الحقل
oauthScopes
نطاقات التفويض للمشروع (ويكون مطلوبًا عادةً للإضافات).(في Apps Script فقط) الحقل
urlFetchWhitelist
هو حقل يضمن أنّ أي نقاط نهاية يتم جلبها تتطابق مع قائمة محدّدة من بادئات عناوين URL التي تستخدم HTTPS. لمزيد من المعلومات، يُرجى الاطّلاع على إدراج عناوين URL في القائمة المسموح بها.
تعيد الروابط في نماذج ملف البيان التوجيه إلى أوصاف الحقل في مستندات مرجع ملف البيان ذات الصلة لكل من إضافات Google Workspace HTTP و برمجة التطبيقات.
برمجة تطبيقات
{ "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" } } }, "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" } } "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" ] }
عناوين URL في القائمة المسموح بها
تستخدِم قوائم السماح لتحديد عناوين URL معيّنة تمت الموافقة مسبقًا على وصول النص البرمجي أو الإضافة إليها. تساعد قوائم السماح في حماية بيانات المستخدمين، فعند تحديد قائمة سماح، لا يمكن لمشاريع النصوص البرمجية الوصول إلى عناوين URL لم تتم إضافتها إلى قائمة السماح.
هذا الحقل اختياري عند تثبيت إصدار تجريبي، ولكنّه مطلوب عند إنشاء إصدار.
يمكنك استخدام قوائم السماح عندما ينفّذ النص البرمجي أو الإضافة الإجراءات التالية:
- يستردّ المعلومات أو يجلبها من موقع خارجي (مثل نقاط نهاية HTTPS) باستخدام خدمة
UrlFetch
في Apps Script. لإضافة عناوين URL إلى القائمة المسموح بها من أجل استرجاع البيانات، أدرِج الحقلurlFetchWhitelist
في ملف البيان. - يفتح عنوان URL أو يعرضه استجابةً لإجراء اتّخذه المستخدم (مطلوب لإضافات Google Workspace التي تفتح عناوين URL أو تعرضها خارج Google). لإضافة عناوين URL إلى القائمة المسموح بها لفتحها، أدرِج الحقل
addOns.common.openLinkUrlPrefixes
في ملف البيان.
إضافة بادئات إلى القائمة المسموح بها
عند تحديد قوائم السماح في ملف البيان (من خلال تضمين الحقل addOns.common.openLinkUrlPrefixes
أو urlFetchWhitelist
)، يجب تضمين قائمة ببادئات عناوين URL. يجب أن تستوفي البادئات التي تضيفها إلى البيان المتطلبات التالية:
- يجب أن تكون كل بادئة عنوان URL صالحًا.
- يجب أن تستخدم كل بادئة
https://
، وليسhttp://
. - يجب أن تتضمّن كل بادئة نطاقًا كاملاً.
- يجب أن يحتوي كل بادئة على مسار غير فارغ. على سبيل المثال،
https://www.google.com/
صالح ولكنhttps://www.google.com
غير صالح. - يمكنك استخدام أحرف البدل لمطابقة بادئات النطاقات الفرعية لعناوين URL.
- يمكن استخدام حرف بدل
*
واحد في الحقلaddOns.common.openLinkUrlPrefixes
لمطابقة جميع الروابط، ولكن لا يُنصح بذلك لأنّه قد يعرّض بيانات المستخدم للخطر ويؤدي إلى إطالة عملية مراجعة الإضافة. لا تستخدِم حرف البدل إلا إذا كانت وظيفة الإضافة تتطلّب ذلك.
عند تحديد ما إذا كان عنوان 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
. لا يمكنك استخدام أكثر من حرف بدل واحد لمطابقة نطاقات فرعية متعددة، ويجب أن يمثّل حرف البدل البادئة الرئيسية لعنوان 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
(يجب توفير نطاق فرعي واحد على الأقل)
يتم فرض بعض قواعد البادئة عند محاولة حفظ ملف البيان. على سبيل المثال، تتسبّب البادئات التالية في حدوث خطأ إذا كانت مضمّنة في ملف البيان عند محاولة الحفظ:
https://*.*.example.com/foo
(لا يُسمح بأحرف بدل متعدّدة)https://subdomain.*.example.com/foo
(يجب استخدام أحرف البدل كبادئة أولى)