在 Microsoft Graph 中使用组Working with groups in Microsoft Graph

组是用户和其他主体的集合,他们共享对 Microsoft 服务或应用中资源的访问权限。Groups are collections of users and other principals who share access to resources in Microsoft services or in your app. Microsoft Graph 提供了可用于根据方案创建和管理不同类型组和组功能的 API。Microsoft Graph provides APIs that you can use to create and manage different types of groups and group functionality according to your scenario. Microsoft Graph 中所有与组相关的操作都需要征得管理员同意。All group-related operations in Microsoft Graph require administrator consent.

注意:只能通过工作或学校帐户创建组。Note: Groups can only be created through work or school accounts. 个人 Microsoft 帐户不支持组。Personal Microsoft accounts don't support groups.

类型Type 用例Use case groupTypegroupType 启用邮件mail-enabled 启用安全机制security-enabled 可以通过 API 创建和管理吗?Can be created and managed via API?
Office 365 组Office 365 groups 促进用户与共享 Microsoft Online 资源的协作。Facilitating user collaboration with shared Microsoft online resources. ["Unified"] true false 可访问Yes
安全组Security groups 控制用户对应用中资源的访问。Controlling user access to in-app resources. [] false true Yes
启用邮件的安全组Mail-enabled security groups 使用共享的组邮箱,控制用户对应用中资源的访问。Controlling user access to in-app resources, with a shared group mailbox. [] true true No
通讯组Distribution groups 将邮件分发给组中的成员。Distributing mail to the members of the group. 建议使用 Office 365 组,因为它提供的资源集更丰富。It is recommended to use Office 365 groups due to the richer set of resources it provides. [] true false No

Office 365 组Office 365 groups

Office 365 组的强大之处在于它的协作本质,它是项目或团队中相互协作的用户的理想之选。The power of Office 365 groups is in its collaborative nature, perfect for people who work together on a project or a team. 创建时,它们包含组成员共享的资源,包括:They are created with resources that members of the group share, including:

  • Outlook 对话Outlook conversations
  • Outlook 日历Outlook calendar
  • SharePoint 文件SharePoint files
  • OneNote 笔记本OneNote notebook
  • SharePoint 团队网站SharePoint team site
  • Planner 计划Planner plans
  • Intune 设备管理Intune device management

Outlook 中的组示例Group in Outlook example

下面是 Outlook 中组的 JSON 表示形式。The following is a JSON representation of groups in Outlook.


{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "4c5ee71b-e6a5-4343-9e2c-4244bc7e0938",
    "deletedDateTime": null,
    "classification": "MBI",
    "createdDateTime": "2016-08-23T14:46:56Z",
    "description": "This is a group in Outlook",
    "displayName": "OutlookGroup101",
    "groupTypes": [
        "Unified"
    ],
    "mail": "outlookgroup101@service.microsoft.com",
    "mailEnabled": true,
    "mailNickname": "outlookgroup101",
    "preferredLanguage": null,
    "proxyAddresses": [
        "smtp:outlookgroup101@microsoft.onmicrosoft.com",
        "SMTP:outlookgroup101@service.microsoft.com"
    ],
    "securityEnabled": false,
    "theme": null,
    "visibility": "Public"
}

若要详细了解 Office 365 组和管理员体验,请参阅了解 Office 365 组To learn more about Office 365 groups and the administrator experiences, see Learn about Office 365 Groups.

安全组和启用邮件的安全组Security groups and mail-enabled security groups

安全组用于控制用户对资源的访问。Security groups are for controlling user access to resources. 通过检查用户是否是安全组的成员,应用可以在用户尝试访问应用中的某些安全资源时决定是否授权。By checking whether a user is a member of a security group, your app can make authorization decisions when that user is trying to access some secure resources in your app. 安全组的成员可以是用户和其他安全组。Security groups can have users and other security groups as members.

启用邮件的安全组的使用方式与安全组基本相同,不同之处在于添加了组的共享邮箱功能。Mail-enabled security groups are used in the same way that security groups are, but with the added feature of a shared mailbox for the groups. 无法通过 API 创建启用邮件的安全组,但其他组操作仍适用。Mail-enabled security groups can't be created through the API, but other group operations work. 启用邮件的安全组为只读。Mail-enabled security groups are read only. 若要了解更多信息,请参阅 Exchange 文章管理启用邮件的安全组Learn more in the Manage mail-enabled security groups Exchange article.

安全组示例Security group example

下面是安全组的 JSON 表示形式。The following is a JSON representation of a security group.

