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

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

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

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

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

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

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

• للحصول على معلومات حول ملفات البيان الخاصة بالإضافات التي تم إنشاؤها باستخدام نقاط نهاية HTTP، يُرجى الرجوع إلى المرجع 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 الصفحة الرئيسية التلقائية.

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

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

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

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

  • ‫Drive onItemsSelectedTrigger

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

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

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

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

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

• يضبط الحقل oauthScopes نطاقات التفويض للمشروع (ويكون مطلوبًا عادةً للإضافات).

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

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

ملاحظة: تتضمّن بيانات التطبيق مكونات أخرى. ترتبط الحقول ضمن الحقل 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"
      }
    }
  },
  "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"
      }
    }
    "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 في Apps Script. لإضافة عناوين URL إلى القائمة المسموح بها من أجل استرجاع البيانات، أدرِج الحقل urlFetchWhitelist في ملف البيان.
• يفتح عنوان URL أو يعرضه استجابةً لإجراء اتّخذه المستخدم (مطلوب لإضافات Google Workspace التي تفتح عناوين URL أو تعرضها خارج Google). لإضافة عناوين URL إلى القائمة المسموح بها لفتحها، أدرِج الحقل addOns.common.openLinkUrlPrefixes في ملف البيان.

ملاحظة: إنّ القائمة البيضاء، كما هو مستخدَم في urlFetchWhitelist، هو مصطلح قديم ومرادف لمصطلح القائمة المسموح بها وتم استبداله به. لمزيد من المعلومات، يُرجى الاطّلاع على كتابة مستندات شاملة.

إضافة بادئات إلى القائمة المسموح بها

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