Usar a API do Microsoft Pesquisa para pesquisar pessoas
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"
}
]
}
}
]
}
]
}
]
}