ملفات البيان الخاصة بإضافات 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 التالية:

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

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

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

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

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

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

  • تتيح إعدادات بيان العيّنة ما يلي:

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

    • (برمجة تطبيقات فقط) حلّان لمكالمات الفيديو في التقويم

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

    • ‫Drive onItemsSelectedTrigger

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

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

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

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

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

    • (بروتوكول HTTP فقط) HttpOptions لإرسال عنوان منح الأذونات وإتاحة التحكّم الأدق بالأذونات.

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

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

تعيد الروابط في النماذج التوجيه إلى أوصاف الحقول في مرجع ملف البيان الخاص بإضافات برمجة التطبيقات و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 في برمجة تطبيقات. لإضافة عناوين 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 (يجب استخدام أحرف البدل كبادئة أولى)