列出人员
命名空间：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/