Campos y códigos de error de los métodos de acceso

Cuándo usar esta referencia

Use esta referencia cuando escriba una integración o interprete una respuesta del clúster y necesite el conjunto exacto de campos, el tipo de parámetro, el nivel de acceso y el significado de un código. Para los procedimientos paso a paso, consulte las guías sobre la gestión de usuarios, sobre roles y privilegios y sobre el inicio de sesión y las sesiones; para el modelo de permisos, consulte Modelo de acceso de vStack Center. En las tablas siguientes, VDC significa centro de datos virtual, el objeto cuyo ámbito define vdc_id.

Resumen de métodos

Usuarios

Método	Parámetros	Acceso	Devuelve
user-list	ninguno	Cluster master	un mapa de usuarios activos, con el id como clave de cadena
user-get	id	Cluster master	el perfil de un usuario
user-create	name, fullname	Cluster master	el id de la cuenta creada
user-delete	id	Cluster master	data vacío
user-set-password	id, password	contraseña propia: cualquier usuario; id de otro usuario: Cluster master	data vacío
user-unlock	id	Cluster master	el id de la cuenta desbloqueada
user-params-get	ninguno	usuario actual	el objeto JSON de configuración guardado
user-params-set	objeto arbitrario	usuario actual	data vacío

Roles y asignaciones de usuarios

Método	Parámetros	Acceso	Devuelve
user-role	ninguno	usuario actual	UID y authmap
user-roles	user_id, q	roles propios: cualquier usuario; user_id de otro usuario: Cluster master	un mapa VDC → rol; con la clave q, un mapa VDC → matriz de roles
user-roles-v2	user_id	el privilegio View Own User Roles (7102); user_id de otro usuario: View Any User Roles (7106)	un mapa rol → atributos de ámbito
user-roles-map	ninguno	Cluster master	todos los usuarios con sus asignaciones desglosadas
user-role-assign	user_id, vdc_id, role_id	Cluster master	data vacío
user-role-deassign	user_id, vdc_id, role_id	Cluster master	data vacío

El parámetro vdc_id de user-role-assign es obligatorio para un rol vinculado a un ámbito; en user-role-deassign es siempre obligatorio. El indicador q de user-roles se determina por la presencia de la clave en params; su valor no se lee. El indicador q no es compatible con user-roles-v2.

Roles y privilegios

Método	Parámetros	Acceso	Devuelve
role-list	ninguno	no se especifica en la documentación canónica de la API	todos los roles con scope_ids, creator y marcas de tiempo
role-get	id	un rol global con el privilegio View Role Details (7114)	el rol con sus privileges y scope_ids completos
role-scopes	id	el privilegio View Role Scopes (7115)	los atributos de ámbito del rol con self_referencing = false
role-create	name, privileges, scope_ids	Cluster master	el id del rol creado
role-set	id, name, remove_privileges, add_privileges, scope_ids	Cluster master	data vacío
role-delete	id	Cluster master	data vacío
role-privilege-list	ninguno	el privilegio View Role Privileges (7108), concedido a los siete roles fijos	un mapa role_id → matriz de privilege_id
privilege-list	ninguno	el privilegio View Privileges (7107), concedido a los siete roles fijos	el registro de privilegios con categorías, ámbitos y métodos
privilege-categories	ninguno	el privilegio View Privilege Categories (7109), concedido a los siete roles fijos	un mapa category_id → nombre
privilege-scopes	ninguno	el privilegio View Privilege Scopes (7110), concedido a los siete roles fijos	el catálogo de atributos de ámbito

Restricciones de acceso de las cuentas

Método	Parámetros	Acceso	Devuelve
user-remote-list	user_id	Cluster master	una matriz de CIDR permitidos
user-remote-add	user_id, remote	Cluster master	data vacío
user-remote-delete	user_id, remote	Cluster master	data vacío
user-vhost-list	user_id	Cluster master	una matriz de vhosts permitidos
user-vhost-add	user_id, vhost	Cluster master	data vacío
user-vhost-delete	user_id, vhost	Cluster master	data vacío

Sesión y configuración de seguridad

