بيانات إضافات 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 الصفحة الرئيسية التلقائية.
  • تتيح نماذج إعدادات البيان ما يلي:
  • الحقل oauthScopes تحدد نطاقات التفويض للمشروع (عادةً ما يكون ذلك مطلوبًا والإضافات).
  • (برمجة التطبيقات فقط) urlFetchWhitelist هو حقل يضمن تطابق أي نقاط نهاية تم جلبها مع قائمة ببادئات عناوين URL التي تستخدم HTTPS لمزيد من المعلومات، يُرجى مراجعة إضافة عناوين URL إلى القائمة المسموح بها

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