إنشاء إضافة على Google Workspace باستخدام Node.js

يمكنك إنشاء إضافات Google Workspace في وظائف Cloud Run باستخدام وقت تشغيل Node.js.

الأهداف

  • إعداد البيئة
  • أنشئ دالة Cloud Run ونشرها.
  • أنشئ الإضافة وانشرها.
  • ثبِّت الإضافة.

المتطلبات الأساسية

إعداد البيئة

افتح مشروعك على السحابة الإلكترونية في Google Cloud Console

  1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة اختيار مشروع.

    اختيار مشروع على السحابة الإلكترونية

  2. اختَر مشروع Google Cloud الذي تريد استخدامه. أو انقر على إنشاء مشروع واتّبِع التعليمات الظاهرة على الشاشة. في حال إنشاء مشروع على Google Cloud، قد تحتاج إلى تفعيل الفوترة للمشروع.

إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

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

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > Google Auth platform > العلامة التجارية.

    الانتقال إلى "الهوية البصرية للعلامة التجارية"

  2. إذا سبق لك ضبط Google Auth platform، يمكنك ضبط إعدادات "شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth" التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك الرسالة Google Auth platform لم يتم ضبطه بعد، انقر على البدء:
    1. ضمن معلومات التطبيق، في اسم التطبيق، أدخِل اسمًا للتطبيق.
    2. في البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
    3. انقر على التالي.
    4. ضمن الجمهور، اختَر داخلي.
    5. انقر على التالي.
    6. ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات فيه بشأن أي تغييرات تطرأ على مشروعك.
    7. انقر على التالي.
    8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت توافق عليها، ضَع علامة في المربّع أوافق على "سياسة بيانات المستخدمين في خدمات Google API".
    9. انقر على متابعة.
    10. انقر على إنشاء.
  3. يمكنك حاليًا تخطّي إضافة النطاقات. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسسة Google Workspace، عليك تغيير نوع المستخدم إلى خارجي. بعد ذلك، أضِف نطاقات التفويض التي يتطلّبها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على الدليل الكامل حول ضبط موافقة OAuth.

إنشاء دالة Cloud Run ونشرها

  1. انقر على تفويض لتوفير Cloud Shell والاتصال به.

  2. في "وحدة Cloud Shell الطرفية"، فعِّل واجهة برمجة التطبيقات الخاصة بدوال Cloud Run وواجهة برمجة التطبيقات الخاصة بـ Cloud Build وواجهة برمجة التطبيقات الخاصة بإضافات Google Workspace وواجهة برمجة التطبيقات الخاصة بـ Compute Engine وواجهة برمجة التطبيقات الخاصة بـ Cloud Run:

    gcloud services enable cloudfunctions.googleapis.com  \
                    cloudbuild.googleapis.com  \
                    gsuiteaddons.googleapis.com  \
                    compute.googleapis.com  \
                    run.googleapis.com

  3. شغِّل Cloud Shell Editor من خلال النقر على زر "أداة تعديل الرموز" فتح المحرِّر في شريط أدوات نافذة Cloud Shell.

    يوفّر محرّر الرموز البرمجية المضمّن هذا سهولة عرض الملفات وتعديلها في البيئة نفسها التي يتم فيها إنشاء المشاريع ونشرها.

  4. في الدليل الفارغ، أنشِئ الملف function.js باستخدام نموذج الرمز التالي:

    /**
 * Cloud Run function that loads the homepage for a
 * Google Workspace add-on.
 *
 * @param {Object} req Request sent from Google
 * @param {Object} res Response to send back
 */
exports.loadHomePage = function addonsHomePage (req, res) {
  res.send(createAction());
};

