列出人员

命名空间：microsoft.graph

检索一组 person 对象，这些对象按与 user 的相关程度进行排序，相关程度由用户的通信和协作模式以及业务关系决定。

可以通过 People API 获取此信息。 有关示例，请参阅示例部分和文章使用 People API 获取与你最相关的人员的信息。

注意

对于新开发，我们建议将 Microsoft 搜索 API (POST /search/query 与) 一起使用entityTypes: ["person"]，而不是People API (GET /me/people 和 GET /users/{id | userPrincipalName}/people) 。 People API 处于维护模式。 有关详细信息，请参阅 searchEntity：查询 和 使用 Microsoft 搜索 API 搜索人员。

此 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 关键字，以根据从与此人的电子邮件对话中提取的主题查找人员。 有关信息和示例，请参阅 使用 People API 获取与你最相关的人员的信息，以执行模糊搜索部分。
$select string 要在响应中添加的属性列表（以逗号分隔）。 为了获得最佳性能，只需选择所需的属性子集。
$skip int 跳过前 n 个结果，对分页很有用。 使用 $search 时不支持此功能。
$top int 要在结果页上返回的最大结果数。 有关详细信息，请参阅 top 参数。

请求标头

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

请求正文

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

响应

如果成功，此方法将在响应正文中返回响应 200 OK 代码和 人员 对象的集合。 响应可以包含一个 person 对象或 person 对象的集合。

示例

请求

以下示例显示了一个请求。

GET https://graph.microsoft.com/v1.0/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,
            "jobTitle": null,
            "companyName": null,
            "yomiCompany": "",
            "department": null,
            "officeLocation": null,
            "profession": "",
            "userPrincipalName": "",
            "imAddress": null,
            "scoredEmailAddresses": [
                {
                    "address": "Marketing@contoso.com",
                    "relevanceScore": 30.0
                }
            ],
            "phones": [],
            "postalAddresses": [],
            "websites": [],
            "personType": {
                "class": "Group",
                "subclass": "UnifiedGroup"
            }
        },
        {
            "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",
            "displayName": "Isaiah Langer",
            "givenName": "Isaiah",
            "surname": "Langer",
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "jobTitle": "Web Marketing Manager",
            "companyName": null,
            "yomiCompany": "",
            "department": "Sales & Marketing",
            "officeLocation": "20/1101",
            "profession": "",
            "userPrincipalName": "IsaiahL@contoso.com",
            "imAddress": "sip:isaiahl@contoso.com",
            "scoredEmailAddresses": [
                {
                    "address": "IsaiahL@contoso.com",
                    "relevanceScore": 20.0
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "personType": {
                "class": "Person",
                "subclass": "OrganizationUser"
            }
        }
    ]
}

相关内容

  • Last updated on