یک اشتراک Google Workspace ایجاد کنید

این صفحه نحوه استفاده از API رویدادهای Google Workspace را برای ایجاد اشتراک در یک منبع Google Workspace توضیح می‌دهد. اشتراک Google Workspace به برنامه شما اجازه می‌دهد تا اطلاعاتی در مورد رویدادهای Google Workspace دریافت کند، که نشان‌دهنده تغییرات در یک منبع Google Workspace است. برای کسب اطلاعات در مورد اینکه API رویدادهای Google Workspace از کدام منابع و انواع رویدادها پشتیبانی می‌کند، به نمای کلی API رویدادهای Google Workspace مراجعه کنید.

این صفحه شامل مراحل زیر برای ایجاد اشتراک Google Workspace است:

  1. محیط خود را تنظیم کنید.
  2. یک موضوع Pub/Sub در Google Cloud ایجاد و در آن مشترک شوید. شما از این موضوع به عنوان نقطه پایانی برای دریافت رویدادهای Google Workspace استفاده می‌کنید.
  3. متد create از API رویدادهای فضای کاری گوگل (Google Workspace Events API) را روی منبع Subscription فراخوانی کنید.
  4. اشتراک Google Workspace خود را آزمایش کنید تا مطمئن شوید موضوع Pub/Sub شما رویدادهایی را که در آنها مشترک شده‌اید، دریافت می‌کند.
  5. به صورت اختیاری، می‌توانید نحوه‌ی ارسال رویدادها به یک نقطه‌ی پایانی برای برنامه‌ی خود را پیکربندی کنید تا برنامه بتواند رویداد را پردازش کند و در صورت لزوم، اقدامی انجام دهد.

پیش‌نیازها

اسکریپت برنامه‌ها

  • یک پروژه اسکریپت برنامه‌ها:
    • به جای پروژه پیش‌فرضی که به طور خودکار توسط Apps Script ایجاد شده است، از پروژه Google Cloud خود استفاده کنید.
    • برای تمام محدوده‌هایی که برای پیکربندی صفحه رضایت OAuth اضافه کرده‌اید، باید محدوده‌ها را به فایل appsscript.json در پروژه Apps Script خود نیز اضافه کنید. برای مثال، اگر محدوده chat.messages را مشخص کرده‌اید، موارد زیر را اضافه کنید: 
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages"
]
    • سرویس پیشرفته Google Workspace Events را فعال کنید .

پایتون

  • پایتون ۳.۶ یا بالاتر
  • ابزار مدیریت بسته pip
  • جدیدترین کتابخانه‌های کلاینت گوگل برای پایتون. برای نصب یا به‌روزرسانی آنها، دستور زیر را در رابط خط فرمان خود اجرا کنید: 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib

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

بخش بعدی نحوه تنظیم محیط شما قبل از ایجاد اشتراک Google Workspace را توضیح می‌دهد.

فعال کردن API رویدادهای Google Workspace و Google Cloud Pub/Sub API

قبل از استفاده از APIهای گوگل، باید آنها را در یک پروژه گوگل کلود فعال کنید. می‌توانید یک یا چند API را در یک پروژه گوگل کلود فعال کنید.

کنسول گوگل کلود

در کنسول Google Cloud، پروژه Google Cloud مربوط به برنامه خود را باز کنید و API رویدادهای Google Workspace و Pub/Sub را فعال کنید:

فعال کردن APIها

جی‌کلاود

  1. در دایرکتوری کاری خود، به حساب گوگل خود وارد شوید:

    gcloud auth login

  2. پروژه خود را برای برنامه خود روی پروژه Cloud تنظیم کنید:

    gcloud config set project PROJECT_ID

    به جای PROJECT_ID ، شناسه پروژه مربوط به پروژه ابری برنامه خود را وارد کنید.

  3. فعال کردن API رویدادهای Google Workspace و Google Cloud Pub/Sub API:

    gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

ایجاد اعتبارنامه‌های شناسه کلاینت OAuth

برای دستورالعمل‌های خاص در مورد نحوه ایجاد شناسه کلاینت OAuth ، نوع برنامه خود را انتخاب کنید:

