ملفات بيانات إضافات Google Workspace

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يستخدم مشروع برمجة التطبيقات ملف manifest لتهيئة تفاصيل معينة حول النص البرمجي وتشغيله. لمعرفة كيفية عرض البيان وتعديله، راجع البيان.

يتناول هذا المستند تفاصيل ضبط ملف بيان لإحدى إضافات Google Workspace.

بنية البيان لإضافات Google Workspace

تستخدم إضافات Google Workspace ملف بيان مشروع برمجة التطبيقات لتحديد عدة جوانب لمظهر الإضافة وسلوكها. يتم تنظيم خصائص البيان لإضافات Google Workspace ضمن قسم addOns في بنية كائن البيان.

نموذج لإعداد بيان إضافة Google Workspace

يعرض نموذج البيان أدناه قسمًا من ملف البيان الذي يحدّد إضافة Google Workspace، بما في ذلك الجوانب التالية:

  • يحدّد قسم addOns.common في البيان الاسم وعنوان URL للشعار والألوان وغيرها من الإعدادات العامة غير المستقلة على المضيف للإضافة.
  • يحدد البيان الصفحة الرئيسية الشائعة، ولكنه يحدد أيضًا الصفحات الرئيسية لكل من التقويم وDrive والمستندات وجداول البيانات والعروض التقديمية. يستخدم Gmail الصفحة الرئيسية الافتراضية.
  • تتيح نماذج إعدادات البيان ما يلي:
    • تقويما eventOpen وeventUpdated، واثنين من حلول مؤتمر التقويم.
    • إجراءان عامان.
    • مساحة تخزين سحابي onItemsSelectedTrigger.
    • عبارة عن إجراء يتم إنشاؤه في Gmail وعامل تشغيل سياقي.
    • الواجهات الخاصة بالملفات في "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google"
  • يحدّد الحقل oauthScopes نطاقات التفويض للمشروع (مطلوب عادةً للإضافات).
  • والحقل urlFetchWhitelist حقل اختياري يضمن تطابق أي نقاط نهاية تم جلبها مع قائمة محدّدة من بادئات عناوين URL التي تستخدم بروتوكول HTTPS. ولمزيد من المعلومات، يمكنك الاطّلاع على عناوين URL المُدرجة في القائمة المسموح بها.

وتوجّه الروابط في النموذج إلى أوصاف هذا الحقل في مستندات مرجعية للبيان.

// Sample configuration of the addOns section in a manifest file:
{
  "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"
      }
    },

    "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"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ],
}

إضافة عناوين 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 مماثلاً أو فرعيًا للبادئة، هذا يعني أنّ العنوان مطابق.

على سبيل المثال، تتطابق البادئة 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 (يجب استخدام أحرف البدل كبادئة قبلية)