更新用户

命名空间：microsoft.graph

更新 user 对象的属性。 若要使用此 API 更新 agentUser，请在请求正文中指定值为 @odata.type#microsoft.graph.agentUser 属性。

  • 并非所有属性都可以由具有默认权限的成员或访客用户更新，而无需管理员角色。 比较成员和来宾默认 权限，查看其可管理的属性。
  • 外部租户中的 Microsoft Entra 外部 ID 也可以使用此 API 操作来更新其详细信息。 有关可更新的属性列表，请参阅 外部租户中的默认用户权限 。
  • 对于同步用户，更新某些属性的能力还取决于授权来源以及是否启用了同步。

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

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

权限

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

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

特定场景的权限

  • User.ReadWrite 是更新已登录用户详细信息的最小特权。
  • 你的个人 Microsoft 帐户必须绑定到 Microsoft Entra 租户，才能使用个人 Microsoft 帐户上的 User.ReadWrite 委派权限更新你的个人资料。
  • 若要更新 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。

HTTP 请求

更新您自己的用户属性。

注意

调用 /me 终结点需要已登录的用户，因此需要委派权限。 使用 /me 终结点时，不支持应用程序权限。

PATCH /me

更新其他用户的属性。

PATCH /users/{id | userPrincipalName}

请求标头

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

请求正文

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

下表指定可更新的属性。

若要使用此 API 更新 agentUser，必须在请求正文中指定 @odata.type#microsoft.graph.agentUser。

属性 类型 说明
aboutMe String 任意形式的文本输入字段，用于介绍用户自身。
accountEnabled Boolean 启用帐户时为 true，否则为 false。 创建用户时此属性是必需的。
  • User.EnableDisableAccount.All + User.Read.All 是更新此属性所需的权限的最小特权组合。
  • 在委派方案中， 特权身份验证管理员 是允许为租户中 所有 管理员更新此属性的最小特权角色。 一般而言，登录用户必须具有更高特权的管理员角色，如 “谁可以执行敏感操作”中所示。
  • 在仅限应用的情况下，除了 Microsoft Graph 权限外，还必须为应用分配更高特权的管理员角色，如“ 谁可以执行敏感操作”中所示。
    		•
    ageGroup ageGroup 设置用户的年龄组。 允许的值：null、、 MinorNotAdult和 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) 。 更新 employeeOrgData 时包括这两个属性值;如果省略任何内容，系统会将其 null设置为 。
    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 是更新此属性的最小特权权限。
  • 在委派方案中， 特权身份验证管理员 是允许为租户中 所有 管理员更新此属性的最小特权角色。 一般而言，登录用户必须具有更高特权的管理员角色，如 “谁可以执行敏感操作”中所示。
  • 在仅限应用的情况下，除了 Microsoft Graph 权限外，还必须为应用分配更高特权的管理员角色，如“ 谁可以执行敏感操作”中所示。
    		•
    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"]。 要更新此属性，请传入您希望用户拥有的所有电子邮件地址;否则，现有值将被指定的值覆盖。 最多可存储 250 个值，每个值限制为 250 个字符。

  • User-Mail.ReadWrite.All 是更新此属性的最小特权权限。
  • 在委派方案中， 特权身份验证管理员 是允许为租户中 所有 管理员更新此属性的最小特权角色。 一般而言，登录用户必须具有更高特权的管理员角色，如 “谁可以执行敏感操作”中所示。
  • 在仅限应用的情况下，除了 Microsoft Graph 权限外，还必须为应用分配更高特权的管理员角色，如“ 谁可以执行敏感操作”中所示。
    		•
    passwordPolicies String 指定用户的密码策略。 此值表示枚举，其中一个可能 DisableStrongPassword为枚举值，允许指定超过默认策略的密码。 DisablePasswordExpiration 也可以指定 。 两者可以一起指定;例如： DisablePasswordExpiration, DisableStrongPassword。
    passwordProfile passwordProfile 指定用户的密码配置文件。 配置文件包含用户的密码。 配置文件中的密码必须满足 passwordPolicies 属性指定的最低要求。 默认情况下，必须使用强密码。 作为最佳实践，请始终将 forceChangePasswordNextSignIn 设置为 true。 这不能用于联合用户。
  • User-PasswordProfile.ReadWrite.All 是更新此属性的最小特权权限。
  • 在委派方案中，用户管理员Microsoft Entra 角色是支持为非管理员用户更新此属性的最低特权管理员角色。 特权身份验证管理员 是允许为租户中 所有 管理员更新此属性的最小特权角色。 一般而言，登录用户必须具有更高的特权管理员角色，如 “谁可以重置密码”中所示。
  • 在仅限应用的情况下，必须为调用应用分配受支持的权限，并且至少分配用户管理员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、 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"
}

    响应

    以下示例显示了相应的响应。

    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。

    • User-PasswordProfile.ReadWrite.All 是更新 passwordProfile 属性的最小特权权限。
    • 在委派方案中，必须为呼叫应用分配受支持的权限，并为已登录用户分配受支持的 Microsoft Entra 角色。
      • 特权身份验证管理员 是允许为租户中 所有 管理员更新此属性的最小特权角色。
      • 一般而言，登录用户必须具有更高的特权管理员角色，如 “谁可以重置密码”中所示。
    • 在使用 Microsoft Graph 应用程序权限的仅限应用的方案中， User-PasswordProfile.ReadWrite.All 是最低特权权限。

    请求

    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

    相关内容

    • 上次更新时间为