برنامه وب

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

    به بخش مشتریان بروید

  2. روی ایجاد کلاینت کلیک کنید.
  3. روی نوع برنامه > برنامه وب کلیک کنید.
  4. در فیلد نام ، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نمایش داده می‌شود.
  5. URI های مجاز مربوط به برنامه خود را اضافه کنید:
    • برنامه‌های سمت کلاینت (جاوااسکریپت) – در قسمت Authorized JavaScript origins ، روی Add URI کلیک کنید. سپس، یک URI برای استفاده در درخواست‌های مرورگر وارد کنید. این دامنه‌هایی را که برنامه شما می‌تواند از آنها درخواست‌های API را به سرور OAuth 2.0 ارسال کند، مشخص می‌کند.
    • برنامه‌های سمت سرور (جاوا، پایتون و موارد دیگر) – در زیر Authorized redirect URIs ، روی Add URI کلیک کنید. سپس، یک URI نقطه پایانی که سرور OAuth 2.0 می‌تواند به آن پاسخ ارسال کند را وارد کنید.
  6. روی ایجاد کلیک کنید.

    اعتبارنامه‌ی تازه ایجاد شده در زیر شناسه‌های کلاینت OAuth 2.0 ظاهر می‌شود.

    به شناسه کلاینت توجه کنید. از رمزهای کلاینت برای برنامه‌های وب استفاده نمی‌شود.

اندروید

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

    به بخش مشتریان بروید

  2. روی ایجاد کلاینت کلیک کنید.
  3. روی نوع برنامه > اندروید کلیک کنید.
  4. در فیلد «نام»، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نمایش داده می‌شود.
  5. در فیلد "Package name"، نام بسته را از فایل AndroidManifest.xml خود وارد کنید.
  6. در فیلد «اثر انگشت گواهی SHA-1»، اثر انگشت گواهی SHA-1 تولید شده خود را وارد کنید.
  7. روی ایجاد کلیک کنید.

    اعتبارنامه‌ی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر می‌شود.

آی‌او‌اس

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

    به بخش مشتریان بروید

  2. روی ایجاد کلاینت کلیک کنید.
  3. روی نوع برنامه > iOS کلیک کنید.
  4. در فیلد «نام»، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نمایش داده می‌شود.
  5. در فیلد «شناسه بسته»، شناسه بسته را مطابق با آنچه در فایل Info.plist برنامه ذکر شده است، وارد کنید.
  6. اختیاری: اگر برنامه شما در فروشگاه اپل اپ استور (Apple App Store) نمایش داده می‌شود، شناسه فروشگاه اپ (App Store ID) را وارد کنید.
  7. اختیاری: در فیلد «شناسه تیم»، رشته ۱۰ کاراکتری منحصر به فردی را که توسط اپل تولید شده و به تیم شما اختصاص داده شده است، وارد کنید.
  8. روی ایجاد کلیک کنید.

    اعتبارنامه‌ی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر می‌شود.

برنامه کروم

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

    به بخش مشتریان بروید

  2. روی ایجاد کلاینت کلیک کنید.
  3. روی نوع برنامه > افزونه کروم کلیک کنید.
  4. در فیلد «نام»، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نمایش داده می‌شود.
  5. در فیلد «شناسه کالا»، رشته شناسه ۳۲ کاراکتری منحصر به فرد برنامه خود را وارد کنید. می‌توانید این مقدار شناسه را در نشانی اینترنتی فروشگاه وب کروم برنامه خود و در داشبورد توسعه‌دهندگان فروشگاه وب کروم پیدا کنید.
  6. روی ایجاد کلیک کنید.

    اعتبارنامه‌ی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر می‌شود.

برنامه دسکتاپ

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

    به بخش مشتریان بروید

  2. روی ایجاد کلاینت کلیک کنید.
  3. روی نوع برنامه > برنامه دسکتاپ کلیک کنید.
  4. در فیلد نام ، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نمایش داده می‌شود.
  5. روی ایجاد کلیک کنید.

    اعتبارنامه‌ی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر می‌شود.

تلویزیون‌ها و دستگاه‌های ورودی محدود

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

    به بخش مشتریان بروید

  2. روی ایجاد کلاینت کلیک کنید.
  3. روی نوع برنامه > تلویزیون‌ها و دستگاه‌های ورودی محدود کلیک کنید.
  4. در فیلد «نام»، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نمایش داده می‌شود.
  5. روی ایجاد کلیک کنید.

    اعتبارنامه‌ی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر می‌شود.

