更新用户

  • 项目

命名空间：microsoft.graph

更新 user 对象的属性。 并非所有属性都可以在没有管理员角色的情况下由具有其默认权限的成员或来宾用户更新。 比较成员和来宾默认 权限，查看其可管理的属性。

客户通过Microsoft Entra ID客户还可以使用此 API 操作来更新其详细信息。 有关他们可以更新的属性列表，请参阅 客户租户中的默认用户权限 。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） User.ReadWrite User.ManageIdentities.All、User.EnableDisableAccount.All、User.ReadWrite.All、Directory.ReadWrite.All
委派（个人 Microsoft 帐户） User.ReadWrite 不可用。
应用程序 User.ManageIdentities.All User.EnableDisableAccount.All、User.ReadWrite.All、Directory.ReadWrite.All

注意

  • 若要为具有特权管理员角色的用户更新敏感用户属性，例如 accountEnabled、 mobilePhone和其他Mails ，请执行以下操作：
    • 在委派方案中，必须为应用分配 Directory.AccessAsUser.All 委派权限，并且调用用户必须具有更高特权的管理员角色，如 谁可以执行敏感操作中所述。
    • 在仅应用方案中，必须为应用分配更高特权的管理员角色，如 谁可以执行敏感操作中所述。
  • 个人 Microsoft 帐户必须绑定到Microsoft Entra租户，才能使用个人 Microsoft 帐户的 User.ReadWrite 委托权限更新配置文件。
  • 更新 identities 属性需要 User.ManageIdentities.All 权限。 此外，不允许将 B2C 本地帐户添加到现有 user 对象，除非 user 对象已包含本地帐户标识。

HTTP 请求

PATCH /users/{id | userPrincipalName}

请求标头

标头 值
Authorization 持有者 {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。
customSecurityAttributes customSecurityAttributeValue 保留分配给目录对象的自定义安全属性的值的开放式复杂类型。

若要更新此属性，必须为调用主体分配"属性分配管理员"角色，并且必须向其授予 CustomSecAttributeAssignment.ReadWrite.All 权限。
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
employeeLeaveDateTime DateTimeOffset 用户离开或将离开组织的日期和时间。 时间戳类型使用 ISO 8601 格式表示日期和时间信息，并且始终采用 UTC 时间。 例如，2014 年 1 月 1 日午夜 UTC 为 2014-01-01T00:00:00Z。

对于委托方案，调用用户必须具有全局管理员角色，并且调用应用分配有 User.Read.All 和 User-LifeCycleInfo.ReadWrite.All 委托权限。
employeeOrgData employeeOrgData 表示组织数据 (例如，与用户关联的部门和 costCenter) 。
interests String collection 用户介绍自身兴趣的列表。
jobTitle String 用户的职务。
mail String 用户的 SMTP 地址，例如， jeff@contoso.com。 对此属性的更改还会更新用户的 proxyAddresses 集合，以将值包含为 SMTP 地址。 对于 Azure AD B2C 帐户，此属性最多只能使用唯一 SMTP 地址更新 10 次。 无法更新为 null。
mailNickname String 用户的邮件别名。 创建用户时必须指定此属性。
mobilePhone String 用户的主要移动电话号码。
mySite String 用户个人网站的 URL。
officeLocation String 用户公司地点的办公室位置。
onPremisesExtensionAttributes onPremisesExtensionAttributes 包含用户的 extensionAttributes 1-15。 单个扩展属性不可选择或不可筛选。 对于 onPremisesSyncEnabled 用户，这组属性集的授权来源是本地，并且为只读。 这些扩展属性也称 Exchange 自定义属性 1-15。
onPremisesImmutableId String 此属性用于将本地 Active Directory用户帐户与其Microsoft Entra用户对象相关联。 如果将联合域用于用户的 userPrincipalName (UPN) 属性，则必须在 Graph 中创建新用户帐户时指定此属性。 重要： 指定 $ 此属性时，不能使用 和 _ 字符。
otherMails 字符串集合 用户的其他电子邮件地址列表；例如：["bob@contoso.com", "Robert@fabrikam.com"]。
passwordPolicies String 指定用户的密码策略。 此值表示枚举，其中一个可能 DisableStrongPassword为枚举值，允许指定超过默认策略的密码。 DisablePasswordExpiration 也可以指定 。 两者可以一起指定：例如： DisablePasswordExpiration, DisableStrongPassword。
passwordProfile PasswordProfile 指定用户的密码配置文件。 配置文件包含用户的密码。 配置文件中的密码必须满足 passwordPolicies 属性指定的最低要求。 默认情况下，必须使用强密码。 最佳做法是始终将 forceChangePasswordNextSignIn 设置为 true。 这不能用于联合用户。

在委派访问中，必须代表已登录用户向调用应用分配 Directory.AccessAsUser.All 委派权限。 在仅限应用程序访问中，必须为调用应用分配 User.ReadWrite.All 应用程序权限，并至少分配用户管理员Microsoft Entra角色。
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 String 用户的用户主体名称 (UPN)。 UPN 是基于 Internet 标准 RFC 822 的用户的 Internet 样式登录名称。 按照惯例，此名称应映射到用户的电子邮件名称。 常规格式是 alias@domain，其中 domain 必须位于租户的已验证域集合中。 可从 组织 的 verifiedDomains 属性访问租户的已验证域。
注意：此属性不能包含重音字符。 仅支持使用以下字符：A - Z、a - z、0 - 9、 ' . - _ ! # ^ ~。 有关允许字符的完整列表，请参阅用户名策略。
userType String 可用于对目录中的用户类型进行分类的字符串值，例如MemberGuest。

注意

  • 只有应用程序权限的应用无法更新以下属性：aboutMe、birthdayemployeeHireDate、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。

请求

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

若要从用户对象中删除架构扩展的值，请将 ext55gb1l09_msLearnCourses 属性设置为 null。

响应

HTTP/1.1 204 No Content

示例 5：向用户分配具有字符串值的自定义安全属性

以下示例演示如何向用户分配具有字符串值的自定义安全属性。

  • 属性集：Engineering
  • 属性：ProjectDate
  • 属性数据类型：字符串
  • 属性值： "2022-10-01"

若要分配自定义安全属性，必须为调用主体分配"属性分配管理员"角色，并且必须授予CustomSecAttributeAssignment.ReadWrite.All 权限。

有关自定义安全属性分配的示例，请参阅示例：使用 Microsoft 图形 API分配、更新、列出或删除自定义安全属性分配。

请求

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

相关内容