Использование API Microsoft Поиск для поиска людей

Статья
03/26/2023

Приложения 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"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Дальнейшие действия

Использование API Поиска (Майкрософт) для запроса данных