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

Propriedades de pessoas retornadas

A API de pessoas retorna o seguinte conjunto de propriedades.

Tipos de pessoa

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

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