列出人员

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

检索按用户相关性排序 的人员 对象 列表，该列表由用户的通信和协作模式以及业务关系决定。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） People.Read People.Read.All
委派（个人 Microsoft 帐户） People.Read 不可用。
应用程序 People.Read.All 不可用。

HTTP 请求

GET /me/people
GET /users/{id | userPrincipalName}/people

可选的查询参数

此方法支持以下 OData 查询参数来帮助自定义响应。

名称 值 说明
$filter string 将响应限制为仅记录中包含指定条件的那些人员。
$orderby string 默认情况下，按与查询的相关程度对响应中的人员进行排序。 可以使用 $orderby 参数更改响应中的人员排序。
$search string 按姓名或别名搜索人员。 支持模糊匹配。 参数仅适用于搜索已登录用户的相关人员，而不适用于搜索与其他用户相关的人员。 此外还支持 topic 关键字，以根据从与此人的电子邮件对话中提取的主题查找人员。 有关信息和示例，请参阅使用人员 API 获取与你最相关的人员的信息中的执行模糊搜索部分。
$select string 要在响应中添加的属性列表（以逗号分隔）。 为了获得最佳性能，请仅选择所需的属性子集。
$skip int 跳过前 n 个结果，这对于分页很有用。 使用 $search 时不支持跳过。
$top int 在结果页上返回的最大结果数。 有关详细信息，请参阅 top 参数。

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
接受 application/json

请求正文

请勿提供此方法的请求正文。

响应

如果成功，此方法在响应正文中返回响应 200 OK 代码和 person 对象的集合。

示例

浏览

本部分中的请求基于通信、协作和业务关系，获取与已登录用户 (/me) 最相关的人员。

默认情况下，每个响应都会返回10条记录，但您可以 改变这点 使用 $顶部 参数。 这些请求需要人员。读取权限。

请求

下面是默认请求的示例。

GET https://graph.microsoft.com/beta/me/people

响应

以下示例显示了相应的响应。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "33b43a5b-87d6-41ec-91f8-a2610048105f",
            "displayName": "Marketing",
            "givenName": null,
            "surname": null,
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": null,
            "companyName": null,
            "yomiCompany": "",
            "department": null,
            "officeLocation": null,
            "profession": "",
            "mailboxType": "GroupMailbox",
            "personType": "ModernGroup",
            "userPrincipalName": "",
            "emailAddresses": [
                {
                    "address": "Marketing@contoso.com",
                    "rank": 30
                }
            ],
            "phones": [],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        },
        {
            "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",
            "displayName": "Isaiah Langer",
            "givenName": "Isaiah",
            "surname": "Langer",
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": "Web Marketing Manager",
            "companyName": null,
            "yomiCompany": "",
            "department": "Sales & Marketing",
            "officeLocation": "20/1101",
            "profession": "",
            "mailboxType": "Mailbox",
            "personType": "Person",
            "userPrincipalName": "IsaiahL@contoso.com",
            "emailAddresses": [
                {
                    "address": "IsaiahL@contoso.com",
                    "rank": 20
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        }
    ]
}

请求人员的后续页面。

如果第一个响应不包含相关人员的完整列表，则可以使用 $top 和 $skip 发出第二个请求，以请求更多信息页。 如果 先前的请求 有附加信息，以下请求可从服务器获取下一页的人员。

GET https://graph.microsoft.com/beta/me/people/?$top=10&$skip=10

对响应进行排序

默认情况下，按与查询的相关程度对响应中的人员进行排序。 可以使用 $orderby 参数更改响应中的人员排序。 此查询选择与您最相关的人员，按他们的显示名称对他们进行排序，然后返回排序列表中的前10个人。

GET https://graph.microsoft.com/beta/me/people/?$orderby=DisplayName

更改返回的人数和返回的字段

可以通过设置 $top 参数更改响应中返回的人员数。

以下示例请求与 最相关的 /me1,000 人。 请求还通过仅请求人员的显示名称来限制从服务器发送回的数据量。

GET https://graph.microsoft.com/beta/me/people/?$top=1000&$select=DisplayName

选择要返回的字段

可以使用 $select 参数选择一个或多个字段来限制从服务器返回的数据量。 该 @ odata.id 字段总会返回。

以下示例将响应限制为 10 个最相关的人的 DisplayName 和 EmailAddress 。

GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses

使用过滤来限制响应

可以使用 $filter 参数将响应限制为记录中包含指定条件的那些人员。

以下查询将响应限制为源为“Directory”的人员。

GET https://graph.microsoft.com/beta/me/people/?$filter=Sources/Any (source: source/Type  eq 'Directory')

选择要在筛选的响应中返回的字段

可以结合 $select 和 $filter 参数创建自定义用户相关人员列表，并且只获取应用程序需要的字段。

以下示例获取其 显示 名称等于指定名称的人员的 DisplayName 和 EmailAddress 。 在本示例中，只返回显示名称等于“Nestor Kellum”的人。

+GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses&$filter=DisplayName eq 'Nestor Kellum'

搜索人员

本部分中的请求还会获取与已登录用户最相关的人员 (/me) 。 搜索请求需要人员。读取权限。

使用搜索选择人员

使用 $search 参数选择符合某组特定条件的人员。

以下搜索查询返回与其 GivenName 或 Surname 以字母“j”开头的相关 /me 人员。

GET https://graph.microsoft.com/beta/me/people/?$search=j

使用搜索来指定相关主题

以下请求返回与名称包含“ma”且与“功能规划”关联的相关 /me 人员。

GET https://graph.microsoft.com/beta/me/people/?$search="ma topic: feature planning"

以下请求对名为“Hermaini Hall”的人员进行搜索。由于有一个名为“Herminia Hull”的人员与登录用户相关，因此将返回“Herminia Hull”的信息。

GET https://graph.microsoft.com/beta/me/people/?$search="hermaini hall"

以下请求获取与用户组织中的另一个人最相关的人员。 此请求需要 User.ReadBasic.All 人员。Read.All 权限。 在此示例中，将显示 Nestor Kellum 的相关人员。

GET https://graph.microsoft.com/beta/users('nestork@contoso.com')/people/