Compartilhar via


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

Próximas etapas