پلتفرم جهانی ویندوز (UWP)

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

    به بخش مشتریان بروید

  2. روی ایجاد کلاینت کلیک کنید.
  3. روی نوع برنامه > پلتفرم جهانی ویندوز (UWP) کلیک کنید.
  4. در فیلد «نام»، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نمایش داده می‌شود.
  5. در فیلد «شناسه فروشگاه»، مقدار منحصر به فرد ۱۲ کاراکتری شناسه فروشگاه مایکروسافت برنامه خود را وارد کنید. می‌توانید این شناسه را در آدرس اینترنتی فروشگاه مایکروسافت برنامه خود و در مرکز شرکا پیدا کنید.
  6. روی ایجاد کلیک کنید.

    اعتبارنامه‌ی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر می‌شود.

فایل JSON مخفی کلاینت را دانلود کنید

فایل مخفی کلاینت، یک نمایش JSON از اعتبارنامه‌های شناسه کلاینت OAuth است که برنامه شما می‌تواند هنگام ارائه اعتبارنامه‌ها به آن ارجاع دهد.

  1. در کنسول گوگل کلود، به Menu > APIs & Services > Credentials بروید.

    به اعتبارنامه‌ها بروید

  2. در زیر شناسه‌های کلاینت OAuth 2.0 ، روی شناسه کلاینتی که ایجاد کرده‌اید کلیک کنید.

  3. روی دانلود JSON کلیک کنید.

  4. فایل را با نام credentials.json ذخیره کنید.

ایجاد و عضویت در یک موضوع Pub/Sub

در این بخش، شما یک موضوع انتشار/زیرموضوع ایجاد می‌کنید و در آن موضوع مشترک می‌شوید. موضوع انتشار/زیرموضوع شما به عنوان نقطه پایانی اعلان عمل می‌کند که در آن اشتراک Google Workspace شما رویدادها را دریافت می‌کند.

برای کسب اطلاعات بیشتر در مورد ایجاد و مدیریت موضوعات Pub/Sub، به مستندات Pub/Sub مراجعه کنید.

برای ایجاد و عضویت در یک موضوع Pub/Sub:

کنسول گوگل کلود

  1. در کنسول گوگل کلود، به صفحه Pub/Sub بروید:

    به Google Cloud Pub/Sub بروید

    مطمئن شوید که پروژه ابری برای برنامه شما انتخاب شده است.

  2. روی کلیک کنید و موضوع را ایجاد کنید و موارد زیر را انجام دهید:

    1. یک نام برای موضوع خود وارد کنید، مانند workspace-events-topic .
    2. گزینه «افزودن یک اشتراک پیش‌فرض» را انتخاب شده باقی بگذارید. نام این اشتراک پیش‌فرض در Pub/Sub مشابه نام موضوع شما است، مانند workspace-events-topic-sub .
    3. اختیاری: ویژگی‌های اضافی را برای موضوع خود به‌روزرسانی یا پیکربندی کنید.

  3. روی ایجاد کلیک کنید. نام کامل موضوع شما به صورت projects/ PROJECT_ID /topics/ TOPIC_ID قالب‌بندی می‌شود. شما از این نام کامل در مرحله بعد استفاده خواهید کرد.

  4. دسترسی انتشار پیام‌های Pub/Sub را به موضوع خود اعطا کنید:

    1. در صفحه موضوع خود، به پنل کناری بروید و برگه مجوزها را باز کنید.
    2. روی افزودن مدیر اصلی کلیک کنید.
    3. در فیلد «افزودن مدیران» ، حساب سرویس مربوط به برنامه Google Workspace که رویدادها را به اشتراک شما ارائه می‌دهد، اضافه کنید:
      1. برای رویدادهای چت، chat-api-push@system.gserviceaccount.com .
      2. پیش‌نمایش توسعه‌دهنده: : برای رویدادهای درایو، drive-api-event-push@system.gserviceaccount.com .
      3. برای رویدادهای Meet، meet-api-event-push@system.gserviceaccount.com .
    4. در منوی «اختصاص نقش‌ها» ، Pub/Sub Publisher را انتخاب کنید.
    5. روی ذخیره کلیک کنید. به‌روزرسانی مجوزهای موضوع شما ممکن است چند دقیقه طول بکشد.

