使用 Microsoft Graph 人员 API 获取与你最相关的人员的信息

项目
10/18/2023

Microsoft Graph 应用程序可以使用人员 API 检索与用户最相关的人员。相关性由用户的通信和协作模式及业务关系决定。人员可以是本地联系人，也可以来自组织目录，也可以来自最近通信的人。

除了生成此见解外，人员 API 还提供模糊匹配搜索支持，以及检索与登录用户组织中其他用户相关的用户列表功能。

人员 API 对于人员选择方案（例如撰写电子邮件或创建会议）非常有用。例如，可以在电子邮件撰写方案中使用人员 API。

将某人纳入相关人员或"正在处理"人员

若要将人员作为与 Delve 中的配置文件所有者相关联或与之"合作"，要显示在所有者的个人资料卡片中或由人员 API 返回，则该人员与配置文件所有者之间必须存在公共关系。下图显示了用户 A、与其他用户（用户 B）的关系的索引，以及显示用户关系子集的公共配置文件。

“同事”关系的图像

下面是公共关系的示例：

在组织结构图中连接的个人：经理、直接下属、 (共享同一经理)
人数少于 30 的公共组或通讯组列表的成员。公共组具有可在目录中找到的成员身份列表。

如果配置文件所有者与某人通信，并且他们之间没有公共关系，例如组织结构图连接或共同的组，则他们一直在通信的事实对其他人不可见。

人员的排名（即他们在配置文件所有者页面上的显示顺序）由个人资料所有者与列表中的人员之间的公共通信决定。

公共交互的示例包括：

作为公共组的一部分相互发送或接收电子邮件
作为组的一部分，或在已邀请了超过 X 名用户的情况下邀请用户参加会议

排名不会根据用户 A（查看其他人的页面的用户）的身份发生变化。排名由用户 B（配置文件所有者）和用户 C（显示在配置文件所有者的列表中）之间的交互级别确定。

若要显示用户 C，配置文件所有者必须位于一个相对较小的组或通讯组列表中，该用户是公共用户 (这意味着成员资格列表在目录中) 。

组织外部的人员不会显示在配置文件所有者的列表中。人员他们通过电子邮件发送或会面，但不属于同一组织的人员，则不会像所有者一起工作的人一样出现。

禁用"正在使用"

管理员可以在两个级别管理与配置文件所有者相关的人员显示或返回：

对于组织：
- 为整个组织启用。这是默认设置。
- 禁用整个组织，而不是配置文件所有者。
对于组织中的Microsoft Entra组：
- 为指定的Microsoft Entra组禁用。这对于为除Microsoft Entra组中的成员以外的组织启用“使用”非常有用。

有关详细信息，请参阅自定义人员见解隐私控制。

Authorization

若要在 Microsoft Graph 中调用人员 API，你的应用需要相应的权限：

