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

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

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

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

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

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

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

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

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

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

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

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

Apps Script

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