جی‌کلاود

  1. در پروژه ابری خود، با اجرای دستور زیر یک تاپیک ایجاد کنید:

    gcloud pubsub topics create TOPIC_ID

    به جای TOPIC_ID ، یک شناسه منحصر به فرد برای موضوع خود، مانند workspace-events-topic قرار دهید.

    خروجی، نام کامل موضوع را که به صورت projects/ PROJECT_ID /topics/ TOPIC_ID قالب‌بندی شده است، نمایش می‌دهد. نام را یادداشت کنید و مطمئن شوید که مقدار PROJECT_ID ، شناسه پروژه ابری برای برنامه شما باشد. شما از نام موضوع در مرحله بعدی و برای ایجاد اشتراک Google Workspace بعداً استفاده می‌کنید.

  2. دسترسی انتشار پیام‌ها در موضوع خود را اعطا کنید:

    gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

    موارد زیر را جایگزین کنید:

    • TOPIC_NAME : نام کامل موضوع که خروجی مرحله قبل است. با فرمت projects/ PROJECT_ID /topics/ TOPIC_ID .

    • GOOGLE_WORKSPACE_APPLICATION : برنامه Google Workspace که باید رویدادها را به اشتراک شما ارسال کند:

      • برای دریافت رویدادها از چت، chat-api-push@system.gserviceaccount.com استفاده کنید.
      • پیش‌نمایش توسعه‌دهنده: برای دریافت رویدادها از Drive، drive-api-event-push@system.gserviceaccount.com استفاده کنید.
      • برای دریافت رویدادها از Meet، meet-api-event-push@system.gserviceaccount.com استفاده کنید.

    به‌روزرسانی مجوزهای موضوع شما ممکن است چند دقیقه طول بکشد.

  3. برای موضوع مورد نظر، یک اشتراک Pub/Sub ایجاد کنید: 

     gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

    موارد زیر را جایگزین کنید:

    • SUBSCRIPTION_NAME : نامی برای اشتراک شما، مانند workspace-events-subscription .
    • TOPIC_NAME : نام موضوعی که در مرحله قبل ایجاد کردید.

مشترک شدن در یک منبع Google Workspace

در این بخش، شما در منبع Google Workspace که می‌خواهید رویدادها را رصد کنید، مشترک می‌شوید.

انتخاب و شناسایی منبع هدف

در اشتراک Google Workspace، منبع هدف ، منبع Google Workspace است که شما رویدادها را رصد می‌کنید. منبع هدف در فیلد targetResource اشتراک نمایش داده می‌شود و با استفاده از نام کامل منبع قالب‌بندی شده است. برای مثال، برای اشتراکی که یک فضای Google Chat ( spaces/AAAABBBBBBB ) را رصد می‌کند، مقدار targetResource برابر است با //chat.googleapis.com/spaces/AAAABBBBBBB .

یک منبع هدف برای چت مشخص کنید

منبع هدف قالب محدودیت‌ها
فضا

//chat.googleapis.com/spaces/ SPACE

که در آن SPACE شناسه در نام منبع مربوط به منبع space Chat API است. می‌توانید شناسه را از URL فضا یا با استفاده از متد spaces.list() به دست آورید.

 کاربر چت یا برنامه چتی که اشتراک را تأیید می‌کند، باید از طریق Google Workspace یا حساب گوگل خود عضو این فضا باشد. پشتیبانی می‌کند از:
تمام فضاهای یک کاربر

//chat.googleapis.com/spaces/-

 این اشتراک فقط رویدادهای مربوط به فضاهایی را دریافت می‌کند که کاربر از طریق Google Workspace یا حساب Google خود در آنها عضو است. فقط از احراز هویت کاربر پشتیبانی می‌کند.
کاربر

//cloudidentity.googleapis.com/users/ USER

که در آن USER شناسه در نام منبع مربوط به منبع user Chat API است. برای جزئیات بیشتر، به بخش شناسایی و تعیین کاربران Google Chat مراجعه کنید.

این اشتراک فقط رویدادهای مربوط به کاربری که اشتراک را تأیید کرده است را دریافت می‌کند. یک کاربر نمی‌تواند از طرف سایر کاربران اشتراک را تأیید کند. فقط از احراز هویت کاربر پشتیبانی می‌کند.