People.Read - 用于进行常规的个人资料 API 调用；例如 https://graph.microsoft.com/v1.0/me/people/。 People.Read 需要获得最终用户的同意。
People.Read.All - 在进行检索与登录用户组织中指定用户相关度最高的人员 (https://graph.microsoft.com/v1.0/users/{id}/people) 调用时需要。 People.Read.All 需要获得管理员的同意。

浏览人员

本部分中的请求可获取与已登录用户 () /me 或已登录用户组织中的特定用户最相关的人员。这些请求需要人员。读取或人员。Read.All 权限分别。默认情况下，每个响应返回 10 条记录，但可以使用 $top 查询参数更改此内容。

获取相关人员集合。

以下请求根据通信和协作模式及业务关系获取与登录用户 (/me) 相关度最高的人员。

GET https://graph.microsoft.com/v1.0/me/people/

以下示例显示了相应的响应。默认情况下，每个响应返回 10 条记录。可以使用 $top 查询参数更改此设置。此示例使用 $top 将响应限制为三条记录。

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

请求后续人员页面

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

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

以下示例显示了相应的响应。默认情况下，每个响应返回 10 条记录。可以使用 $top 查询参数更改此设置。此示例使用 $top 将响应限制为三条记录。

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

{
  "value": [
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola",
      "givenName": "Felix",
      "surname": "Coppola",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Legal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2109",
      "profession": "",
      "userPrincipalName": "FelixC@contoso.com",
      "imAddress": "sip:FelixC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "FelixC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0104"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland",
      "givenName": "Lenora",
      "surname": "Rowland",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/1106",
      "profession": "",
      "userPrincipalName": "LenoraR@contoso.com",
      "imAddress": "sip:LenoraR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LenoraR@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 954 555 0118"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette",
      "givenName": "Manuel",
      "surname": "Collette",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Accountant II",
      "companyName": null,
      "yomiCompany": "",
      "department": "Finance",
      "officeLocation": "98/2202",
      "profession": "",
      "userPrincipalName": "ManuelC@contoso.com",
      "imAddress": "sip:ManuelC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ManuelC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+20 255501070"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

对响应进行排序

默认情况下，响应中的人员按其与查询的相关性进行排序。可以使用 $orderby 参数更改响应中人员的顺序。此查询选择与你最相关的人员，按其 displayName 对其进行排序，然后返回排序列表中的前 10 个人。

GET https://graph.microsoft.com/v1.0/me/people/?$orderby=displayName

以下示例显示了相应的响应。默认情况下，每个响应返回 10 条记录。可以使用 $top 参数更改此设置。以下示例使用 $top 将响应限制为三条记录。

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

{
  "value": [
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos",
      "givenName": "Adriana",
      "surname": "Ramos",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/2111",
      "profession": "",
      "userPrincipalName": "AdrianaR@contoso.com",
      "imAddress": "sip:AdrianaR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AdrianaR@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 425 555 0109"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley",
      "givenName": "Alyce",
      "surname": "Cooley",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "131/1104",
      "profession": "",
      "userPrincipalName": "AlyceC@contoso.com",
      "imAddress": "sip:AlyceC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyceC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 858 555 0110"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke",
      "givenName": "Alyssa",
      "surname": "Clarke",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Corporate Security Officer",
      "companyName": null,
      "yomiCompany": "",
      "department": "Operations",
      "officeLocation": "24/1106",
      "profession": "",
      "userPrincipalName": "AlyssaC@contoso.com",
      "imAddress": "sip:AlyssaC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyssaC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 262 555 0106"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

更改返回的人员和字段数

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

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

GET https://graph.microsoft.com/v1.0/me/people/?$top=1000&$Select=displayName

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

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye"
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman"
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey"
    },
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Roscoe Seidel"
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke"
    },
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos"
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley"
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Wayne Leeper"
    },
    {
      "id": "E7D40AC5-0078-4575-B1F3-F738124C4BC9",
      "displayName": "Jan Travis"
    },
    {
      "id": "6F99D1CC-4FCC-49E4-9160-E8AB01BF3E83",
      "displayName": "Charlotte Delacruz"
    },
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola"
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland"
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette"
    }
  ]
}

包含的结果类型

默认情况下，Microsoft Graph 只为邮箱提供你所保存的联系人或最有可能与你互动的人的结果。要检索整个组织范围的目录结果，请如下所示指定一个 HTTP 标头。

"X-PeopleQuery-QuerySources: Mailbox,Directory”

选择要返回的字段

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

以下示例将响应限制为 10 个相关度最高人员的 displayName 和 scoredEmailAddresses。

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses

以下示例显示了相应的响应。默认情况下，每个响应返回 10 条记录。可以使用 $top 参数更改此设置。此示例使用 $top 将响应限制为三条记录。

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

使用筛选器限制响应

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

以下查询将响应限制为包含 personType 属性的 person 实例，该属性将 person 分配为类，将 organizationUser 分配为子类。

GET https://graph.microsoft.com/v1.0/me/people/?$filter=personType/class eq 'Person' and personType/subclass eq 'OrganizationUser'

以下示例显示了相应的响应。默认情况下，每个响应返回 10 条记录。可以使用 $top 参数更改此设置。此示例使用 $top 将响应限制为三条记录。

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

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

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

以下示例获取其显示名称等于指定名称的人员的 displayName 和 scoredEmailAddresses 。在此示例中，仅返回显示名称等于“Lorrie Frye”的用户。

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses&$filter=displayName eq 'Lorrie Frye'

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

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

浏览其他用户的相关人员

以下请求获取与登录用户组织中的其他人员相关度最高的人员，例如在实现参与工作功能中所述。此请求需要具有 People.Read.All 权限。上节所述的所有查询参数也都适用。

在本示例中显示了 Roscoe Seidel 的相关人员。

