Использование API Microsoft Поиск для поиска людей
Приложения Microsoft Graph могут использовать API Microsoft Поиск для получения пользователей, которые наиболее важны для пользователя. Релевантность определяется шаблонами общения и совместной работы пользователя, а также его бизнес-отношениями. Люди могут быть локальными контактами или из каталога организации или людьми из последних сообщений.
Наряду с созданием этой аналитики поиск также обеспечивает поддержку поиска нечеткого сопоставления и возможность получения списка пользователей, релевантных другому пользователю в организации вошедшего в систему пользователя.
API Люди
Для поиска людей в организации можно использовать следующие API.
- /Поиск
- /Людей
Примечание.
Мы рекомендовали пользователям вызывать конечную точку /search , а не конечную точку /people . В дальнейшем все будущие инвестиции будут доступны только в конечной точке /search/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 |
| rank | Integer |
| summary | String |
| surname | String |
| userPrincipalName | String |
Типы пользователей
В следующей таблице показаны типы и подтипы людей, поддерживаемые в API людей.
| Поддерживаемые варианты пользователей, групп и комнат | Сведения о типе получателя | Mailbox | Каталог | тип Люди | подтип Люди | Примечания |
|---|---|---|---|---|---|---|
| Пользователь организации | UserMailbox, MailUser | Да | Да | Пользователь | ОрганизацияПользователь | Пользователь, принадлежащий организации. |
| Пользователь организации без адреса электронной почты | Пользователь | Y (выключено по умолчанию) | Y (выключено по умолчанию) | Пользователь | ОрганизацияПользователь | Пользователь, принадлежащий организации. |
| Контакт организации | MailContact, Contact | Нет | Да | Пользователь | OrganizationContact | Контакт, явно добавленный в глобальный список адресов (GAL) администратором клиента, но не входит в организацию. |
| Частный контакт | Контакт | Да | Недоступно | Пользователь | PersonalContact | Контакт, явно созданный пользователем, который не принадлежит организации. Если пользователь вручную добавляет в свои контакты кого-то из сотрудников организации, он по-прежнему будет классифицироваться как OrganizationUser. |
| Частный контакт без адреса электронной почты | Контакт | Y (выключено по умолчанию) | Недоступно | Пользователь | PersonalContact | Контакт, явно созданный пользователем, который не принадлежит организации. Если пользователь вручную добавляет в свои контакты кого-то из сотрудников организации, он по-прежнему будет классифицироваться как OrganizationUser. |
| Неявный контакт из журнала коммуникаций | Контакт | Да | Недоступно | Пользователь | ImplicitContact | Контакт, выводимый из журнала общения (электронной почты и чата), что у нас недостаточно информации о, чтобы определить, является ли он человеком, группой и т. д. В бизнес-учетных записях это всегда будет контакт за пределами организации, так как внутренние контакты организации, найденные в журнале коммуникаций, всегда будут классифицироваться как OrganizationUser. Для учетных записей потребителей все, что не является , PersonalContact классифицируется как ImplicitContact. |
| Неявный контакт из журнала чата | Контакт | Да | Н/Д | Пользователь | ChatImplicitContact | То же самое, что ImplicitContactи , но если журнал сообщений находится исключительно из чата. |
| Room | Rooms | Да | Да | Прочее | Room | |
| Guest | GuestUser | Да | Да | Прочее | Guest | |
| Скрытый гость | GuestUser | Y (выключено по умолчанию) | Y (выключено по умолчанию) | Прочее | Guest | |
| Современная группа | Группа | Да | Да | Группа | UnifiedGroup | Группа, известная как: Группа Exchange 365, Современные группы Группы Microsoft 365. Дополнительные сведения о Группы Microsoft 365 см. в статье Сведения о Группы Microsoft 365. |
| Группа Teams | Группа | Да | Да | Группа | UnifiedGroup | То же, что и Группы Microsoft 365, но представляет внутреннюю команду в Microsoft Teams. |
| Скрытая группа Teams | Группа | Y (выключено по умолчанию) | Да | Группа | UnifiedGroup | Скрытая группа Teams. |
| Список рассылки | Группа | Да | Да | Группа | PublicDistributionList | Классический список рассылки Exchange или группа безопасности с поддержкой почты. |
| Личный список рассылки | Контакт | Y (выключено по умолчанию) | Н/Д | Группа | PersonalDistributionList | Виртуальная группа рассылки, созданная пользователем в качестве помощника для отправки сообщений электронной почты нескольким контактам простым способом. Используется только для Outlook в Интернете создания в качестве функции пользовательского интерфейса, а не для других вызывающих. |
| Скрытый объект любого типа, кроме гостевой группы и группы Teams | Нет | Нет |
Сведения о запросе
Сделайте результаты 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"
}
]
}
}
]
}
]
}
]
}