یک منبع هدف برای Drive شناسایی کنید

منبع هدف قالب محدودیت‌ها (در صورت وجود)
فایل //drive.googleapis.com/files/ FILE

که در آن FILE شناسه‌ی نام منبع files API درایو است. می‌توانید شناسه را از آدرس اینترنتی فایل یا با استفاده از متد files.list به دست آورید.

 کاربری که اشتراک را تأیید می‌کند، باید مجوز دسترسی به فایل درون اشتراک را متناسب با رویداد «اشتراک در» داشته باشد.
درایو مشترک //drive.googleapis.com/drives/ DRIVE

که در آن DRIVE شناسه در نام منبع مربوط به منبع drives از API drives است. می‌توانید شناسه را از URL درایو یا با استفاده از متد drives.list به دست آورید.

 این اشتراک فقط رویدادهای مربوط به موارد موجود در درایو مشترکی را دریافت می‌کند که کاربر از طریق حساب Google Workspace یا حساب Google خود در آن عضو است.

یک منبع هدف برای Meet شناسایی کنید

منبع هدف قالب محدودیت‌ها (در صورت وجود)
فضای جلسات //meet.googleapis.com/spaces/ SPACE

که در آن SPACE شناسه در نام منبع مربوط به منبع spaces Meet REST API است. برای جزئیات بیشتر، به نحوه شناسایی فضای جلسه توسط Meet مراجعه کنید.

کاربر //cloudidentity.googleapis.com/users/ USER

که در آن USER شناسه موجود در فیلد signedinUser.user از منبع participants Meet REST API است. برای جزئیات بیشتر، به Work with participants مراجعه کنید.

این اشتراک، رویدادهای مربوط به تمام فضاهای جلسه‌ای که کاربر مالک آن فضا است را دریافت می‌کند. معمولاً، مالک فضای جلسه، برگزارکننده رویداد تقویم گوگل مرتبط با آن فضای جلسه نیز هست.

ایجاد اشتراک Google Workspace

برای ایجاد یک اشتراک، از متد subscriptions.create از API رویدادهای Google Workspace برای ایجاد یک منبع Subscription استفاده می‌کنید. فیلدهای زیر را مشخص می‌کنید:

  • targetResource : یک فضای کاری گوگل که در بخش قبل شناسایی کردید و با استفاده از نام کامل منبع قالب‌بندی شده است.
  • eventTypes : آرایه‌ای از یک یا چند نوع رویداد که می‌خواهید در مورد منبع دریافت کنید. برای مثال، اگر برنامه شما فقط نیاز به دانستن پیام‌های جدید ارسال شده به فضای چت دارد، برنامه شما می‌تواند فقط در رویدادهای مربوط به پیام‌های ایجاد شده مشترک شود.
  • notificationEndpoint : یک نقطه پایانی اعلان که در آن اشتراک Google Workspace شما رویدادها را ارائه می‌دهد. شما از موضوع Pub/Sub که در بخش قبلی ایجاد کردید استفاده می‌کنید.
  • payloadOptions : گزینه‌هایی برای مشخص کردن میزان داده‌های منبع که باید در payload رویداد گنجانده شوند. این پیکربندی بر زمان انقضای اشتراک شما تأثیر می‌گذارد. برای کسب اطلاعات بیشتر، به Event data مراجعه کنید.

برای ایجاد اشتراک Google Workspace:

