Use a API de pessoas no Microsoft Graph para obter informações sobre as pessoas mais relevantes para você

Os aplicativos do Microsoft Graph podem usar a API de pessoas 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. As pessoas podem ser contatos locais ou do diretório de uma organização e pessoas de comunicações recentes.

Junto com a geração desse insight, a API de pessoas também fornece suporte de 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.

A API de pessoas é útil para pessoas que escolhem cenários, como compor um e-mail ou criar uma reunião. Por exemplo, você pode usar a API de pessoas em cenários de composição de e-mail.

Incluindo uma pessoa como relevante ou "trabalhando com"

Para que uma pessoa seja incluída como relevante ou "trabalhando com" um proprietário de perfil no Delve, seja exibida no cartão de perfil do proprietário ou retornada pela API de pessoas, deve haver um relacionamento público entre a pessoa e o proprietário do perfil. A ilustração a seguir mostra um Usuário A, um índice de relacionamentos com outros usuários (Usuário B) e um perfil público mostrando um subconjunto de relacionamentos de usuários.

Imagem sobre trabalhar com relacionamentos

A seguir, exemplos de relações públicas:

Indivíduos conectados no organograma: gerente, subordinado, colegas (compartilham o mesmo gerente)
Membros de um grupo público ou lista de distribuição com menos de 30 pessoas. Os grupos públicos têm listas de membros que estão disponíveis no diretório.

Se o proprietário do perfil se comunica com alguém e não há nenhum relacionamento público entre eles, como uma conexão com um organograma ou um grupo em comum, o fato de eles estarem se comunicando não é visível para outros.

A classificação das pessoas ( ou seja, a ordem pela qual aparecem na página do proprietário do perfil) é determinada pela comunicação pública entre o proprietário do perfil e a pessoa na lista.

Alguns exemplos de interação pública:

Enviar ou receber emails diretamente um ao outro como parte de um grupo público
Convidar usuários para reuniões como parte de um grupo ou onde mais de X pessoas são convidadas

A classificação não muda com base em quem é o usuário A (a pessoa que está vendo a página de outra pessoa). A classificação é determinada pelo nível de interação entre o Usuário B (proprietário do perfil) e o Usuário C (pessoa que aparece na lista do proprietário do perfil).

Para que o Usuário C apareça, o proprietário do perfil deve estar em um grupo relativamente pequeno ou lista de distribuição com aquele usuário que é público (o que significa que a lista de membros está disponível no diretório).

Pessoas externo à organização não são apresentados na lista do proprietário do perfil. Pessoas enviarem e-mails ou se encontrarem, mas que não fazem parte da mesma organização, também não aparecem como pessoas com quem o proprietário trabalha.

Desabilitando "trabalhando com"

Os administradores podem gerenciar a exibição ou retorno de pessoas relevantes para o proprietário de um perfil em dois níveis:

Para uma organização:
- Habilite para toda a organização. Esta é a configuração padrão.
- Desabilite para toda a organização, exceto para o proprietário do perfil.
Para um grupo de Microsoft Entra na organização:
- Desative para um grupo de Microsoft Entra especificado. Isto é útil para ativar o "working-with" para uma organização, exceto para membros no grupo Microsoft Entra.

Para obter mais informações, consulte personalizar o controle de privacidade do insight de pessoas.

Autorização

Para chamar a API de pessoas no Microsoft Graph, a sua aplicação precisa das permissões adequadas:

