Список людей

Пространство имен: microsoft.graph

Получение списка объектов-пользователей , упорядоченных по их релевантности для пользователя, который определяется шаблонами взаимодействия и совместной работы пользователя, а также бизнес-отношениями.

Этот API доступен в следующих национальных облачных развертываниях.

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

HTTP-запрос

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

Необязательные параметры запросов

Этот метод поддерживает следующие параметры запроса OData для настройки ответа.

Заголовки запросов

Текст запроса

Не указывайте текст запроса для этого метода.

Отклик

В случае успешного 200 OK выполнения этот метод возвращает код отклика и коллекцию объектов person в тексте ответа.

Примеры

Обзор

Запросы в этом разделе получают людей, наиболее подходящих для пользователя, выполнившего вход (/me), на основе общения, совместной работы и деловых связей.

По умолчанию каждый ответ возвращает 10 записей, но это можно изменить с помощью параметра $top . Для этих запросов требуется Люди. Разрешение на чтение.

Запрос

Ниже приведен пример запроса по умолчанию.

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

mgc-beta users people list --user-id {user-id}

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

Отклик

Ниже показан пример отклика.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

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": "[email protected]",
                    "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": "[email protected]",
            "emailAddresses": [
                {
                    "address": "[email protected]",
                    "rank": 20
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        }
    ]
}

Запрос последующей страницы людей

Если первый ответ не содержит полный список соответствующих людей, можно выполнить второй запрос, используя $top и $skip , чтобы запросить дополнительные страницы информации. Если предыдущий запрос содержит дополнительные сведения, следующий запрос получает следующую страницу людей с сервера.

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

Сортировка в отклике

По умолчанию люди в ответе сортируются по степени соответствия запросу. Этот порядок можно изменить с помощью параметра $orderby. Этот запрос выбирает наиболее подходящих людей, сортирует их по отображаемой имени, а затем возвращает первые 10 человек в отсортированный список.

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

Изменение числа возвращенных пользователей и возвращенных полей

Вы можете изменить количество людей, возвращаемых в отклике, настроив параметр $top.

В следующем примере запрашивают 1000 пользователей, наиболее важных для /me. Запрос также ограничивает объем данных, отправляемых обратно с сервера, запрашивая только отображаемое имя пользователя.

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

Выбор возвращаемых полей

Вы можете ограничить объем данных, возвращаемых с сервера, с помощью параметра $select , чтобы выбрать одно или несколько полей. Поле @odata.id всегда возвращается.

В следующем примере ответ ограничивается displayName и EmailAddress из 10 наиболее релевантных пользователей.

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

Использование фильтра для ограничения ответа

Вы можете использовать параметр $filter, чтобы ограничить количество информации в отклике и возвращать только тех людей, записи которых содержат указанные критерии.

Следующий запрос ограничивает ответ пользователями с исходным каталогом.

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

Выбор полей для возврата в отфильтрованном ответе

Сочетая параметры $select и $filter, вы можете создать настраиваемый список людей, релевантных для пользователя, и получать только те поля, которые необходимы вашему приложению.

В следующем примере возвращаются значения DisplayName и EmailAddress людей, отображаемое имя которых равно указанному имени. В этом примере возвращаются только те, у кого отображаемое имя равно "Nestor Kellum".

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

Поиск людей

Запросы в этом разделе также содержат людей, наиболее релевантных для пользователя, выполнившего вход (/me). Поиск запросам требуется Люди. Разрешение на чтение.

Использование поиска для выбора людей

Используйте параметр $search для выбора людей, удовлетворяющих определенному набору критериев.

Следующий поисковый запрос возвращает людей, /me для которых GivenName или Фамилия начинается с буквы "j".

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

Использование поиска для указания соответствующего раздела

Следующий запрос возвращает пользователей, /me имя которых содержит "ma" и которые имеют связь с "планированием функций".

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

Выполнение нечеткого поиска

Следующий запрос выполняет поиск человека с именем Hermaini Hall. Так как для пользователя, выполнившего вход, имеется лицо с именем "Herminia Hull", возвращается информация для "Herminia Hull".

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

Связанные люди

Следующий запрос возвращает людей, наиболее релевантных другому человеку в организации пользователя. Для этого запроса требуется user.ReadBasic.All для Люди. Разрешение Read.All. В этом примере отображаются соответствующие люди Нестора Келлума.

GET https://graph.microsoft.com/beta/users('[email protected]')/people/