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

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