updateRole

On this page本页内容

Definition定义

updateRole

Updates a user-defined role. 更新用户定义的角色。The updateRole command must run on the role's database.updateRole命令必须在角色的数据库上运行。

An update to a field completely replaces the previous field's values. 对字段的更新将完全替换上一个字段的值。To grant or remove roles or privileges without replacing all values, use one or more of the following commands:要在不替换所有值的情况下授予或删除角色或权限，请使用以下一个或多个命令：

Warning警告

An update to the privileges or roles array completely replaces the previous array's values.对privileges或roles数组的更新将完全替换上一个数组的值。

The updateRole command uses the following syntax. updateRole命令使用以下语法。To update a role, you must provide the privileges array, roles array, or both:要更新角色，必须提供privileges数组、roles数组或两者：

{
  updateRole: "<role>",
  privileges:
      [
        { resource: { <resource> }, actions: [ "<action>", ... ] },
        ...
      ],
  roles:
      [
        { role: "<role>", db: "<database>" } | "<role>",
        ...
      ],
  authenticationRestrictions:
      [
        {
          clientSource: ["<IP>" | "<CIDR range>", ...],
          serverAddress: ["<IP>", ...]
        },
        ...
      ]
  writeConcern: <write concern document>,
  comment: <any>
}

The updateRole command has the following fields:updateRole命令具有以下字段：

Field字段Type类型Description描述
updateRolestringThe name of the user-defined role role to update.要更新的用户定义角色角色的名称。
privilegesarrayOptional. 可选。Required if you do not specify roles array. 如果未指定roles数组，则为必填项。The privileges to grant the role. 授予角色的权限。An update to the privileges array overrides the previous array's values. privileges数组的更新将覆盖上一个数组的值。For the syntax for specifying a privilege, see the privileges array. 有关指定权限的语法，请参阅privileges数组。
rolesarrayOptional. 可选。Required if you do not specify privileges array. 如果未指定privileges数组，则为必填项。The roles from which this role inherits privileges. 此角色从中继承权限的角色。An update to the roles array overrides the previous array's values. 对roles数组的更新将覆盖上一个数组的值。
authenticationRestrictionsarrayOptional.可选。 .. include:: /includes/fact-auth-restrictions-role-desc.rst
writeConcerndocument

Optional. 可选。The level of write concern for the operation. 操作的写入关注级别。See Write Concern Specification.请参阅写入关注规范。

commentany

Optional. 可选。A user-provided comment to attach to this command. 用户提供了附加到此命令的注释。Once set, this comment appears alongside records of this command in the following locations:设置后，此注释将与此命令的记录一起显示在以下位置：

A comment can be any valid BSON type(string, integer, object, array, etc).注释可以是任何有效的BSON类型（字符串、整数、对象、数组等）。

New in version 4.4.在版本4.4中新增。

Roles

In the roles field, you can specify both built-in roles and user-defined roles.在roles字段中，可以指定内置角色和用户定义角色。

To specify a role that exists in the same database where updateRole runs, you can either specify the role with the name of the role:要指定运行updateRole的同一数据库中存在的角色，可以使用角色名称指定角色：

"readWrite"

Or you can specify the role with a document, as in:也可以使用文档指定角色，如：

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.若要指定存在于其他数据库中的角色，请使用文档指定该角色。

Authentication Restrictions身份验证限制

The authenticationRestrictions document can contain only the following fields. authenticationRestrictions文档只能包含以下字段。The server throws an error if the authenticationRestrictions document contains an unrecognized field:如果authenticationRestrictions文档包含无法识别的字段，服务器将抛出错误：

Field NameValue值Description描述
clientSourceArray of IP addresses and/or CIDR ranges IP地址和/或CIDR范围的数组If present, when authenticating a user, the server verifies that the client's IP address is either in the given list or belongs to a CIDR range in the list. 如果存在，在验证用户时，服务器将验证客户端的IP地址是否在给定列表中或是否属于列表中的CIDR范围。If the client's IP address is not present, the server does not authenticate the user. 如果客户端的IP地址不存在，则服务器不会对用户进行身份验证。
serverAddressArray of IP addresses and/or CIDR ranges IP地址和/或CIDR范围的数组A list of IP addresses or CIDR ranges to which the client can connect. 客户端可以连接到的IP地址或CIDR范围的列表。If present, the server will verify that the client's connection was accepted via an IP address in the given list. 如果存在，服务器将验证客户端的连接是否通过给定列表中的IP地址被接受。If the connection was accepted via an unrecognized IP address, the server does not authenticate the user. 如果通过无法识别的IP地址接受连接，则服务器不会对用户进行身份验证。
Important重要

If a user inherits multiple roles with incompatible authentication restrictions, that user becomes unusable.如果用户继承了具有不兼容身份验证限制的多个角色，则该用户将无法使用。

For example, if a user inherits one role in which the clientSource field is ["198.51.100.0"] and another role in which the clientSource field is ["203.0.113.0"] the server is unable to authenticate the user.例如，如果用户继承了clientSource字段为["198.51.100.0"]的一个角色和clientSource字段是["203.0.113.0"]的另一个角色，则服务器无法对用户进行身份验证。

For more information on authentication in MongoDB, see Authentication.有关MongoDB中身份验证的更多信息，请参阅身份验证。

Behavior行为

A role's privileges apply to the database where the role is created. 角色的权限应用于创建角色的数据库。The role can inherit privileges from other roles in its database. 该角色可以从其数据库中的其他角色继承权限。A role created on the admin database can include privileges that apply to all databases or to the cluster and can inherit privileges from roles in other databases.在admin数据库上创建的角色可以包括应用于所有数据库或集群的权限，并且可以继承其他数据库中角色的权限。

Required Access所需访问权限

You must have the revokeRole action on all databases in order to update a role.必须对所有数据库执行revokeRole操作才能更新角色。

You must have the grantRole action on the database of each role in the roles array to update the array.必须对roles数组中每个角色的数据库执行grantRole操作才能更新数组。

You must have the grantRoleaction on the database of each privilege in the privileges array to update the array. 必须对privileges数组中每个权限的数据库执行grantRole操作才能更新该数组。If a privilege's resource spans databases, you must have grantRole on the admin database. 如果权限的资源跨越数据库，则必须在admin数据库上具有grantRole。A privilege spans databases if the privilege is any of the following:如果权限是以下任一项，则该权限跨越数据库：

  • a collection in all databases所有数据库中的集合
  • all collections and all database所有集合和所有数据库
  • the cluster resourcecluster资源

You must have the setAuthenticationRestrictionaction on the database of the target role to update a role's authenticationRestrictions document.必须对目标角色的数据库执行setAuthenticationRestriction操作才能更新角色的authenticationRestrictions文档。

Example示例

The following is an example of the updateRole command that updates the myClusterwideAdmin role on the admin database. 以下是updateRole命令的示例，该命令更新admin数据库上的myClusterwideAdmin角色。While the privileges and the roles arrays are both optional, at least one of the two is required:虽然privileges和roles数组都是可选的，但至少需要其中一个：

db.adminCommand(
   {
     updateRole: "myClusterwideAdmin",
     privileges:
         [
           {
             resource: { db: "", collection: "" },
             actions: [ "find" , "update", "insert", "remove" ]
           }
         ],
     roles:
         [
           { role: "dbAdminAnyDatabase", db: "admin" }
         ],
     writeConcern: { w: "majority" }
   }
)

To view a role's privileges, use the rolesInfo command.要查看角色的权限，请使用rolesInfo命令。

←  rolesInfoReplication Commands →