حوزه های API رویدادهای Google Workspace را انتخاب کنید

این سند حاوی اطلاعات مربوط به مجوز و احراز هویت مختص API رویدادهای Google Workspace است. قبل از مطالعه این سند، حتماً اطلاعات عمومی احراز هویت و مجوز Google Workspace را در بخش «درباره احراز هویت و مجوز بیشتر بدانید» مطالعه کنید.

پیکربندی OAuth 2.0 برای احراز هویت

صفحه رضایت OAuth را پیکربندی کنید و محدوده‌هایی را برای تعریف اطلاعات نمایش داده شده به کاربران و بررسی‌کنندگان برنامه انتخاب کنید و برنامه خود را ثبت کنید تا بتوانید بعداً آن را منتشر کنید.

محدوده‌های API رویدادهای Google Workspace

برای تعریف سطح دسترسی اعطا شده به برنامه خود، باید حوزه‌های مجوز را شناسایی و اعلام کنید. حوزه مجوز، یک رشته URI از نوع OAuth 2.0 است که شامل نام برنامه Google Workspace، نوع داده‌هایی که به آنها دسترسی دارد و سطح دسترسی است. حوزه‌ها، درخواست‌های برنامه شما برای کار با داده‌های Google Workspace، از جمله داده‌های حساب Google کاربران، هستند.

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

در صورت امکان، توصیه می‌کنیم از محدوده‌های غیرحساس استفاده کنید زیرا محدوده دسترسی به ازای هر فایل را اعطا می‌کند و دسترسی را به عملکردهای خاص مورد نیاز یک برنامه محدود می‌کند.

API رویدادهای Google Workspace از محدوده‌های برنامه‌های Google Workspace که از اشتراک‌ها پشتیبانی می‌کنند، استفاده می‌کند. اگر برنامه شما از قبل از محدوده‌هایی که برای اشتراک شما لازم است استفاده می‌کند، نیازی به اضافه کردن محدوده‌های اضافی برای استفاده از API رویدادهای Google Workspace ندارید.

جدول زیر محدوده‌های پشتیبانی‌شده برای Google Workspace Events API را نمایش می‌دهد:

کد محدوده توضیحات کاربرد
گوگل چت
https://www.googleapis.com/auth/chat.bot به برنامه‌های چت گوگل اجازه می‌دهد چت‌ها را مشاهده کرده و پیام ارسال کنند. به همه ویژگی‌های موجود در برنامه‌های چت دسترسی می‌دهد. غیر حساس
https://www.googleapis.com/auth/chat.memberships مشاهده، اضافه کردن و حذف اعضا از مکالمات در گوگل چت.
حساس
https://www.googleapis.com/auth/chat.memberships.readonly مشاهده اعضا در مکالمات گوگل چت.
حساس
https://www.googleapis.com/auth/chat.app.memberships

مشاهده، اضافه کردن، به‌روزرسانی و حذف اعضا از مکالمات و فضاهای موجود در Google Chat به عنوان یک برنامه چت.

نیاز به تایید مدیر دارد.

این محدوده فقط از احراز هویت برنامه با حساب‌های سرویس پشتیبانی می‌کند. شما نمی‌توانید با استفاده از این محدوده، با اعتبارنامه‌های کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید.


حساس
https://www.googleapis.com/auth/chat.spaces ایجاد مکالمات و فضاها و مشاهده یا به‌روزرسانی فراداده‌ها (از جمله تنظیمات تاریخچه) در Google Chat. حساس
https://www.googleapis.com/auth/chat.spaces.readonly مشاهده چت و فضاهای خالی در گوگل چت.
حساس
https://www.googleapis.com/auth/chat.app.spaces

ایجاد مکالمات و فضاها و مشاهده یا به‌روزرسانی فراداده‌ها (از جمله تنظیمات تاریخچه) در Google Chat به عنوان یک برنامه چت.

نیاز به تایید مدیر دارد.

این محدوده فقط از احراز هویت برنامه با حساب‌های سرویس پشتیبانی می‌کند. شما نمی‌توانید با استفاده از این محدوده، با اعتبارنامه‌های کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید.


