通过

更新用户

  • 项目

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

特定方案的权限

  • 个人Microsoft帐户必须绑定到Microsoft Entra租户，才能使用个人Microsoft帐户的 User.ReadWrite 委托权限更新配置文件。
  • 若要为具有特权管理员角色的用户更新敏感用户属性，例如 accountEnabled、 mobilePhone和其他Mails ，请执行以下操作：
    • 在委派方案中，必须为应用分配 Directory.AccessAsUser.All 委托权限，并且已登录用户必须具有更高的特权管理员角色，如 谁可以执行敏感操作中所述。
    • 在仅限应用的方案中，除了Microsoft Graph 权限外，还必须为应用分配更高的特权管理员角色，如 谁可以执行敏感操作中所述。
  • 更新 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 权限。
  • User-Mail.ReadWrite.All 是更新 otherMails 属性的最低特权权限。
  • User-PasswordProfile.ReadWrite.All 是更新 passwordProfile 属性的最低特权权限。
  • User-Phone.ReadWrite.All 是更新 businessPhone 和 mobilePhone 属性的最低特权权限。
  • User.EnableDisableAccount.All + User.Read.All 是更新 accountEnabled 属性的权限的最低特权组合。
  • 需要 User.ManageIdentities.All 才能更新 identities 属性。

HTTP 请求

PATCH /users/{id | userPrincipalName}

请求标头

标头 值
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/json

请求正文

在请求正文中， 仅 提供要更新的属性的值。 请求正文中未包含的现有属性会保留其以前的值，或者根据对其他属性值的更改重新计算。

下表指定可更新的属性。

属性 类型 说明
aboutMe String 任意形式的文本输入字段，用于介绍用户自身。
accountEnabled Boolean 启用帐户时为 true，否则为 false。 创建用户时此属性是必需的。
  • User.EnableDisableAccount.All + User.Read.All 是更新此属性所需的最低权限组合。
  • 在委派方案中， 特权身份验证管理员 是允许为租户中的所有管理员更新此属性的最低特权角色。
    		•
    ageGroup ageGroup 设置用户的年龄组。 允许的值： null、 Minor、 NotAdult和 Adult。 请参阅法定年龄组属性定义以了解详细信息。
    birthday DateTimeOffset 用户的生日。 时间戳类型表示采用 ISO 8601 格式的日期和时间信息，始终采用 UTC 时区。 例如，2014 年 1 月 1 日午夜 UTC 为 2014-01-01T00:00:00Z
    businessPhones String collection 用户的电话号码。 注意： 虽然这是一个字符串集合，但只能为此属性设置一个数字。 User-Phone.ReadWrite.All 是更新此属性的最低特权权限。
    城市 String 用户所在的城市。
    CompanyName String 用户关联的公司的名称。 此属性可用于描述外部用户所属的公司。 最大长度为 64 个字符。
    consentProvidedForMinor consentProvidedForMinor 设置是否已获得未成年人的同意。 允许的值：null、Granted、Denied 和 NotRequired。 请参阅法定年龄组属性定义以了解详细信息。
    country String 用户所在的国家/地区;例如， US 或 UK。
    customSecurityAttributes customSecurityAttributeValue 保留分配给目录对象的自定义安全属性的值的开放式复杂类型。
  • 若要在委托方案中更新此属性，必须为调用主体分配“属性分配管理员”角色，并且应用被授予 CustomSecAttributeAssignment.ReadWrite.All 委托权限。
  • 若要在仅限应用的情况下使用 Microsoft Graph 权限更新此属性，必须向应用授予 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-LifeCycleInfo.Read.All 和 User.Read.All 权限。
  • 若要在委派方案中更新此属性，管理员需要全局管理员角色。
    		•
    employeeOrgData employeeOrgData 表示组织数据 (例如，与用户关联的部门和 costCenter) 。
    identities objectIdentity 集合 表示可用于登录此用户帐户的标识。 标识可由 Microsoft、组织或诸如 Facebook、Google 和 Microsoft 等社交标识提供者提供，并绑定到用户帐户。 对 标识 的任何更新将替换整个集合，并且必须在集合中提供 userPrincipalName signInType 标识。

    注意： 不允许将 B2C 本地帐户 添加到现有 用户 对象，除非 该用户 对象已包含本地帐户标识。
    interests String collection 用户介绍自身兴趣的列表。
    jobTitle String 用户的职务。
    mail String 用户的 SMTP 地址，例如， jeff@contoso.com。 对此属性的更改还会更新用户的 proxyAddresses 集合，以将值包含为 SMTP 地址。 对于 Azure AD B2C 帐户，此属性最多只能使用唯一 SMTP 地址更新 10 次。 无法更新为 null。
    mailNickname String 用户的邮件别名。 创建用户时必须指定此属性。
    mobilePhone String 用户的主要移动电话号码。 User-Phone.ReadWrite.All 是更新此属性的最低特权权限。
    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"]。 若要更新此属性，请传入你希望用户拥有的所有电子邮件地址;否则，现有值将被指定的值覆盖。

    User-Mail.ReadWrite.All 是更新此属性的最低特权权限。
    passwordPolicies String 指定用户的密码策略。 此值表示枚举，其中一个可能 DisableStrongPassword为枚举值，允许指定超过默认策略的密码。 DisablePasswordExpiration 也可以指定 。 两者可以一起指定：例如： DisablePasswordExpiration, DisableStrongPassword。
    passwordProfile PasswordProfile 指定用户的密码配置文件。 配置文件包含用户的密码。 配置文件中的密码必须满足 passwordPolicies 属性指定的最低要求。 默认情况下，必须使用强密码。 最佳做法是始终将 forceChangePasswordNextSignIn 设置为 true。 这不能用于联合用户。
  • User-PasswordProfile.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。

    • 在委派访问中，必须代表已登录用户向调用应用分配 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"
    }
}

    若要从用户对象中删除架构扩展的值，请将 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

    相关内容