使用 Microsoft 搜索 API 搜索人员

项目
11/07/2024

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

除了生成此见解，搜索还提供模糊匹配搜索支持，并能够检索与已登录用户组织中的其他用户相关的用户列表。

人员 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 的结果更加具体。以下是使请求更具体的几种方法。

示例 1：仅邮箱结果

"Provenances": ["Mailbox"]

示例 2：来自两个源的结果

"Provenances": ["Mailbox", "Directory"]

结果源

人员结果来自两个源：邮箱或目录。默认情况下，结果将来自两个源，并删除冲突，这可确保不会返回相同的值。

注意：如果发生冲突，首选目录源。

邮箱结果包括：

发送电子邮件人员
人员向谁发送电子邮件
与你会面人员
与 Teams 聊天人员
经理组织结构图中的人员
上述人员的公共联系人

当目录源在 Microsoft Entra ID 的全局寻址列表中搜索时，用例的相关方面：

不适用于使用者用户
不会返回不在调用方全局寻址列表中的人员
不会返回 IBP 隐藏 (信息屏障协议) 人员
不会返回地址列表中隐藏人员

获取更多结果

指定大小以获取更多结果。默认情况下，将根据搜索查询匹配项返回 25 个或更少的结果。

"Size": 25

指定分页的最小索引

设置分页的最小索引以指定结果的初始页。默认情况下，分页的最小索引为 0 ，第一个结果最相关。

"From": 0

选择要返回的字段

API 返回一组默认属性，但你可以自定义请求以返回特定数量的属性。以下示例将响应限制为 DisplayName、 EmailAddresses 和 phone 属性。

"Fields": ["DisplayName", "EmailAddresses", "phones"]

使用筛选器限制响应

使用 Filter 对象将响应限制为特定值。可能的筛选器值为： PeopleType、 PeopleSubType。

以下示例演示使用 Filter 对象返回其记录包含指定条件的人员的请求。

示例 1：筛选人员建议

以下示例仅将响应限制为人员建议。响应包含私人联系人和组织联系人。

"Filter": {
  "And": [
    {
      "Term": {
        "PeopleType": "Person"
      }
    }
  ]
},

示例 2：筛选组织中的人员建议

以下示例仅将响应限制为业务用户。

"Filter": {
  "And": [
    {
      "Term": {
        "PeopleType": "Person"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    }
  ]
},

示例 3：筛选到组织中的所有用户、通讯组列表或新式通讯组列表

以下示例将响应限制为不同类别的 PeopleSubtype。

"Filter": {
  "Or": [
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "PublicDistributionList"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "UnifiedGroup"
      }
    }
  ]
},

示例 4：筛选到组织用户和会议室

以下示例限制对组织用户和会议室的响应。

"Filter": {
  "Or": [
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "Rooms"
      }
    }
  ]
},

示例 5：筛选到组织用户和来宾

以下示例将响应限制为组织用户和来宾。

"Filter": {
  "Or": [
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "Guest"
      }
    }
  ]
},

示例 6：合并多个筛选器

以下示例组合了多个筛选器，以将响应限制为指定的条件。

"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 搜索 API 查询数据

通过