Usar a API de Pesquisa da Microsoft para pesquisar pessoas

Os aplicativos do Microsoft Graph podem usar a API de Pesquisa da Microsoft para recuperar as pessoas que são 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. People pode ser contatos locais ou de um diretório de uma organização ou pessoas de comunicações recentes.

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

People APIs

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

• /pesquisar
• /pessoas

Propriedades de pessoas devolvidas

A API de pessoas retorna o seguinte conjunto de propriedades.

Tipos de pessoa

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

Solicitar detalhes

Torne os resultados da API de pessoas mais específicos, fornecendo detalhes adicionais quando você fizer uma solicitação. Veja a seguir algumas maneiras de tornar as solicitações mais específicas.

Exemplo 1: somente resultados da caixa de correio

"Provenances": ["Mailbox"]

Exemplo 2: Resultados de ambas as fontes

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

Fonte de resultados

Os resultados do People vêm 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: em caso de conflito, as fontes de diretório são preferidas.

Os resultados da caixa de correio consistem em:

• People who sent you email
• People para quem você enviou o email
• People com quem você teve reuniões
• People com quem você conversou no Teams
• People no organograma do seu gerente
• Contatos públicos das pessoas acima

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

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

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 de paginação para especificar a página inicial de 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 phones .

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

Usar um filtro para limitar a resposta

Use o objeto Filter para limitar a resposta a valores específicos. Os valores de filtro possíveis 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 por sugestões pessoais

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

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

Exemplo 2: Filtrar sugestões por pessoa na organização

O exemplo a seguir limita a resposta apenas a usuários corporativos.

"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 aos usuários da organização e salas de reunião.

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

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

O exemplo a seguir limita a resposta aos 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: Pesquisar 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