Campos e códigos de erro dos métodos de acesso

Quando usar esta referência

Use esta referência ao escrever uma integração ou interpretar uma resposta do cluster quando precisar do conjunto exato de campos, do tipo de parâmetro, do nível de acesso e do significado de um código. Para procedimentos passo a passo, consulte os guias de gerenciamento de usuários, de papéis e privilégios e de login e sessões; para o modelo de permissões, consulte Modelo de acesso do vStack Center. Nas tabelas abaixo, VDC significa data center virtual, o objeto delimitado por vdc_id.

Resumo dos métodos

Usuários

Método	Parâmetros	Acesso	Retorna
user-list	nenhum	Cluster master	um mapa de usuários ativos, indexado pelo id em string
user-get	id	Cluster master	o perfil de um único usuário
user-create	name, fullname	Cluster master	o id da conta criada
user-delete	id	Cluster master	data vazio
user-set-password	id, password	a própria senha: qualquer usuário; o id de outro usuário: Cluster master	data vazio
user-unlock	id	Cluster master	o id da conta desbloqueada
user-params-get	nenhum	usuário atual	o objeto JSON de configurações salvo
user-params-set	objeto arbitrário	usuário atual	data vazio

Papéis de usuário e atribuições

Método	Parâmetros	Acesso	Retorna
user-role	nenhum	usuário atual	UID e authmap
user-roles	user_id, q	os próprios papéis: qualquer usuário; o user_id de outro usuário: Cluster master	um mapa VDC → papel; com a chave q, um mapa VDC → array de papéis
user-roles-v2	user_id	o privilégio View Own User Roles (7102); o user_id de outro usuário: View Any User Roles (7106)	um mapa papel → atributos de escopo
user-roles-map	nenhum	Cluster master	todos os usuários com as atribuições expandidas
user-role-assign	user_id, vdc_id, role_id	Cluster master	data vazio
user-role-deassign	user_id, vdc_id, role_id	Cluster master	data vazio

O parâmetro vdc_id em user-role-assign é obrigatório para um papel com vinculação de escopo; em user-role-deassign, é sempre obrigatório. O flag q em user-roles é determinado pela presença da chave em params; seu valor não é lido. O flag q não é suportado em user-roles-v2.

Papéis e privilégios

Método	Parâmetros	Acesso	Retorna
role-list	nenhum	não especificado na documentação canônica da API	todos os papéis com scope_ids, creator e carimbos de data/hora
role-get	id	um papel global com o privilégio View Role Details (7114)	o papel com seus privileges e scope_ids completos
role-scopes	id	o privilégio View Role Scopes (7115)	os atributos de escopo do papel com self_referencing = false
role-create	name, privileges, scope_ids	Cluster master	o id do papel criado
role-set	id, name, remove_privileges, add_privileges, scope_ids	Cluster master	data vazio
role-delete	id	Cluster master	data vazio
role-privilege-list	nenhum	o privilégio View Role Privileges (7108), concedido aos sete papéis fixos	um mapa role_id → array de privilege_id
privilege-list	nenhum	o privilégio View Privileges (7107), concedido aos sete papéis fixos	o registro de privilégios com categorias, escopos e métodos
privilege-categories	nenhum	o privilégio View Privilege Categories (7109), concedido aos sete papéis fixos	um mapa category_id → nome
privilege-scopes	nenhum	o privilégio View Privilege Scopes (7110), concedido aos sete papéis fixos	a referência de atributos de escopo

Restrições de acesso da conta

Método	Parâmetros	Acesso	Retorna
user-remote-list	user_id	Cluster master	um array de CIDRs permitidos
user-remote-add	user_id, remote	Cluster master	data vazio
user-remote-delete	user_id, remote	Cluster master	data vazio
user-vhost-list	user_id	Cluster master	um array de vhosts permitidos
user-vhost-add	user_id, vhost	Cluster master	data vazio
user-vhost-delete	user_id, vhost	Cluster master	data vazio

Sessão e configurações de segurança

