Exemple : API REST User Management

Cet exemple montre comment utiliser l'API REST User Management d'opérations cloud pour gérer le cycle de vie d'un utilisateur sur un abonnement cloud.

L'exemple montre comment vérifier que l'utilisateur n'existe pas déjà, inviter un ou plusieurs utilisateurs à rejoindre l'abonnement, mettre à jour les informations utilisateur et supprimer l'utilisateur de l'abonnement.

Avant de commencer

Tous les appels d'API nécessitent un jeton CSRF (cross site forgery request) valide dans l'en-tête IBM-CSRF-TOKEN de l'appel. Obtenez un jeton CSRF via POST /instance/services/csrf_token. Pour plus d'informations, voir Prévention de la falsification de requêtes entre sites (CSRF).

Gérer le cycle de vie de l'utilisateur

Affichez une liste des utilisateurs enregistrés dans l'abonnement.
Avant d'inviter un utilisateur, vous pouvez chercher à vérifier que cet utilisateur n'existe pas déjà dans le système. Pour faciliter l'analyse de la liste des utilisateurs, vous pouvez ajouter des critères de tri à l'appel. L'appel suivant affiche les utilisateurs de l'abonnement par ordre alphabétique, décroissante et par nom de famille :
```
GET /instance/services/users?sort=family_name:desc
```
Sinon, si vous savez que l'utilisateur que vous souhaitez inviter s'appelle John Smith, vous pouvez inclure un terme de recherche pour filtrer la liste afin d'afficher uniquement les utilisateurs contenant John dans leur nom :
```
GET /instance/services/users?search_term=John
```
Si aucun utilisateur ne correspond au terme recherché, l'objet JSON renvoyé par l'appel contient une liste vide.
Pour afficher des informations supplémentaires sur les utilisateurs, par exemple les groupes auxquels ils appartiennent, ajoutez la valeur correspondante au paramètre optional_parts dans l'appel. Séparez les différentes parties facultatives par des virgules. Sachez que ce paramètre peut affecter de manière significative la performance de l'appel. Vous devez donc l'utiliser en association avec des termes de recherche ou une pagination. Exemple :
```
GET /instance/services/users?search_term=John&optional_parts=details,groups
```
Invitez un utilisateur, par exemple John Smith, à rejoindre l'abonnement à l'aide de l'appel suivant :
```
POST /instance/services/users
```
Les informations utilisateur sont transmises en tant qu'objet JSON dans le corps de demande de l'appel. Par exemple, pour inviter un nouvel utilisateur, le corps de l'appel doit contenir au moins l'ID utilisateur :
```
POST /instance/services/users
...
{
  "user_id": "john.smith@host.com"
}
```
Vous pouvez inclure des informations utilisateur supplémentaires en définissant les propriétés correspondantes dans l'objet JSON. Exemple :
```
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"
  }
}
```
Vous pouvez personnaliser l'appel d'invitation de base de plusieurs manières. Voici quelques exemples :
- Ignorer les invitations par courrier électronique
  Par défaut, lorsque des utilisateurs sont invités à rejoindre l'abonnement de cloud, ils reçoivent automatiquement une invitation par courrier électronique afin qu'ils activent leur compte utilisateur. Vous pouvez ne pas souhaiter envoyer ces messages électroniques. Par exemple, lorsque vous voulez affecter les rôles et les droits dont les utilisateurs ont besoin avant l'activation de leur compte. Pour ignorer les e-mails, ajoutez le paramètre skip_email à l'appel :
```
POST /instance/services/users?skip_email=true
...
{
  "user_id": "john.smith@host.com"
}
```
  Lorsque vous avez fini de configurer les comptes utilisateur, vous pouvez envoyer les e-mails d'activation en émettant à nouveau l'appel d'API avec le paramètre skip_email défini sur false.
- Activer automatiquement les comptes utilisateur
  En fonction de la configuration de votre abonnement de cloud, ce dernier peut être activé pour l'authentification SAML (Security Assertion Markup Language). Avec l'authentification SAML, vous pouvez activer automatiquement les comptes utilisateur. Si vous choisissez l'activation automatique, vous devez également ne pas envoyer les courriers électroniques d'activation, comme cela est présenté dans l'appel suivant :
```
POST /instance/services/users?activate_automatically=true&skip_email=true
...
{
  "user_id": "john.smith@host.com"
}
```
- Ajouter des informations de groupe
  En fonction de la configuration de votre abonnement, des utilisateurs sont automatiquement affectés à vos groupes par défaut, par exemple les participants pour l'environnement de production. Si aucun utilisateur n'est affecté automatiquement aux groupes, vous pouvez ajouter les informations de groupe à l'appel API :
```
POST /instance/services/users
...
{
  "user_id": "john.smith@host.com"
   "groups": [ 
   {
    "name": "Participants"
   }
  ]
}
```
  Si vous ne savez pas à quels groupes les utilisateurs doivent appartenir, vous pouvez les affecter ultérieurement à l'aide de l'API Group Management.
- Inviter plusieurs utilisateurs
  Pour inviter plusieurs utilisateurs, utilisez l'appel suivant et incluez les utilisateurs dans l'objet JSON du corps de l'appel. Cet appel est utile si vous voulez importer en bloc des utilisateurs depuis votre registre d'utilisateurs sur site dans le registre d'utilisateurs sur la plateforme cloud. Exemple :
```
POST /instance/services/bulk/users
...
{
  "users": [
    {
      "user_id": "john.smith@host.com"
    },
    {
      "user_id": "jane.smith@host.com"
    }
  ]
}
```
Mettez à jour les informations utilisateur.
Vous pouvez mettre à jour les informations utilisateur de l'une des manières suivantes :
- Envoyez l'objet JSON complet, y compris les propriétés modifiées, avec l'appel. Par exemple, si vous souhaitez changer le numéro de téléphone de John Smith, vous pouvez utiliser l'appel suivant :
```
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"
  }
}
```
  Les informations utilisateur stockées sont entièrement remplacées par les informations envoyées dans le corps de la demande. Si vous omettez des propriétés de l'objet JSON ; par exemple, si la propriété des groupes n'est pas incluse dans le corps, l'utilisateur sera supprimé de tous les groupes.
- Fusionnez les propriétés mises à jour avec les informations utilisateur stockées. Par exemple, pour changer le numéro de téléphone et ajouter l'utilisateur au groupe Opérateurs mais conserver toutes les autres informations utilisateur identiques, utilisez l'appel API REST suivant :
```
PUT /instance/services/users/john.smith@host.com?update_mode=merge
...
{
  "groups": [
    {
      "name": "Operators"
    }
  ],
  "details": {
    "phone_number": "555-555-8321"
  }
}
```
Supprimez un utilisateur d'un abonnement.
Par exemple, pour supprimer John Smith de l'abonnement, utilisez l'appel suivant :
```
DELETE /instance/services/users/john.smith@host.com
```