Получение пользователя

Статья
03/05/2024

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

Получение свойств и связей объекта user.

Эта операция по умолчанию возвращает для каждого пользователя только подмножество наиболее часто используемых свойств. Эти свойства по умолчанию указаны в разделе Свойства. Чтобы получить свойства, которые не возвращаются по умолчанию, выполните операцию GET и укажите их в параметре $select запроса OData. Так как ресурс user поддерживает расширения, с помощью операции GET можно также получить настраиваемые свойства и данные расширения в экземпляре user.

Клиенты через Microsoft Entra ID для клиентов также могут использовать эту операцию API для получения сведений.

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

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

Разрешения

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

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

Совет

Для вызова конечной точки /me требуется вход пользователя и, следовательно, делегированное разрешение. Разрешения приложений не поддерживаются при использовании конечной точки /me.
Разрешение User.Read дает приложению возможность читать профиль и обнаруживать отношения, такие как членство в группах, отчеты и руководитель пользователя, вошедшего в систему.

HTTP-запрос

Для определенного пользователя:

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

Совет

Когда userPrincipalName начинается с символа $, синтаксис URL-адреса запроса GET /users/$x@y.com приводит к сбою с кодом ошибки 400 Bad Request. Это связано с тем, что этот URL-адрес запроса нарушает соглашение об URL-адресе OData, которые ожидают, что только параметры системного запроса будут иметь префикс символа $. Удалите косую черту (/) после /users и заключите userPrincipalName в скобки и одинарные кавычки следующим образом: /users('$x@y.com'). Например, /users('$AdeleVance@contoso.com').
Чтобы запросить пользователя B2B с помощью userPrincipalName, закодируйте хэш-символ (#). То есть замените символ # на %23. Например, /users/AdeleVance_adatum.com%23EXT%23@contoso.com.

Для вошедшего пользователя:

GET /me

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

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

По умолчанию возвращается только ограниченный набор свойств (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName).

Чтобы возвратить альтернативный набор свойств, необходимо указать нужный набор свойств user с помощью параметра запроса OData $select. Например, чтобы вернуть displayName, givenName и postalCode, добавьте в запрос $select=displayName,givenName,postalCodeследующее выражение .

Свойства расширения также поддерживают параметры запроса следующим образом:

Тип расширения	Комментарии
onPremisesExtensionAttributes 1-15	Возвращается только с помощью `$select`.
Расширения схемы	Возвращается только с помощью `$select`.
Открытые расширения	Возвращается только с помощью операции Получить открытое расширение.
Расширения каталога	Возвращается только с помощью `$select`.

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

Заголовок	Значение
Авторизация	Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.

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

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

Отклик

При успешном выполнении этот метод возвращает код отклика 200 OK и объект user в тексте отклика. Он возвращает свойства по умолчанию, если не используется $select для указания конкретных свойств.

В случае успешной обработки запроса этот метод возвращает 202 Accepted, но серверу требуется дополнительное время для выполнения соответствующих фоновых операций.

Примеры

Пример 1. Обычный запрос пользователей

Запрос

GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd


// 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.Users["{user-id}"].GetAsync();


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



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get();


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


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


$result = $graphServiceClient->users()->byUserId('user-id')->get()->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.users.by_user_id('user-id').get()

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "displayName": "Adele Vance",
   "givenName": "Adele",
   "jobTitle": "Retail Manager",
   "mail": "AdeleV@contoso.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

Пример 2. Запрос для вошедшего пользователя

Вы можете получить информацию о вошедшем пользователе, заменив /users/{id | userPrincipalName} на /me.

Запрос

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


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


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



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



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


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.me().get();


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?php
use Microsoft\Graph\GraphServiceClient;


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


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


Import-Module Microsoft.Graph.Users

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


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.me.get()

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "displayName": "Adele Vance",
   "givenName": "Adele",
   "jobTitle": "Retail Manager",
   "mail": "AdeleV@contoso.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

Пример 3. Использование $select для получения определенных свойств пользователя

Чтобы получить определенные свойства, используйте параметр запроса $select OData. Например, чтобы возвратить свойства displayName, givenName,postalCodeи удостоверения,в запрос следует добавить следующее: $select=displayName,givenName,postalCode,identities

Запрос

GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd?$select=displayName,givenName,postalCode,identities


// 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.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","givenName","postalCode","identities" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users get --user-id {user-id} --select "displayName,givenName,postalCode,identities"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","givenName","postalCode","identities"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "givenName", "postalCode", "identities"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd')
	.select('displayName,givenName,postalCode,identities')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","givenName","postalCode","identities"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "displayName,givenName,postalCode,identities"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
		select = ["displayName","givenName","postalCode","identities"],
)

