Administrar grupos¶

Con un grupo das a un equipo entero los mismos roles y atributos de una vez. Esta página muestra cómo crear un grupo, añadir y quitar miembros y suprimir un grupo. Qué es un grupo está en Roles y acceso.

Los grupos se administran con el rol people-admin u org-admin; solo org-admin puede eliminar un grupo. Los grupos aún no tienen pantalla en OS: los administras mediante la API.

Antes de empezar¶

Los ejemplos usan tres variables en tu shell:

OS=https://os.example.com      # la dirección de OS
TOKEN=...                      # un token de acceso de tu propio inicio de sesión
ORG=org_...                    # el id de tu organización

Cómo funciona una solicitud a OS y qué contiene cada respuesta está en La API de acceso.

Crear un grupo¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/groups" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"name": "Ventas", "labels": {"department": "sales"}}'

OS responde 201 con el grupo:

{"id": "grp_...", "name": "Ventas", "labels": {"department": ["sales"]},
 "version": 1, "allowed_actions": ["see", "write", "delete"]}

• name es único en la organización, como máximo 200 caracteres.
• labels son opcionales: etiquetas que las reglas sobre grupos pueden leer, como máximo 32. Una etiqueta tiene un valor o una lista de valores.

GET /api/v1/organisations/$ORG/groups muestra los grupos que puedes ver, en páginas de como máximo 200 (limit, por defecto 50); pasa next_cursor como cursor para la página siguiente.

Cambiar el nombre o las etiquetas de un grupo¶

Sustituyes el grupo entero e indicas la versión que leíste. Está en version y en la cabecera ETag de la respuesta.

curl -s -X PUT "$OS/api/v1/organisations/$ORG/groups/grp_..." \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -H 'If-Match: "1"' \
    -d '{"name": "Ventas Benelux", "labels": {"department": "sales"}}'

Si alguien ha modificado el grupo entretanto, OS responde 409. Lee el grupo de nuevo y repite tu cambio.

Añadir y quitar miembros¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/groups/grp_.../members" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"membership_id": "mem_..."}'

El miembro recibe de inmediato todos los roles y valores del grupo. Por eso debes tener tú mismo todos los roles y todos los valores que da el grupo; de lo contrario OS rechaza con 403 e indica lo que te falta (por qué).

• GET .../groups/grp_.../members muestra los miembros que puedes ver.
• DELETE .../groups/grp_.../members/mem_... saca a un miembro del grupo. El miembro pierde lo que daba el grupo, y conserva lo que tiene por sí mismo o mediante otros grupos.

Un miembro está en como máximo 32 grupos.

Dar roles o atributos a un grupo¶

Un grupo recibe un rol como lo recibe un miembro, con group_id en lugar de member_id: consulta Dar un rol y Dar un valor.

Eliminar un grupo¶

curl -s -X DELETE "$OS/api/v1/organisations/$ORG/groups/grp_..." \
    -H "Authorization: Bearer $TOKEN"

OS responde 204. Los miembros pierden lo que daba el grupo. Los roles y valores que tienen por sí mismos se conservan.

Si OS rechaza¶