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

Приложения Microsoft Graph могут использовать API Microsoft Поиск для получения пользователей, которые наиболее важны для пользователя. Релевантность определяется шаблонами общения и совместной работы пользователя, а также его бизнес-отношениями. Люди могут быть локальными контактами или из каталога организации или людьми из последних сообщений.

Наряду с созданием этой аналитики поиск также обеспечивает поддержку поиска нечеткого сопоставления и возможность получения списка пользователей, релевантных другому пользователю в организации вошедшего в систему пользователя.

API Люди

Для поиска людей в организации можно использовать следующие API.

• /Поиск
• /Людей

Возвращенные свойства людей

API людей возвращает следующий набор свойств.

Типы пользователей

В следующей таблице показаны типы и подтипы людей, поддерживаемые в API людей.

Сведения о запросе

Сделайте результаты 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": "[email protected]",
                                "emailAddresses": [
                                    {
                                        "address": "[email protected]",
                                        "rank": 1
                                    }
                                ],
                                "phones": [
                                    {
                                        "type": "business",
                                        "number": "+44 (20) 12345678"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

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

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