rolesInfo（数据库命令）

定义

rolesInfo

返回指定角色的继承和权限信息，包括用户定义的角色和内置角色。

The rolesInfo command can also retrieve all roles scoped to a database.

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

注意

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

该命令具有以下语法：

db.runCommand(
   {
     rolesInfo: { role: <name>, db: <db> },
     showAuthenticationRestrictions: <Boolean>,
     showBuiltinRoles: <Boolean>,
     showPrivileges: <Boolean>,
     comment: <any>
   }
)

命令字段

该命令接受以下字段：

字段	类型	说明
`rolesInfo`	字符串、文档、数组或整数	The role(s) to return information about. For the syntax for specifying roles, see Behavior.
`showAuthenticationRestrictions`	布尔	可选。将该字段设置为 `true`，以在输出中包含身份验证限制。身份验证限制指出了具有此角色的用户可以连接的 IP 地址。默认情况下，此字段为 `false`，这意味着 `rolesInfo` 输出不包含身份验证限制。
`showBuiltinRoles`	布尔	可选。当`rolesInfo`字段设立为`1`时，设立`showBuiltinRoles`设置为`true`以在输出中包含内置角色。默认，该字段设立为`false` ， `rolesInfo: 1`的输出仅显示用户定义的角色。
`showPrivileges`	布尔	可选。将该字段设置为`true`以显示角色权限，包括从其他角色继承的权限和直接定义的权限。默认，该命令仅返回此角色从中继承权限的角色，而不返回特定权限。
`comment`	any	可选。用户提供的待附加到该命令的注释。设置后，该注释将与该命令的记录一起出现在以下位置： mongod 日志消息，位于 `attr.command.cursor.comment` 字段中。 `command.comment` 字段中的数据库分析器输出。 `currentOp` 输出，在 `command.comment` 字段。注释可以是任何有效的 BSON 类型（字符串、整型、对象、数组等）。

行为

返回单个角色的信息

要指定当前数据库中的角色，请按角色名称指定：

{ rolesInfo: "<rolename>" }

要指定其他数据库中的角色，请通过指定角色和数据库的文档来指定角色：

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

返回多个角色的信息

要指定多个角色，请使用数组。将数组中的每个角色指定为文档或string 。仅当运行命令的数据库上存在该角色时才使用string ：

{
  rolesInfo: [
     "<rolename>",
     { role: "<rolename>", db: "<database>" },
     ...
  ]
}

返回数据库中所有角色的信息

要指定运行该命令的数据库中的所有角色，请指定rolesInfo: 1 。默认情况下，MongoDB 会显示数据库中所有用户定义的角色。要同时包含内置角色，请包含参数值对showBuiltinRoles: true ：

{ rolesInfo: 1, showBuiltinRoles: true }

必需的访问权限

要查看角色的信息，您必须已被显式授予该角色，或必须有权对该角色的数据库执行 viewRole 操作。

输出

rolesInfo.role: 角色的名称。

rolesInfo.db: 定义角色的数据库。每个数据库都有内置角色。数据库还可能具有用户定义的角色。

rolesInfo.isBuiltin: 值为true表示该角色是内置角色。值为false表示该角色是用户定义的角色。

rolesInfo.roles: 直接向此角色提供特权的角色以及定义这些角色的数据库。

rolesInfo.inheritedRoles: All roles from which this role inherits privileges. This includes the roles in the rolesInfo.roles array as well as the roles from which the roles in the rolesInfo.roles array inherit privileges. All privileges apply to the current role. The documents in this field list the roles and the databases on which they are defined.

rolesInfo.privileges

The privileges directly specified by this role; i.e. the array excludes privileges inherited from other roles. By default the output does not include the privileges field. To include the field, specify showPrivileges: true when running the rolesInfo command.

每个权限文档指定了资源以及允许对资源执行的操作。

rolesInfo.inheritedPrivileges

All privileges granted by this role, including those inherited from other roles. By default the output does not include the inheritedPrivileges field. To include the field, specify showPrivileges: true when running the rolesInfo command.