/** Creates a card with two widgets. */
function createAction() {
  return {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "header": {
              "title": "Cats!"
            },
            "sections": [
              {
                "widgets": [
                  {
                    "textParagraph": {
                      "text": "Your random cat:"
                    }
                  },
                  {
                    "image": {
                      "imageUrl": "https://cataas.com/cat"
                     }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  };
}

  5. في الدليل نفسه، أنشئ الملف package.json باستخدام نموذج الرمز التالي:

    {
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

  6. ارجع إلى "وحدة طرفية Cloud Shell" من خلال النقر على زر "تفعيل Cloud Shell" فتح الوحدة الطرفية.

  7. أضِف دور Cloud Build Service Account(roles/cloudbuild.builds.builder) إلى حساب الخدمة التلقائي في Compute Engine.

    أولاً، عليك إعداد إذن حساب الخدمة:

    export PROJECT_ID=$(gcloud config get project)
export SERVICE_ACCOUNT_NAME=$(gcloud compute project-info describe \
  --format="value(defaultServiceAccount)")

    بعد ذلك، امنح إذن حساب الخدمة المطلوب:

    gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/cloudbuild.builds.builder"

  8. شغِّل الأمر التالي لنشر الدالة:

    gcloud run deploy loadHomePage --runtime nodejs22 --trigger-http

    إذا طُلب منك ذلك، حدِّد أنّك لا تسمح باستدعاءات غير مصادَق عليها للدالة. قد يستغرق نشر الدالة بضع دقائق.

إنشاء عملية نشر لإضافة

  1. ابحث عن البريد الإلكتروني لحساب الخدمة الخاص بالإضافة:

    gcloud workspace-add-ons get-authorization

  2. امنح حساب الخدمة دور cloudfunctions.invoker. استبدِل SERVICE_ACCOUNT_EMAIL بالحقل serviceAccountEmail من الخطوة السابقة.

    gcloud run services add-iam-policy-binding loadHomePage \
   --role roles/roles/run.invoker \
   --member serviceAccount:SERVICE_ACCOUNT_EMAIL

  3. احصل على عنوان URL للدالة التي تم نشرها. للحصول على عنوان URL، شغِّل الأمر التالي وابحث عن الحقل url ضمن القسم httpsTrigger:

    gcloud run services describe loadHomePage

  4. ارجع إلى "محرِّر Cloud Shell" من خلال النقر على زر "أداة تعديل الرموز" فتح المحرِّر.

  5. في الدليل نفسه الذي يحتوي على package.json، أنشئ الملف deployment.json باستخدام نموذج الرمز البرمجي التالي. استبدِل URL بـ url للدالة التي تم نشرها من الخطوة السابقة.

    {
  "oauthScopes": ["https://www.googleapis.com/auth/gmail.addons.execute"],
  "addOns": {
    "common": {
      "name": "My HTTP Add-on",
      "logoUrl": "https://raw.githubusercontent.com/webdog/octicons-png/main/black/beaker.png",
      "homepageTrigger": {
        "runFunction": "URL"
      }
    },
    "gmail": {},
    "drive": {},
    "calendar": {},
    "docs": {},
    "sheets": {},
    "slides": {},
    "httpOptions": {
      "granularOauthPermissionSupport": "OPT_IN"
    }
  }
}

  6. ارجع إلى "وحدة Cloud Shell الطرفية" لإنشاء عملية النشر:

    gcloud workspace-add-ons deployments create quickstart \
   --deployment-file=deployment.json

تثبيت الإضافة

  1. ثبِّت عملية النشر في وضع التطوير:

    gcloud workspace-add-ons deployments install quickstart

  2. افتح Gmail أو أعِد تحميله لعرض الإضافة. في شريط الأدوات على اليسار، ابحث عن رمز دورق.

  3. انقر على الرمز لفتح الوظيفة الإضافية. امنح الإذن للإضافة إذا طُلب منك ذلك.

اختياري: التنظيف

لتجنُّب تحمّل رسوم في حسابك، احذف الموارد التي أنشأتها باتّباع الخطوات التالية:

  1. إلغاء تثبيت الإضافة من حسابك على Google:

    gcloud workspace-add-ons deployments uninstall quickstart

  2. لتجنُّب تحمّل رسوم مقابل الموارد المستخدَمة في هذا التشغيل السريع، احذف مشروع Cloud باتّباع الخطوات التالية:

    gcloud projects delete PROJECT_ID

    استبدِل PROJECT_ID بمعرّف مشروع Cloud الذي استخدمته في البدء السريع. يمكنك العثور على معرّف مشروع Cloud في وحدة تحكّم Google Cloud على صفحة "لوحة البيانات".

لإضافة المزيد من الميزات إلى إضافة Google Workspace، يُرجى الرجوع إلى ما يلي: