Listar pessoas

  • Artigo

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 Pessoas. Para obter exemplos, consulte a seção Exemplos e o artigo Usar a API Pessoas para obter informações sobre as pessoas mais relevantes para você.

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

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 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 isso 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. A resposta pode conter um objeto de pessoa ou uma coleção de objetos pessoais.

Exemplos

Solicitação

O exemplo a seguir mostra uma solicitação.

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

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"
            }
        }
    ]
}

Conteúdo relacionado