Método	Parámetros	Acceso	Devuelve
auth-logout	all	cualquier usuario autenticado, para sus propias sesiones	{"result": true}
auth-security-settings-get	ninguno	cualquier usuario autorizado; el conjunto de campos depende del rol	configuración de contraseñas y de bloqueo
auth-security-settings-set	ocho campos de la política, todos opcionales	Cluster master	data vacío

Parámetros con validación

Método	Parámetro	Tipo	Obligatorio	Restricción
user-create	name	string	sí	regex ^[A-Z,a-z,_-]{4,41}$
user-create	fullname	string	no	—
user-delete	id	number	sí	range(min=0); id < 10 está prohibido
user-set-password	id	number	no	de forma predeterminada, el usuario actual
user-set-password	password	string	sí	regex ^[\S]+$ más la política de contraseñas
user-role-assign	user_id, role_id	number	sí	range(min=0); user_id < 10 está prohibido
user-remote-add	remote	string	sí	CIDR IPv4 con máscara de 8–32 o IPv6 con prefijo de 16–128
user-vhost-add	vhost	string	sí	longitud 5–512
role-create	name	string	sí	longitud 1–64, único
role-create	privileges	array<integer>	sí	no vacío; excluye 7111–7113
role-create	scope_ids	array<integer>	no	solo atributos con self_referencing = false
role-set	id	integer	sí	como mínimo 10000
role-delete	id	integer	sí	como mínimo 10000
auth-security-settings-set	max_failed_attempts, failed_attempts_window_minutes, password_min_length	integer	no	range(min=1)
auth-security-settings-set	lockout_duration_minutes	integer	no	range(min=0)
auth-logout	all	boolean	no	de forma predeterminada, false

Campos del perfil de usuario

El conjunto de campos es el mismo para user-get y para cada entrada de user-list.

Campo	Tipo	Descripción
id	integer	identificador del usuario
name	string	nombre de la cuenta
fullname	string | null	nombre completo
created	integer	hora de creación, epoch
modified	integer | null	hora de la última modificación, epoch
failed_login_attempts	integer	contador de intentos fallidos de inicio de sesión
first_failed_at	integer | null	inicio de la ventana de recuento actual, epoch; null significa que no hay intentos fallidos
locked_until	integer | null	hora hasta la que la cuenta está bloqueada, epoch; null significa que no está bloqueada

Campos del rol

Campo	Tipo	Lo devuelve	Descripción
id	integer	role-list, role-get	identificador del rol
name	string	role-list, role-get	nombre del rol
scope_ids	integer[]	role-list, role-get	los atributos de ámbito del rol; una matriz vacía significa que no hay vinculación
privileges	integer[]	role-get	la lista completa de privilegios del rol
creator	integer | null	role-list, role-get	el creador del rol; null en los roles fijos
created_ts	integer	role-list, role-get	hora de creación, marca de tiempo Unix
modified_ts	integer | null	role-list, role-get	hora de la última modificación; null significa que nunca se ha modificado

Roles fijos de la plataforma:

ID	Nombre
1	Cluster Master
2	vDC Admin
3	vDC User
4	vDC Viewer
5	Resource Viewer
6	Security Admin
7	VM Developer

Campos de privilegios y de atributos de ámbito

Una entrada del registro privilege-list:

Campo	Tipo	Descripción
id	number	identificador del privilegio
name	string	nombre del privilegio
category_id	number | null	categoría; null significa que el privilegio no está asignado a ninguna categoría
scope_ids	number[]	los atributos de ámbito del privilegio; una matriz vacía significa un privilegio global
methods	string[]	nombres de los métodos JSON-RPC que requieren este privilegio

Una entrada del catálogo privilege-scopes y role-scopes:

Campo	Tipo	Descripción
id	integer	identificador del atributo de ámbito
name	string	nombre del atributo, como vdc_id o creator
self_referencing	boolean	true significa que el valor se genera a partir de user_id (creator); false significa que procede de las asignaciones de roles (vdc_id)

En la respuesta de role-scopes, self_referencing es siempre false: los atributos autorreferentes no se incluyen en esta respuesta.

Categorías de privilegios (privilege-categories): 1 — vDC, 2 — VM, 3 — Network, 4 — Edge, 5 — Storage, 6 — Node, 7 — Cluster, 8 — User, 9 — Misc, 10 — Auth, 11 — Security, 12 — User Interface, 13 — Unified Storage, 14 — OS Image Library, 15 — Backup.

