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

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

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

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

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

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

سمات البيان الخاصة بإضافات Google Workspace هي: ويتم تنظيمه ضمن القسم addOns من بنية كائن البيان.

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

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

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

يحدِّد القسم addOns.common في البيان الاسم وعنوان URL للشعار والألوان وغيرها من الإعدادات العامة وغير المستندة إلى المضيف للمكوّن الإضافي.
يحدِّد البيان صفحة رئيسية مشتركة، ولكنه يحدِّد أيضًا الصفحات الرئيسية الخاصة بكل من "تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google". يستخدم Gmail الصفحة الرئيسية التلقائية.
تتيح إعدادات نموذج البيان ما يلي:
- عوامل تشغيل eventOpen وeventUpdated في التقويم
- (برمجة التطبيقات فقط) تقويمان حلول المؤتمرات.
- إجراءان عامان
- onItemsSelectedTrigger في Drive
- إجراء إنشاء رسالة في Gmail وعامل تشغيل سياقي
- عنصر linkPreviewTriggers في "مستندات Google" للتعرف على هذا المشغل، راجِع معاينة الروابط التي تحتوي على شرائح ذكية.
- عنصر createActionTriggers في "مستندات Google" للتعرف على هذا المشغل، يُرجى الاطّلاع على إنشاء موارد تابعة لجهات خارجية من قائمة @.
- واجهات خاصة بالملفات لتطبيقات "مستندات Google" و"جداول بيانات Google" والعروض التقديمية.
يحدِّد الحقل oauthScopes نطاقات التفويض للمشروع (مطلوب عادةً لإضافة الإضافات).
(برمجة التطبيقات فقط) 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 نقاط النهاية) باستخدام "برمجة تطبيقات 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 هو نفسه البادئة نفسها أو عنصر ثانوي لها، سيكون عنوان 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 (يجب استخدام أحرف البدل كبادئة مقدّمة)