将 Microsoft Graph API 与 Microsoft Teams 结合使用Use the Microsoft Graph API to work with Microsoft Teams

重要

Microsoft Graph 中/beta的版本下的 api 可能会发生更改。APIs under the /beta version in Microsoft Graph are subject to change. 不支持在生产应用程序中使用这些 API。Use of these APIs in production applications is not supported.

Microsoft Teams 是 Office 365 中基于聊天的工作区,可提供对特定于团队的日历、文件、OneNote 笔记、规划器计划、排班计划等对象的内置访问权限。Microsoft Teams is a chat-based workspace in Office 365 that provides built-in access to team-specific calendars, files, OneNote notes, Planner plans, Shifts schedules, and more.

Microsoft Teams 中的重要资源Key resources in Microsoft Teams

资源Resource 方法Methods
团队team 列出你的团队列出所有团队创建读取更新删除克隆归档取消归档List your teams, list all teams, create, read, update, delete, clone, archive, unarchive
group 添加成员、 移除成员添加所有者、 移除所有者获取文件获取笔记本获取计划获取日历Add member, remove member, add owner, remove owner, get files, get notebook, get plans, get calendar
频道channel 列出创建读取更新删除List, create, read, update, delete
teamsTabteamsTab 列出创建读取更新删除List, create, read, update, delete
teamsAppteamsApp 列出发布更新移除List, publish, update, remove
teamsAppInstallationteamsAppInstallation 列出安装升级移除List, install, upgrade, remove
chatMessage(预览)chatMessage (preview) 列出发送读取List, send, read
调用(预览)call (preview) 应答拒绝重定向静音取消静音更新元数据更改屏幕共享角色列出参与者邀请参与者将所有参与者设为静音Answer, reject, redirect, mute, unmute, update metadata, change screen sharing role, list participants, invite participants, mute all participants
计划(预览)schedule (preview) 创建或替换获取共享Create or replace, get, share
schedulingGroup(预览)schedulingGroup (preview) 创建列出获取替换删除Create, List, Get, Replace, Delete
排班(预览)shift (preview) 创建列出获取替换删除Create, List, Get, Replace, Delete
timeOff(预览)timeOff (preview) 创建列出获取替换删除Create, List, Get, Replace, Delete
timeOffReason(预览)timeOffReason (preview) 创建列出获取替换删除Create, List, Get, Replace, Delete

用户和组Teams and groups

在 Microsoft Graph 中,Microsoft Teams 由资源表示。In Microsoft Graph, Microsoft Teams is represented by a group resource. Microsoft Teams 和 Office 365 组均可满足组协作的各种需求。Both Microsoft Teams and Office 365 groups address the various needs of group collaboration. 几乎所有基于组的功能都适用于 Microsoft Teams 和 Office 365 组,例如组日历、文件、笔记、照片、计划等。Almost all the group-based features apply to Microsoft Teams and Office 365 groups, such as group calendar, files, notes, photo, plans, and so on. 团队与 Office 365 组之间的主要区别在于成员之间的通信模式。The main difference between a team and an Office 365 group is the mode of communication between members. 团队成员的通信方式是在特定团队的上下文中进行持久聊天。Team members communicate by persistent chat in the context of a specific team. Office 365 组成员通过组对话进行通信,它们是在 Outlook 的组上下文中发生的电子邮件对话。Office 365 group members communicate by group conversations, which are email conversations that occur in the context of a group in Outlook.

具有团队的任何组都具有 resourceProvisioningOptions 属性,它包含“团队”。Any group that has a team has a resourceProvisioningOptions property that contains "Team".

注释: 可以更改 Group.resourceProvisioningOptions 属性。Note: The Group.resourceProvisioningOptions property can be changed. 请不要在该集合中添加或删除“团队”;否则,当你列出所有团队时,你将获得错误结果。Do not add or remove "Team" from that collection; otherwise, you'll get incorrect results when you list all teams.

以下是团队和组之间的 API 级别的区别:The following are the differences at the API level between teams and groups:

注意:如果在 Microsoft Teams 应用(而非独立应用中)使用组 API(例如,作为 Microsoft Teams 中运行的选项卡或自动程序的一部分),请按照在 Microsoft Teams 页面中使用 Microsoft Graph 一文中的说明操作。Note: If you use the groups API in a Microsoft Teams app rather than in a standalone app - for example as part of a tab or bot running in Microsoft Teams - follow the guidance in the article Using Microsoft Graph in your Microsoft Teams pages.