nota

La documentación canónica de la API enumera solo las diez primeras categorías en su ejemplo de respuesta, mientras que la base de datos contiene quince: cada nuevo dominio añade su propia categoría. El método devuelve el catálogo completo, así que compruebe la respuesta real del clúster.

Roles de usuario: cuatro formatos de respuesta

Método	Formato de data	Cuándo resulta útil
user-role	UID + authmap: una matriz de objetos con vdc_id, vdc_name, role_id, role_name, GI_account	el cliente necesita mostrar «quién soy y dónde» en una sola llamada
user-roles sin q	un mapa de cadena vdc_id → role_id	comprobar rápidamente un único rol por VDC
user-roles con q	un mapa de cadena vdc_id → matriz de role_id	el usuario tiene más de un rol en un VDC
user-roles-v2	un mapa role_id → scopes, que contiene is_global e ids para cada attr_id	determinar con exactitud cómo está restringido el rol
user-roles-map	un mapa de cadena id de usuario → perfil + matriz roles	hacer un inventario de todas las asignaciones del clúster

Campos de user-roles-v2:

Campo	Tipo	Descripción
data.<role_id>.scopes	object	las claves son los valores de cadena attr_id de los atributos de ámbito del rol
data.<role_id>.scopes.<attr_id>.is_global	boolean	true significa que las asignaciones no contienen valores y el rol no está restringido por el atributo
data.<role_id>.scopes.<attr_id>.ids	integer[]	valores del atributo procedentes de las asignaciones, como una lista de VDC

Los valores válidos de role_id para los roles fijos son 1–7. Los roles personalizados aparecen en las mismas respuestas con identificadores a partir de 10000.

Configuración de seguridad

Campo	Tipo	Quién lo ve en auth-security-settings-get
max_failed_attempts	integer	solo Cluster master
failed_attempts_window_minutes	integer	solo Cluster master
lockout_duration_minutes	integer	solo Cluster master
password_min_length	integer	todos los usuarios autorizados
password_require_uppercase	boolean	todos los usuarios autorizados
password_require_lowercase	boolean	todos los usuarios autorizados
password_require_digits	boolean	todos los usuarios autorizados
password_require_special	boolean	todos los usuarios autorizados

Códigos de error

Usuarios

Código	Mensaje	Métodos
-403	Access denied	user-list, user-roles-map
-403	Access denied	user-roles
-22204	Empty param user_id	user-roles, user-roles-v2
-22205	Bad id param value	user-roles, user-roles-v2
-403	Access denied	user-create
-22505	Bad name param value	user-create
-22515	Failed to add an user	user-create
-22516	User with name '<name>' exists already	user-create
-403	Access denied	user-delete
-22606	Specified user was not found	user-delete
-22610	Build-it users removal prohibited	user-delete
-403	Access denied	user-set-password
-22712	Bad password	user-set-password
-22720	Specified user was not found	user-set-password
-22730…-22735, -22737	requisitos de la política de contraseñas	user-set-password
-403	Access denied	user-get
-22803	No param id	user-get
-22804	Empty param id	user-get
-22805	Bad id param value	user-get
-403	Access denied	user-unlock
-22906	Specified user was not found	user-unlock
-29030	No user with ID==<uid>	user-params-get
-34000	No params at all	user-params-set
-39030	No user with ID==<uid>	user-params-set

Asignación de roles

Código	Mensaje	Métodos
-403	Access denied	user-role-assign
-22320	Build-it users management prohibited / role already assigned	user-role-assign
-403	Access denied	user-role-deassign
-22420	Specified user has no specified role assignment	user-role-deassign
-22421	Build-it users management prohibited	user-role-deassign

Roles y privilegios