اسکریپت برنامه‌ها

  1. در پروژه Apps Script خود، یک فایل اسکریپت جدید با نام createSubscription ایجاد کنید و کد زیر را به آن اضافه کنید: 

    function createSubscription() {
  // The Google Workspace resource to monitor for events.
  const targetResource = 'TARGET_RESOURCE';

  // The types of events to receive.
  const eventTypes = [EVENT_TYPES];

  // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  const pubsubTopic = 'TOPIC_NAME';

  // Whether to include resource data or not.
  const resourceData = RESOURCE_DATA;

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.create({
    targetResource: targetResource,
    eventTypes: eventTypes,
    notificationEndpoint: {
      pubsubTopic: pubsubTopic,
    },
    payloadOptions: {
      includeResource: resourceData
    }
  });
  console.log(response);
}

    موارد زیر را جایگزین کنید:

    • TARGET_RESOURCE : منبع Google Workspace که در آن مشترک می‌شوید، به صورت نام کامل منبع قالب‌بندی شده است. برای مثال، برای مشترک شدن در یک فضای Google Chat با شناسه فضای AAAABBBB ، از //chat.googleapis.com/spaces/AAAABBBB استفاده کنید.
    • EVENT_TYPES : یک یا چند نوع رویداد که می‌خواهید در منبع هدف در آن‌ها مشترک شوید. به صورت آرایه‌ای از رشته‌ها مانند 'google.workspace.chat.message.v1.created' قالب‌بندی می‌شود.
    • TOPIC_NAME : نام کامل موضوع Pub/Sub که در پروژه Cloud خود ایجاد کرده‌اید. با فرمت projects/ PROJECT_ID /topics/ TOPIC_ID .

    • RESOURCE_DATA : یک مقدار بولی که مشخص می‌کند آیا اشتراک شامل داده‌های منبع در payload می‌شود یا خیر:

      • True : شامل تمام داده‌های منبع می‌شود. برای محدود کردن فیلدهایی که شامل می‌شوند، فیلد fieldMask را اضافه کنید و حداقل یک فیلد برای منبع تغییر یافته مشخص کنید. فقط اشتراک‌های منابع چت از شامل شدن داده‌های منبع پشتیبانی می‌کنند.
      • False : داده‌های منابع را شامل نمی‌شود.

  2. برای ایجاد اشتراک Google Workspace، تابع createSubscription را در پروژه Apps Script خود اجرا کنید.

پایتون

  1. در دایرکتوری کاری خود، فایلی با نام create_subscription.py ایجاد کنید و کد زیر را به آن اضافه کنید: 

    """Create subscription."""

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [SCOPES]

# Authenticate with Google Workspace and get user authentication.
flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
CREDENTIALS = flow.run_local_server()

# The Google Workspace resource to monitor for events.
TARGET_RESOURCE = 'TARGET_RESOURCE'

# The types of events to receive.
EVENT_TYPES = [EVENT_TYPES]

# The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API using the service endpoint.
service = build(
    'workspaceevents',
    'v1',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}
response = service.subscriptions().create(body=BODY).execute()
print(response)

    موارد زیر را جایگزین کنید:

    • SCOPES : یک یا چند محدوده‌ی OAuth که از هر نوع رویداد برای اشتراک پشتیبانی می‌کنند. به صورت آرایه‌ای از رشته‌ها قالب‌بندی شده است. برای فهرست کردن چندین محدوده، آنها را با کاما از هم جدا کنید. به عنوان مثال، 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly' .
    • TARGET_RESOURCE : منبع Google Workspace که در آن مشترک می‌شوید، به صورت نام کامل منبع قالب‌بندی شده است. برای مثال، برای مشترک شدن در یک فضای Google Chat با شناسه فضای AAAABBBB ، از //chat.googleapis.com/spaces/AAAABBBB استفاده کنید.
    • EVENT_TYPES : یک یا چند نوع رویداد که می‌خواهید در منبع هدف در آن‌ها مشترک شوید. به صورت آرایه‌ای از رشته‌ها مانند 'google.workspace.chat.message.v1.created' قالب‌بندی می‌شود.
    • TOPIC_NAME : نام کامل موضوع Pub/Sub که در پروژه Cloud خود ایجاد کرده‌اید. با فرمت projects/ PROJECT_ID /topics/ TOPIC_ID .

    • RESOURCE_DATA : یک مقدار بولی که مشخص می‌کند آیا اشتراک شامل داده‌های منبع در payload می‌شود یا خیر:

      • True : شامل تمام داده‌های منبع می‌شود. برای محدود کردن فیلدهایی که شامل می‌شوند، فیلد fieldMask را اضافه کنید و حداقل یک فیلد برای منبع تغییر یافته مشخص کنید. فقط اشتراک‌های منابع چت از شامل شدن داده‌های منبع پشتیبانی می‌کنند.
      • False : داده‌های منابع را شامل نمی‌شود.

  2. برای ایجاد اشتراک Google Workspace، دستور زیر را در ترمینال خود اجرا کنید: 

    python3 create_subscription.py

