Utilizar a API de Pesquisa da Microsoft para procurar pessoas

As aplicações do Microsoft Graph podem utilizar a API do Microsoft Search para obter as pessoas mais relevantes para um utilizador. A relevância é determinada pelos padrões de comunicação e colaboração e pelas relações comerciais do usuário. Pessoas podem ser contactos locais ou do diretório de uma organização ou pessoas de comunicações recentes.

Além de gerar estas informações, a pesquisa também fornece suporte de pesquisa correspondente difuso e a capacidade de obter a lista de utilizadores relevantes para outro utilizador na organização do utilizador com sessão iniciada.

APIs Pessoas

Pode utilizar as seguintes APIs para procurar pessoas dentro de uma organização.

• /search
• /people

Propriedades de pessoas devolvidas

A API de pessoas devolve o seguinte conjunto de propriedades.

Tipos de pessoas

A tabela seguinte mostra os tipos e subtipos de pessoas suportados na API de pessoas.

Solicitar detalhes

Torne os resultados da API de pessoas mais específicos ao fornecer detalhes adicionais quando efetua um pedido. Seguem-se algumas formas de tornar os pedidos mais específicos.

Exemplo 1: apenas resultados da caixa de correio

"Provenances": ["Mailbox"]

Exemplo 2: resultados de ambas as origens

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

Origem dos resultados

Pessoas resultados são provenientes de duas origens, caixa de correio ou diretório. Por predefinição, os resultados serão provenientes de ambas as origens com conflitos a serem removidos, o que garante que os mesmos valores não serão devolvidos.

Nota: em caso de conflito, as origens de diretório são preferenciais.

Os resultados da caixa de correio consistem em:

• Pessoas quem lhe enviou um e-mail
• Pessoas a quem enviou um e-mail
• Pessoas com quem se reuniu
• Pessoas com quem teve conversa no Teams
• Pessoas no organograma do seu gestor
• Contactos públicos das pessoas acima referidas

Aspetos relevantes para o caso de utilização quando uma origem de diretório procura na lista de endereços global no Microsoft Entra ID:

• Não aplicável para utilizadores consumidores
• Pessoas que não estejam na lista de endereçamento global do autor da chamada não serão devolvidas
• Pessoas que estão ocultos pelo IBP (protocolo de barreira de informações) não serão devolvidos
• Pessoas que estão ocultos na lista de endereços não serão devolvidos

Obter mais resultados

Especifique o tamanho para obter mais resultados. Por predefinição, serão devolvidos 25 resultados ou menos com base nas correspondências da 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 predefiniçã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 devolve um conjunto de propriedades predefinidas, mas pode personalizar um pedido para devolver um número específico de propriedades. O exemplo seguinte limita a resposta às propriedades DisplayName, EmailAddresses e telefones .

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

Usar um filtro para limitar a resposta

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

Os exemplos seguintes mostram pedidos que utilizam o objeto Filtro para devolver pessoas cujo registo contém os critérios especificados.

Exemplo 1: filtrar por sugestões de pessoas

O exemplo seguinte limita a resposta a sugestões de apenas pessoas. A resposta contém contactos privados e organizacionais.

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

Exemplo 2: filtrar para sugestões de pessoas na organização

O exemplo seguinte limita a resposta apenas aos utilizadores empresariais.

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

Exemplo 3: filtrar para todos os utilizadores, listas de distribuição ou lista de distribuição moderna na organização

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

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

Exemplo 4: filtrar para utilizadores da organização e salas de reunião

O exemplo seguinte limita a resposta aos utilizadores da organização e às salas de reunião.

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

Exemplo 5: Filtrar para utilizadores e convidados da organização

O exemplo seguinte limita a resposta a utilizadores e convidados da organização.

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

Exemplo 6: Combinar vários filtros

O exemplo seguinte 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"
          }
        }
      ]
    }
  ]
},

Pedido completo

Exemplo: Procurar pessoa pelo nome

O pedido seguinte obtém as pessoas mais relevantes para o utilizador com sessão iniciada, 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

Segue-se 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