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