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

تستخدم الإضافة ملف بيان لضبط تفاصيل معيّنة حول التطبيق وطريقة تشغيله.

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

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

تستخدم إضافات Google Workspace ملف البيان لتحديد جوانب متعدّدة من المظهر والسلوك.

يتم تنظيم خصائص البيان لإضافات Google Workspace ضِمن قسم addOns.

  • للحصول على معلومات عن ملفات بيان برمجة تطبيقات Google، يُرجى الرجوع إلى بنية البيان.

  • للحصول على معلومات عن ملفات البيان للإضافات التي تم إنشاؤها باستخدام نقاط نهاية HTTP، يُرجى الرجوع إلى projects.deployments.

بيانات Google Chat

إذا كانت إضافة Google Workspace توسّع نطاق Google Chat، يمكنك ضبط تطبيق Google Chat من خلال تفعيل و ضبط واجهة Google Chat API في Google Cloud Console.

يتم تجاهل إعدادات ضبط البيان الشائعة (بما في ذلك addons.common) في Chat. استخدِم Chat API لضبط إعدادات Chat التالية:

إذا أنشأت الإضافة في برمجة تطبيقات Google، يمكنك إضافة الكائنَين التاليَين أو تعديلهما في بيانك:

لضبط إعدادات Chat لإضافة، يُرجى الاطّلاع على مقالة ضبط تطبيق Google Chat.

مثال على ضبط بيان إضافة Google Workspace

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

  • يحدّد addOns.common الاسم والشعار والألوان والإعدادات العامة الأخرى للإضافة.

  • يحدّد البيان صفحة رئيسية شائعة، ولكنّه يحدّد أيضًا صفحات رئيسية خاصة بكل من "تقويم Google" وGoogle Drive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google". يستخدم Gmail الصفحة الرئيسية التلقائية.

  • تتيح إعدادات البيان النموذجية ما يلي:

    • مُشغّلا eventOpen وeventUpdated في "تقويم Google"

    • (برمجة تطبيقات Google فقط) حلّان للمؤتمرات في "تقويم Google" .

    • إجراءان عامّان

    • مُشغّل onItemsSelectedTrigger في Drive

    • إجراء إنشاء في Gmail ومُشغّل سياقي

    • كائن linkPreviewTriggers في "مستندات Google" يُرجى الاطّلاع على معاينة الروابط باستخدام الشرائح الذكية.

    • كائن createActionTriggers في "مستندات Google" يُرجى الاطّلاع على إنشاء موارد تابعة لجهة خارجية من قائمة @.

    • واجهات خاصة بالملفات في "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google"

    • خيار sidePanelUri وaddOnOrigins في Google Meet

    • (بروتوكول HTTP فقط) خياران HttpOptions لإرسال عنوان التفويض ودعم الموافقة الدقيقة

  • يضبط الحقل oauthScopes نطاقات تفويض المشروع.

  • (برمجة تطبيقات Google فقط) يضمن urlFetchWhitelist تطابُق نقاط النهاية التي يتم جلبها مع بادئات عناوين URL التي تستخدم HTTPS المحدّدة. يُرجى الاطّلاع على إدراج عناوين URL في القائمة المسموح بها.

تعيد الروابط في الأمثلة توجيهك إلى أوصاف الحقول في مرجع البيان لـ برمجة تطبيقات Google و HTTP إضافات Google Workspace.

تتضمّن البيانات مكوّنات أخرى. ترتبط الحقول ضِمن addOns مباشرةً بإضافات Google Workspace. لا يعرض هذا المثال سوى جزء من ملف بيان كامل ولا يمكن استخدامه بمفرده.

برمجة التطبيقات 

{
  "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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/logoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
    },
  },
  "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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
      ]
    },
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "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 في برمجة تطبيقات Google لإدراج عناوين 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 (يجب استخدام أحرف البدل كبادئة رئيسية)