Listar pessoas

Namespace: microsoft.graph

Recupere uma coleção de objetos person ordenados por relevância para o usuário, o que é determinado pelo padrões de comunicação e colaboração e pelas relações comerciais do usuário.

Você pode obter essas informações por meio da API do People. Para obter exemplos, consulte a seção Exemplos e o artigo Usar a API People para obter informações sobre as pessoas mais relevantes para você.

Observação

Para novos desenvolvimentos, recomendamos usar a API de Pesquisa da Microsoft (POST /search/query com entityTypes: ["person"]) em vez da API People (GET /me/people e GET /users/{id | userPrincipalName}/people). A API People está em modo de manutenção. Para obter mais informações, consulte searchEntity: consultar e Usar a API de Pesquisa da Microsoft para pesquisar pessoas.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global	Governo dos EUA L4	US Government L5 (DOD)	China operada pela 21Vianet
✅	✅	✅	❌

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão	Permissões menos privilegiadas	Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante)	People.Read	People.Read.All
Delegado (conta pessoal da Microsoft)	People.Read	Indisponível.
Aplicativo	People.Read.All	Indisponível.

Solicitação HTTP

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

Parâmetros de consulta opcionais

Este método dá suporte a Parâmetros de consulta OData para ajudar a personalizar a resposta.

Nome	Valor	Descrição
$filter	string	Limita a resposta apenas às pessoas cujo registro contém os critérios especificados.
$orderby	cadeia de caracteres	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.
$search	string	Pesquisar pessoas por nome ou alias. Suporta correspondência difusa. O parâmetro só funciona para pesquisar pessoas relevantes do usuário conectado, não para pesquisar pessoas relevantes para outros usuários. Também dá suporte a `topic` palavra-chave para encontrar pessoas com base em tópicos extraídos a partir de conversas de email com essa pessoa. Para obter informações e exemplos, consulte a seção Executar uma pesquisa difusa em Use the People API para obter informações sobre as pessoas mais relevantes para você.
$select	string	Lista separada por vírgulas de propriedades para incluir na resposta. Para obter um desempenho ideal, selecione apenas o subconjunto de propriedades necessárias.
$skip	int	Ignore os primeiros n resultados, úteis para paginação. Isso não é suportado ao usar $search.
$top	int	O número máximo de resultados a serem retornados em uma página de resultados. Para obter mais informações, consulte parâmetro superior.

Cabeçalhos de solicitação

Nome	Descrição
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Aceitar	application/json

Corpo da solicitação

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

Resposta

Se for bem-sucedido, esse método retornará um 200 OK código de resposta e uma coleção de objetos person no corpo da resposta. A resposta pode conter um objeto de pessoa ou uma coleção de objetos de pessoa.

Exemplos

Solicitação

O exemplo a seguir mostra uma solicitação.

GET https://graph.microsoft.com/v1.0/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();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.



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

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-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)

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


// 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();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


const options = {
	authProvider,
};

const client = Client.init(options);

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

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


<?php
use Microsoft\Graph\GraphServiceClient;


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


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

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


Import-Module Microsoft.Graph.People

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

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph 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()

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Resposta

O exemplo a seguir mostra a resposta.

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,
            "jobTitle": null,
            "companyName": null,
            "yomiCompany": "",
            "department": null,
            "officeLocation": null,
            "profession": "",
            "userPrincipalName": "",
            "imAddress": null,
            "scoredEmailAddresses": [
                {
                    "address": "Marketing@contoso.com",
                    "relevanceScore": 30.0
                }
            ],
            "phones": [],
            "postalAddresses": [],
            "websites": [],
            "personType": {
                "class": "Group",
                "subclass": "UnifiedGroup"
            }
        },
        {
            "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",
            "displayName": "Isaiah Langer",
            "givenName": "Isaiah",
            "surname": "Langer",
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "jobTitle": "Web Marketing Manager",
            "companyName": null,
            "yomiCompany": "",
            "department": "Sales & Marketing",
            "officeLocation": "20/1101",
            "profession": "",
            "userPrincipalName": "IsaiahL@contoso.com",
            "imAddress": "sip:isaiahl@contoso.com",
            "scoredEmailAddresses": [
                {
                    "address": "IsaiahL@contoso.com",
                    "relevanceScore": 20.0
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "personType": {
                "class": "Person",
                "subclass": "OrganizationUser"
            }
        }
    ]
}

Para obter detalhes sobre a API People e mais exemplos, consulte Usar a API People para obter informações sobre as pessoas mais relevantes para você.

Comentários

Esta página foi útil?

Last updated on 2026-08-20

Listar pessoas

Permissões

Solicitação HTTP

Parâmetros de consulta opcionais

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Solicitação

Resposta

Conteúdo relacionado

Comentários

Recursos adicionais