Usar a API do Microsoft Pesquisa para pesquisar pessoas

Artigo
04/17/2024

Os aplicativos do Microsoft Graph podem usar a API do Microsoft Pesquisa para recuperar as pessoas mais relevantes para um usuário. A relevância é determinada pelos padrões de comunicação e colaboração e pelas relações comerciais do usuário. Pessoas podem ser contatos locais ou do diretório de uma organização ou pessoas de comunicações recentes.

Além de gerar esse insight, a pesquisa também fornece suporte de pesquisa correspondente difuso e a capacidade de recuperar a lista de usuários relevantes para outro usuário na organização do usuário conectado.

APIs Pessoas

Você pode usar as APIs a seguir para pesquisar pessoas dentro de uma organização.

/Busca
/Pessoas

Observação

Recomendamos que os usuários chamem o /search ponto de extremidade em vez do ponto de /people extremidade. Daqui para frente, todos os investimentos futuros só estarão disponíveis no /search ponto de extremidade; o /people ponto de extremidade está no modo de manutenção.

Propriedades de pessoas retornadas

A API de pessoas retorna o seguinte conjunto de propriedades.

Propriedade	Tipo
additionalOfficeLocation	Cadeia de caracteres
CompanyName	String
department	String
displayName	Cadeia de caracteres
emailAddress	Cadeia de caracteres
givenName	Cadeia de caracteres
hitId	Cadeia de caracteres
imAddress	String
jobTitle	String
officeLocation	String
personType	Cadeia de caracteres
telefones	Cadeia de caracteres
classificação	Número inteiro
summary	Cadeia de caracteres
surname	Cadeia de caracteres
userPrincipalName	Cadeia de caracteres

Tipos de pessoa

A tabela a seguir mostra tipos de pessoas e subtipos com suporte na API de pessoas.

Variações de pessoas, grupos e salas com suporte	Detalhes do tipo de destinatário	Mailbox	Diretório	Pessoas tipo	Pessoas subtipo	Observações
Usuário da organização	UserMailbox, MailUser	S	S	Pessoa	OrganizationUser	Um usuário que pertence à organização.
Usuário da organização sem endereço de email	Usuário	Y (Desativado por padrão)	Y (Desativado por padrão)	Pessoa	OrganizationUser	Um usuário que pertence à organização.
Contato da organização	MailContact, Contact	N	S	Pessoa	OrganizationContact	Um contato adicionado explicitamente à GAL (lista de endereços global) pelo administrador do locatário, mas isso não faz parte da organização.
Contato privado	Contato	S	N/D	Pessoa	PersonalContact	Um contato criado explicitamente pelo usuário que não pertence à organização. Se o usuário adicionar manualmente aos seus contatos alguém parte da organização, ele ainda será classificado como `OrganizationUser`.
Contato privado sem endereço de email	Contato	Y (Desativado por padrão)	N/D	Pessoa	PersonalContact	Um contato criado explicitamente pelo usuário que não pertence à organização. Se o usuário adicionar manualmente aos seus contatos alguém parte da organização, ele ainda será classificado como `OrganizationUser`.
Contato implícito do histórico de comunicação	Contato	S	N/D	Pessoa	ImplicitContact	Um contato inferido do histórico de comunicação (email e chat) que não temos informações suficientes para determinar se é uma pessoa, um grupo etc. Em contas comerciais, esse sempre será um contato externo da organização, pois os contatos internos da organização encontrados no histórico de comunicação sempre serão classificados como `OrganizationUser`. Para contas de consumidor, qualquer coisa que não seja uma `PersonalContact` é classificada como `ImplicitContact`.
Contato implícito do histórico de chat	Contato	S	N/D	Pessoa	ChatImplicitContact	O mesmo que `ImplicitContact`, mas quando o histórico de comunicação é exclusivamente do chat.
Room	Rooms	S	S	Outros	Room
Guest	GuestUser	S	S	Outros	Guest
Convidado oculto	GuestUser	Y (Desativado por padrão)	Y (Desativado por padrão)	Outros	Guest
Grupo moderno	Agrupar	S	S	Agrupar	UnifiedGroup	Grupo conhecido como: Grupo exchange 365, grupos modernos, Grupos do Microsoft 365. Para obter mais informações sobre Grupos do Microsoft 365, consulte Saiba mais sobre Grupos do Microsoft 365.
Grupo teams	Agrupar	S	S	Agrupar	UnifiedGroup	O mesmo que Grupos do Microsoft 365, mas representa internamente uma equipe no Microsoft Teams.
Grupo do Teams Ocultos	Agrupar	Y (Desativado por padrão)	S	Agrupar	UnifiedGroup	Grupo do Teams Ocultos.
Lista de distribuição	Agrupar	S	S	Agrupar	PublicDistributionList	Lista de distribuição clássica do Exchange ou grupo de segurança habilitado para email.
Lista de distribuição pessoal	Contato	Y (Desativado por padrão)	N/D	Agrupar	PersonalDistributionList	Um grupo de distribuição virtual criado pelo usuário como auxiliar para enviar emails para vários contatos de maneira fácil. Usado apenas para Outlook na Web compor como um recurso UX, não retornado para outros chamadores.
Objeto oculto de qualquer tipo, exceto grupo Convidado e Teams		N	N