People.Read - Use para fazer chamadas de API para pessoas em geral; por exemplo, https://graph.microsoft.com/v1.0/me/people/. People.Read requer o consentimento do usuário final.
People.Read.All - necessária para recuperar as pessoas mais relevantes para um usuário especificado nas chamadas (https://graph.microsoft.com/v1.0/users/{id}/people) da organização do usuário conectado. People.Read.All requer o consentimento do administrador.

Procurar pessoas

Os pedidos nesta secção obtêm as pessoas mais relevantes para o utilizador com sessão iniciada (/me) ou para um utilizador específico na organização do utilizador com sessão iniciada. Estes pedidos requerem a Pessoas. Ler ou Pessoas. Permissão Read.All, respetivamente. Por predefinição, cada resposta devolve 10 registos, mas pode alterá-lo com o parâmetro de consulta $top .

Obter uma coleção de pessoas relevantes

A solicitação a seguir obtém as pessoas mais relevantes para o usuário conectado (/me), com base nos padrões de comunicação e colaboração e nas relações comerciais.

GET https://graph.microsoft.com/v1.0/me/people/

O exemplo a seguir mostra a resposta. Por predefinição, cada resposta devolve 10 registos. Pode alterar isto com o parâmetro de consulta $top . Este exemplo utiliza $top para limitar a resposta a três registos.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Solicitar uma página subsequente de pessoas

Se a primeira resposta não contiver a lista completa de pessoas relevantes, pode fazer um segundo pedido com $top e $skip para pedir páginas adicionais de informações. Se a solicitação anterior tiver informações adicionais, a solicitação seguinte retornará a próxima página de pessoas do servidor.

GET https://graph.microsoft.com/v1.0/me/people/?$top=3&$skip=10

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola",
      "givenName": "Felix",
      "surname": "Coppola",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Legal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2109",
      "profession": "",
      "userPrincipalName": "FelixC@contoso.com",
      "imAddress": "sip:FelixC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "FelixC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0104"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland",
      "givenName": "Lenora",
      "surname": "Rowland",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/1106",
      "profession": "",
      "userPrincipalName": "LenoraR@contoso.com",
      "imAddress": "sip:LenoraR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LenoraR@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 954 555 0118"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette",
      "givenName": "Manuel",
      "surname": "Collette",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Accountant II",
      "companyName": null,
      "yomiCompany": "",
      "department": "Finance",
      "officeLocation": "98/2202",
      "profession": "",
      "userPrincipalName": "ManuelC@contoso.com",
      "imAddress": "sip:ManuelC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ManuelC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+20 255501070"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Classificar a resposta

Por predefinição, as pessoas na resposta são ordenadas pela respetiva relevância para a sua consulta. Pode alterar a ordem das pessoas na resposta com o parâmetro $orderby . Esta consulta seleciona as pessoas mais relevantes para si, ordena-as pelo respetivo displayName e, em seguida, devolve as primeiras 10 pessoas na lista ordenada.

GET https://graph.microsoft.com/v1.0/me/people/?$orderby=displayName

O exemplo a seguir mostra a resposta. Por predefinição, cada resposta devolve 10 registos. Pode alterar isto com o parâmetro $top . O exemplo seguinte utiliza $top para limitar a resposta a três registos.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos",
      "givenName": "Adriana",
      "surname": "Ramos",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/2111",
      "profession": "",
      "userPrincipalName": "AdrianaR@contoso.com",
      "imAddress": "sip:AdrianaR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AdrianaR@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 425 555 0109"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley",
      "givenName": "Alyce",
      "surname": "Cooley",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "131/1104",
      "profession": "",
      "userPrincipalName": "AlyceC@contoso.com",
      "imAddress": "sip:AlyceC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyceC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 858 555 0110"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke",
      "givenName": "Alyssa",
      "surname": "Clarke",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Corporate Security Officer",
      "companyName": null,
      "yomiCompany": "",
      "department": "Operations",
      "officeLocation": "24/1106",
      "profession": "",
      "userPrincipalName": "AlyssaC@contoso.com",
      "imAddress": "sip:AlyssaC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyssaC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 262 555 0106"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Alterar o número de pessoas e campos retornados

Você pode alterar o número de pessoas retornadas na resposta definindo o parâmetro $top.

O exemplo seguinte pede às 1000 pessoas mais relevantes para /me. O pedido também limita a quantidade de dados enviados do servidor ao pedir apenas o displayName da pessoa.

GET https://graph.microsoft.com/v1.0/me/people/?$top=1000&$Select=displayName

O exemplo a seguir mostra a resposta.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye"
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman"
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey"
    },
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Roscoe Seidel"
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke"
    },
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos"
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley"
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Wayne Leeper"
    },
    {
      "id": "E7D40AC5-0078-4575-B1F3-F738124C4BC9",
      "displayName": "Jan Travis"
    },
    {
      "id": "6F99D1CC-4FCC-49E4-9160-E8AB01BF3E83",
      "displayName": "Charlotte Delacruz"
    },
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola"
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland"
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette"
    }
  ]
}

Tipos de resultados incluídos

Por padrão, o Microsoft Graph exibe resultados apenas de caixa de correio, que são seus contatos salvos ou pessoas com as quais você provavelmente interagirá. Para recuperar os resultados do diretório de toda a organização, especifique um cabeçalho HTTP, conforme mostrado.

"X-PeopleQuery-QuerySources: Mailbox,Directory”

Selecione os campos para retornar

Pode limitar a quantidade de dados devolvidos do servidor com o parâmetro $select para escolher um ou mais campos. O @odata.id campo é sempre devolvido.

O exemplo a seguir limita a resposta ao displayName e scoredEmailAddresses das 10 pessoas mais relevantes.

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses

O exemplo a seguir mostra a resposta. Por predefinição, cada resposta devolve 10 registos. Pode alterar isto com o parâmetro $top . Este exemplo utiliza $top para limitar a resposta a três registos.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

Usar um filtro para limitar a resposta

Você pode usar o parâmetro $filter para limitar a resposta apenas às pessoas cujo registro contém os critérios especificados.

A consulta a seguir limita a resposta a instâncias person com a propriedade personType com as atribuições de person como classe e organizationUser como subclasse.

GET https://graph.microsoft.com/v1.0/me/people/?$filter=personType/class eq 'Person' and personType/subclass eq 'OrganizationUser'

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Selecionar os campos a serem retornados em uma resposta filtrada

Você pode combinar os parâmetros $select e $filter para criar uma lista personalizada de pessoas relevantes para o usuário e obter somente os campos necessários para seu aplicativo.

O exemplo seguinte obtém o displayName e scoredEmailAddresses de pessoas cujo nome a apresentar é igual ao nome especificado. Neste exemplo, só são devolvidas as pessoas cujo nome a apresentar seja igual a "Frye de Camião".

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses&$filter=displayName eq 'Lorrie Frye'

O exemplo a seguir mostra a resposta.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

Procurar pessoas relevantes de outro usuário

A solicitação a seguir obtém as pessoas mais relevantes para outra pessoa na organização do usuário conectado, conforme descrito na Implementação do recurso de trabalho. Esta solicitação requer a permissão People.Read.All. Os parâmetros de consulta descritos nas seções acima também se aplicam.

Neste exemplo, as pessoas relevantes de Vinícius Monte são exibidas.

GET https://graph.microsoft.com/v1.0/users('roscoes@contoso.com')/people/

O exemplo a seguir mostra a resposta. Por predefinição, cada resposta devolve 10 registos. Pode alterar isto com o parâmetro $top . O exemplo abaixo utiliza $top para limitar a resposta a três registos.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "56155636-703F-47F2-B657-C83F01F49BBC",
      "displayName": "Clifton Clemente",
      "givenName": "Clifton",
      "surname": "Clemente",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Director",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2106",
      "profession": "",
      "userPrincipalName": "CliftonC@contoso.com",
      "imAddress": "sip:CliftonC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "CliftonC@contoso.com",
          "relevanceScore": 20
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BF27D5A-AB4F-4C43-BED0-7DAD9EB0C1C4",
      "displayName": "Sheree Mitchell",
      "givenName": "Sheree",
      "surname": "Mitchell",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/2107",
      "profession": "",
      "userPrincipalName": "ShereeM@contoso.com",
      "imAddress": "sip:ShereeM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ShereeM@contoso.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0107"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "B3E5302D-EAF0-4E8B-8C6C-A2AE64B4B163",
      "displayName": "Vincent Matney",
      "givenName": "Vincent",
      "surname": "Matney",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Engineering",
      "companyName": null,
      "yomiCompany": "",
      "department": "Engineering",
      "officeLocation": "23/2102",
      "profession": "",
      "userPrincipalName": "VincentM@contoso.com",
      "imAddress": "sip:VincentM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "VincentM@contoso.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 502 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Pesquisar pessoas

Os pedidos nesta secção permitem-lhe procurar pessoas relevantes para o utilizador com sessão iniciada (/me) e outros utilizadores na organização do utilizador com sessão iniciada. Estes pedidos requerem a Pessoas. permissão de Ler, exceto para procurar as pessoas relevantes de outros utilizadores, o que requer Pessoas. Read.All. Por predefinição, cada resposta devolve 10 registos, mas pode alterá-lo com o parâmetro $top .

Usar a pesquisa para selecionar pessoas

Use o parâmetro $search para selecionar as pessoas que atendem a determinado conjunto de critérios.

A consulta de pesquisa a seguir retorna pessoas relevantes para /me cujo displayName ou emailAddress tem uma palavra que começa com a letra "j".

GET https://graph.microsoft.com/v1.0/me/people/?$search=j

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Jan Travis",
      "givenName": "Jan",
      "surname": "Travis",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "VP Sales",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "19/3123",
      "profession": "",
      "userPrincipalName": "JanT@contoso.com",
      "imAddress": "sip:JanT@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "JanT@contoso.com",
          "relevanceScore": -12.297347783416837
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 732 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "C43BF05E-5B6B-4DCF-B2FC-0837B09E0FA9",
      "displayName": "Jacob Cazares (TAILSPIN)",
      "givenName": null,
      "surname": null,
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JacobC@tailspintoys.com",
          "relevanceScore": -12.298154282019846
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "PersonalContact"
      }
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Jewell Montgomery",
      "givenName": "Jewell",
      "surname": "Montgomery",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "JewellM@contoso.com",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JewellM@contoso.com",
          "relevanceScore": -12.531408487977451
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Realizar uma pesquisa difusa

As pesquisas implementam um algoritmo de correspondência difusa. Devolvem resultados com base numa correspondência exata e também em inferências sobre a intenção da pesquisa. Por exemplo, imagine um usuário com um nome de exibição de "Tyler Lee" e um endereço de email tylerle@example.com, o qual está na coleção de pessoas do usuário conectado. Todas as seguintes pesquisas devolvem este utilizador Tyler como um dos resultados.

GET https://graph.microsoft.com/v1.0/me/people?$search="tyler"                //matches both Tyler's name and email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle"              //matches Tyler's email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle@example.com"  //matches Tyler's email. Note the quotes to enclose '@'.
GET https://graph.microsoft.com/v1.0/me/people?$search="tiler"                //fuzzy match with Tyler's name
GET https://graph.microsoft.com/v1.0/me/people?$search="tyler lee"            //matches Tyler's name. Note the quotes to enclose the space.

Comentários

Esta página foi útil?

Last updated on 2025-08-12