本指南介绍了如何对 Google Chat API 的 Membership
资源使用 create()
方法,将用户、Google 群组或 Chat 应用邀请或添加到聊天室(也称为创建成员资格)。创建会员资格时,如果指定会员已关闭自动接受政策,那么在收到邀请后,他们必须先接受聊天室邀请,然后才能加入。否则,创建会员资格会直接将成员添加到指定聊天室。
如果您是 Google Workspace 管理员,则可以将用户、Google 群组或 Chat 应用添加到 Google Workspace 组织中的任何聊天室。
Membership
资源表示有人为用户或 Google Chat 应用发出了加入聊天室的邀请、用户或 Google Chat 应用已加入聊天室,还是未加入聊天室。
前提条件
Node.js
- 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
- 设置环境:
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用和配置 Google Chat API,为 Chat 应用提供名称、图标和说明。
- 安装 Node.js Cloud 客户端库。
- 根据您要在 Google Chat API 请求中采用的身份验证方式创建访问凭据:
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据以 JSON 文件 (
client_secrets.json
) 的形式保存到本地目录。 - 如需以 Chat 应用的身份进行身份验证,请创建服务账号凭据,并将凭据保存为名为
credentials.json
的 JSON 文件。
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据以 JSON 文件 (
- 根据您是要以用户身份还是以 Chat 应用的身份进行身份验证, 选择授权范围。
Python
- 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
- 设置环境:
- 创建 Google Cloud 项目。
- 配置 OAuth 同意屏幕。
- 启用和配置 Google Chat API,为 Chat 应用提供名称、图标和说明。
- 安装 Python Cloud 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式创建访问凭据:
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据以 JSON 文件 (
client_secrets.json
) 的形式保存到本地目录。 - 如需以 Chat 应用的身份进行身份验证,请创建服务账号凭据,并将凭据保存为名为
credentials.json
的 JSON 文件。
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据以 JSON 文件 (
- 根据您是要作为用户还是 Chat 应用进行身份验证, 选择授权范围。
Java
- 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
- 设置环境:
- 创建 Google Cloud 项目。
- 配置 OAuth 同意屏幕。
- 启用和配置 Google Chat API,为 Chat 应用提供名称、图标和说明。
- 安装 Java Cloud 客户端库。
- 根据您要在 Google Chat API 请求中采用的身份验证方式创建访问凭据:
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据保存为名为
client_secrets.json
的 JSON 文件,保存到本地目录中。 - 如需以 Chat 应用的身份进行身份验证,请创建服务账号凭据,并将凭据保存为名为
credentials.json
的 JSON 文件。
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据保存为名为
- 根据您是要以用户身份还是以 Chat 应用的身份进行身份验证, 选择授权范围。
Apps 脚本
- 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
- 设置您的环境:
- 创建 Google Cloud 项目。
- 配置 OAuth 同意屏幕。
- 为您的 Chat 应用启用和配置 Google Chat API,并为其指定一个名称、图标和说明。
- 创建一个独立的 Apps 脚本项目,然后开启高级聊天服务。
- 在本指南中,您必须使用用户身份验证或应用身份验证。如需以 Chat 应用的身份进行身份验证,请创建服务账号凭据。如需了解相关步骤,请参阅作为 Google Chat 应用进行身份验证和授权。
- 根据您是要以用户身份还是以 Chat 应用的身份进行身份验证, 选择授权范围。
以用户身份邀请或添加用户加入聊天室
如需通过用户身份验证邀请用户或将用户添加到聊天室,请在请求中传递以下内容:
- 指定
chat.memberships
授权范围。 - 调用
CreateMembership()
方法。 - 将
parent
作为要在其中创建成员资格的聊天室的资源名称进行传递。 - 将
membership
作为Membership
的实例传递,并使用以下代码设置其字段member
:- 设置为
HUMAN
的type
字段。 - 将
name
字段设置为users/{user}
,其中{user}
是您要添加到聊天室的用户。如需指定 Chat 用户,请将{user}
替换为以下任一项:
- 设置为
以下示例通过用户身份验证将用户添加到聊天室:
Node.js
Python
Java
Apps 脚本
如需运行该示例,请替换以下内容:
SPACE_NAME
:聊天室的name
中的 ID。您可以通过调用ListSpaces()
方法或从聊天室的网址中获取 ID。USER_NAME
:用户 ID。
Chat API 会返回一个 Membership
实例,其中详细说明了创建的用户成员资格。
邀请 Google 群组或将群组添加到聊天室
如需通过用户身份验证邀请 Google 群组或将 Google 群组添加到聊天室(应用身份验证不支持向聊天室邀请或添加 Google 群组),请在请求中传递以下内容:
- 指定
chat.memberships
授权范围。 - 调用
CreateMembership()
方法。 - 将
parent
作为要在其中创建成员资格的聊天室的资源名称进行传递。 - 将
membership
作为Membership
的实例传递,并将groupMember
的字段name
设置为groups/{group}
,其中{group}
是您要创建成员资格的群组 ID。您可以使用 Cloud Identity API 检索群组的 ID。
您无法将 Google 群组中的群组添加到群聊或私信中,只能添加到命名聊天室中。
以下示例将群组添加到需要用户身份验证的命名聊天室:
Node.js
Python
Java
Apps 脚本
如需运行该示例,请替换以下内容:
SPACE_NAME
:聊天室的name
中的 ID。您可以通过调用ListSpaces()
方法或从聊天室的网址中获取 ID。GROUP_NAME
:群组 ID。
Chat API 会返回一个 Membership
实例,其中详细说明了创建的用户成员资格。
将 Chat 应用添加到聊天室
Chat 应用无法将其他应用添加为聊天室的成员。如需将 Chat 应用添加到聊天室或两位用户之间的私信中,请在请求中使用用户身份验证传递以下内容(应用身份验证不支持邀请或将 Chat 应用添加到聊天室):
- 指定
chat.memberships.app
授权范围。 - 调用
CreateMembership()
方法。 - 将
parent
作为要创建成员资格的聊天室的资源名称传递。 - 将
membership
作为Membership
的实例传递,并使用以下代码设置其字段member
:- 设置为
BOT
的type
字段。 name
字段设置为users/app
;一个别名,表示调用 Chat API 的应用。
- 设置为
以下示例将 Chat 应用添加到聊天室:
Node.js
Python
Java
Apps 脚本
如需运行示例,请将 SPACE_NAME
替换为聊天室的 name
中的 ID。您可以通过调用 ListSpaces()
方法或从聊天室的网址中获取 ID。
Chat API 会返回一个 Membership
实例,其中详细说明了创建的用户成员资格。
将用户作为 Chat 应用邀请或添加到聊天室
应用身份验证需要一次性管理员批准。
如需通过应用身份验证邀请用户或将用户添加到聊天室,请在请求中传递以下内容:
- 指定
chat.app.memberships
授权范围。 - 对
membership
资源调用create
方法。 - 将
parent
设置为要创建成员资格的聊天室的资源名称。 - 将
member
设置为users/{user}
,其中{user}
是您要为其创建会员资格的用户,并且符合以下条件之一:
创建 API 密钥
如需调用 Developer Preview API 方法,您必须使用相应 API 发现文档的非公开开发者预览版。如需对请求进行身份验证,您必须传递 API 密钥。
如需创建 API 密钥,请打开应用的 Google Cloud 项目,然后执行以下操作:
- 在 Google Cloud 控制台中,依次点击“菜单”图标 > API 和服务 > 凭据。
- 依次点击创建凭据 > API 密钥。
- 此时将显示您的新 API 密钥。
- 点击“复制”图标 以复制要在应用代码中使用的 API 密钥。您还可以在项目凭据的“API 密钥”部分找到 API 密钥。
- 点击限制密钥可更新高级设置并限制 API 密钥的使用。如需了解详情,请参阅应用 API 密钥限制。
编写用于调用 Chat API 的脚本
以下示例使用应用身份验证将用户添加到聊天室:
Python
- 在工作目录中,创建一个名为
chat_membership_app_create.py
的文件。 在
chat_membership_app_create.py
中添加以下代码:from google.oauth2 import service_account from apiclient.discovery import build # Define your app's authorization scopes. # When modifying these scopes, delete the file token.json, if it exists. SCOPES = ["https://www.googleapis.com/auth/chat.app.memberships"] def main(): ''' Authenticates with Chat API using app authentication, then adds a user to a Chat space by creating a membership. ''' # Specify service account details. creds = ( service_account.Credentials.from_service_account_file('credentials.json') .with_scopes(SCOPES) ) # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds, discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY') # Use the service endpoint to call Chat API. result = chat.spaces().members().create( # The space in which to create a membership. parent = 'spaces/SPACE', # Specify which user the membership is for. body = { 'member': { 'name':'users/USER', 'type': 'HUMAN' } } ).execute() # Prints details about the created membership. print(result) if __name__ == '__main__': main()
在代码中进行以下替换:
API_KEY
:您为构建 Chat API 服务端点而创建的 API 密钥。SPACE
:聊天室名称,您可以通过 Chat API 中的spaces.list
方法或聊天室的网址获取该名称。USER
:用户 ID。
在工作目录中,构建并运行示例:
python3 chat_membership_app_create.py
以 Google Workspace 管理员身份向聊天室添加用户或 Google 群组
如果您是 Google Workspace 管理员,则可以调用 create()
方法将用户、Google 群组或 Chat 应用添加到 Google Workspace 组织中的任何聊天室。
如需以 Google Workspace 管理员身份调用此方法,请执行以下操作:
如需了解详情和示例,请参阅以 Google Workspace 管理员身份管理 Google Chat 聊天室。
限制和注意事项
- 使用应用身份验证时,Chat 应用可以邀请或添加用户,但 Google 群组或 Chat 应用无法执行此操作。如需自行添加,Chat 应用必须使用
chat.memberships
授权范围的用户身份验证。