رابط برنامه‌نویسی کاربردی رویدادهای فضای کاری گوگل (Google Workspace Events API) یک عملیات طولانی‌مدت تکمیل‌شده را برمی‌گرداند که شامل نمونه‌ای از منبع Subscription است که شما ایجاد کرده‌اید.

اشتراک Google Workspace خود را آزمایش کنید

برای بررسی اینکه آیا رویدادهای Google Workspace را دریافت می‌کنید، می‌توانید یک رویداد را فعال کنید و پیام‌ها را به اشتراک Pub/Sub منتقل کنید.

برای آزمایش اشتراک Google Workspace خود:

کنسول گوگل کلود

  1. یک یا چند نوع رویداد را در منبع هدف اشتراک Google Workspace خود فعال کنید. برای مثال، اگر در یک فضای چت در پیام‌های جدید مشترک شده‌اید، پیامی را در آن فضا ارسال کنید.

  2. در کنسول گوگل کلود، به صفحه Pub/Sub بروید:

    به میخانه/مشترک بروید

    مطمئن شوید که پروژه ابری برای برنامه شما انتخاب شده است.

  3. در منوی «میخانه/زیرمجموعه» ، روی «اشتراک‌ها» کلیک کنید.

  4. در جدول، اشتراک انتشار/زیرمجموعه را برای موضوع خود پیدا کنید و روی نام اشتراک کلیک کنید.

  5. روی برگه پیام‌ها کلیک کنید.

  6. روی Pull کلیک کنید. ممکن است چند دقیقه طول بکشد تا یک رویداد یک پیام Pub/Sub ایجاد کند.

جی‌کلاود

  1. یک یا چند نوع رویداد را در منبع هدف اشتراک Google Workspace خود فعال کنید. برای مثال، اگر در یک فضای چت در پیام‌های جدید مشترک شده‌اید، پیامی را در آن فضا ارسال کنید.

  2. دستور زیر را اجرا کنید: 

    gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

    موارد زیر را جایگزین کنید:

    • PUBSUB_SUBSCRIPTION_NAME : نام کامل اشتراک Pub/Sub شما، که به صورت projects/ PROJECT_ID /subscriptions/ SUBSCRIPTION_ID قالب‌بندی شده است.
    • MESSAGE_COUNT : حداکثر تعداد پیام‌های Pub/Sub که می‌خواهید دریافت کنید.

    ممکن است چند دقیقه طول بکشد تا یک رویداد، پیام Pub/Sub را ایجاد کند.

برای هر رویداد Google Workspace که فعال می‌کنید، پیامی به اشتراک Pub/Sub شما ارسال می‌شود که حاوی آن رویداد است. برای جزئیات بیشتر، به دریافت رویدادها به عنوان پیام‌های Google Cloud Pub/Sub مراجعه کنید.

نحوه دریافت رویدادها توسط برنامه خود را پیکربندی کنید

اشتراک Pub/Sub که ایجاد کرده‌اید مبتنی بر pull است. پس از اینکه اشتراک Pub/Sub خود را آزمایش کردید، می‌توانید نوع تحویل را به‌روزرسانی کنید تا نحوه دریافت رویدادها توسط برنامه شما تغییر کند. به عنوان مثال، می‌توانید اشتراک Pub/Sub را روی یک نوع تحویل push پیکربندی کنید تا برنامه شما بتواند رویدادها را مستقیماً به یک نقطه پایانی برنامه دریافت کند.

برای کسب اطلاعات بیشتر در مورد پیکربندی اشتراک Pub/Sub، به مستندات Pub/Sub مراجعه کنید.

به عنوان یک برنامه چت گوگل، در رویدادهای فضای چت مشترک شوید

شما می‌توانید به عنوان یک برنامه چت از فضایی که برنامه چت در آن عضویت دارد، در رویدادهای چت مشترک شوید. برنامه‌های چت نمی‌توانند در رویدادهای کاربر مشترک شوند.

ایجاد کلید API

برای فراخوانی متد API پیش‌نمایش توسعه‌دهنده، باید از یک نسخه پیش‌نمایش توسعه‌دهنده غیرعمومی از سند کشف API استفاده کنید. برای تأیید اعتبار درخواست، باید یک کلید API ارسال کنید.