Código	Mensaje	Métodos
-22500	Access denied: only Cluster Master can create roles	role-create
-22501	Privileges list must not be empty	role-create
-22502	Role management privileges cannot be assigned to custom roles	role-create
-22503	Privilege ID not found	role-create
-22504	Scope ID not found	role-create
-22505	Self-referencing scope cannot be assigned to custom role	role-create
-22506	Role with name already exists	role-create
-22510	Access denied: only Cluster Master can edit roles	role-set
-22511	Cannot modify a fixed role	role-set
-22512	Role not found	role-set
-22513	Role management privileges cannot be assigned to custom roles	role-set
-22514	Privilege ID not found	role-set
-22515	Scope ID not found	role-set
-22516	Role with name already exists	role-set
-22517	Self-referencing scope cannot be assigned to custom role	role-set
-22520	Access denied: only Cluster Master can delete roles	role-delete
-22521	Cannot delete a fixed role	role-delete
-22522	Role not found	role-delete
-22530	Role not found	role-get
-22540	Role not found	role-scopes

El rango -225xx se usa dos veces: user-create y el grupo role-* usan los mismos números. Por ejemplo, -22505 significa «nombre de usuario no válido» en user-create y «ámbito autorreferente prohibido» en role-create, mientras que -22516 significa que ya está en uso un nombre de usuario o un nombre de rol. Interprete el código según el método llamado y no solo por el número.

Restricciones de acceso de las cuentas

Código	Mensaje	Métodos
-403	Access denied	los seis métodos del grupo
-24504	user_id param has been ommited	user-remote-list
-24505	user_id param is NULL	user-remote-list
-24506	user_id param value is not numeric	user-remote-list
-24604	user_id param has been ommited	user-vhost-list
-24605	user_id param is NULL	user-vhost-list
-24606	user_id param value is not numeric	user-vhost-list
-24712	remote param value is not CIDR	user-remote-add
-24713	remote param has mask out of range 8..32	user-remote-add
-24714	User ID==<id> has remote <cidr> already	user-remote-add
-24715	Invalid CIDR syntax of remote param	user-remote-add
-24812	remote param value is not CIDR / vhost param has bad length	user-remote-delete, user-vhost-add
-24814	User ID==<id> has no remote <cidr> / has vhost <vhost> already	user-remote-delete, user-vhost-add
-24815	Invalid CIDR syntax of remote param	user-remote-delete
-24912	vhost param has bad length	user-vhost-delete
-24914	User ID==<id> has no vhost <vhost>	user-vhost-delete

La documentación canónica de la API indica el par -24812, -24814 tanto para user-remote-delete como para user-vhost-add. Interprete su significado según el método llamado.

Sesión y configuración de seguridad

Código	Mensaje	Dónde se produce
-9494	No session token	cualquier llamada sin params.auth.cookie
-11000	el token no figura entre las sesiones activas, ha caducado o se ha invalidado	auth-logout y cualquier llamada con un token no válido
-125	Temp token expired or invalid	user-set-password con temp_token
-126	Method not allowed with temp token	cualquier llamada con temp_token excepto user-set-password y auth-security-settings-get
-127	Temp token allows changing own password only	user-set-password con temp_token
-403	Access denied	auth-security-settings-set
-29101	Security settings not found	auth-security-settings-get
-29102	error de base de datos	auth-security-settings-get, auth-security-settings-set

Restricciones de identificadores

Rango	Significado	Consecuencia
usuarios id < 10	cuentas integradas	no se pueden eliminar (-22610); sus asignaciones de roles no se pueden cambiar (-22320, -22421)
roles id < 10000	los roles fijos de la plataforma	no se pueden modificar (-22511) ni eliminar (-22521); creator es null
roles id ≥ 10000	roles personalizados	se crean con role-create; su eliminación se propaga en cascada a sus asignaciones
privilegios 7111–7113	gestión de roles	no se pueden asignar a un rol personalizado (-22502, -22513)

Ejemplo: configuración completa de un usuario

{"jsonrpc": "2.0", "method": "user-create", "params": {"name": "ops_duty", "fullname": "Ops Duty"}, "id": "1"}

{"jsonrpc": "2.0", "method": "user-set-password", "params": {"id": 12, "password": "<пароль>"}, "id": "2"}

{"jsonrpc": "2.0", "method": "user-role-assign", "params": {"user_id": 12, "vdc_id": 10, "role_id": 2}, "id": "3"}

{"jsonrpc": "2.0", "method": "user-roles-map", "id": "4"}

La última llamada es una comprobación: su respuesta debe mostrar una asignación para el usuario 12 con role_id: 2 y el vdc_id necesario.