حساس
https://www.googleapis.com/auth/chat.messages.reaction s مشاهده، اضافه کردن و حذف واکنش‌ها به پیام‌ها در چت.
حساس
https://www.googleapis.com/auth/chat.messages.reactions.readonly مشاهده واکنش‌ها به یک پیام در چت.
حساس
https://www.googleapis.com/auth/chat.messages مشاهده، نوشتن، ارسال، به‌روزرسانی و حذف پیام‌ها، و افزودن، مشاهده و حذف واکنش‌ها به پیام‌ها. محدود شده
https://www.googleapis.com/auth/chat.messages.readonly پیام‌ها و واکنش‌ها را در Google Chat مشاهده کنید.
محدود شده
https://www.googleapis.com/auth/chat.app.messages.readonly

پیام‌ها و واکنش‌ها را در Google Chat به عنوان یک برنامه چت مشاهده کنید.

نیاز به تایید مدیر دارد.

این محدوده فقط از احراز هویت برنامه با حساب‌های سرویس پشتیبانی می‌کند. شما نمی‌توانید با استفاده از این محدوده، با اعتبارنامه‌های کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید.


محدود شده
گوگل درایو
https://www.googleapis.com/auth/drive.file فایل‌های Drive جدیدی ایجاد کنید، یا فایل‌های موجود را که با یک برنامه باز می‌کنید یا کاربر هنگام استفاده از API انتخابگر گوگل یا انتخابگر فایل برنامه با یک برنامه به اشتراک می‌گذارد، تغییر دهید. غیر حساس
https://www.googleapis.com/auth/drive تمام فایل‌های Drive خود را مشاهده و مدیریت کنید. محدود شده
https://www.googleapis.com/auth/drive.readonly تمام فایل‌های Drive خود را مشاهده و دانلود کنید. محدود شده
https://www.googleapis.com/auth/drive.metadata مشاهده و مدیریت فراداده‌های فایل‌های موجود در درایو شما. محدود شده
https://www.googleapis.com/auth/drive.metadata.readonly مشاهده فراداده فایل‌های موجود در درایو شما. محدود شده
گوگل میت
https://www.googleapis.com/auth/meetings.space.created به برنامه‌ها اجازه دهید تا فراداده‌های مربوط به فضاهای جلسه ایجاد شده توسط برنامه شما را ایجاد، اصلاح و بخوانند.
حساس
https://www.googleapis.com/auth/meetings.space.readonly به برنامه‌ها اجازه دهید تا فراداده‌های مربوط به هر فضای جلسه‌ای که کاربر به آن دسترسی دارد را بخوانند.
حساس

ستون «استفاده» در جدول قبلی، حساسیت هر محدوده را طبق تعاریف زیر نشان می‌دهد:

  • غیرحساس : این محدوده‌ها کوچکترین محدوده دسترسی مجوز را ارائه می‌دهند و فقط به تأیید اولیه برنامه نیاز دارند. برای اطلاعات در مورد این الزام، به الزامات تأیید مراجعه کنید.

  • حساس : این محدوده‌ها دسترسی به داده‌های خاص کاربر گوگل را که توسط کاربر برای برنامه شما مجاز شده است، فراهم می‌کنند. این امر مستلزم آن است که شما تأیید هویت برنامه را انجام دهید. برای اطلاعات بیشتر در مورد این الزام، به الزامات محدوده حساس و محدود مراجعه کنید.

  • محدود : این محدوده‌ها دسترسی گسترده‌ای به داده‌های کاربر گوگل ارائه می‌دهند و شما را ملزم به طی کردن یک فرآیند تأیید محدوده محدود می‌کنند. برای اطلاعات بیشتر در مورد این الزام، به خدمات API گوگل: سیاست داده‌های کاربر و الزامات اضافی برای محدوده‌های خاص API مراجعه کنید. اگر داده‌های محدوده محدود را روی سرورها ذخیره می‌کنید (یا منتقل می‌کنید)، باید ارزیابی امنیتی را انجام دهید.

اگر برنامه شما نیاز به دسترسی به هر API گوگل دیگری دارد، می‌توانید آن محدوده‌ها را نیز اضافه کنید. برای اطلاعات بیشتر در مورد محدوده‌های API گوگل، به بخش «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» مراجعه کنید.

برای اطلاعات بیشتر در مورد حوزه‌های خاص OAuth 2.0، به حوزه‌های OAuth 2.0 برای APIهای گوگل مراجعه کنید.

تأیید هویت OAuth

