تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

يتم تنظيم سمات بيان إضافات Google Workspace ضمن قسم addOns من بنية عنصر البيان.

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

ملفات البيان في Google Chat

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

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

اسم تطبيق Chat وشعاره ووصفه، التي تظهر في واجهة مستخدم Chat فقط
عوامل تشغيل تطبيق Chat

إذا أنشأت الإضافة في Apps Script، عليك أيضًا إضافة العناصر التالية أو تعديلها في ملف البيان:

addons.chat (مطلوب)
oauthScopes (مطلوب إذا كان تطبيق Google Chat يستخدم نطاقات OAuth)

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

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

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

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

تنقل الروابط في العيّنة إلى أوصاف هذا الحقل في مستندات مرجع البيان المقابلة لـ Apps Script وHTTP إضافات 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"
      }
    }
  },
  "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"
      }
    }
  },
  "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 معيّنة تمت الموافقة عليها مسبقًا للوصول إليها من خلال النص البرمجي أو الإضافة. تساعد قوائم المسموح بها في حماية data المستخدمين. عند تحديد قائمة مسموح بها، لا يمكن لمشاريع النصوص البرمجية الوصول إلى عناوين 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 (يجب استخدام أحرف البدل كبادئة مقدّمة)