Список людей

Статья
08/23/2023

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

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

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

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

Глобальная служба	Правительство США L4	Правительство США L5 (DOD)	Китай управляется 21Vianet
✅	✅	✅	✅

Разрешения

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

Тип разрешения	Разрешения с наименьшими привилегиями	Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись)	People.Read	People.Read.All
Делегированные (личная учетная запись Майкрософт)	People.Read	Недоступно.
Для приложений	People.Read.All	Недоступно.

HTTP-запрос

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

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

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

Имя	Значение	Описание
$filter	string	Позволяет возвращать в отклике только тех людей, чьи записи содержат указанные критерии.
$orderby	строка	По умолчанию люди в ответе сортируются по степени соответствия запросу. Этот порядок можно изменить с помощью параметра $orderby.
$search	string	Поиск пользователей по имени или псевдониму. Поддерживается нечеткое соответствие. Параметр применяется только для поиска людей, относящихся к вошедшему пользователю, а не для поиска людей, относящихся к другим пользователям. Также поддерживает ключевое слово `topic` для поиска людей с учетом тем, извлеченных из бесед электронной почты с определенным человеком. Сведения и примеры см. в разделе Выполнение нечеткого поискав статье Использование API Люди для получения сведений о наиболее важных для вас людях.
$select	string	Разделенный запятыми список свойств, включаемых в ответ. Для оптимальной производительности выберите только подмножество необходимых свойств.
$skip	int	Пропустите первые n результатов, полезных для разбиения по страницам. Пропуск не поддерживается при использовании $search.
$top	int	Максимальное количество результатов, возвращаемых на странице результатов. Дополнительные сведения см. в разделе Top Parameter.

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

Имя	Описание
Авторизация	Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Accept	application/json

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

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

Отклик

В случае успешного 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();

Важно!

Пакеты SDK для Microsoft Graph по умолчанию используют версию API версии 1.0 и поддерживают не все типы, свойства и API, доступные в бета-версии. Дополнительные сведения о доступе к бета-API с помощью SDK см. в статье Использование пакетов Microsoft Graph SDK с бета-API.

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.


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

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по 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)

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по 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();

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.


const options = {
	authProvider,
};

const client = Client.init(options);

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

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.


<?php
use Microsoft\Graph\GraphServiceClient;


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


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

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.


Import-Module Microsoft.Graph.Beta.People

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

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

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

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

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

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

Если первый ответ не содержит полный список соответствующих людей, можно выполнить второй запрос, используя $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('nestork@contoso.com')/people/

Список людей

Разрешения

HTTP-запрос

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

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

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

Отклик

Примеры

Обзор

Запрос

Отклик

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

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

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

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

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

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

Поиск людей

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

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

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

Обратная связь

Обратная связь

Дополнительные ресурсы

Список людей

Разрешения

HTTP-запрос

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

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

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

Отклик

Примеры

Обзор

Запрос

Отклик

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

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

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

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

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

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

Поиск людей

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

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

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

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

Обратная связь

Обратная связь

Дополнительные ресурсы