本指南介绍了如何使用 Google Chat API 的 Membership
资源中的 create()
方法来邀请或添加用户、Google 群组或 Chat 应用加入聊天室,也称为创建成员资格。创建会员时,如果指定会员关闭了自动接受政策,则系统会向其发送邀请,并且该会员必须接受群组邀请才能加入。否则,创建会员资格会将相应成员直接添加到指定聊天室。
如果您是 Google Workspace 管理员,则可以将用户、Google 群组或 Chat 应用添加到 Google Workspace 组织中的任何聊天室。
Membership
资源表示人工用户或 Google Chat 应用是否受邀加入聊天室、是否是聊天室的成员,或者是否不在聊天室中。
前提条件
Node.js
- 拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
- 设置环境:
- 创建 Google Cloud 项目。
- 配置 OAuth 同意屏幕。
- 启用并配置 Google Chat API,为您的 Chat 应用指定名称、图标和说明。
- 安装 Node.js Cloud 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式,创建访问凭据:
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据保存为名为
credentials.json
的 JSON 文件,保存到本地目录。 - 如需以 Chat 应用的身份进行身份验证,请创建服务账号凭据,并将该凭据保存为名为
credentials.json
的 JSON 文件。
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据保存为名为
- 选择授权范围,具体取决于您是想以用户身份还是以 Chat 应用身份进行身份验证。
Python
- 拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
- 设置环境:
- 创建 Google Cloud 项目。
- 配置 OAuth 同意屏幕。
- 启用并配置 Google Chat API,为您的 Chat 应用指定名称、图标和说明。
- 安装 Python Cloud 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式,创建访问凭据:
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据保存为名为
credentials.json
的 JSON 文件,保存到本地目录。 - 如需以 Chat 应用的身份进行身份验证,请创建服务账号凭据,并将该凭据保存为名为
credentials.json
的 JSON 文件。
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据保存为名为
- 选择授权范围,具体取决于您是想以用户身份还是以 Chat 应用身份进行身份验证。
Java
- 拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
- 设置环境:
- 创建 Google Cloud 项目。
- 配置 OAuth 同意屏幕。
- 启用并配置 Google Chat API,为您的 Chat 应用指定名称、图标和说明。
- 安装 Java Cloud 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式,创建访问凭据:
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据保存为名为
credentials.json
的 JSON 文件,保存到本地目录。 - 如需以 Chat 应用的身份进行身份验证,请创建服务账号凭据,并将该凭据保存为名为
credentials.json
的 JSON 文件。
- 如需以 Chat 用户身份进行身份验证,请创建 OAuth 客户端 ID 凭据,并将凭据保存为名为
- 选择授权范围,具体取决于您是想以用户身份还是以 Chat 应用身份进行身份验证。
Apps 脚本
- 拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
- 设置环境:
- 创建 Google Cloud 项目。
- 配置 OAuth 同意屏幕。
- 启用并配置 Google Chat API,为您的 Chat 应用指定名称、图标和说明。
- 创建独立的 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 密钥
如需调用开发者预览版 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.memberships
授权范围的用户身份验证。