ملفات بيانات إضافات 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".
  • إجراءان عامان.
  • حساب onItemsSelectedTrigger على Drive.
  • إجراء إنشاء في Gmail ومشغّل سياقي.
  • مستند linkPreviewTrigger في "مستندات Google". للاطّلاع على مزيد من المعلومات عن هذا المشغِّل، اطّلِع على معاينة الروابط باستخدام الشرائح الذكية.
  • واجهات محددة للملفات في "مستندات 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"
      },
      "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) باستخدام خدمة برمجة التطبيقات 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 (يجب استخدام أحرف البدل كبادئة.)