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