Beispiel: REST-API User Management

Bevor Sie einen Benutzer einladen, müssen Sie sicherstellen, dass der Benutzer nicht bereits auf dem System vorhanden ist. Um das Scannen der Benutzerliste zu vereinfachen, können Sie dem Aufruf Sortierkriterien hinzufügen. Mit dem folgenden Aufruf werden die Benutzer in der Subskription alphabetisch in absteigender Reihenfolge nach Familienname angezeigt:

GET /instance/services/users?sort=family_name:desc

Wenn Sie wissen, dass der Benutzer, der eingeladen werden soll, John Smith heißt, können Sie auch einen Suchbegriff zum Filtern der Liste einschließen, um nur Benutzer anzuzeigen, deren Namen 'John' enthalten:

GET /instance/services/users?search_term=John

Wenn keine Benutzer mit dem Suchbegriff übereinstimmen, enthält das von dem Aufruf zurückgegebene JSON-Objekt eine leere Liste.

Um weitere Informationen zu den Benutzern anzuzeigen, wie beispielsweise die Gruppen, denen sie angehören, müssen Sie dem Parameter optional_parts für den Aufruf den entsprechenden Wert hinzufügen. Trennen Sie mehrere optionale Teile durch ein Komma. Beachten Sie, dass sich dieser Parameter deutlich auf die Leistung des Aufrufs auswirken kann und Sie ihn in Verbindung mit Suchbegriffen oder Seitenwechseln verwenden sollten. Beispiel:

GET /instance/services/users?search_term=John&optional_parts=details,groups

POST /instance/services/users

Die Benutzerinformationen werden als JSON-Objekt an den Anforderungshauptteil des Aufrufs übergeben. Zum Einladen eines neuen Benutzers muss der Hauptteil des Aufrufs beispielsweise mindestens die Benutzer-ID enthalten:

POST /instance/services/users
...
{
  "user_id": "john.smith@host.com"
}

Sie können weitere Benutzerinformationen aufnehmen, indem Sie die entsprechenden Eigenschaften im JSON-Objekt festlegen. Beispiel:

POST /instance/services/users
...
{
  "user_id": "john.smith@host.com",
  "email": "john.smith@host.com",
  "given_name": "John",
  "family_name": "Smith",
  "groups": [
    {
      "name": "Participants"
    }
  ],
  "details": {
    "phone_number": "555-555-8377",
    "preferred_language": "de"
  }
}

Sie können den grundlegenden Einladungsaufruf auf verschiedene Arten anpassen. Einige Beispiele:

• E-Mail-Einladungen überspringen
  Wenn Benutzer zur Cloudsubskription eingeladen werden, erhalten sie standardmäßig eine Einladungs-E-Mail für die Aktivierung ihres Benutzerkontos. Möglicherweise möchten Sie nicht, dass diese E-Mails gesendet werden, beispielsweise damit Sie die Rollen und Berechtigungen zuweisen können, die Benutzer benötigen, bevor sie ihre Konten aktivieren. Fügen Sie den Parameter skip_email zum Aufruf hinzu, um die E-Mails zu überspringen:

  POST /instance/services/users?skip_email=true
  ...
  {
    "user_id": "john.smith@host.com"
  }

  Wenn Sie die Einrichtung der Benutzerkonten abgeschlossen haben, können Sie die Aktivierungs-E-Mails senden, indem Sie den API-Aufruf erneut ausgeben, wobei der Parameter skip_email auf false gesetzt ist.
• Benutzerkonten automatisch aktivieren
  Abhängig von der Konfiguration Ihrer Cloudsubskription ist diese Option möglicherweise für die Security Assertion Markup Language-Authentifizierung (SAML) aktiviert. Mit der SAML-Authentifizierung können Sie Benutzerkonten automatisch aktivieren. Wenn Sie die automatische Aktivierung auswählen, müssen Sie ebenfalls das Senden von Aktivierungs-E-Mails überspringen, wie im folgenden Aufruf gezeigt:

  POST /instance/services/users?activate_automatically=true&skip_email=true
  ...
  {
    "user_id": "john.smith@host.com"
  }

• Gruppeninformationen hinzufügen
  Abhängig von der Konfiguration Ihrer Subskription werden Benutzer automatisch Ihren Standardgruppen zugewiesen, z. B. der Gruppe 'Teilnehmer' für die Produktionsumgebung. Wenn Benutzer nicht automatisch Gruppen zugewiesen werden, können Sie die Gruppeninformationen in dem API-Aufruf hinzufügen:

  POST /instance/services/users
  ...
  {
    "user_id": "john.smith@host.com"
     "groups": [ 
     {
      "name": "Participants"
     }
    ]
  }

  Wenn Sie nicht wissen, zu welchen Gruppen Benutzer gehören sollen, können Sie sie später mithilfe der Group Management-API zuweisen.
• Mehrere Benutzer einladen
  Um mehrere Benutzer einzuladen, verwenden Sie den folgenden Aufruf und schließen Sie die Benutzer in das JSON-Objekt im Hauptteil des Aufrufs ein. Dieser Aufruf ist nützlich, wenn Sie einen Massenimport für Benutzer aus Ihrer lokalen Benutzerregistry in die Benutzerregistry der Cloudplattform durchführen möchten. Beispiel:

  POST /instance/services/bulk/users
  ...
  {
    "users": [
      {
        "user_id": "john.smith@host.com"
      },
      {
        "user_id": "jane.smith@host.com"
      }
    ]
  }

Sie können die Benutzerinformationen auf die folgenden Arten aktualisieren:

• Senden Sie das vollständige JSON-Objekt mit den geänderten Eigenschaften mit dem Aufruf ab. Wenn Sie beispielsweise die Telefonnummer von John Smith ändern möchten, können Sie den folgenden Aufruf verwenden:

  PUT /instance/services/users/john.smith@host.com
  ...
  {
    "user_id": "john.smith@host.com",
    "email": "john.smith@host.com",
    "given_name": "John",
    "family_name": "Smith",
    "groups": [
      {
        "name": "Participants"
      }
    ],
    "details": {
      "phone_number": "555-555-8321",
      "preferred_language": "de"
    }
  }

  Die gespeicherten Benutzerinformationen werden vollständig durch die Informationen ersetzt, die im Anforderungshauptteil gesendet werden. Wenn Sie Eigenschaften aus dem JSON-Objekt auslassen, z. B. wenn die Gruppeneigenschaft nicht im Hauptteil enthalten ist, werden die Benutzer aus allen Gruppen entfernt.
• Führen Sie die aktualisierten Eigenschaften mit den gespeicherten Benutzerinformationen zusammen. Beispiel: Um die Telefonnummer zu ändern und den Benutzer der Gruppe 'Operatoren' hinzuzufügen, aber alle anderen Benutzerinformationen beizubehalten, müssen Sie den folgenden REST-API-Aufruf verwenden:

  PUT /instance/services/users/john.smith@host.com?update_mode=merge
  ...
  {
    "groups": [
      {
        "name": "Operators"
      }
    ],
    "details": {
      "phone_number": "555-555-8321"
    }
  }

Zum Löschen von John Smith aus der Subskription verwenden Sie zum Beispiel den folgenden Aufruf:

DELETE /instance/services/users/john.smith@host.com