request_configuration = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,givenName,postalCode,identities)/$entity",
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "postalCode": "98004",
    "identities": [
        {
            "signInType": "userPrincipalName",
            "issuer": "contoso.com",
            "issuerAssignedId": "AdeleV@contoso.com"
        }
    ]
}

Пример 4. Получение значения расширения схемы для пользователя

Идентификатор расширения схемы в этом примере: ext55gb1l09_msLearnCourses

Запрос

GET https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e?$select=ext55gb1l09_msLearnCourses


// 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.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "ext55gb1l09_msLearnCourses" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users get --user-id {user-id} --select "ext55gb1l09_msLearnCourses"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
	Select: [] string {"ext55gb1l09_msLearnCourses"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"ext55gb1l09_msLearnCourses"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e')
	.select('ext55gb1l09_msLearnCourses')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["ext55gb1l09_msLearnCourses"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "ext55gb1l09_msLearnCourses"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
		select = ["ext55gb1l09_msLearnCourses"],
)

request_configuration = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(ext55gb1l09_msLearnCourses)/$entity",
    "ext55gb1l09_msLearnCourses": {
        "@odata.type": "#microsoft.graph.ComplexExtensionValue",
        "courseType": "Developer",
        "courseName": "Introduction to Microsoft Graph",
        "courseId": 1
    }
}

Пример 5. Получение назначений настраиваемых атрибутов безопасности для пользователя

В следующем примере показано, как получить пользовательские назначения атрибутов безопасности для пользователя.

Атрибут №1

Набор атрибутов: Engineering
Атрибут: Project
Тип данных атрибута: коллекция строк
Значение атрибута: ["Baker","Cascade"]

Атрибут №2

Набор атрибутов: Engineering
Атрибут: CostCenter
Тип данных атрибута: коллекция целых чисел
Значение атрибута: [1001]

Атрибут №3

Набор атрибутов: Engineering
Атрибут: Certification
Тип данных атрибута: логический
Значение атрибута: true

Атрибут №4

Набор атрибутов: Marketing
Атрибут: EmployeeId
Тип данных атрибута: строка
Значение атрибута: "QN26904"

Чтобы получить назначения настраиваемых атрибутов безопасности, вызывающему субъекту должна быть назначена роль читателя назначения атрибутов или администратора назначения атрибутов, а также должно быть предоставлено разрешение CustomSecAttributeAssignment.Read.All или CustomSecAttributeAssignment.ReadWrite.All.

Дополнительные примеры назначений настраиваемых атрибутов безопасности см. в разделе Примеры. Назначение, обновление, перечисление или удаление назначений настраиваемых атрибутов безопасности с помощью microsoft API Graph.

Запрос

GET https://graph.microsoft.com/v1.0/users/{id}?$select=customSecurityAttributes


// 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.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "customSecurityAttributes" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users get --user-id {user-id} --select "customSecurityAttributes"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
	Select: [] string {"customSecurityAttributes"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"customSecurityAttributes"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/{id}')
	.select('customSecurityAttributes')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["customSecurityAttributes"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "customSecurityAttributes"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
		select = ["customSecurityAttributes"],
)

request_configuration = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Marketing": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "EmployeeId": "QN26904"
        },
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Project@odata.type": "#Collection(String)",
            "Project": [
                "Baker",
                "Cascade"
            ],
            "CostCenter@odata.type": "#Collection(Int32)",
            "CostCenter": [
                1001
            ],
            "Certification": true
        }
    }
}

Если пользователю не назначены настраиваемые атрибуты безопасности или у вызывающего субъекта нет доступа, ответ будет следующим:

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}

Получение пользователя

Разрешения

HTTP-запрос

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

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

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

Отклик

Примеры

Пример 1. Обычный запрос пользователей

Запрос

Отклик

Пример 2. Запрос для вошедшего пользователя

Запрос

Отклик

Пример 3. Использование $select для получения определенных свойств пользователя

Запрос

Отклик

Пример 4. Получение значения расширения схемы для пользователя

Запрос

Отклик

Пример 5. Получение назначений настраиваемых атрибутов безопасности для пользователя

Запрос

Отклик

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

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

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