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

يمكنك إنشاء إضافات Google Workspace في Cloud Functions باستخدام وقت تشغيل Node.js الذي يعمل في Gmail وGoogle Drive و"تقويم Google" و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google".

الأهداف

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

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

إعداد البيئة

افتح مشروعك على السحابة الإلكترونية في 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 Function ونشرها

  1. من "وحدة تحكّم Google Cloud"، انقر على تفعيل Cloud Shell تفعيل زر Cloud Shell.

    تفعيل Cloud Shell

    يتم فتح "وحدة Cloud Shell الطرفية" وبدء جلسة في اللوحة السفلية من Google Cloud Console.

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

  3. في "وحدة Cloud Shell الطرفية"، فعِّل واجهة Cloud Functions API وواجهة Cloud Build API وواجهة Google Workspace add-ons API وواجهة Compute Engine API:

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

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

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

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

    /**
 * Cloud 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"
                     }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  };
}

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

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

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

  8. أضِف دور 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"

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

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

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

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

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

    gcloud workspace-add-ons get-authorization

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

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

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

    gcloud functions 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، يُرجى الرجوع إلى ما يلي: