Listar pessoas

Namespace: microsoft.graph

Obtenha uma lista de objetos de pessoa ordenados pela respetiva relevância para o utilizador, que é determinada pelos padrões de comunicação e colaboração do utilizador e pelas relações comerciais.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Solicitação HTTP

GET /me/people
GET /users/{id | userPrincipalName}/people

Parâmetros de consulta opcionais

Este método suporta os seguintes parâmetros de consulta OData para ajudar a personalizar a resposta.

Cabeçalhos de solicitação

Corpo da solicitação

Não forneça um corpo de solicitação para esse método.

Resposta

Se for bem-sucedido, este método devolve um 200 OK código de resposta e uma coleção de objetos de pessoa no corpo da resposta.

Exemplos

Navegar

Os pedidos nesta secção obtêm as pessoas mais relevantes para o utilizador com sessão iniciada (/me), com base na comunicação, colaboração e relações comerciais.

Por padrão, cada resposta retorna 10 registros, mas você pode alterar esse número usando o parâmetro $top. Estes pedidos requerem a Pessoas. permissão de Ler.

Solicitação

Segue-se um exemplo do pedido predefinido.

GET https://graph.microsoft.com/beta/me/people

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.People.GetAsync();

// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
people, err := graphClient.Me().People().Get(context.Background(), nil)

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

PersonCollectionResponse result = graphClient.me().people().get();

const options = {
	authProvider,
};

const client = Client.init(options);

let people = await client.api('/me/people')
	.version('beta')
	.get();

<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->me()->people()->get()->wait();

Import-Module Microsoft.Graph.Beta.People

# A UPN can also be used as -UserId.
Get-MgBetaUserPerson -UserId $userId

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.me.people.get()

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{
    "value": [
        {
            "id": "33b43a5b-87d6-41ec-91f8-a2610048105f",
            "displayName": "Marketing",
            "givenName": null,
            "surname": null,
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": null,
            "companyName": null,
            "yomiCompany": "",
            "department": null,
            "officeLocation": null,
            "profession": "",
            "mailboxType": "GroupMailbox",
            "personType": "ModernGroup",
            "userPrincipalName": "",
            "emailAddresses": [
                {
                    "address": "Marketing@contoso.com",
                    "rank": 30
                }
            ],
            "phones": [],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        },
        {
            "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",
            "displayName": "Isaiah Langer",
            "givenName": "Isaiah",
            "surname": "Langer",
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": "Web Marketing Manager",
            "companyName": null,
            "yomiCompany": "",
            "department": "Sales & Marketing",
            "officeLocation": "20/1101",
            "profession": "",
            "mailboxType": "Mailbox",
            "personType": "Person",
            "userPrincipalName": "IsaiahL@contoso.com",
            "emailAddresses": [
                {
                    "address": "IsaiahL@contoso.com",
                    "rank": 20
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        }
    ]
}

Solicitação de 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 mais páginas 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/beta/me/people/?$top=10&$skip=10

Classificar a resposta

Por padrão, as pessoas na resposta são classificadas pela relevância delas à consulta. Você pode alterar a ordem das pessoas na resposta usando o parâmetro $orderby. Essa consulta seleciona as pessoas mais relevantes para você classificando-as pelo nome de exibição e retorna as dez primeiras pessoas da lista classificada.

GET https://graph.microsoft.com/beta/me/people/?$orderby=DisplayName

Alteração do número de pessoas e dos 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 nome a apresentar da pessoa.

GET https://graph.microsoft.com/beta/me/people/?$top=1000&$select=DisplayName

Seleção dos campos que devem ser retornados

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

O exemplo seguinte limita a resposta a DisplayName e EmailAddress das 10 pessoas mais relevantes.

GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses

Uso de 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 seguinte limita a resposta a pessoas com a origem "Diretório".

GET https://graph.microsoft.com/beta/me/people/?$filter=Sources/Any (source: source/Type  eq 'Directory')

Selecionar os campos a devolver numa 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 o EmailAddress de pessoas cujo nome a apresentar é igual ao nome especificado. Neste exemplo, somente as pessoas cujo nome de exibição é igual a "Nestor Kellum" são retornadas.

+GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses&$filter=DisplayName eq 'Nestor Kellum'

Pesquisar pessoas

Os pedidos nesta secção também obtêm as pessoas mais relevantes para o utilizador com sessão iniciada (/me). Os pedidos de pesquisa requerem a Pessoas. permissão de Ler.

Utilizar 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 seguinte devolve pessoas relevantes para /me cujo GivenName ou Apelido começa com a letra "j".

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

Uso da pesquisa para especificar um tópico relevante

O pedido seguinte devolve pessoas relevantes para /me cujo nome contém "ma" e que têm uma associação com "planeamento de funcionalidades".

GET https://graph.microsoft.com/beta/me/people/?$search="ma topic: feature planning"

Execução de uma pesquisa difusa

O pedido seguinte procura uma pessoa chamada "Hermaini Hall". Uma vez que existe uma pessoa com o nome "Herminia Hull" relevante para o utilizador com sessão iniciada, as informações de "Herminia Hull" são devolvidas.

GET https://graph.microsoft.com/beta/me/people/?$search="hermaini hall"

Pessoas relacionadas

O pedido seguinte obtém as pessoas mais relevantes para outra pessoa na organização do utilizador. Este pedido requer o User.ReadBasic.All para Pessoas. Permissão Read.All. Neste exemplo, são apresentadas as pessoas relevantes de Nestor Kellum.

GET https://graph.microsoft.com/beta/users('nestork@contoso.com')/people/