Method: spaces.setup

יוצר מרחב ומוסיף אליו משתמשים שצוינו. המשתמש שמבצע את השיחה מצורף אוטומטית למרחב, ולכן אין לציין אותו כחבר בבקשה. דוגמה מופיעה במאמר הגדרת מרחב עם משתתפים ראשוניים.

כדי לציין את המשתמשים האנושיים שרוצים להוסיף, מוסיפים חברויות עם membership.member.name מתאים. כדי להוסיף משתמש אנושי, משתמשים ב-users/{user}, כאשר {user} יכול להיות כתובת האימייל של המשתמש. למשתמשים באותו ארגון ב-Workspace, הערך של {user} יכול להיות גם id של האדם מ-People API, או id של המשתמש מ-Directory API. לדוגמה, אם מזהה פרופיל האדם ב-People API עבור user@example.com הוא 123456789, אפשר להוסיף את המשתמש למרחב על ידי הגדרת membership.member.name ל-users/user@example.com או ל-users/123456789.

כדי לציין את קבוצות Google שרוצים להוסיף, מוסיפים חברות עם membership.group_member.name המתאים. כדי להוסיף או להזמין קבוצת Google, משתמשים ב-groups/{group}, כאשר {group} הוא id של הקבוצה מ-Cloud Identity Groups API. לדוגמה, אתם יכולים להשתמש ב-Cloud Identity Groups lookup API כדי לאחזר את המזהה 123456789 של כתובת אימייל קבוצתית group@example.com, ואז להוסיף את הקבוצה למרחב על ידי הגדרת membership.group_member.name ל-groups/123456789. אי אפשר להוסיף קבוצות אימייל, וקבוצות Google אפשר להוסיף רק כחברים במרחבים עם שם.

במרחבים עם שם או בצ'אטים קבוצתיים, אם המתקשר חוסם חלק מהמשתתפים או נחסם על ידם, או אם אין לו הרשאה להוסיף חלק מהמשתתפים, הם לא יצורפו למרחב שנוצר.

כדי ליצור צ'אט ישיר (DM) בין המשתמש המתקשר לבין משתמש אנושי אחר, צריך לציין בדיוק חברות אחת שתייצג את המשתמש האנושי. אם משתמש אחד חוסם את השני, הבקשה נכשלת והצ'אט הישיר לא נוצר.

כדי ליצור צ'אט ישיר בין המשתמש שמתקשר לבין האפליקציה שמתקשרת, מגדירים את Space.singleUserBotDm ל-true ולא מציינים חברות כלשהי. אפשר להשתמש בשיטה הזו רק כדי להגדיר צ'אט ישיר עם אפליקציית השיחות. כדי להוסיף את אפליקציית השיחות כחברה במרחב או בצ'אט ישיר קיים בין שני משתמשים, אפשר לעיין במאמר בנושא הזמנה או הוספה של משתמש או אפליקציה למרחב.

אם כבר קיים צ'אט ישיר בין שני משתמשים, גם אם משתמש אחד חוסם את השני בזמן שליחת הבקשה, הצ'אט הישיר הקיים יוחזר.

אין תמיכה במרחבים עם תשובות בשרשור. אם מופיעה הודעת השגיאה 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 כתובה בתחביר של gRPC Transcoding.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג 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.

כדי ליצור שיחה ישירה בין אדם לבין אפליקציית Chat לשיחות, מגדירים את Space.spaceType ל-DIRECT_MESSAGE ואת Space.singleUserBotDm ל-true. אל תגדירו את Space.displayName או Space.spaceDetails.

אם מרחב DIRECT_MESSAGE כבר קיים, המרחב הזה מוחזר במקום ליצור מרחב חדש.
requestId

string

אופציונלי. מזהה ייחודי לבקשה. מומלץ להשתמש במזהה ייחודי אוניברסלי (UUID) אקראי. ציון מזהה בקשה הופך את הבקשה לאידמפוטנטית, וכך אפשר לוודא שמספר בקשות זהות עם אותו מזהה בקשה יובילו ליצירת מרחב אחד בלבד. בקשות עוקבות עם אותו מזהה בקשה מחזירות את המרחב הקיים ולא מעדכנות אותו, גם אם הפרטים המבוקשים שונים מהמצב הנוכחי.

כדי להשתמש בשדה הזה בצורה יעילה:

  • חשוב לוודא שהבקשות הבאות זהות ומשתמשות באותם פרטי אימות כמו הבקשה המקורית.
  • אם כבר נוצר מרחב עם מזהה הבקשה שצוין, הבקשה מחזירה את המרחב הזה. שימו לב: יכול להיות שהמרחב שיוחזר לא יאוכלס במלואו. ה-API משקף את המרחב בבקשה שלכם עם שם המשאב שהוקצה על ידי המערכת. כדי לאחזר את המטא-נתונים העדכניים של המרחב, קוראים ל-spaces.get.
  • שימוש חוזר במזהה בקשה קיים עם משתמש מאומת אחר מוביל לשגיאה.
memberships[]

object (Membership)

אופציונלי. משתמשים או קבוצות ב-Google Chat שרוצים להזמין למרחב. לא צריך להוסיף את המשתמש המתקשר, כי הוא מתווסף אוטומטית.

כרגע אפשר להגדיר עד 49 חברים (בנוסף למתקשר).

במינוי של אדם, השדה Membership.member צריך להכיל user עם הערך name (בפורמט users/{user}) והערך type צריך להיות User.Type.HUMAN. אפשר להוסיף רק משתמשים שהם בני אדם כשמגדירים מרחב (הוספת אפליקציות ל-Chat נתמכת רק בהגדרת צ'אט ישיר עם אפליקציית השיחות). אפשר גם להוסיף חברים באמצעות כתובת האימייל של המשתמש ככתובת חלופית ל-{user}. לדוגמה, user.name יכול להיות users/example@gmail.com. כדי להזמין משתמשי Gmail או משתמשים מדומיינים חיצוניים של Google Workspace, צריך להשתמש בכתובת האימייל של המשתמש עבור {user}.

כדי להוסיף חברים לקבוצה ב-Google, השדה Membership.group_member צריך להכיל group עם הערך name (בפורמט groups/{group}). אפשר להוסיף קבוצות ב-Google רק אם הערך של Space.spaceType הוא SPACE.

אופציונלי כשמגדירים את Space.spaceType ל-SPACE.

חובה להשתמש בתג הזה כשמגדירים את Space.spaceType לערך GROUP_CHAT, וגם כשמגדירים לפחות שני חברים.

חובה להשתמש בפרמטר הזה כשמגדירים את Space.spaceType ל-DIRECT_MESSAGE עם משתמש אנושי, וגם כשמגדירים חברות אחת בדיוק.

השדה הזה צריך להיות ריק כשיוצרים שיחה אישית בין אדם לבין אפליקציית Chat לביצוע שיחות (כשמגדירים את Space.spaceType ל-DIRECT_MESSAGE ואת Space.singleUserBotDm ל-true).

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של Space.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

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

מידע נוסף זמין במדריך ההרשאות.