{
    "@odata.type": "#microsoft.graph.group",
    "id": "f87faa71-57a8-4c14-91f0-517f54645106",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2016-07-20T09:21:23Z",
    "description": "This group is a Security Group",
    "displayName": "SecurityGroup101",
    "groupTypes": [],
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "",
    "preferredLanguage": null,
    "proxyAddresses": [],
    "securityEnabled": true
}

动态成员资格Dynamic membership

所有类型的组都可以有成员资格规则,用于根据用户属性自动在组中添加或删除成员。All types of groups can have dynamic membership rules that automatically add or remove members from the group based on user properties. 例如,“市场营销部员工”组包含所有 department 属性设置为“Marketing”的用户,这样可以将新入职的市场营销部员工自动添加到组中,并自动在组中删除从市场营销部离职的员工。For example, a "Marketing employees" group would include every user with the department property set to "Marketing", so that new marketing employees are automatically added to the group and employees who leave the department are automatically removed from the group. 在组创建期间,可以在“membershipRule”字段中将此规则指定为 "membershipRule": 'user.department -eq "Marketing"'This rule can be specified in a "membershipRule" field during group creation as "membershipRule": 'user.department -eq "Marketing"'. GroupType 还必须包括 "DynamicMembership"GroupType must also include "DynamicMembership". 下面的请求为市场营销部员工新建 Office 365 组:The following request creates a new Office 365 group for the marketing employees:

POST https://graph.microsoft.com/beta/groups
{
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mailEnabled": true,
    "mailNickname": "marketing",
    "securityEnabled": false,
    "membershipRule": 'user.department -eq "Marketing"',
    "membershipRuleProcessingState": "on"
}

若要详细了解如何表述 membershipRules,请参阅在 Azure Active Directory 中创建基于属性的动态组成员资格规则To learn more about formulating membershipRules, see Create attribute-based rules for dynamic group membership in Azure Active Directory.

注意:动态成员资格规则要求租户必须在 Azure Active Directory Premium P1 或更高层拥有许可证。Note: Dynamic membership rules requires the tenant to have a license at tier Azure Active Directory Premium P1 or greater.

其他类型的组Other types of groups

Yammer 中的 office 365 组用于通过 Yammer 帖子促进用户协作。Office 365 groups in Yammer are used to facilitate user collaboration through Yammer posts. 可以通过读取请求返回这种类型的组,但无法通过 API 访问它们的帖子。This type of group can be returned through a read request, but their posts can't be accessed through the API. 如果对组启用了 Yammer 帖子和对话源,将会禁用默认的 Office 365 组对话。When Yammer posts and conversation feeds are enabled on a group, default Office 365 group conversations are disabled. 若要了解详细信息,请参阅 Yammer 开发人员 API 文档To learn more, see Yammer developer API docs.

基于组的许可Group-based licensing

可以使用基于组的许可将一个或多个产品许可证分配给 Azure AD 组。You can use group-based licensing to assign one or more product licenses to an Azure AD group. Azure AD 可确保许可证分配给组的所有成员。Azure AD ensures that the licenses are assigned to all members of the group. 任何加入该组的新成员都获得了相应的许可证。Any new members who join the group are assigned the appropriate licenses. 他们离开组时,将移除这些许可证。When they leave the group, those licenses are removed. 功能只能与安全组和有 securityEnabled=TRUE 的 Office 365 组一起使用。The feature can only be used with security groups and Office 365 groups that have securityEnabled=TRUE. 若要了解基于组的许可的详细信息,请参阅什么是 Azure Active Directory 中基于组的许可?To learn more about group-based licensing, see What is group-based licensing in Azure Active Directory?.

常见用例Common use cases

使用 Microsoft Graph,可以执行下面的常见操作。Using Microsoft Graph, you can perform the following common operations.

用例Use cases REST 资源REST resources 另请参阅See also
组对象和方法Group object and methods
创建新组、获取现有组、更新组的属性和删除组。Create new groups, get existing groups, update the properties on groups, and delete groups. 目前,只有 Outlook 中的安全组和组才能通过 API 创建。Currently, only security groups and groups in Outlook can be created through the API. groupgroup 新建组Create new groups
列出组List groups
更新组Update groups
删除组Delete groups
组成员资格方法Group membership methods
列出组中的成员,并添加或删除成员。List the members of a group, and add or remove members. useruser
groupgroup
列出成员List members
添加成员Add member
删除成员Remove member
确定用户是否是组成员,并获取用户所属的全部组。Determine whether a user is a member of a group, get all the groups the user is a member of. useruser
groupgroup
检查成员组Check member groups
获取成员组Get member groups
列出组的所有者,并添加或删除所有者。List the owners of a group, and add or remove owners. useruser
groupgroup
列出所有者List owners
添加成员Add member
删除成员Remove member