更新用户
本文内容
命名空间:microsoft.graph
更新 user 对象的属性。 并非所有属性都可以在没有管理员角色的情况下由具有其默认权限的成员或来宾用户更新。 比较成员和来宾默认 权限,查看其可管理的属性。
权限
要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限 。
权限类型
权限(从最低特权到最高特权)
委派(工作或学校帐户)
User.ReadWrite、User.ReadWrite.All、User.ManageIdentities.All、Directory.ReadWrite.All
委派(个人 Microsoft 帐户)
User.ReadWrite
应用程序
User.ReadWrite.All、User.ManageIdentities.All、Directory.ReadWrite.All
备注
如需更新其他用户的 businessPhones 、mobilePhone 或 otherMails 属性,仅允许针对非管理员或分配了以下角色之一的用户执行该操作:目录读取者、来宾邀请者、消息中心读取者和报告读取者。 有关详细信息,请参阅 Azure AD 内置角色帮助人员(密码) 。 这适用于获得了 User.ReadWrite.All 或 Directory.ReadWrite.All 委派或应用程序权限的应用。 只有分配了 Directory.AccessAsUser.All 权限的全局管理员才能为更多特权管理员更新这些属性。
个人 Microsoft 帐户必须绑定到 AAD 租户,才能使用 User.ReadWrite 对个人 Microsoft 帐户的委派权限更新配置文件。
更新 标识 属性需要 User.ManageIdentities.All 权限。此外,不允许将 B2C 本地帐户 添加到现有 用户 对象,除非 用户 对象已包含本地帐户标识。
HTTP 请求
PATCH /users/{id | userPrincipalName}
标头
值
Authorization
Bearer {token}。必需。
Content-Type
application/json
请求正文
在请求正文中,提供应更新的相关字段的值。请求正文中不包括的现有属性将保留其以前的值,或根据对其他属性值的更改重新计算。为了获得最佳性能,不应包括尚未更改的现有值。
属性
类型
说明
aboutMe
String
任意形式的文本输入字段,用于介绍用户自身。
accountEnabled
Boolean
启用帐户时为 true,否则为 false。 创建用户时此属性是必需的。 分配了 Directory.AccessAsUser.All 委派权限的全局管理员可以更新租户中所有管理员的 accountEnabled 状态。
ageGroup
ageGroup
设置用户的年龄组。 允许的值:null、Minor、NotAdult 和 Adult。 请参阅法定年龄组属性定义 以了解详细信息。
birthday
DateTimeOffset
用户的生日。时间戳类型表示使用 ISO 8601 格式的日期和时间信息,并且始终处于 UTC 时间。例如,2014 年 1 月 1 日午夜 UTC 为 2014-01-01T00:00:00Z
businessPhones
String collection
用户的电话号码。注意:虽然这是字符串集合,但是只能为该属性设置一个号码。
城市
String
用户所在的城市。
CompanyName
String
与用户关联的公司名称。 此属性可用于描述外部用户所属的公司。 最大长度为 64 个字符。
consentProvidedForMinor
consentProvidedForMinor
设置是否已获得未成年人的同意。 允许的值:null、Granted、Denied 和 NotRequired。 请参阅法定年龄组属性定义 以了解详细信息。
country
String
用户所在的国家/地区;例如, US 或 UK。
department
String
用户工作部门的名称。
displayName
String
用户通讯簿中显示的名称,通常是用户名字、中间名首字母和姓氏的组合。此属性在创建用户时是必需的,并且在更新过程中不能清除。
employeeId
String
由组织分配给该用户的员工标识符。 最大长度为 16 个字符。
employeeType
String
捕获企业员工类型。 例如,Employee、Contractor、Consultant 或 Vendor。 仅在 $select 上返回。
givenName
String
用户的名。
employeeHireDate
DateTimeOffset
用户的雇佣日期。时间戳类型表示使用 ISO 8601 格式的日期和时间信息,并且始终处于 UTC 时间。例如,2014 年 1 月 1 日午夜 UTC 为 2014-01-01T00:00:00Z
interests
String collection
用户介绍自身兴趣的列表。
jobTitle
String
用户的职务。
mail
String
用户的 SMTP 地址,例如, jeff@contoso.onmicrosoft.com。 对此属性的更改也将更新用户的 proxyAddresses 集合,以便将该值包含为 SMTP 地址。 对于 Azure AD B2C 帐户,此属性最多可以使用唯一的 SMTP 地址更新 10 次。
mailNickname
String
用户的邮件别名。创建用户时必须指定此属性。
mobilePhone
String
用户的主要移动电话号码。
mySite
String
用户个人网站的 URL。
officeLocation
String
用户公司地点的办公室位置。
onPremisesExtensionAttributes
onPremisesExtensionAttributes
包含用户的 extensionAttributes 1-15。 请注意,单个扩展属性既不可选择,也不可筛选。 对于 onPremisesSyncEnabled 用户,这组属性集的授权来源是本地,并且为只读。 这些扩展属性也称 Exchange 自定义属性 1-15。
onPremisesImmutableId
String
此属性用于将本地 Active Directory 用户帐户关联到他们的 Azure AD 用户对象。如果对用户的 userPrincipalName (UPN) 属性使用联盟域,在 Graph 中创建新用户帐户时必须指定此属性。重要事项: 指定该属性时不能使用 $ 和 _ 字符。
otherMails
字符串集合
用户的其他电子邮件地址列表;例如:["bob@contoso.com", "Robert@fabrikam.com"]。
passwordPolicies
String
指定用户的密码策略。此值是一个枚举,其中一个可能的值为 DisableStrongPassword,这允许指定比默认策略更弱的密码。也可指定 DisablePasswordExpiration。两者可以一起指定,例如:DisablePasswordExpiration, DisableStrongPassword。
passwordProfile
PasswordProfile
指定用户的密码配置文件。配置文件包含用户的密码。创建用户时此属性是必需的。配置文件中的密码必须满足 passwordPolicies 属性指定的最低要求。默认情况下,必须使用强密码。不能用于联合用户。 在委派访问中,必须代表已登录用户向调用应用分配 Directory.AccessAsUser.All 委派权限。 在仅限应用程序的访问权限中,必须为调用应用分配 User.ReadWrite.All 应用程序权限,以及至少 用户管理员 Azure AD 角色 。
pastProjects
String collection
供用户枚举其过去项目的列表。
postalCode
String
用户邮政地址的邮政编码。邮政编码特定于用户所在的国家/地区。在美国,此属性包含邮政编码。
preferredLanguage
String
用户的首选语言。应遵循 ISO 639-1 代码,例如 en-US。
responsibilities
String collection
供用户枚举其职责的列表。
schools
String collection
供用户枚举其学习过的学校列表。
skills
String collection
供用户枚举其技能的列表。
state
String
用户地址中的省/市/自治区或省。
streetAddress
String
用户公司地点的街道地址。
surname
String
用户的姓氏。
usageLocation
String
两个字母的国家/地区代码(ISO 标准 3166)。 由于法律要求,将被分配许可证的用户需要检查国家/地区的服务可用性。 示例包括:US、JP、GB。不可为 null。
userPrincipalName
字符串
用户的用户主体名称 (UPN)。UPN 是用户基于 Internet 标准 RFC 822 的 Internet 式登录名。按照惯例,此名称应映射到用户的电子邮件名称。常规格式是 alias@domain,其中,domain 必须位于租户的已验证域集合中。可从 组织 的 verifiedDomains 属性访问租户的已验证域。 注意:此属性不能包含突出字符。 仅支持使用以下字符:A - Z、a - z、0 - 9、 ' . - _ ! # ^ ~。 有关允许字符的完整列表,请参阅用户名策略 。
userType
String
可用于对目录中的用户类型进行分类的字符串值,例如Member``Guest。
备注
只有应用程序权限的应用无法更新以下属性:aboutMe 、birthday employeeHireDate 、interests 、mySite 、pastProjects 、responsibilities 、schools 和 skills 。
要更新以下属性,必须在其自身 PATCH 请求中指定它们,而无需包含上表中列出的其他属性:aboutMe 、birthday 、interests 、mySite 、pastProjects 、responsibilities 、schools 和 skills 。
管理扩展名和关联的数据
使用此 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"
}
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
BusinessPhones = new List<String>()
{
"+1 425 555 0109"
},
OfficeLocation = "18/2111"
};
await graphClient.Me
.Request()
.UpdateAsync(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
const user = {
businessPhones: [
'+1 425 555 0109'
],
officeLocation: '18/2111'
};
await client.api('/me')
.update(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];
NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me"]]];
[urlRequest setHTTPMethod:@"PATCH"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
MSGraphUser *user = [[MSGraphUser alloc] init];
NSMutableArray *businessPhonesList = [[NSMutableArray alloc] init];
[businessPhonesList addObject: @"+1 425 555 0109"];
[user setBusinessPhones:businessPhonesList];
[user setOfficeLocation:@"18/2111"];
NSError *error;
NSData *userData = [user getSerializedDataWithError:&error];
[urlRequest setHTTPBody:userData];
MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {
//Request Completed
}];
[meDataTask execute];
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
User user = new User();
LinkedList<String> businessPhonesList = new LinkedList<String>();
businessPhonesList.add("+1 425 555 0109");
user.businessPhones = businessPhonesList;
user.officeLocation = "18/2111";
graphClient.me()
.buildRequest()
.patch(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)
requestBody := msgraphsdk.NewUser()
requestBody.SetBusinessPhones( []String {
"+1 425 555 0109",
}
officeLocation := "18/2111"
requestBody.SetOfficeLocation(&officeLocation)
graphClient.Me().Patch(requestBody)
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
$params = @{
BusinessPhones = @(
"+1 425 555 0109"
)
OfficeLocation = "18/2111"
}
# A UPN can also be used as -UserId.
Update-MgUser -UserId $userId -BodyParameter $params
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
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"
}
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
BusinessPhones = new List<String>()
{
"+1 425 555 0109"
},
OfficeLocation = "18/2111"
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
const user = {
businessPhones: [
'+1 425 555 0109'
],
officeLocation: '18/2111'
};
await client.api('/users/{id}')
.update(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];
NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users/{id}"]]];
[urlRequest setHTTPMethod:@"PATCH"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
MSGraphUser *user = [[MSGraphUser alloc] init];
NSMutableArray *businessPhonesList = [[NSMutableArray alloc] init];
[businessPhonesList addObject: @"+1 425 555 0109"];
[user setBusinessPhones:businessPhonesList];
[user setOfficeLocation:@"18/2111"];
NSError *error;
NSData *userData = [user getSerializedDataWithError:&error];
[urlRequest setHTTPBody:userData];
MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {
//Request Completed
}];
[meDataTask execute];
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
User user = new User();
LinkedList<String> businessPhonesList = new LinkedList<String>();
businessPhonesList.add("+1 425 555 0109");
user.businessPhones = businessPhonesList;
user.officeLocation = "18/2111";
graphClient.users("{id}")
.buildRequest()
.patch(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)
requestBody := msgraphsdk.NewUser()
requestBody.SetBusinessPhones( []String {
"+1 425 555 0109",
}
officeLocation := "18/2111"
requestBody.SetOfficeLocation(&officeLocation)
userId := "user-id"
graphClient.UsersById(&userId).Patch(requestBody)
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
$params = @{
BusinessPhones = @(
"+1 425 555 0109"
)
OfficeLocation = "18/2111"
}
Update-MgUser -UserId $userId -BodyParameter $params
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
HTTP/1.1 204 No Content
示例 3:更新用户的 passwordProfile 以重置其密码
下列示例展示重置其他用户密码的请求。
请求
PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json
{
"passwordProfile": {
"forceChangePasswordNextSignIn": false,
"password": "xWwvJ]6NMw+bWH-d"
}
}
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
PasswordProfile = new PasswordProfile
{
ForceChangePasswordNextSignIn = false,
Password = "xWwvJ]6NMw+bWH-d"
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
const user = {
passwordProfile: {
forceChangePasswordNextSignIn: false,
password: 'xWwvJ]6NMw+bWH-d'
}
};
await client.api('/users/{id}')
.update(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];
NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users/{id}"]]];
[urlRequest setHTTPMethod:@"PATCH"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
MSGraphUser *user = [[MSGraphUser alloc] init];
MSGraphPasswordProfile *passwordProfile = [[MSGraphPasswordProfile alloc] init];
[passwordProfile setForceChangePasswordNextSignIn: false];
[passwordProfile setPassword:@"xWwvJ]6NMw+bWH-d"];
[user setPasswordProfile:passwordProfile];
NSError *error;
NSData *userData = [user getSerializedDataWithError:&error];
[urlRequest setHTTPBody:userData];
MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {
//Request Completed
}];
[meDataTask execute];
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
User user = new User();
PasswordProfile passwordProfile = new PasswordProfile();
passwordProfile.forceChangePasswordNextSignIn = false;
passwordProfile.password = "xWwvJ]6NMw+bWH-d";
user.passwordProfile = passwordProfile;
graphClient.users("{id}")
.buildRequest()
.patch(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)
requestBody := msgraphsdk.NewUser()
passwordProfile := msgraphsdk.NewPasswordProfile()
requestBody.SetPasswordProfile(passwordProfile)
forceChangePasswordNextSignIn := false
passwordProfile.SetForceChangePasswordNextSignIn(&forceChangePasswordNextSignIn)
password := "xWwvJ]6NMw+bWH-d"
passwordProfile.SetPassword(&password)
userId := "user-id"
graphClient.UsersById(&userId).Patch(requestBody)
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
$params = @{
PasswordProfile = @{
ForceChangePasswordNextSignIn = $false
Password = "xWwvJ]6NMw+bWH-d"
}
}
Update-MgUser -UserId $userId -BodyParameter $params
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
响应
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"
}
}
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
AdditionalData = new Dictionary<string, object>()
{
{"ext55gb1l09_msLearnCourses", "{\"courseType\":\"Admin\"}"}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
const user = {
ext55gb1l09_msLearnCourses: {
courseType: 'Admin'
}
};
await client.api('/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e')
.update(user);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)
requestBody := msgraphsdk.NewSchemaExtension()
owner := "ef4cb9a8-97c3-4ca7-854b-5cb5ced376fa"
requestBody.SetOwner(&owner)
requestBody.SetProperties( []ExtensionSchemaProperty {
msgraphsdk.NewExtensionSchemaProperty(),
SetAdditionalData(map[string]interface{}{
"name": "courseId",
"type": "Integer",
}
msgraphsdk.NewExtensionSchemaProperty(),
SetAdditionalData(map[string]interface{}{
"name": "courseName",
"type": "String",
}
msgraphsdk.NewExtensionSchemaProperty(),
SetAdditionalData(map[string]interface{}{
"name": "courseType",
"type": "String",
}
msgraphsdk.NewExtensionSchemaProperty(),
SetAdditionalData(map[string]interface{}{
"name": "courseSupervisors",
"type": "String",
}
}
schemaExtensionId := "schemaExtension-id"
graphClient.SchemaExtensionsById(&schemaExtensionId).Patch(requestBody)
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
$params = @{
}
Update-MgUser -UserId $userId -BodyParameter $params
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
SchemaExtension schemaExtension = new SchemaExtension();
schemaExtension.owner = "ef4cb9a8-97c3-4ca7-854b-5cb5ced376fa";
LinkedList<ExtensionSchemaProperty> propertiesList = new LinkedList<ExtensionSchemaProperty>();
ExtensionSchemaProperty properties = new ExtensionSchemaProperty();
properties.name = "courseId";
properties.type = "Integer";
propertiesList.add(properties);
ExtensionSchemaProperty properties1 = new ExtensionSchemaProperty();
properties1.name = "courseName";
properties1.type = "String";
propertiesList.add(properties1);
ExtensionSchemaProperty properties2 = new ExtensionSchemaProperty();
properties2.name = "courseType";
properties2.type = "String";
propertiesList.add(properties2);
ExtensionSchemaProperty properties3 = new ExtensionSchemaProperty();
properties3.name = "courseSupervisors";
properties3.type = "String";
propertiesList.add(properties3);
schemaExtension.properties = propertiesList;
graphClient.schemaExtensions("exto6x7sfft_courses")
.buildRequest()
.patch(schemaExtension);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档 。
响应
HTTP/1.1 204 No Content
注意: 若要从用户对象中删除架构扩展值,请将属性设置为 null。例如:
PATCH https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e
Content-type: application/json
{
"ext55gb1l09_msLearnCourses": null
}
另请参阅