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

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

الأهداف

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

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

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

• فعِّل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق من حالة الفوترة لمشاريعك

• تم ضبط Cloud SDK باستخدام مشروع على السحابة الإلكترونية.

إعداد البيئة

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

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

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

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

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

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

1. في Google API Console، انتقِل إلى "القائمة" > منصة Google Auth > العلامة التجارية.

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

2. إذا سبق لك إعداد منصة Google Auth، يمكنك ضبط إعدادات "شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth" التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك الرسالة لم يتم إعداد منصة Google Auth بعد، انقر على البدء:
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" من خلال النقر على فتح الوحدة الطرفية.

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. لتجنُّب تحمّل رسوم مقابل الموارد المستخدَمة في هذا التشغيل السريع، احذف مشروع على السحابة الإلكترونية:

   gcloud projects delete PROJECT_ID
   

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

مواضيع ذات صلة

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

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