يستخدم مشروع "برمجة تطبيقات Google" ملف بيان لضبط تفاصيل معيّنة حول النص البرمجي وعمله. للتعرّف على كيفية عرض أحد البيانات وتعديله، يُرجى الاطّلاع على ملفات البيان.
ويتناول هذا المستند تفاصيل ضبط ملف البيان لإضافة Google Workspace.
بنية بيان إضافات Google Workspace
تستخدم إضافات Google Workspace ملف بيان مشروع "برمجة تطبيقات Google"
لتحديد جوانب عديدة من
مظهر الإضافة وسلوكها. يتم تنظيم سمات البيان "إضافات Google Workspace" ضمن قسم addOns
من بنية عنصر البيان.
نموذج إعداد بيان إضافة Google Workspace
يعرض نموذج البيان التالي قسم ملف البيان الذي يعرّف إضافات Google Workspace، بما في ذلك الجوانب التالية:
- يحدّد القسم
addOns.common
في البيان الاسم وعنوان URL للشعار والألوان والإعدادات العامة الأخرى المستقلة عن المضيف. - يحدد البيان صفحة رئيسية شائعة، ولكنه يحدد أيضًا الصفحات الرئيسية الخاصة بكل من "تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google". يستخدم Gmail الصفحة الرئيسية التلقائية.
- يتيح نموذج إعدادات البيان ما يلي:
- مشغِّلا التقويم
eventOpen
وeventUpdated
، واثنان من حلول "تقويم Google" لمؤتمرات. - إجراءان عالميان.
- حساب Drive
onItemsSelectedTrigger
. - إجراء إنشاء في Gmail وعامل تشغيل سياقي
- مستند
linkPreviewTrigger
. لمزيد من المعلومات حول هذا المشغِّل، راجِع معاينة الروابط باستخدام الشرائح الذكية. - واجهات خاصة بالملف في "المستندات" و"جداول البيانات" و"العروض التقديمية".
- مشغِّلا التقويم
- يحدد الحقل
oauthScopes
نطاقات التفويض للمشروع (عادةً ما تكون مطلوبة للإضافات). - الحقل
urlFetchWhitelist
هو حقل يضمن أن تتطابق أي نقاط نهاية تم استرجاعها مع قائمة محدّدة من بادئات عناوين URL التي تستخدم HTTPS. لمزيد من المعلومات، يمكنك الاطّلاع على عناوين URL للقائمة المسموح بها.
توجه الروابط الموجودة في النموذج إلى أوصاف هذا الحقل في المستندات المرجعية للبيان.
{ "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://en.wikipedia.org/wiki/", "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" } ] }, "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/" ] }
عناوين URL للقائمة المسموح بها
يمكنك استخدام القوائم المسموح بها لتحديد عناوين URL محدّدة تمت الموافقة مسبقًا على وصولها من خلال النص البرمجي أو الإضافة. تساعد القوائم المسموح بها في حماية بيانات المستخدمين، فعند تحديد قائمة مسموح بها، لا يمكن لمشاريع النصوص البرمجية الوصول إلى عناوين 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 هو نفسه أو عنصر ثانوي للبادئة، يكون العنوان مطابقًا.
على سبيل المثال، تتطابق البادئة 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
(يجب استخدام أحرف البدل كبادئة)