Method: spaces.setup

یک فضا ایجاد می‌کند و کاربران مشخص شده را به آن اضافه می‌کند. کاربر فراخوانی شده به طور خودکار به فضا اضافه می‌شود و نباید به عنوان عضویت در درخواست مشخص شود. برای مثال، به بخش «تنظیم فضا با اعضای اولیه» مراجعه کنید.

برای مشخص کردن اعضای انسانی که باید اضافه شوند، عضویت‌ها را با membership.member.name مناسب اضافه کنید. برای اضافه کردن یک کاربر انسانی، users/{user} استفاده کنید، که در آن {user} می‌تواند آدرس ایمیل کاربر باشد. برای کاربرانی که در همان فضای کاری سازمان‌دهی شده‌اند، {user} همچنین می‌تواند id شخص از People API یا id کاربر در Directory API باشد. به عنوان مثال، اگر شناسه پروفایل Person در People API برای user@example.com برابر با 123456789 باشد، می‌توانید با تنظیم membership.member.name به users/user@example.com یا users/123456789 کاربر را به فضا اضافه کنید.

برای مشخص کردن گروه‌های گوگلی که باید اضافه شوند، عضویت‌ها را با membership.group_member.name مناسب اضافه کنید. برای اضافه کردن یا دعوت از یک گروه گوگل، groups/{group} استفاده کنید، که در آن {group} id گروه از API گروه‌های هویت ابری است. به عنوان مثال، می‌توانید از API جستجوی گروه‌های هویت ابری برای بازیابی شناسه 123456789 برای ایمیل گروهی group@example.com استفاده کنید، سپس می‌توانید با تنظیم membership.group_member.name به groups/123456789 ، گروه را به فضا اضافه کنید. ایمیل گروهی پشتیبانی نمی‌شود و گروه‌های گوگل فقط می‌توانند به عنوان عضو در فضاهای نامگذاری شده اضافه شوند.

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

برای ایجاد یک پیام مستقیم (DM) بین کاربر تماس گیرنده و یک کاربر انسانی دیگر، دقیقاً یک عضویت را برای نمایش کاربر انسانی مشخص کنید. اگر یک کاربر، کاربر دیگر را مسدود کند، درخواست با شکست مواجه می‌شود و DM ایجاد نمی‌شود.

برای ایجاد یک DM بین کاربر فراخوانی‌کننده و برنامه فراخوانی‌کننده، Space.singleUserBotDm را روی true تنظیم کنید و هیچ عضویتی را مشخص نکنید. شما فقط می‌توانید از این روش برای راه‌اندازی یک DM با برنامه فراخوانی‌کننده استفاده کنید. برای افزودن برنامه فراخوانی‌کننده به عنوان عضوی از یک فضا یا یک DM موجود بین دو کاربر انسانی، به بخش دعوت یا افزودن یک کاربر یا برنامه به یک فضا مراجعه کنید.

اگر یک DM از قبل بین دو کاربر وجود داشته باشد، حتی اگر یکی از کاربران در زمان ارسال درخواست، کاربر دیگر را مسدود کند، DM موجود بازگردانده می‌شود.

فضاهایی با پاسخ‌های رشته‌ای پشتیبانی نمی‌شوند. اگر هنگام تنظیم یک فضا، پیام خطای ALREADY_EXISTS را دریافت کردید، displayName دیگری را امتحان کنید. ممکن است یک فضای موجود در سازمان Google Workspace از قبل از این نام نمایشی استفاده کند.

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

  • https://www.googleapis.com/auth/chat.spaces.create
  • https://www.googleapis.com/auth/chat.spaces

درخواست HTTP

POST https://chat.googleapis.com/v1/spaces:setup

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "space": {
    object (Space)
  },
  "requestId": string,
  "memberships": [
    {
      object (Membership)
    }
  ]
}
فیلدها
space

object ( Space )

الزامی. فیلد Space.spaceType الزامی است.

