Gruppen verwalten¶

Mit einer Gruppe geben Sie einem ganzen Team auf einmal dieselben Rollen und Attribute. Diese Seite zeigt, wie Sie eine Gruppe anlegen, Mitglieder hinzufügen und entfernen und eine Gruppe wieder auflösen. Was eine Gruppe ist, steht unter Rollen und Zugriff.

Gruppen verwalten Sie mit der Rolle people-admin oder org-admin; eine Gruppe löschen kann nur org-admin. Gruppen haben in OS noch keinen Bildschirm: Sie verwalten sie über die API.

Bevor Sie beginnen¶

Die Beispiele nutzen drei Variablen in Ihrer Shell:

OS=https://os.example.com      # die Adresse von OS
TOKEN=...                      # ein Zugriffstoken Ihrer eigenen Anmeldung
ORG=org_...                    # die ID Ihrer Organisation

Wie eine Anfrage an OS funktioniert und was jede Antwort enthält, steht unter Die Zugriffs-API.

Eine Gruppe anlegen¶

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

OS antwortet 201 mit der Gruppe:

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

• name ist in der Organisation eindeutig, höchstens 200 Zeichen.
• labels sind optional: Labels, die Regeln über Gruppen lesen können, höchstens 32. Ein Label hat einen Wert oder eine Liste von Werten.

GET /api/v1/organisations/$ORG/groups zeigt die Gruppen, die Sie sehen dürfen, seitenweise mit höchstens 200 (limit, Standard 50); geben Sie next_cursor als cursor mit, um die nächste Seite zu erhalten.

Eine Gruppe umbenennen oder anders labeln¶

Sie ersetzen die Gruppe als Ganzes und nennen die Version, die Sie gelesen haben. Sie steht in version und im Header ETag der Antwort.

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": "Vertrieb Benelux", "labels": {"department": "sales"}}'

Hat jemand die Gruppe inzwischen geändert, antwortet OS 409. Lesen Sie die Gruppe erneut und wiederholen Sie Ihre Änderung.

Mitglieder hinzufügen und entfernen¶

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_..."}'

Das Mitglied erhält sofort alle Rollen und Werte der Gruppe. Deshalb müssen Sie selbst jede Rolle und jeden Wert haben, den die Gruppe gibt; sonst lehnt OS mit 403 ab und nennt, was Ihnen fehlt (warum).

• GET .../groups/grp_.../members zeigt die Mitglieder, die Sie sehen dürfen.
• DELETE .../groups/grp_.../members/mem_... nimmt ein Mitglied aus der Gruppe. Das Mitglied verliert, was die Gruppe gab, und behält, was es selbst oder über andere Gruppen hat.

Ein Mitglied ist in höchstens 32 Gruppen.

Einer Gruppe Rollen oder Attribute geben¶

Eine Gruppe erhält eine Rolle so, wie ein Mitglied sie erhält, mit group_id statt member_id: siehe Eine Rolle geben und Einen Wert geben.

Eine Gruppe löschen¶

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

OS antwortet 204. Die Mitglieder verlieren, was die Gruppe gab. Rollen und Werte, die sie selbst haben, bleiben.

Wenn OS ablehnt¶