Método	Parâmetros	Acesso	Retorna
auth-logout	all	qualquer usuário autenticado, para as próprias sessões	{"result": true}
auth-security-settings-get	nenhum	qualquer usuário autorizado; o conjunto de campos depende do papel	configurações de senha e de bloqueio
auth-security-settings-set	oito campos da política, todos opcionais	Cluster master	data vazio

Parâmetros com validação

Método	Parâmetro	Tipo	Obrigatório	Restrição
user-create	name	string	sim	regex ^[A-Z,a-z,_-]{4,41}$
user-create	fullname	string	não	—
user-delete	id	number	sim	range(min=0); id < 10 é proibido
user-set-password	id	number	não	o padrão é o usuário atual
user-set-password	password	string	sim	regex ^[\S]+$ mais a política de senhas
user-role-assign	user_id, role_id	number	sim	range(min=0); user_id < 10 é proibido
user-remote-add	remote	string	sim	CIDR IPv4 com máscara de 8–32 ou IPv6 com prefixo de 16–128
user-vhost-add	vhost	string	sim	comprimento de 5–512
role-create	name	string	sim	comprimento de 1–64, único
role-create	privileges	array<integer>	sim	não vazio; exclui 7111–7113
role-create	scope_ids	array<integer>	não	somente atributos com self_referencing = false
role-set	id	integer	sim	no mínimo 10000
role-delete	id	integer	sim	no mínimo 10000
auth-security-settings-set	max_failed_attempts, failed_attempts_window_minutes, password_min_length	integer	não	range(min=1)
auth-security-settings-set	lockout_duration_minutes	integer	não	range(min=0)
auth-logout	all	boolean	não	o padrão é false

Campos do perfil de usuário

O conjunto de campos é o mesmo para user-get e para cada entrada de user-list.

Campo	Tipo	Descrição
id	integer	identificador do usuário
name	string	nome da conta
fullname	string | null	nome completo
created	integer	horário de criação, epoch
modified	integer | null	horário da última modificação, epoch
failed_login_attempts	integer	contador de tentativas de login malsucedidas
first_failed_at	integer | null	início da janela de contagem atual, epoch; null significa que não há tentativas malsucedidas
locked_until	integer | null	horário até o qual a conta está bloqueada, epoch; null significa não bloqueada

Campos do papel

Campo	Tipo	Retornado por	Descrição
id	integer	role-list, role-get	identificador do papel
name	string	role-list, role-get	nome do papel
scope_ids	integer[]	role-list, role-get	os atributos de escopo do papel; um array vazio significa sem vinculação
privileges	integer[]	role-get	a lista completa de privilégios do papel
creator	integer | null	role-list, role-get	o criador do papel; null para papéis fixos
created_ts	integer	role-list, role-get	horário de criação, timestamp unix
modified_ts	integer | null	role-list, role-get	horário da última modificação; null significa nunca modificado

Os papéis fixos da plataforma:

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

Campos de privilégios e de atributos de escopo

Uma entrada do registro privilege-list:

Campo	Tipo	Descrição
id	number	identificador do privilégio
name	string	nome do privilégio
category_id	number | null	categoria; null significa que o privilégio não está atribuído a uma categoria
scope_ids	number[]	os atributos de escopo do privilégio; um array vazio significa um privilégio global
methods	string[]	nomes dos métodos JSON-RPC que exigem este privilégio

Uma entrada da referência privilege-scopes e role-scopes:

Campo	Tipo	Descrição
id	integer	identificador do atributo de escopo
name	string	nome do atributo, como vdc_id ou creator
self_referencing	boolean	true significa que o valor é gerado a partir de user_id (creator); false significa que vem das atribuições de papéis (vdc_id)

Na resposta de role-scopes, self_referencing é sempre false: os atributos autorreferenciais não são incluídos nessa resposta.