Microsoft Teams 中的成员身份更改Membership changes in Microsoft Teams

若要向团队添加成员和所有者,请使用相同的 ID 更改的成员身份。To add members and owners to a team, change the membership of the group with the same ID.

用例Use case 谓词Verb URLURL
添加成员Add member POSTPOST /groups/{id}/members/$ref/groups/{id}/members/$ref
删除成员Remove member DELETEDELETE /groups/{id}/members/{userId}/$ref/groups/{id}/members/{userId}/$ref
添加所有者Add owner POSTPOST /groups/{id}/owners/$ref/groups/{id}/owners/$ref
移除所有者Remove owner DELETEDELETE /groups/{id}/owners/{userId}/$ref/groups/{id}/owners/{userId}/$ref
更新团队Update team PATCHPATCH /teams/{id}/teams/{id}

我们建议你在添加所有者时,还将该用户添加为成员。We recommend that when you add an owner, you also add that user as a member. 如果团队的所有者不是其成员,则所有权和成员身份更改可能不会立即显示在 Microsoft Teams 中。If a team has an owner who is not also a member, ownership and membership changes might not show up immediately in Microsoft Teams. 此外,不同的应用程序和 API 将以不同的方式进行处理。In addition, different apps and APIs will handle that differently. 例如,Microsoft Teams 将显示用户是其成员或所有者的团队,而 Microsoft Teams PowerShell cmdlet 和 /me/joinedTeams API 仅显示用户是其成员的团队。For example, Microsoft Teams will show teams that the user is either a member or an owner of, while the Microsoft Teams PowerShell cmdlets and the /me/joinedTeams API will only show teams the user is a member of. 为了避免混淆,请也将全部所有者添加到成员列表中。To avoid confusion, add all owners to the members list as well.

已知问题:当调用 DELETE /groups/{id}/owners 时,也会从 /groups/{id}/members list 中移除用户。Known issue: when DELETE /groups/{id}/owners is called, the user is also removed from the /groups/{id}/members list. 若要解决此问题,我们建议你从所有者和成员中移除用户,等待 10 秒后,将其添加回成员。To work around this, we recommend that you remove the user from both owners and members, then wait 10 seconds, then add them back to members.

在添加和移除成员和所有者时,请勿在 ID 两边添加大括号 { }。When adding and removing members and owners, don't put braces { } around the ID.

速度Speed 语法Syntax
快速Fast https://graph.microsoft.com/beta/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members/48d31887-5fad-4d73-a9f5-3c356e68a038/$refhttps://graph.microsoft.com/beta/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members/48d31887-5fad-4d73-a9f5-3c356e68a038/$ref
慢速Slow https://graph.microsoft.com/beta/groups/{02bd9fd6-8f93-4758-87c3-1fb73740a315}/members/{48d31887-5fad-4d73-a9f5-3c356e68a038}/$refhttps://graph.microsoft.com/beta/groups/{02bd9fd6-8f93-4758-87c3-1fb73740a315}/members/{48d31887-5fad-4d73-a9f5-3c356e68a038}/$ref

同样,如果 URL 或有效负载中的 userId 显示为 UPN 而不是 GUID,则性能会变慢。Similarly, if the userId in the URL or payload is expressed as a UPN rather than as a GUID, the performance will be slower.

速度Speed 语法Syntax
快速Fast 48d31887-5fad-4d73-a9f5-3c356e68a03848d31887-5fad-4d73-a9f5-3c356e68a038
慢速Slow john@example.comjohn@example.com

当采用较慢的路径时,如果当前团队成员或所有者登录到 Microsoft Teams 应用程序/网站,则更改将在一小时内反映出来。When the slower path is taken, if a current team member or owner is signed in to the Microsoft Teams application/website, the change will be reflected within an hour. 如果这些用户都未登录到 Microsoft Teams 应用程序/网站,则更改将在其中一个用户登录后一小时内反映出来。If none of those users are signed in to the Microsoft Teams application/website, the change will not be reflected until an hour after one of them signs in.

备注

租户来宾始终通过慢速路径进行处理。Tenant guests are always processed via the slow path.

另请参阅See also

Microsoft Teams API 概述Microsoft Teams API overview