استفاده از برخی از محدوده‌های OAuth ممکن است مستلزم آن باشد که برنامه شما از طریق مرکز راهنمایی تأیید برنامه OAuth اقدام کند. برای تعیین زمان و نوع تأیید مورد نیاز، سوالات متداول برنامه OAuth را مطالعه کنید. همچنین به شرایط خدمات Google Drive مراجعه کنید.

انواع احراز هویت مورد نیاز

این بخش توضیح می‌دهد که کدام نوع احراز هویت مورد نیاز یا پشتیبانی می‌شود و حوزه‌های پشتیبانی‌شده برای هر روش از Google Workspace Events API را ارائه می‌دهد.

برای اشتراک در رویدادهای Google Chat، API رویدادهای Google Workspace از احراز هویت کاربر و برنامه برای فراخوانی برخی از متدهای خود پشتیبانی می‌کند. اگر یک متد API از هر دو اعتبارنامه پشتیبانی کند، نوع اعتبارنامه استفاده شده در فراخوانی بر نتیجه‌ای که برگردانده می‌شود تأثیر می‌گذارد. برای مثال، اگر متد subscriptions.list را با احراز هویت کاربر فراخوانی کنید، API لیستی از اشتراک‌هایی را که کاربر احراز هویت شده می‌تواند به آنها دسترسی داشته باشد، برمی‌گرداند. اگر از احراز هویت برنامه استفاده کنید، API لیستی از اشتراک‌هایی را که برنامه می‌تواند به آنها دسترسی داشته باشد، برمی‌گرداند. برای کسب اطلاعات بیشتر در مورد انواع احراز هویت چت، به بخش احراز هویت و مجوزدهی برنامه‌های چت و درخواست‌های Google Chat API مراجعه کنید.

جدول زیر نشان می‌دهد که کدام حوزه‌ها و انواع احراز هویت برای هر روش Google Workspace Events API مورد نیاز یا پشتیبانی می‌شوند:

روش احراز هویت کاربر الزامی یا پشتیبانی شده احراز هویت برنامه پشتیبانی می‌شود (فقط برنامه‌های چت گوگل) دامنه‌های مجوز پشتیبانی می‌شوند
ایجاد اشتراک —

با احراز هویت کاربر، برای هر نوع رویداد به یک محدوده پشتیبانی‌شده نیاز است:

  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly
  • drive.file
  • drive
  • drive.readonly
  • drive.metadata
  • drive.metadata.readonly
  • meetings.space.created
  • meetings.space.readonly

پیش‌نمایش توسعه‌دهنده : با احراز هویت برنامه و تأیید مدیر (فقط برنامه‌های Google Chat)، برای هر نوع رویداد به یک محدوده پشتیبانی‌شده نیاز دارد:

  • chat.app.memberships
  • chat.app.spaces
  • chat.app.messages.readonly
دریافت اشتراک با احراز هویت کاربر، این روش به محدوده‌ای نیاز دارد که حداقل از یک نوع رویداد برای اشتراک پشتیبانی کند .

با احراز هویت برنامه (فقط برنامه‌های چت گوگل):

  • chat.bot
اشتراک‌ها را فهرست کنید با احراز هویت کاربر، این روش به محدوده‌ای نیاز دارد که حداقل از یک نوع رویداد برای اشتراک پشتیبانی کند .

با احراز هویت برنامه (فقط برنامه‌های چت گوگل):

  • chat.bot
به‌روزرسانی اشتراک —

با احراز هویت کاربر، برای هر نوع رویداد به یک محدوده پشتیبانی‌شده نیاز است:

  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly
  • drive.file
  • drive
  • drive.readonly
  • drive.metadata
  • drive.metadata.readonly
  • meetings.space.created
  • meetings.space.readonly

پیش‌نمایش توسعه‌دهنده : با احراز هویت برنامه و تأیید مدیر (فقط برنامه‌های Google Chat)، برای هر نوع رویداد به یک محدوده پشتیبانی‌شده نیاز دارد:

  • chat.app.memberships
  • chat.app.spaces
  • chat.app.messages.readonly
فعال‌سازی مجدد اشتراک —

با احراز هویت کاربر، برای هر نوع رویداد به یک محدوده پشتیبانی‌شده نیاز است:

  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly
  • drive.file
  • drive
  • drive.readonly
  • drive.metadata
  • drive.metadata.readonly
  • meetings.space.created
  • meetings.space.readonly