برای ایجاد یک فاصله، Space.spaceType را روی SPACE و Space.displayName تنظیم کنید. اگر هنگام تنظیم یک فاصله، پیام خطای ALREADY_EXISTS را دریافت کردید، یک displayName دیگر را امتحان کنید. ممکن است یک فضای موجود در سازمان Google Workspace از قبل از این نام نمایشی استفاده کند.

برای ایجاد چت گروهی، Space.spaceType را روی GROUP_CHAT تنظیم کنید. Space.displayName تنظیم نکنید.

برای ایجاد یک مکالمه ۱:۱ بین انسان‌ها، Space.spaceType را روی DIRECT_MESSAGE تنظیم کنید و Space.singleUserBotDm را روی false تنظیم کنید. Space.displayName یا Space.spaceDetails را تنظیم نکنید.

برای ایجاد یک مکالمه ۱:۱ بین یک انسان و برنامه چت فراخوانی شده، Space.spaceType را روی DIRECT_MESSAGE و Space.singleUserBotDm را روی true تنظیم کنید. Space.displayName یا Space.spaceDetails را تنظیم نکنید.

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

requestId

string

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

برای استفاده موثر از این فیلد:

  • اطمینان حاصل کنید که درخواست‌های بعدی یکسان هستند و از همان اعتبارنامه‌های احراز هویت درخواست اصلی استفاده می‌کنند.
  • اگر فضایی از قبل با شناسه درخواست ارائه شده ایجاد شده باشد، درخواست آن فضا را برمی‌گرداند. توجه داشته باشید که فضای برگردانده شده ممکن است به طور کامل پر نشده باشد؛ API فضای موجود در درخواست شما را با نام منبع اختصاص داده شده توسط سیستم پر می‌کند. برای بازیابی آخرین فراداده برای فضا، spaces.get را فراخوانی کنید.
  • استفاده مجدد از یک شناسه درخواست موجود با یک کاربر احراز هویت شده متفاوت منجر به خطا می‌شود.
memberships[]

object ( Membership )

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

این مجموعه در حال حاضر امکان عضویت تا ۴۹ نفر (علاوه بر تماس‌گیرنده) را فراهم می‌کند.

برای عضویت انسانی، فیلد Membership.member باید شامل یک user با name ثبت شده (فرمت: users/{user} ) و type داده شده روی User.Type.HUMAN باشد. شما فقط می‌توانید هنگام تنظیم یک فضا، کاربران انسانی را اضافه کنید (افزودن برنامه‌های چت فقط برای تنظیم پیام مستقیم با برنامه فراخوانی پشتیبانی می‌شود). همچنین می‌توانید اعضا را با استفاده از ایمیل کاربر به عنوان نام مستعار برای {user} اضافه کنید. به عنوان مثال، user.name می‌تواند users/example@gmail.com باشد. برای دعوت از کاربران Gmail یا کاربران از دامنه‌های خارجی Google Workspace، ایمیل کاربر باید برای {user} استفاده شود.

برای عضویت در گروه گوگل، فیلد Membership.group_member باید شامل group باشد که name آن ذکر شده باشد (فرمت groups/{group} ). شما فقط می‌توانید گروه‌های گوگل را هنگام تنظیم Space.spaceType روی SPACE اضافه کنید.

اختیاری هنگام تنظیم Space.spaceType روی SPACE .

هنگام تنظیم Space.spaceType روی GROUP_CHAT ، همراه با حداقل دو عضویت، الزامی است.

هنگام تنظیم Space.spaceType روی DIRECT_MESSAGE با یک کاربر انسانی، همراه با دقیقاً یک عضویت، الزامی است.

هنگام ایجاد مکالمه ۱:۱ بین یک انسان و برنامه چت فراخوانی شده (هنگام تنظیم Space.spaceType روی DIRECT_MESSAGE و Space.singleUserBotDm روی true )، باید خالی باشد.

بدنه پاسخ

در صورت موفقیت، بدنه پاسخ شامل نمونه‌ای از Space است.

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.create

برای اطلاعات بیشتر، به راهنمای مجوز مراجعه کنید.