Listar pessoas

Artigo
08/23/2023

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Recupere uma lista de objetos de pessoa ordenados por sua relevância para o usuário, que é determinada pelos padrões de comunicação e colaboração do usuário e relações comerciais.

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

Serviço global	Governo dos EUA L4	GOVERNO DOS EUA L5 (DOD)	China operada pela 21Vianet
✅	✅	✅	✅

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas 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 privilegiadas mais altas
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

Esse método dá suporte aos seguintes 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 Usar a API Pessoas 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 um desempenho ideal, selecione apenas o subconjunto de propriedades necessárias.
$skip	int	Ignore os primeiros resultados n, úteis para paginação. Não há suporte para ignorar 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, confira o 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 de pessoa no corpo da resposta.

Exemplos

Navegar

As solicitações nesta seção obtêm as pessoas mais relevantes para o usuário conectado (/me), com base nas relações de comunicação, colaboração e negócios.

Por padrão, cada resposta retorna 10 registros, mas você pode alterar esse número usando o parâmetro $top. Essas solicitações exigem o Pessoas. Permissão de leitura.

Solicitação

A seguir está um exemplo da solicitação padrão.

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

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users people list --user-id {user-id}

Importante

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



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



people, err := graphClient.Me().People().Get(context.Background(), nil)

Importante

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

Importante

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')
	.version('beta')
	.get();

Importante

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

Importante

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.Beta.People

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

Importante

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


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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

Importante

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.

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, você poderá fazer uma segunda solicitação usando $top e $skip para solicitar 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 a seguir solicita as 1.000 pessoas mais relevantes para /me. A solicitação também limita a quantidade de dados enviados do servidor solicitando apenas o nome de exibição da pessoa.

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

Seleção dos campos que devem ser retornados

Você pode limitar a quantidade de dados retornados do servidor usando o parâmetro $select para escolher um ou mais campos. O campo @odata.id é sempre retornado.

O exemplo a seguir limita a resposta ao 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 a seguir 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')

Selecionando 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 a seguir obtém o DisplayName e EmailAddress de pessoas cujo nome de exibição é 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

As solicitações nesta seção também obtêm as pessoas mais relevantes para o usuário conectado (/me). Pesquisa solicitações exigem o Pessoas. Permissão de leitura.

Usando 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 GivenName ou Sobrenome 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

A solicitação a seguir retorna pessoas relevantes para /me cujo nome contém "ma" e que têm uma associação com "planejamento de recursos".

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

Execução de uma pesquisa difusa

A solicitação a seguir faz uma pesquisa por uma pessoa chamada "Hermaini Hall". Como há uma pessoa chamada "Herminia Hull" relevante para o usuário conectado, as informações de "Herminia Hull" são retornadas.

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

A solicitação a seguir obtém as pessoas mais relevantes para outra pessoa na organização do usuário. Essa solicitação requer o User.ReadBasic.All para Pessoas. Permissão Read.All. Neste exemplo, as pessoas relevantes de Nestor Kellum são exibidas.

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

Listar pessoas

Permissões

Solicitação HTTP

Parâmetros de consulta opcionais

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Navegar

Solicitação

Resposta

Solicitação de uma página subsequente de pessoas

Classificar a resposta

Alteração do número de pessoas e dos campos retornados

Seleção dos campos que devem ser retornados

Uso de um filtro para limitar a resposta

Selecionando os campos a serem retornados em uma resposta filtrada

Pesquisar pessoas

Usando a pesquisa para selecionar pessoas

Uso da pesquisa para especificar um tópico relevante

Execução de uma pesquisa difusa

Comentários

Comentários

Recursos adicionais

Listar pessoas

Permissões

Solicitação HTTP

Parâmetros de consulta opcionais

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Navegar

Solicitação

Resposta

Solicitação de uma página subsequente de pessoas

Classificar a resposta

Alteração do número de pessoas e dos campos retornados

Seleção dos campos que devem ser retornados

Uso de um filtro para limitar a resposta

Selecionando os campos a serem retornados em uma resposta filtrada

Pesquisar pessoas

Usando a pesquisa para selecionar pessoas

Uso da pesquisa para especificar um tópico relevante

Execução de uma pesquisa difusa

Pessoas relacionadas

Comentários

Comentários

Recursos adicionais