Method: spaces.setup

建立聊天室，並在其中新增指定使用者。系統會自動將通話使用者新增至聊天室，因此不應在要求中指定成員資格。如需範例，請參閱「設定含有初始成員的聊天室」。

如要指定要新增的人類成員，請新增適當 membership.member.name 的成員資格。如要新增真人使用者，請使用 users/{user}，其中 {user} 可以是使用者的電子郵件地址。如果使用者位於同一個 Workspace 機構，{user} 也可以是 People API 中的 id，或是 Directory API 中的使用者 id。舉例來說，如果 user@example.com 的 People API Person 設定檔 ID 為 123456789，您可以將 membership.member.name 設為 users/user@example.com 或 users/123456789，將使用者新增至空間。

如要指定要新增的 Google 群組，請使用適當的 membership.group_member.name 新增成員。如要新增或邀請 Google 群組，請使用 groups/{group}，其中 {group} 是 Cloud Identity Groups API 中群組的 id。舉例來說，您可以使用 Cloud Identity Groups 查詢 API 擷取群組電子郵件地址 group@example.com 的 ID 123456789，然後將 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

這個網址使用 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。

如要建立真人之間的 1:1 對話，請將 Space.spaceType 設為 DIRECT_MESSAGE，並將 Space.singleUserBotDm 設為 false。請勿設定 Space.displayName 或 Space.spaceDetails。

如要建立真人與通話 Chat 應用程式的 1:1 對話，請將 Space.spaceType 設為 DIRECT_MESSAGE，並將 Space.singleUserBotDm 設為 true。請勿設定 Space.displayName 或 Space.spaceDetails。

如果 DIRECT_MESSAGE 聊天室已存在，系統會傳回該聊天室，而不是建立新聊天室。
requestId

string

(選用步驟) 這項要求的專屬 ID。建議使用隨機 UUID。指定要求 ID 可讓要求成為冪等要求，確保多個相同要求 (具有相同要求 ID) 只會建立一個空間。後續要求若使用相同要求 ID，系統會傳回現有空間，即使要求詳細資料與目前狀態不同，也不會更新空間。

如要有效使用這個欄位，請按照下列指示操作：

  • 請確保後續要求與原始要求完全相同，並使用相同的驗證憑證。
  • 如果已使用提供的要求 ID 建立聊天室，要求會傳回該聊天室。請注意，傳回的空間可能不會完全填入資料；API 會回應您要求中的空間，並填入系統指派的資源名稱。如要擷取聊天室的最新中繼資料，請呼叫 spaces.get。
  • 如果使用現有的要求 ID，但驗證的使用者不同，就會發生錯誤。
memberships[]

object (Membership)

(選用步驟) 要邀請加入聊天室的 Google Chat 使用者或群組。請省略通話使用者，因為系統會自動新增。

目前這組最多可有 49 個成員 (不含呼叫者)。

如果是人類成員，Membership.member 欄位必須包含已填入 name 的 user (格式：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})。只有在將 Space.spaceType 設為 SPACE 時，才能新增 Google 群組。

將 Space.spaceType 設為 SPACE 時，此為選填屬性。

將 Space.spaceType 設為 GROUP_CHAT 時，必須提供這項資訊，且至少要有兩個會員方案。

如果將 Space.spaceType 設為 DIRECT_MESSAGE，且使用者為真人，則必須提供這項資訊，且只能提供一項會員資格。

在建立人與通話 Chat 應用程式之間的 1:1 對話時，必須為空白 (將 Space.spaceType 設為 DIRECT_MESSAGE，並將 Space.singleUserBotDm 設為 true 時)。

回應主體

如果成功，回應主體會包含 Space 的執行個體。

授權範圍

需要下列其中一種 OAuth 範圍：

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

詳情請參閱授權指南。