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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

أنشئ إضافة على Google Workspace في Cloud Functions باستخدام وقت تشغيل Node.js.

.

الأهداف

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

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

• مشروع على Google Cloud

• تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تعرَّف على كيفية التحقّق من حالة الفوترة لمشاريعك.

• تم ضبط حزمة تطوير برامج Cloud مع مشروع Cloud.

إعداد البيئة

فتح مشروعك على Cloud في Google Cloud Console

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

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

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

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

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

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

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

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

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

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

   تفعيل Cloud Shell

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

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

3. في Cloud Shell Terminal، فعِّل 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 بالنقر على فتح المحرِّر في toolbar (شريط الأدوات) في نافذة 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 الطرفية من خلال النقر على فتح وحدة الطرفية.

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": {}
     }
   }
   

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

• إنشاء إضافة في Google Workspace باستخدام نقاط نهاية HTTP
• Codelab: إنشاء إضافة Google Workspace باستخدام Node.js وCloud Run
• معاينة الروابط باستخدام الشرائح الذكية