更新用户

命名空间: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

备注

  • 如需更新其他用户的 businessPhonesmobilePhoneotherMails 属性,仅允许针对非管理员或分配了以下角色之一的用户执行该操作:目录读取者、来宾邀请者、消息中心读取者和报告读取者。 有关详细信息,请参阅 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 设置用户的年龄组。 允许的值:nullMinorNotAdultAdult。 请参阅法定年龄组属性定义以了解详细信息。
birthday DateTimeOffset 用户的生日。时间戳类型表示使用 ISO 8601 格式的日期和时间信息,并且始终处于 UTC 时间。例如,2014 年 1 月 1 日午夜 UTC 为 2014-01-01T00:00:00Z
businessPhones String collection 用户的电话号码。注意:虽然这是字符串集合,但是只能为该属性设置一个号码。
城市 String 用户所在的城市。
CompanyName String 与用户关联的公司名称。 此属性可用于描述外部用户所属的公司。 最大长度为 64 个字符。
consentProvidedForMinor consentProvidedForMinor 设置是否已获得未成年人的同意。 允许的值:nullGrantedDeniedNotRequired。 请参阅法定年龄组属性定义以了解详细信息。
country String 用户所在的国家/地区;例如, USUK
department String 用户工作部门的名称。
displayName String 用户通讯簿中显示的名称,通常是用户名字、中间名首字母和姓氏的组合。此属性在创建用户时是必需的,并且在更新过程中不能清除。
employeeId String 由组织分配给该用户的员工标识符。 最大长度为 16 个字符。
employeeType String 捕获企业员工类型。 例如,EmployeeContractorConsultantVendor。 仅在 $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)。 由于法律要求,将被分配许可证的用户需要检查国家/地区的服务可用性。 示例包括:USJPGB。不可为 null。
userPrincipalName 字符串 用户的用户主体名称 (UPN)。UPN 是用户基于 Internet 标准 RFC 822 的 Internet 式登录名。按照惯例,此名称应映射到用户的电子邮件名称。常规格式是 alias@domain,其中,domain 必须位于租户的已验证域集合中。可从 组织verifiedDomains 属性访问租户的已验证域。
注意:此属性不能包含突出字符。 仅支持使用以下字符:A - Za - z0 - 9 ' . - _ ! # ^ ~。 有关允许字符的完整列表,请参阅用户名策略
userType String 可用于对目录中的用户类型进行分类的字符串值,例如Member``Guest

备注

  • 只有应用程序权限的应用无法更新以下属性:aboutMebirthday employeeHireDateinterestsmySitepastProjectsresponsibilitiesschoolsskills
  • 要更新以下属性,必须在其自身 PATCH 请求中指定它们,而无需包含上表中列出的其他属性:aboutMebirthdayinterestsmySitepastProjectsresponsibilitiesschoolsskills

管理扩展名和关联的数据

使用此 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 以重置其密码

下列示例展示重置其他用户密码的请求。

请求

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

响应

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
}

另请参阅