DELETE | Excluir grupo de usuários

Descrição

Exclua um grupo de usuários. A plataforma aplica uma exclusão lógica, então o registro é desativado em vez de apagado, e todos os vínculos de membro do grupo são removidos junto com ele. O vínculo de membro isoladamente nunca bloqueia a exclusão.

A exclusão é recusada enquanto o grupo ainda está em uso em outro lugar. Quatro referências bloqueiam a exclusão, e a resposta identifica qual delas se aplica.

Esta requisição não usa o cabeçalho If-Match.

Atenção

Excluir um grupo tem o mesmo efeito que POST | Desativar grupo de usuários: o grupo fica inativo e todos os seus vínculos de membro são removidos. Após a exclusão:

GET | Consultar um grupo de usuários retorna 200 com active: false.
O grupo continua aparecendo em GET | Listar todos os grupos de usuários, a menos que você filtre com user_group.active=true.
POST | Ativar grupo de usuários restaura o grupo, mas não os seus membros.
O nome continua reservado. Criar um grupo com o mesmo nome retorna 422 api.validation.unique.
Uma nova requisição DELETE no mesmo grupo retorna 204 novamente.

Pré-requisitos

Uma aplicação com a autorização Users concedida pelo administrador no A2A. Para mais informações, acesse Como gerenciar autorizações no A2A API v2.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação A2A.

Requisição

DELETE /api/v2/iam/user-groups/{id}

Parâmetros de path

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer	Sim	Código de identificação único do grupo de usuários.

Exemplo de requisição

DELETE {{url}}/api/v2/iam/user-groups/7

Resposta

HTTP/1.1 204 No Content
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34

Uma exclusão bem-sucedida não retorna corpo.

Bloqueios

Quando o grupo ainda é referenciado, a plataforma retorna 409 com o código api.resource.in_use, e o array details identifica a referência.

Cada resposta identifica uma única referência. A plataforma verifica as referências na ordem da tabela a seguir e para na primeira que encontra. Depois que você elimina uma referência, uma nova requisição pode retornar a próxima.

Código em `details[].code`	Significado	Solução
`user_group.in_use.access_policies`	O grupo ainda tem vínculos ativos com políticas de acesso.	Remova os vínculos, acesse POST \| Remover políticas de acesso de um grupo de usuários.
`user_group.in_use.ldap_sync`	O grupo está vinculado a uma sincronização LDAP ativa.	Remova o grupo do escopo da sincronização e tente novamente.
`user_group.in_use.review`	Um membro do grupo tem uma revisão de usuário pendente ou em andamento.	Conclua a revisão e tente novamente.
`user_group.in_use.certification_owners`	O grupo tem proprietários de campanha de certificação ativos.	Remova os proprietários ou conclua a campanha e tente novamente.

Exemplo de resposta de erro

{
  "code": "api.resource.in_use",
  "message": "User group is in use by active access-policy bindings.",
  "details": [
    {
      "code": "user_group.in_use.access_policies"
    }
  ]
}

Erros

Código HTTP	Mensagem	Possível causa	Solução
`401`	`api.auth.unauthorized`	O token de acesso está ausente, inválido ou expirou.	Solicite um novo token de acesso.
`404`	`api.resource.not_found`	O grupo de usuários não existe, ou está fora do escopo da autorização.	Verifique o código de identificação e o escopo da autorização.
`409`	`api.resource.in_use`	O grupo ainda é referenciado.	Verifique o código retornado em `details` e elimine a referência. Veja Bloqueios.
`429`	`api.rate_limit_exceeded`	O limite de requisições foi excedido.	Aguarde o número de segundos retornado no cabeçalho `Retry-After` e tente novamente.

Para as mensagens de erro de autenticação e a política de 403 versus 404, acesse API v2 - Convenções e comportamentos compartilhados.