Обновление пользователя
Пространство имен: microsoft.graph
Обновление свойств объекта user.
- Не все свойства могут быть обновлены пользователями-участниками или гостевыми пользователями с разрешениями по умолчанию без ролей администратора. Сравните разрешения по умолчанию для участника и гостя, чтобы узнать, какими свойствами они могут управлять.
- Клиенты через Microsoft Entra ID для клиентов также могут использовать эту операцию API для обновления своих сведений. Список свойств, которые они могут обновить, см. в статье Разрешения пользователей по умолчанию в клиентах клиентов .
- Для синхронизированных пользователей возможность обновления определенных свойств дополнительно определяется источником центра и включена ли синхронизация.
Этот API доступен в следующих национальных облачных развертываниях.
Глобальная служба | Правительство США L4 | Правительство США L5 (DOD) | Китай управляется 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Разрешения
Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.
Тип разрешения | Разрешения с наименьшими привилегиями | Более высокие привилегированные разрешения |
---|---|---|
Делегированные (рабочая или учебная учетная запись) | User.ReadWrite | User.ManageIdentities.All, User.EnableDisableAccount.All, User.ReadWrite.All, Directory.ReadWrite.All |
Делегированные (личная учетная запись Майкрософт) | User.ReadWrite | Недоступно. |
Приложение | User.ManageIdentities.All | User.EnableDisableAccount.All, User.ReadWrite.All, Directory.ReadWrite.All |
Примечание.
- Чтобы обновить конфиденциальные свойства пользователей, такие как accountEnabled, mobilePhone и другие сообщения Электронной почты для пользователей с привилегированными ролями администратора, выполните следующие действия:
- В делегированных сценариях приложению должно быть назначено делегированное разрешение Directory.AccessAsUser.All , а вызывающий пользователь должен иметь более высокую привилегированную роль администратора, как указано в разделе Кто может выполнять конфиденциальные действия.
- В сценариях только для приложений приложению должна быть назначена более высокая роль привилегированного администратора, как указано в разделе Кто может выполнять конфиденциальные действия.
- Ваша личная учетная запись Майкрософт должна быть привязана к клиенту Microsoft Entra, чтобы обновить профиль с делегированным разрешением User.ReadWrite для личной учетной записи Майкрософт.
- Для обновления свойства удостоверений требуется разрешение User.ManageIdentities.All . Кроме того, добавление локальной учетной записи B2C к существующему объекту пользователя не допускается, если только объект пользователя не содержит идентификатор локальной учетной записи.
- Чтобы обновить свойство employeeLeaveDateTime, выполните следующие действия:
- В делегированных сценариях администратору требуется роль глобального администратора ; приложению должны быть предоставлены делегированные разрешения User.Read.All и User-LifeCycleInfo.ReadWrite.All .
- В сценариях только для приложений с разрешениями Microsoft Graph приложению должны быть предоставлены разрешения User.Read.All и User-LifeCycleInfo.ReadWrite.All .
- Чтобы обновить свойство customSecurityAttributes , выполните следующие действия:
- В делегированных сценариях администратору должна быть назначена роль администратора назначения атрибутов , а приложению — разрешение CustomSecAttributeAssignment.ReadWrite.All .
- В сценариях только для приложений с разрешениями Microsoft Graph приложению должно быть предоставлено разрешение CustomSecAttributeAssignment.ReadWrite.All .
HTTP-запрос
PATCH /users/{id | userPrincipalName}
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
Content-Type | application/json |
Текст запроса
В тексте запроса укажите только значения свойств для обновления. Существующие свойства, которые не включены в текст запроса, сохраняют свои предыдущие значения или пересчитываются на основе изменений других значений свойств.
В следующей таблице указаны свойства, которые можно обновить.
Свойство | Тип | Описание |
---|---|---|
aboutMe | String | Свободное текстовое поле, где пользователь может рассказать о себе. |
accountEnabled | Логический | Если учетная запись обеспечена — true , в противном случае — false . Это свойство обязательно указывать при создании пользователя. Администратор привилегированной проверки подлинности, которому назначено делегированное разрешение Directory.AccessAsUser.All , является наименее привилегированной ролью, которая может обновлять состояние accountEnabled всех администраторов в клиенте. |
ageGroup | ageGroup | Устанавливает возрастную группу пользователя. Допустимые значения: null , Minor , NotAdult и Adult . Дополнительные сведения см. в разделе Определения свойств юридических возрастных групп. |
birthday | DateTimeOffset | День рождения пользователя. Тип Timestamp представляет сведения о времени и дате с использованием формата ISO 8601 (всегда применяется формат UTC). Например, значение полуночи 1 января 2014 г. в формате UTC: 2014-01-01T00:00:00Z . |
businessPhones | Коллекция строк | Номера телефонов пользователя. ПРИМЕЧАНИЕ. Несмотря на то что это коллекция строк, для этого свойства можно задать только один номер. |
city | String | Город, в котором находится пользователь. |
CompanyName | String | Имя компании, с которым связан пользователь. Это свойство может быть полезно для описания компании внешнего пользователя. Максимальная длина: 64 символа. |
consentProvidedForMinor | consentProvidedForMinor | Устанавливает, получено ли согласие для несовершеннолетних. Допустимые значения: null , Granted , Denied и NotRequired . Дополнительные сведения см. в разделе Определения свойств юридических возрастных групп. |
country | String | Страна или регион, в котором находится пользователь, например US или UK . |
customSecurityAttributes | customSecurityAttributeValue | Открытый сложный тип, который содержит значение настраиваемого атрибута безопасности, назначенного объекту каталога. |
department | String | Название отдела, в котором работает пользователь. |
displayName | String | Имя пользователя, отображаемое в адресной книге. Обычно это сочетание имени, отчества и фамилии пользователя. Это свойство является обязательным при создании пользователя и его невозможно очистить во время обновлений. |
employeeId | String | Идентификатор сотрудника, назначенный пользователю организацией. Максимальная длина составляет 16 символов. |
employeeType | String | Фиксирует тип корпоративного работника. Например, Employee , Contractor , Consultant или Vendor . Возвращается только с помощью оператора $select . |
givenName; | String | Простое имя пользователя. |
employeeHireDate | DateTimeOffset | Дата найма пользователя. Тип Timestamp представляет сведения о времени и дате с использованием формата ISO 8601 (всегда применяется формат UTC). Например, значение полуночи 1 января 2014 г. в формате UTC: 2014-01-01T00:00:00Z . |
employeeLeaveDateTime | DateTimeOffset | Дата и время, когда пользователь покинет организацию или покинет ее. Тип метки времени представляет сведения о дате и времени в формате ISO 8601 и всегда находится в формате UTC. Например, значение полуночи 1 января 2014 г. в формате UTC: 2014-01-01T00:00:00Z .В делегированных сценариях вызывающий пользователь должен иметь роль глобального администратора , а вызывающему приложению назначены делегированные разрешения User.Read.All и User-LifeCycleInfo.ReadWrite.All . |
employeeOrgData | employeeOrgData | Представляет данные организации (например, division и costCenter), связанные с пользователем. |
interests; | Коллекция строк | Список интересов пользователя. |
jobTitle | String | Должность пользователя. |
String | SMTP-адрес пользователя, например [email protected] . Изменения этого свойства также обновят коллекцию proxyAddresses пользователя, чтобы включить значение в качестве SMTP-адреса. Для Azure AD учетных записей B2C это свойство можно обновить до 10 раз с помощью уникальных SMTP-адресов. Не удается обновить до null . |
|
mailNickname | String | Почтовый псевдоним для пользователя. Это свойство должно быть указано при создании пользователя. |
mobilePhone | String | Основной сотовый телефон пользователя. |
mySite | String | URL-адрес личного сайта пользователя. |
officeLocation | String | Расположение офиса на месте работы пользователя. |
onPremisesExtensionAttributes | onPremisesExtensionAttributes | Содержит свойства extensionAttribute 1–15 для пользователя. Отдельные атрибуты расширения не могут быть выбраны или фильтруемы. Для пользователей onPremisesSyncEnabled исходным центром управления для этого набора свойств является локальная среда, и он предназначен только для чтения. Эти атрибуты расширения также называются настраиваемыми атрибутами 1–15 Exchange. |
onPremisesImmutableId | String | Это свойство используется для связывания учетной записи пользователя локальная служба Active Directory с объектом Microsoft Entra пользователя. Это свойство должно быть указано при создании новой учетной записи пользователя в Graph, если вы используете федеративный домен для свойства userPrincipalName (UPN) пользователя. Важный: Символы $ и _ нельзя использовать при указании этого свойства. |
otherMails | Коллекция строк | Список дополнительных адресов электронной почты для пользователя. Например: ["[email protected]", "[email protected]"] . |
passwordPolicies | String | Задает политики паролей для пользователя. Это свойство представляет собой перечисление с возможным значением DisableStrongPassword . Оно позволяет использовать менее надежные пароли, чем предусмотрено политикой по умолчанию. Вы также можете указать значение DisablePasswordExpiration . Их можно указать вместе; например: DisablePasswordExpiration, DisableStrongPassword . |
passwordProfile | PasswordProfile | Задает профиль пароля для пользователя. Профиль содержит пароль пользователя. Пароль в профиле должен соответствовать минимальным требованиям, указанным в свойстве passwordPolicies. По умолчанию требуется надежный пароль. Рекомендуется всегда задавать для параметра forceChangePasswordNextSignIn значение true . Его нельзя использовать для федеративных пользователей. |
pastProjects | Коллекция строк | Список предыдущих проектов пользователя. |
postalCode | String | Почтовый индекс адреса пользователя. Формат почтового индекса зависит от страны или региона пользователя. В США для этого атрибута используется ZIP-код. |
preferredLanguage | String | Предпочитаемый язык для пользователя. Он должен быть представлен в формате ISO 639-1, например en-US . |
responsibilities; | Коллекция строк | Список обязанностей пользователя. |
schools | Коллекция строк | Список для пользователя для перечисления учебных заведений, которые они посещали. |
skills | Коллекция строк | Список навыков пользователя. |
state | String | Область, республика, край или округ в адресе пользователя. |
streetAddress | String | Почтовый адрес места работы пользователя. |
surname | String | Фамилия пользователя. |
usageLocation | String | Двухбуквенный код страны (по стандарту ISO 3166). Необходим для пользователей, которым будут назначены лицензии, в связи с законодательным требованием проверять доступность служб в разных странах. Примеры: US , JP и GB . Значение null не допускается. |
userPrincipalName | String | Имя участника-пользователя. Имя участника-пользователя — это имя для входа в интернет-стиле для пользователя, основанное на стандарте Интернета RFC 822. В соответствии с соглашением оно должно указывать на имя пользователя для электронной почты. Общий формат: псевдоним@домен. При этом домен должен входить в коллекцию проверенных доменов клиента. Доступ к проверенным доменам клиента можно получить с помощью свойства verifiedDomains объекта organization. ПРИМЕЧАНИЕ. Это свойство не может содержать знаки акцента. Разрешены только следующие символы: A - Z , a - z , 0 - 9 , ' . - _ ! # ^ ~ . Полный список разрешенных символов см. в политиках имен пользователей. |
userType | String | Строковое значение, с помощью которого можно классифицировать типы пользователей в каталоге, например Member и Guest . |
Примечание.
- Следующие свойства не могут быть обновлены приложением только с разрешениями приложения: aboutMe, birthday, employeeHireDate, interests, mySite, pastProjects, responsibilities, schools, и skills.
- Чтобы обновить следующие свойства, необходимо указать их в своем запросе PATCH, не включив другие свойства: aboutMe, день рождения, интересы, mySite, pastProjects, обязанности, учебные заведения и навыки.
Управление расширениями и связанными данными
Используйте этот API для управления каталогом, схемой и открытыми расширениями и их данными для пользователей следующим образом:
- Добавление, обновление и хранение данных в расширениях для существующего пользователя
- Для расширений каталогов и схем удалите все сохраненные данные, задав для свойства пользовательского расширения значение
null
. Для открытых расширений используйте API удаления открытых расширений.
Отклик
В случае успешного выполнения этот метод возвращает код отклика 204 No Content
.
Пример
Пример 1. Обновление свойств вошедшего пользователя
Запрос
Ниже показан пример запроса.
PATCH https://graph.microsoft.com/v1.0/me
Content-type: application/json
{
"businessPhones": [
"+1 425 555 0109"
],
"officeLocation": "18/2111"
}
Отклик
Ниже показан пример отклика.
HTTP/1.1 204 No Content
Пример 2. Обновление свойств указанного пользователя
Запрос
Ниже показан пример запроса.
PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json
{
"businessPhones": [
"+1 425 555 0109"
],
"officeLocation": "18/2111"
}
Отклик
Ниже показан пример отклика.
HTTP/1.1 204 No Content
Пример 3. Обновление passwordProfile пользователя и сброс пароля
В приведенном ниже примере показан запрос на сброс пароля другого пользователя. Рекомендуется всегда задавать для параметра forceChangePasswordNextSignIn значение true
.
- При делегированном доступе вызывающему приложению должен быть назначено делегированное разрешение от имени вошедшего пользователя Directory.AccessAsUser.All.
- При доступе только к приложению вызывающему приложению необходимо назначить разрешение приложения User.ReadWrite.All (минимальные привилегии) или Directory.ReadWrite.All (более высокие привилегии) и по крайней мере роль администратора пользователейMicrosoft Entra.
Запрос
PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json
{
"passwordProfile": {
"forceChangePasswordNextSignIn": false,
"password": "xWwvJ]6NMw+bWH-d"
}
}
Отклик
HTTP/1.1 204 No Content
Пример 4. Добавление или обновление значений расширения схемы для пользователя
Можно обновить или назначить значение одному свойству или всем свойствам в расширении.
Запрос
PATCH https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e
Content-type: application/json
{
"ext55gb1l09_msLearnCourses": {
"courseType": "Admin"
}
}
Чтобы удалить значение расширения схемы из объекта user, задайте для свойства ext55gb1l09_msLearnCourses значение null
.
Отклик
HTTP/1.1 204 No Content
Пример 5. Назначение пользовательского атрибута безопасности со строковым значением пользователю
В следующем примере показано, как назначить пользователю настраиваемый атрибут безопасности со строковым значением.
- Набор атрибутов:
Engineering
- Атрибут:
ProjectDate
- Тип данных атрибута: строка
- Значение атрибута:
"2022-10-01"
Чтобы назначить настраиваемые атрибуты безопасности, вызывающему субъекту должна быть присвоена роль администратора назначения атрибутов и должно быть предоставлено разрешение CustomSecAttributeAssignment.ReadWrite.All.
Примеры назначений настраиваемых атрибутов безопасности см. в разделе Примеры. Назначение, обновление, перечисление или удаление назначений настраиваемых атрибутов безопасности с помощью API Graph Майкрософт.
Запрос
PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json
{
"customSecurityAttributes":
{
"Engineering":
{
"@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
"ProjectDate":"2022-10-01"
}
}
}
Отклик
HTTP/1.1 204 No Content