با Node.js یک افزونه Google Workspace بسازید

افزونه‌های Google Workspace را در توابع Cloud Run با استفاده از زمان اجرای Node.js ایجاد کنید.

اهداف

• محیط خود را تنظیم کنید.
• یک تابع Cloud Run ایجاد و مستقر کنید.
• افزونه را ایجاد و نصب کنید.
• افزونه را نصب کنید.

پیش‌نیازها

• یک پروژه ابری گوگل .

• مطمئن شوید که صورتحساب را برای پروژه ابری خود فعال کرده‌اید. یاد بگیرید که چگونه وضعیت صورتحساب پروژه‌های خود را تأیید کنید .

• Cloud SDK با پروژه Cloud پیکربندی شده است.

محیط خود را تنظیم کنید

پروژه ابری خود را در کنسول گوگل کلود باز کنید

1. در کنسول گوگل کلود، به صفحه انتخاب پروژه بروید.

   یک پروژه ابری انتخاب کنید

2. پروژه گوگل کلود مورد نظر خود را انتخاب کنید. یا روی ایجاد پروژه کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید. اگر یک پروژه گوگل کلود ایجاد می‌کنید، ممکن است لازم باشد پرداخت هزینه را برای آن پروژه فعال کنید .

صفحه رضایت OAuth را پیکربندی کنید

افزونه‌های Google Workspace نیاز به پیکربندی صفحه رضایت دارند. پیکربندی صفحه رضایت OAuth افزونه شما، آنچه گوگل به کاربران نمایش می‌دهد را تعریف می‌کند.

1. در کنسول گوگل کلود، به menu Menu > برویدGoogle Auth platform > برندسازی .

   به بخش برندسازی بروید

2. اگر قبلاً تنظیمات را انجام داده‌اید Google Auth platformمی‌توانید تنظیمات صفحه رضایت OAuth زیر را در Branding ، Audience و Data Access پیکربندی کنید. اگر پیامی با این مضمون مشاهده کردید Google Auth platform هنوز پیکربندی نشده است ، روی شروع کار کلیک کنید:
1. در قسمت اطلاعات برنامه ، در قسمت نام برنامه ، نامی برای برنامه وارد کنید.
2. در ایمیل پشتیبانی کاربر ، یک آدرس ایمیل پشتیبانی انتخاب کنید که کاربران در صورت داشتن هرگونه سوال در مورد رضایت خود بتوانند با شما تماس بگیرند.
3. روی بعدی کلیک کنید.
4. در قسمت مخاطبان ، داخلی (Internal) را انتخاب کنید.
5. روی بعدی کلیک کنید.
6. در قسمت اطلاعات تماس ، یک آدرس ایمیل وارد کنید که از طریق آن بتوانید از هرگونه تغییر در پروژه خود مطلع شوید.
7. روی بعدی کلیک کنید.
8. در قسمت Finish ، سیاست داده‌های کاربر سرویس‌های API گوگل را مرور کنید و در صورت موافقت، گزینه «من با سیاست‌های داده‌های کاربر سرویس‌های API گوگل موافقم» را انتخاب کنید.
9. روی ادامه کلیک کنید.
10. روی ایجاد کلیک کنید.
3. فعلاً می‌توانید از اضافه کردن محدوده‌ها صرف نظر کنید. در آینده، وقتی برنامه‌ای برای استفاده در خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر (User type) را به خارجی (External) تغییر دهید. سپس محدوده‌های مجوز مورد نیاز برنامه خود را اضافه کنید. برای کسب اطلاعات بیشتر، به راهنمای کامل پیکربندی رضایت OAuth مراجعه کنید.

یک تابع Cloud Run ایجاد و مستقر کنید

1. برای تأمین و اتصال به Cloud Shell، روی Authorize کلیک کنید.

2. در ترمینال Cloud Shell، API توابع Cloud Run، API ساخت Cloud، API افزونه‌های Google Workspace، API موتور محاسبات و API اجرای Cloud را فعال کنید:

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

3. با کلیک کردن، ویرایشگر Cloud Shell را اجرا کنید. ویرایشگر را در نوار ابزار پنجره 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)، دستور زیر را اجرا کنید و در بخش httpsTrigger به دنبال فیلد url بگردید:

   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. برای مشاهده افزونه، جیمیل را باز یا دوباره بارگذاری کنید. در نوار ابزار سمت راست، به دنبال نماد لیوان باشید.

3. برای باز کردن افزونه، روی نماد کلیک کنید. در صورت درخواست، افزونه را تأیید کنید.

اختیاری: تمیز کردن

برای جلوگیری از اعمال هزینه به حسابتان، منابعی را که ایجاد کرده‌اید حذف کنید:

1. افزونه را از حساب گوگل خود حذف کنید:

   gcloud workspace-add-ons deployments uninstall quickstart
   

2. برای جلوگیری از تحمیل هزینه برای منابع استفاده شده در این راهنمای سریع، پروژه Cloud را حذف کنید:

   gcloud projects delete PROJECT_ID
   

   به جای PROJECT_ID شناسه پروژه ابری که برای شروع سریع استفاده کرده‌اید را قرار دهید. می‌توانید شناسه پروژه ابری را در کنسول گوگل کلود در صفحه داشبورد پیدا کنید.

مباحث مرتبط

برای افزودن ویژگی‌های بیشتر به افزونه‌ی Google Workspace خود، به موارد زیر مراجعه کنید:

• ساخت افزونه‌ی Google Workspace با استفاده از نقاط پایانی HTTP
• Codelab: با Node.js و Cloud Run یک افزونه Google Workspace بسازید
• پیش‌نمایش لینک‌ها با تراشه‌های هوشمند