Categorias de privilégios (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.

observação

A documentação canônica da API lista apenas as dez primeiras categorias no seu exemplo de resposta, enquanto o banco de dados contém quinze: cada novo domínio adiciona sua própria categoria. O método retorna a referência completa, portanto verifique a resposta real do cluster.

Papéis de usuário: quatro formatos de resposta

Método	Formato de data	Quando é útil
user-role	UID + authmap: um array de objetos com vdc_id, vdc_name, role_id, role_name, GI_account	o cliente precisa mostrar "quem sou e onde" em uma única chamada
user-roles sem q	um mapa vdc_id em string → role_id	verificação rápida de um único papel por VDC
user-roles com q	um mapa vdc_id em string → array de role_id	o usuário tem mais de um papel em um VDC
user-roles-v2	um mapa role_id → scopes, contendo is_global e ids para cada attr_id	determinar exatamente como o papel é restringido
user-roles-map	um mapa id de usuário em string → perfil + array roles	inventariar todas as atribuições do cluster

Campos em user-roles-v2:

Campo	Tipo	Descrição
data.<role_id>.scopes	object	as chaves são os valores attr_id em string dos atributos de escopo do papel
data.<role_id>.scopes.<attr_id>.is_global	boolean	true significa que não há valores nas atribuições e que o papel não é restringido pelo atributo
data.<role_id>.scopes.<attr_id>.ids	integer[]	valores do atributo vindos das atribuições, como uma lista de VDCs

Os valores válidos de role_id para papéis fixos são 1–7. Os papéis personalizados aparecem nas mesmas respostas com identificadores a partir de 10000.

Configurações de segurança

Campo	Tipo	Visível em auth-security-settings-get para
max_failed_attempts	integer	somente Cluster master
failed_attempts_window_minutes	integer	somente Cluster master
lockout_duration_minutes	integer	somente Cluster master
password_min_length	integer	todos os usuários autorizados
password_require_uppercase	boolean	todos os usuários autorizados
password_require_lowercase	boolean	todos os usuários autorizados
password_require_digits	boolean	todos os usuários autorizados
password_require_special	boolean	todos os usuários autorizados

Códigos de erro

Usuários

Código	Mensagem	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 da política de senhas	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

Atribuição de papéis

Código	Mensagem	Métodos
-403	Access denied	user-role-assign
-22320	Build-it users management prohibited / papel já atribuído	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

Papéis e privilégios

Código	Mensagem	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

A faixa -225xx é usada duas vezes: user-create e o grupo role-* usam os mesmos números. Por exemplo, -22505 significa "nome de usuário inválido" em user-create e "escopo autorreferencial proibido" em role-create, enquanto -22516 significa que um nome de usuário ou um nome de papel já está em uso. Interprete o código pelo método chamado, e não apenas pelo número.

Restrições de acesso da conta

Código	Mensagem	Métodos
-403	Access denied	todos os seis métodos do 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

A documentação canônica da API lista o par -24812, -24814 tanto para user-remote-delete quanto para user-vhost-add. Interprete o significado pelo método chamado.

Sessão e configurações de segurança

Código	Mensagem	Onde ocorre
-9494	No session token	qualquer chamada sem params.auth.cookie
-11000	o token não foi encontrado entre as sessões ativas, expirou ou foi invalidado	auth-logout e qualquer chamada com token inválido
-125	Temp token expired or invalid	user-set-password usando temp_token
-126	Method not allowed with temp token	qualquer chamada com temp_token, exceto user-set-password e auth-security-settings-get
-127	Temp token allows changing own password only	user-set-password usando temp_token
-403	Access denied	auth-security-settings-set
-29101	Security settings not found	auth-security-settings-get
-29102	erro de banco de dados	auth-security-settings-get, auth-security-settings-set

Restrições de identificadores

Faixa	Significado	Consequência
usuários id < 10	contas integradas	não podem ser excluídas (-22610); as atribuições de papéis não podem ser alteradas (-22320, -22421)
papéis id < 10000	os papéis fixos da plataforma	não podem ser modificados (-22511) nem excluídos (-22521); creator é null
papéis id ≥ 10000	papéis personalizados	criados com role-create; a exclusão se propaga em cascata para suas atribuições
privilégios 7111–7113	gerenciamento de papéis	não podem ser atribuídos a um papel personalizado (-22502, -22513)

Exemplo: configuração completa de um usuário

{"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"}

A última chamada é uma verificação: sua resposta deve mostrar uma atribuição para o usuário 12 com role_id: 2 e o vdc_id necessário.