پیش‌نمایش توسعه‌دهنده : با احراز هویت برنامه و تأیید مدیر (فقط برنامه‌های Google Chat)، برای هر نوع رویداد به یک محدوده پشتیبانی‌شده نیاز دارد:

  • chat.app.memberships
  • chat.app.spaces
  • chat.app.messages.readonly
حذف اشتراک با احراز هویت کاربر، این روش به محدوده‌ای نیاز دارد که حداقل از یک نوع رویداد برای اشتراک پشتیبانی کند .

با احراز هویت برنامه (فقط برنامه‌های چت گوگل):

  • chat.bot

محدوده‌ها بر اساس نوع رویداد

وقتی API رویدادهای Google Workspace را با استفاده از احراز هویت کاربر فراخوانی می‌کنید، باید یک یا چند محدوده (scope) را مشخص کنید که با انواع رویدادهای اشتراک مطابقت داشته باشند.

جدول زیر نشان می‌دهد که کدام حوزه‌های مجوز برای هر نوع رویداد پشتیبانی می‌شوند:

رویدادها انواع رویداد دامنه‌های مجوز پشتیبانی می‌شوند
گوگل چت
پیامی ارسال یا به‌روزرسانی می‌شود.
  • google.workspace.chat.message.v1.created
  • google.workspace.chat.message.v1.updated
 با احراز هویت کاربر :
  • chat.messages
  • chat.messages.readonly
با احراز هویت برنامه و تأیید مدیر (موجود در پیش‌نمایش توسعه‌دهندگان ):
  • chat.app.messages.readonly
یک واکنش اضافه یا حذف می‌شود، یا چندین واکنش تغییر می‌کنند.
  • google.workspace.chat.reaction.v1.created
  • google.workspace.chat.reaction.v1.deleted
  • google.workspace.chat.reaction.v1.batchChanged
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.messages
  • chat.messages.readonly
یک عضویت ایجاد، به‌روزرسانی یا حذف می‌شود، یا چندین عضویت تغییر می‌کنند.
  • google.workspace.chat.membership.v1.created
  • google.workspace.chat.membership.v1.updated
  • google.workspace.chat.membership.v1.deleted
  • google.workspace.chat.membership.v1.batchChanged
 با احراز هویت کاربر :
  • chat.memberships
  • chat.memberships.readonly
با احراز هویت برنامه و تأیید مدیر (موجود در پیش‌نمایش توسعه‌دهندگان ):
  • chat.app.memberships
یک فاصله به‌روزرسانی یا حذف می‌شود.
  • google.workspace.chat.space.v1.updated
  • google.workspace.chat.space.v1.deleted
 با احراز هویت کاربر :
  • chat.spaces
  • chat.spaces.readonly
با احراز هویت برنامه و تأیید مدیر (موجود در پیش‌نمایش توسعه‌دهندگان ):
  • chat.app.spaces
گوگل درایو
یک فایل ایجاد می‌شود، تغییر می‌کند، منتقل می‌شود، حذف می‌شود، به سطل زباله انداخته می‌شود یا از سطل زباله حذف می‌شود.
  • google.workspace.drive.file.v3.added
  • google.workspace.drive.file.v3.moved
  • google.workspace.drive.file.v3.contentChanged
  • google.workspace.drive.file.v3.deleted
  • google.workspace.drive.file.v3.trashed
  • google.workspace.drive.file.v3.untrashed
  • drive
  • drive.file
  • drive.metadata
یک پیشنهاد دسترسی روی یک فایل ایجاد یا حل می‌شود.
  • google.workspace.drive.accessProposal.v3.created
  • google.workspace.drive.accessProposal.v3.resolved
  • drive
  • drive.file
  • drive.metadata
  • drive.metadata
  • drive.metadata.readonly
گوگل میت
یک کنفرانس شروع یا پایان می‌یابد.
  • google.workspace.meet.conference.v2.started
  • google.workspace.meet.conference.v2.ended
  • meetings.space.created
  • meetings.space.readonly
یک شرکت‌کننده به کنفرانس می‌پیوندد یا آن را ترک می‌کند.
  • google.workspace.meet.participant.v2.joined
  • google.workspace.meet.participant.v2.left
  • meetings.space.created
  • meetings.space.readonly
یک ضبط ایجاد شد.
  • google.workspace.meet.recording.v2.fileGenerated
  • meetings.space.created
  • meetings.space.readonly
یک رونوشت تهیه شد.
  • google.workspace.meet.transcript.v2.fileGenerated
  • meetings.space.created
  • meetings.space.readonly