培训
认证
Microsoft 365 Certified: Administrator Expert - Certifications
如果你是部署和管理 Microsoft 365 并执行 Microsoft 365 租户级云和混合环境的实现和管理的管理员,则此认证最适合你。
Microsoft Graph 应用程序可以使用 Microsoft 搜索 API 检索与用户最相关的人员。 相关性由用户的通信和协作模式及业务关系决定。 人员可以是本地联系人,也可以是来自组织的目录或最近通信的人员。
除了生成此见解,搜索还提供模糊匹配搜索支持,并能够检索与已登录用户组织中的其他用户相关的用户列表。
可以使用以下 API 搜索组织内部的人员。
备注
我们建议用户调用终结点而不是/search
/people
终结点。 今后,所有未来的投资将仅在终结点中 /search
可用; /people
终结点处于维护模式。
people API 返回以下属性集。
属性 | 类型 |
---|---|
additionalOfficeLocation | String |
CompanyName | String |
department | String |
displayName | String |
emailAddress | String |
givenName | String |
hitId | String |
imAddress | String |
jobTitle | String |
officeLocation | String |
personType | String |
phones | String |
排名 | 整数 |
摘要 | String |
surname | String |
userPrincipalName | String |
下表显示了人员 API 中支持的人员类型和子类型。
支持的人员、组和会议室变体 | 收件人类型详细信息 | 邮箱 | 目录 | 人员类型 | 人员子类型 | 注释 |
---|---|---|---|---|---|---|
组织用户 | UserMailbox、MailUser | Y | Y | 个人 | OrganizationUser | 属于组织的用户。 |
没有电子邮件地址的组织用户 | 用户 | Y (默认关闭) | Y (默认关闭) | 个人 | OrganizationUser | 属于组织的用户。 |
组织联系人 | MailContact、Contact | N | Y | 个人 | OrganizationContact | 租户管理员 (GAL) 显式添加到全局地址列表的联系人,但这不是组织的一部分。 |
私人联系人 | 联系人 | Y | 不适用 | 个人 | PersonalContact | 由不属于组织的用户显式创建的联系人。 如果用户手动将其联系人添加到组织中的某个人,则仍会将其归类为 OrganizationUser 。 |
没有电子邮件地址的专用联系人 | 联系人 | Y (默认关闭) | 不适用 | 个人 | PersonalContact | 由不属于组织的用户显式创建的联系人。 如果用户手动将其联系人添加到组织中的某个人,则仍会将其归类为 OrganizationUser 。 |
来自通信历史记录的隐式接触 | 联系人 | Y | 不适用 | 个人 | ImplicitContact | 从通信历史记录推断的联系人 (电子邮件和聊天) ,我们没有足够的信息来确定该联系人是否是人员、组等。在业务帐户上,这始终是外部组织联系人,因为在通信历史记录中找到的组织内部联系人将始终归类为 OrganizationUser 。 对于使用者帐户,不属于 PersonalContact 的任何内容都归类为 ImplicitContact 。 |
聊天历史记录中隐式联系人 | 联系人 | Y | 不适用 | 个人 | ChatImplicitContact | 与 ImplicitContact 相同,但通信历史记录仅来自聊天。 |
Room | Rooms | Y | Y | 其他 | Room | |
Guest | GuestUser | Y | Y | 其他 | Guest | |
隐藏的来宾 | GuestUser | Y (默认关闭) | Y (默认关闭) | 其他 | Guest | |
新式组 | 组 | Y | Y | 组 | UnifiedGroup | 组称为:Exchange 365 组、新式组Microsoft 365 组。 有关Microsoft 365 组的详细信息,请参阅了解Microsoft 365 组。 |
Teams 组 | 组 | Y | Y | 组 | UnifiedGroup | 与 Microsoft 365 组 相同,但在 Microsoft Teams 中代表内部团队。 |
隐藏的 Teams 组 | 组 | Y (默认关闭) | Y | 组 | UnifiedGroup | 隐藏的 Teams 组。 |
通讯组列表 | 组 | Y | Y | 组 | PublicDistributionList | 已启用经典 Exchange 通讯组列表或邮件的安全组。 |
个人通讯组列表 | 联系人 | Y (默认关闭) | 不适用 | 组 | PersonalDistributionList | 由用户创建的虚拟通讯组,作为帮助程序,可以轻松地向多个联系人发送电子邮件。 仅用于Outlook 网页版撰写作为 UX 功能,不返回给其他调用方。 |
来宾和 Teams 组以外的任何类型的隐藏对象 | N | N |
在发出请求时提供其他详细信息,使人员 API 的结果更加具体。 以下是使请求更具体的几种方法。
"Provenances": ["Mailbox"]
"Provenances": ["Mailbox", "Directory"]
人员结果来自两个源:邮箱或目录。 默认情况下,结果将来自两个源,并删除冲突,这可确保不会返回相同的值。
注意:如果发生冲突,首选目录源。
邮箱结果包括:
当目录源在 Microsoft Entra ID 的全局寻址列表中搜索时,用例的相关方面:
指定大小以获取更多结果。 默认情况下,将根据搜索查询匹配项返回 25 个或更少的结果。
"Size": 25
设置分页的最小索引以指定结果的初始页。 默认情况下,分页的最小索引为 0
,第一个结果最相关。
"From": 0
API 返回一组默认属性,但你可以自定义请求以返回特定数量的属性。 以下示例将响应限制为 DisplayName、 EmailAddresses 和 phone 属性。
"Fields": ["DisplayName", "EmailAddresses", "phones"]
使用 Filter 对象将响应限制为特定值。 可能的筛选器值为: PeopleType、 PeopleSubType。
以下示例演示使用 Filter 对象返回其记录包含指定条件的人员的请求。
以下示例仅将响应限制为人员建议。 响应包含私人联系人和组织联系人。
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
}
]
},
以下示例仅将响应限制为业务用户。
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
}
]
},
以下示例将响应限制为不同类别的 PeopleSubtype。
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "PublicDistributionList"
}
},
{
"Term": {
"PeopleSubtype": "UnifiedGroup"
}
}
]
},
以下示例限制对组织用户和会议室的响应。
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Rooms"
}
}
]
},
以下示例将响应限制为组织用户和来宾。
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
},
以下示例组合了多个筛选器,以将响应限制为指定的条件。
"Filter": {
"And": [
{
"Or": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleType": "Other"
}
}
]
},
{
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
}
]
},
以下请求根据通信和协作模式以及业务关系获取与已登录用户最相关的人员。
POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"person"
],
"query": {
"queryString": "contoso"
},
"from": 0,
"size": 25
}
]
}
下面是响应的示例,其中包含一条与搜索条件匹配的消息。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.searchResponse",
"value": [
{
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "fc138b85-18ac-48e0-80a4-633ae4b594e0@41f988bf-86f1-53af-91ab-2d7cd034db47",
"rank": 1,
"summary": "",
"resource": {
"@odata.type": "#microsoft.graph.person",
"displayName": "Example User",
"givenName": "User",
"surname": "User",
"department": "Finance",
"officeLocation": "London",
"userPrincipalName": "example.user@contoso.com",
"emailAddresses": [
{
"address": "example.user@contoso.com",
"rank": 1
}
],
"phones": [
{
"type": "business",
"number": "+44 (20) 12345678"
}
]
}
}
]
}
]
}
]
}
培训
认证
Microsoft 365 Certified: Administrator Expert - Certifications
如果你是部署和管理 Microsoft 365 并执行 Microsoft 365 租户级云和混合环境的实现和管理的管理员,则此认证最适合你。