GET https://graph.microsoft.com/v1.0/users('roscoes@contoso.com')/people/

以下示例显示了相应的响应。默认情况下，每个响应返回 10 条记录。可以使用 $top 参数更改此设置。以下示例使用 $top 将响应限制为三条记录。

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

{
  "value": [
    {
      "id": "56155636-703F-47F2-B657-C83F01F49BBC",
      "displayName": "Clifton Clemente",
      "givenName": "Clifton",
      "surname": "Clemente",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Director",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2106",
      "profession": "",
      "userPrincipalName": "CliftonC@contoso.com",
      "imAddress": "sip:CliftonC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "CliftonC@contoso.com",
          "relevanceScore": 20
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BF27D5A-AB4F-4C43-BED0-7DAD9EB0C1C4",
      "displayName": "Sheree Mitchell",
      "givenName": "Sheree",
      "surname": "Mitchell",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/2107",
      "profession": "",
      "userPrincipalName": "ShereeM@contoso.com",
      "imAddress": "sip:ShereeM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ShereeM@contoso.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0107"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "B3E5302D-EAF0-4E8B-8C6C-A2AE64B4B163",
      "displayName": "Vincent Matney",
      "givenName": "Vincent",
      "surname": "Matney",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Engineering",
      "companyName": null,
      "yomiCompany": "",
      "department": "Engineering",
      "officeLocation": "23/2102",
      "profession": "",
      "userPrincipalName": "VincentM@contoso.com",
      "imAddress": "sip:VincentM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "VincentM@contoso.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 502 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

搜索人员

通过本部分中的请求，可以搜索与已登录用户 (/me) 以及已登录用户组织中的其他用户相关的人员。这些请求需要人员。读取权限，但搜索其他用户的相关人员除外，这需要人员。Read.All。默认情况下，每个响应返回 10 条记录，但可以使用 $top 参数更改此内容。

使用搜索选择人员

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

以下搜索查询返回与 /me 相关且 displayName 或 emailAddress 包含以字母“j”开头的单词的人员。

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

以下示例显示了相应的响应。默认情况下，每个响应返回 10 条记录。可以使用 $top 参数更改此设置。此示例使用 $top 将响应限制为三条记录。

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

{
  "value": [
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Jan Travis",
      "givenName": "Jan",
      "surname": "Travis",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "VP Sales",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "19/3123",
      "profession": "",
      "userPrincipalName": "JanT@contoso.com",
      "imAddress": "sip:JanT@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "JanT@contoso.com",
          "relevanceScore": -12.297347783416837
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 732 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "C43BF05E-5B6B-4DCF-B2FC-0837B09E0FA9",
      "displayName": "Jacob Cazares (TAILSPIN)",
      "givenName": null,
      "surname": null,
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JacobC@tailspintoys.com",
          "relevanceScore": -12.298154282019846
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "PersonalContact"
      }
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Jewell Montgomery",
      "givenName": "Jewell",
      "surname": "Montgomery",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "JewellM@contoso.com",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JewellM@contoso.com",
          "relevanceScore": -12.531408487977451
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

执行模糊搜索

搜索实现模糊匹配算法。它们基于完全匹配以及有关搜索意向的推断返回结果。例如，假设用户显示名称为“Tyler Lee”，电子邮件地址为 tylerle@example.com，用户位于登录用户的 people 集合中。以下所有搜索都会将此用户 Tyler 作为结果之一返回。

GET https://graph.microsoft.com/v1.0/me/people?$search="tyler"                //matches both Tyler's name and email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle"              //matches Tyler's email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle@example.com"  //matches Tyler's email. Note the quotes to enclose '@'.
GET https://graph.microsoft.com/v1.0/me/people?$search="tiler"                //fuzzy match with Tyler's name
GET https://graph.microsoft.com/v1.0/me/people?$search="tyler lee"            //matches Tyler's name. Note the quotes to enclose the space.

通过

使用 Microsoft Graph 人员 API 获取与你最相关的人员的信息

将某人纳入相关人员或"正在处理"人员

禁用"正在使用"

Authorization

浏览人员

获取相关人员集合。

请求后续人员页面

对响应进行排序

更改返回的人员和字段数

包含的结果类型

选择要返回的字段

使用筛选器限制响应

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

浏览其他用户的相关人员

搜索人员

使用搜索选择人员

执行模糊搜索

反馈

其他资源