Solicitar detalhes

Torne os resultados da API de pessoas mais específicos, fornecendo detalhes adicionais ao fazer uma solicitação. A seguir estão algumas maneiras de tornar as solicitações mais específicas.

Exemplo 1: somente resultados de caixa de correio

"Provenances": ["Mailbox"]

Exemplo 2: Resultados de ambas as fontes

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

Fonte de resultados

Pessoas resultados são provenientes de duas fontes, caixa de correio ou diretório. Por padrão, os resultados virão de ambas as fontes com conflitos sendo removidos, o que garante que os mesmos valores não sejam retornados.

Observação: no caso de um conflito, as fontes de diretório são preferenciais.

Os resultados da caixa de correio consistem em:

Pessoas que lhe enviou um email
Pessoas para quem você enviou email
Pessoas você teve reunião com
Pessoas você conversou com o Teams
Pessoas no gráfico de organização do seu gerente
Contatos públicos das pessoas acima

Aspectos relevantes para o caso de uso quando uma fonte de diretório pesquisa na lista de endereçamento global em Microsoft Entra ID:

Não aplicável para usuários consumidores
Pessoas que não estão na lista de endereçamento global do chamador não serão retornados
Pessoas que estão ocultos pelo IBP (protocolo de barreira de informações) não serão retornados
Pessoas que estão ocultos na lista de endereços não serão retornados

Obter mais resultados

Especifique o tamanho para obter mais resultados. Por padrão, 25 resultados ou menos serão retornados com base nas correspondências de consulta de pesquisa.

"Size": 25

Especificar o índice mínimo para paginação

Defina o índice mínimo para paginação para especificar a página inicial dos resultados. Por padrão, o índice mínimo para paginação é 0 e o primeiro resultado é o mais relevante.

"From": 0

Selecione os campos para retornar

A API retorna um conjunto de propriedades padrão, mas você pode personalizar uma solicitação para retornar um número específico de propriedades. O exemplo a seguir limita a resposta às propriedades DisplayName, EmailAddresses e telefones .

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

Usar um filtro para limitar a resposta

Use o objeto Filter para limitar a resposta a valores específicos. Os possíveis valores de filtro são: PeopleType, PeopleSubType.

Os exemplos a seguir mostram solicitações que usam o objeto Filter para retornar pessoas cujo registro contém os critérios especificados.

Exemplo 1: Filtrar sugestões de pessoa

O exemplo a seguir limita a resposta a apenas sugestões de pessoa. A resposta contém contatos privados e de organização.

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

Exemplo 2: Filtrar sugestões de pessoa dentro da organização

O exemplo a seguir limita o reponse somente aos usuários empresariais.

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

Exemplo 3: Filtrar para todos os usuários, listas de distribuição ou lista de distribuição moderna na organização

O exemplo a seguir limita a resposta a diferentes categorias de PeopleSubtype.

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

Exemplo 4: Filtrar para usuários da organização e salas de reunião

O exemplo a seguir limita a resposta a usuários da organização e salas de reunião.

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

Exemplo 5: Filtrar para usuários e convidados da organização

O exemplo a seguir limita a resposta a usuários e convidados da organização.

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

Exemplo 6: Combinar vários filtros

O exemplo a seguir combina vários filtros para limitar a resposta aos critérios especificados.

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

Solicitação completa

Exemplo: Pesquisa pessoa pelo nome

A solicitação a seguir obtém as pessoas mais relevantes para o usuário conectado, com base em padrões de comunicação e colaboração e relações comerciais.

Solicitação

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "person"
      ],
      "query": {
        "queryString": "contoso"
      },
      "from": 0,
      "size": 25
    }
  ]
}

Resposta

A seguir está um exemplo da resposta, que contém uma mensagem que corresponde ao critério de pesquisa.

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"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Próximas etapas

Usar a API de Pesquisa da Microsoft para consultar dados