برای ایجاد کلید API، پروژه Google Cloud برنامه خود را باز کنید و موارد زیر را انجام دهید:

  1. در کنسول گوگل کلود، به Menu > APIs & Services > Credentials بروید.

    به اعتبارنامه‌ها بروید

  2. روی ایجاد اعتبارنامه > کلید API کلیک کنید.
  3. کلید API جدید شما نمایش داده می‌شود.
    • برای کپی کردن کلید API خود جهت استفاده در کد برنامه، روی گزینه کپی کردن کلیک کنید. کلید API را می‌توانید در بخش «کلیدهای API» در اعتبارنامه‌های پروژه خود نیز پیدا کنید.
    • برای جلوگیری از استفاده غیرمجاز، توصیه می‌کنیم مکان و نوع APIهایی که کلید API می‌تواند استفاده شود را محدود کنید. برای جزئیات بیشتر، به افزودن محدودیت‌های API مراجعه کنید.

اسکریپتی بنویسید که API رویدادهای Google Workspace را فراخوانی کند

در اینجا نحوه ایجاد اشتراک در رویدادهای فضای چت با احراز هویت برنامه و تأیید مدیر آمده است:

  1. در صورت لزوم، یک برنامه چت بسازید .

  2. در یک منبع چت مشترک شوید ، اما:

    1. به جای احراز هویت کاربر، به عنوان یک برنامه چت با تأیید یکباره مدیر، احراز هویت کنید .

    2. محدوده‌های مجوزدهی را مشخص کنید که به برنامه چت اجازه می‌دهد در رویدادهای چت مشترک شود. این محدوده‌های مجوزدهی همیشه با chat.app شروع می‌شوند و شامل موارد زیر هستند:

      • https://www.googleapis.com/auth/chat.app.memberships : در رویدادهای اعضای فضای چت مشترک شوید.
      • https://www.googleapis.com/auth/chat.app.messages.readonly : در رویدادهای پیام و واکنش فضای چت مشترک شوید.
      • https://www.googleapis.com/auth/chat.app.spaces : در رویدادهای فضای چت مشترک شوید.

نمونه کد زیر در رویدادهای پیام در یک فضای چت مشخص مشترک می‌شود:

پایتون 

  """Create subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = ['https://www.googleapis.com/auth/chat.app.messages.readonly']

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # The Google Workspace resource to monitor for events.
  TARGET_RESOURCE = '//chat.googleapis.com/spaces/SPACE_ID'

  # The types of events to receive.
  EVENT_TYPES = [
                  'google.workspace.chat.message.v1.created',
                  'google.workspace.chat.message.v1.updated',
                  'google.workspace.chat.message.v1.deleted',
                ]

  # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  TOPIC = 'TOPIC_NAME'

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1beta',
      credentials=CREDENTIALS,
      discoveryServiceUrl='https://workspaceevents.googleapis.com/$discovery/rest?version=v1beta&labels=DEVELOPER_PREVIEW&key=API_KEY',
  )

  BODY = {
      'target_resource': TARGET_RESOURCE,
      'event_types': EVENT_TYPES,
      'notification_endpoint': {'pubsub_topic': TOPIC},
      'payload_options': {'include_resource': RESOURCE_DATA},
  }
  response = service.subscriptions().create(body=BODY).execute()
  print(response)

موارد زیر را جایگزین کنید:

  • SPACE_ID : نام فضا، که می‌توانید از متد spaces.list در Chat API یا از URL فضا به دست آورید.
  • TOPIC_NAME : نام کامل موضوع Pub/Sub که در پروژه Cloud خود ایجاد کرده‌اید. با فرمت projects/ PROJECT_ID /topics/ TOPIC_ID .
  • API_KEY : کلید API که برای ساخت نقطه پایانی سرویس برای Google Workspace Events API ایجاد کرده‌اید.

  • RESOURCE_DATA : یک مقدار بولی که مشخص می‌کند آیا اشتراک شامل داده‌های منبع در payload می‌شود یا خیر:

    • True : شامل تمام داده‌های منبع می‌شود. برای محدود کردن فیلدهایی که شامل می‌شوند، فیلد fieldMask را اضافه کنید و حداقل یک فیلد برای منبع تغییر یافته مشخص کنید. فقط اشتراک‌های منابع چت از شامل شدن داده‌های منبع پشتیبانی می‌کنند.
    • False : داده‌های منابع را شامل نمی‌شود.