每个权限文档指定了资源以及允许对资源执行的操作。

示例

本节中的示例展示如何使用rolesInfo命令：

查看单个角色的信息
查看多个角色的信息
查看数据库的所有用户定义角色
查看数据库的所有用户定义角色和内置角色
查看角色的身份验证限制

查看单个角色的信息

以下命令返回products数据库中定义的角色associate的角色继承信息：

db.runCommand(
    {
      rolesInfo: { role: "associate", db: "products" }
    }
)

以下命令返回运行该命令的数据库上角色siteManager的角色继承信息：

db.runCommand(
    {
      rolesInfo: "siteManager"
    }
)

以下命令返回products数据库上定义的角色associate的角色继承和特权：

db.runCommand(
    {
      rolesInfo: { role: "associate", db: "products" },
      showPrivileges: true
    }
)

查看多个角色的信息

以下命令将返回两个不同数据库上两个角色的信息：

db.runCommand(
    {
      rolesInfo: [
         { role: "associate", db: "products" },
         { role: "manager", db: "resources" }
      ]
    }
)

以下同时返回角色继承和特权：

db.runCommand(
    {
      rolesInfo: [
         { role: "associate", db: "products" },
         { role: "manager", db: "resources" }
      ],
      showPrivileges: true
    }
)

查看数据库的所有用户定义角色

以下操作返回运行该命令的数据库上的所有用户定义角色，并包括特权：

db.runCommand(
    {
      rolesInfo: 1,
      showPrivileges: true
    }
)

示例输出（为便于阅读已被缩短）：

{
  roles: [
    {
      _id: 'products.associate',
      role: 'associate',
      db: 'products',
      privileges: [
        {
          resource: { db: 'products', collection: '' },
          actions: [ 'bypassDocumentValidation' ]
        }
      ],
      roles: [ { role: 'readWrite', db: 'products' } ],
      isBuiltin: false,
      inheritedRoles: [ { role: 'readWrite', db: 'products' } ],
      inheritedPrivileges: [
        {
          resource: { db: 'products', collection: '' },
          actions: [ 'bypassDocumentValidation' ]
        },
        {
          resource: { db: 'products', collection: '' },
          actions: [
            'changeStream',
            'collStats',
            'compactStructuredEncryptionData',
            ...
          ]
        },
        ...
      ]
    }
  ],
  ok: 1
}

查看数据库的所有用户定义角色和内置角色

以下操作返回运行该命令的数据库上的所有角色，包括内置角色和用户定义的角色：

db.runCommand(
    {
      rolesInfo: 1,
      showBuiltinRoles: true
    }
)

示例输出（为便于阅读已被缩短）：

{
  roles: [
    {
      role: 'enableSharding',
      db: 'products',
      isBuiltin: true,
      roles: [],
      inheritedRoles: []
    },
    {
      role: 'userAdmin',
      db: 'products',
      isBuiltin: true,
      roles: [],
      inheritedRoles: []
    },
    {
      role: 'read',
      db: 'products',
      isBuiltin: true,
      roles: [],
      inheritedRoles: []
    },
    ...
  ],
  ok: 1
}

查看角色的身份验证限制

以下操作返回products数据库上的所有用户定义角色，并包括身份验证限制：

db.runCommand(
    {
      rolesInfo: 1,
      showAuthenticationRestrictions: true
    }
)

示例输出：

{
  roles: [
    {
      _id: 'products.associate',
      role: 'associate',
      db: 'products',
      roles: [ { role: 'readWrite', db: 'products' } ],
      authenticationRestrictions: [
        [ { clientSource: [ '198.51.100.0' ] } ]
      ],
      isBuiltin: false,
      inheritedRoles: [ { role: 'readWrite', db: 'products' } ],
      inheritedAuthenticationRestrictions: [
        [ { clientSource: [ '198.51.100.0' ] } ]
      ]
    }
  ],
  ok: 1
}