تستخدم إحدى الإضافات ملف بيان لضبط تفاصيل معيّنة حول التطبيق وتشغيله.
تتناول هذه المستندات تفاصيل ضبط بيان لإضافة Google Workspace.
بنية البيان لإضافات Google Workspace
تستخدم إضافات Google Workspace ملف البيان لتحديد العديد من جوانب الإضافات المظهر والسلوك.
سمات البيان الخاصة بإضافات Google Workspace هي:
ويتم تنظيمه ضمن القسم addOns
من بنية كائن البيان.
- للحصول على معلومات حول ملفات بيان "برمجة تطبيقات Google"، يُرجى الاطّلاع على بنية البيان:
- للحصول على معلومات عن ملفات البيان للإضافات التي تم إنشاؤها باستخدام نقاط نهاية HTTP، يُرجى الرجوع إلى مرجع REST:
projects.deployments
.
نموذج لإعدادات بيان إضافة Google Workspace
يعرض نموذج البيان التالي قسم ملف البيان الذي يحدِّد إضافة Google Workspace، بما في ذلك الجوانب التالية:
- يحدِّد القسم
addOns.common
في البيان الاسم وعنوان URL للشعار والألوان وغيرها من الإعدادات العامة وغير المستندة إلى المضيف للمكوّن الإضافي. - يحدِّد البيان صفحة رئيسية مشتركة، ولكنه يحدِّد أيضًا الصفحات الرئيسية الخاصة بكل من "تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google". يستخدم Gmail الصفحة الرئيسية التلقائية.
- تتيح إعدادات نموذج البيان ما يلي:
- عوامل تشغيل
eventOpen
وeventUpdated
في التقويم - (برمجة التطبيقات فقط) تقويمان حلول المؤتمرات.
- إجراءان عامان
onItemsSelectedTrigger
في Drive- إجراء إنشاء رسالة في Gmail وعامل تشغيل سياقي
- عنصر
linkPreviewTriggers
في "مستندات Google" للتعرف على هذا المشغل، راجِع معاينة الروابط التي تحتوي على شرائح ذكية. - عنصر
createActionTriggers
في "مستندات Google" للتعرف على هذا المشغل، يُرجى الاطّلاع على إنشاء موارد تابعة لجهات خارجية من قائمة @. - واجهات خاصة بالملفات لتطبيقات "مستندات Google" و"جداول بيانات Google" والعروض التقديمية.
- عوامل تشغيل
- يحدِّد الحقل
oauthScopes
نطاقات التفويض للمشروع (مطلوب عادةً لإضافة الإضافات). - (برمجة التطبيقات فقط)
urlFetchWhitelist
هو حقل يضمن تطابق أي نقاط نهاية تم جلبها مع قائمة ببادئات عناوين URL التي تستخدم HTTPS لمزيد من المعلومات، يُرجى الاطّلاع على إدراج عناوين URL في القائمة المسموح بها.
تنقل الروابط في العيّنة إلى أوصاف هذا الحقل في مستندات مرجع البيان المقابلة لـ Apps Script وHTTP إضافات Google Workspace.
برمجة تطبيقات
{ "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" } } }, "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 محدّدة تمت الموافقة مسبقًا على الوصول إليها. من خلال النص البرمجي أو الإضافة تساعد القوائم المسموح بها في حماية المستخدمين data; عند تحديد قائمة مسموح بها، لا يمكن لمشاريع النصوص البرمجية الوصول إلى عناوين URL التي تحتوي على لم تتم إضافته إلى القائمة المسموح بها.
يكون هذا الحقل اختياريًا عند تثبيت عملية نشر تجريبية، ولكنه مطلوب عندما في إنشاء عملية نشر ذات إصدارات
يمكنك استخدام القوائم المسموح بها عند تنفيذ النص البرمجي أو الإضافة. الإجراءات التالية:
- استرجاع المعلومات أو استرجاعها من موقع خارجي (مثل HTTPS
نقاط النهاية) باستخدام "برمجة تطبيقات Google"
UrlFetch
خدمة ما. لإضافة عناوين 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 هو نفسه البادئة نفسها أو عنصر ثانوي لها، سيكون عنوان 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
(يجب استخدام أحرف البدل كبادئة مقدّمة)