Ejemplo: API REST de User Management

En este ejemplo se muestra cómo utilizar la API REST de User Management de operaciones de nube para gestionar el ciclo de vida de un usuario en una suscripción de nube.

En el ejemplo se comprueba que el usuario no exista ya, se invita a uno o varios usuarios a la suscripción, se actualiza la información de usuario y finalmente se suprime el usuario de la suscripción.

Antes de empezar

Todas las llamadas de API requieren una señal de falsificación de solicitud entre sitios (CSRF) válida en la cabecera IBM-CSRF-TOKEN de la llamada. Obtenga una señal CSRF mediante POST /instance/services/csrf_token. Para obtener más información, consulte Cómo evitar la falsificación de solicitudes entre sitios.

Gestionar el ciclo de vida del usuario

Visualizar una lista de usuario registrados en la suscripción.
Antes de invitar a un usuario, querrá asegurarse de que éste no exista ya en el sistema. Para facilitar la exploración de la lista de usuarios, puede añadir criterios de ordenación a la llamada. La llamada siguiente muestra alfabéticamente los usuarios de la suscripción por orden descendente de los apellidos:
```
GET /instance/services/users?sort=family_name:desc
```
Si sabe que el usuario que desea invitar se llama John Smith, también puede incluir un término de búsqueda para filtrar la lista y mostrar solo los usuarios que incluyan John en el nombre:
```
GET /instance/services/users?search_term=John
```
Si ningún usuario coincide con el término de búsqueda, el objeto JSON devuelto por la llamada contiene una lista vacía.
Para visualizar información adicional sobre los usuarios, como por ejemplo los grupos a los que pertenecen, añada a la llamada el valor correspondiente al parámetro optional_parts. Separe con una coma los diferentes componentes opcionales. Tenga en cuenta que este parámetro puede afectar significativamente al rendimiento de la llamada y que debe utilizarlo en combinación con términos de búsqueda o paginación. Por ejemplo:
```
GET /instance/services/users?search_term=John&optional_parts=details,groups
```
Invite a un usuario, por ejemplo John Smith, a la suscripción mediante la llamada siguiente:
```
POST /instance/services/users
```
La información de usuarios se pasa como un objeto JSON en el cuerpo de solicitud de la llamada. Por ejemplo, para invitar a un usuario nuevo, el cuerpo de la llamada debe contener como mínimo el ID de usuario:
```
POST /instance/services/users
...
{
  "user_id": "john.smith@host.com"
}
```
Puede incluir información de usuario adicional estableciendo las propiedades correspondientes en el objeto JSON. Por ejemplo:
```
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"
  }
}
```
Puede personalizar la llamada de invitación básica de varias maneras. Aquí tiene algunos ejemplos:
- Omitir invitaciones por correo electrónico
  De forma predeterminada, cuando se invita a los usuarios a la suscripción en la nube, estos reciben automáticamente un correo electrónico de invitación para activar la cuenta de usuario correspondiente. Puede optar por omitir el envío de estos correos electrónicos, por ejemplo, para poder asignar los roles y los permisos que los usuarios necesitan antes de que activen sus cuentas. Para omitir los correos electrónicos, añada el parámetro skip_email a la llamada:
```
POST /instance/services/users?skip_email=true
...
{
  "user_id": "john.smith@host.com"
}
```
  Cuando haya terminado de configurar las cuentas de usuario, puede enviar los correos electrónicos de activación emitiendo de nuevo la llamada de API con el parámetro skip_email establecido en false.
- Activar automáticamente cuentas de usuario
  Según como se haya configurado la suscripción en la nube, puede estar habilitada para la autenticación de Security Assertion Markup Language (SAML). Con la autenticación SAML puede activar automáticamente las cuentas de usuario. Si elige la activación automática, también debe omitir el envío de correos electrónicos de activación, tal como se muestra en la llamada siguiente:
```
POST /instance/services/users?activate_automatically=true&skip_email=true
...
{
  "user_id": "john.smith@host.com"
}
```
- Añadir información de grupo
  Según como se haya configurado la suscripción, los usuarios se asignan automáticamente a los grupos predeterminados, por ejemplo Participantes para el entorno de producción. Si los usuarios no se asignan automáticamente a grupos, puede añadir la información de grupo a la llamada de API.
```
POST /instance/services/users
...
{
  "user_id": "john.smith@host.com"
   "groups": [ 
   {
    "name": "Participants"
   }
  ]
}
```
  Si no sabe a qué grupos deben pertenecer los usuarios, puede asignarlos posteriormente utilizando la API de Group Management.
- Invitar a varios usuarios
  Para invitar a varios usuarios, utilice la llamada siguiente e incluya los usuarios en el objeto JSON, en el cuerpo de la llamada. Esta llamada es útil si desea realizar una importación masiva de usuarios del registro de usuarios local en el registro de usuarios de la plataforma en la nube. Por ejemplo:
```
POST /instance/services/bulk/users
...
{
  "users": [
    {
      "user_id": "john.smith@host.com"
    },
    {
      "user_id": "jane.smith@host.com"
    }
  ]
}
```
Actualizar información de usuario.
Puede actualizar la información de usuario de las maneras siguientes:
- Envíe el objeto JSON completo con la llamada, incluidas las propiedades cambiadas. Por ejemplo, si desea cambiar el número de teléfono de John Smith, puede utilizar la llamada siguiente:
```
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"
  }
}
```
  La información de usuario almacenada se sustituye completamente por la información que se envía en el cuerpo de solicitud. Si omite las propiedades del objeto JSON, por ejemplo, si la propiedad groups no está incluida en el cuerpo, el usuario se eliminará de todos los grupos.
- Fusionar las propiedades actualizadas con la información de usuario almacenada. Por ejemplo, para cambiar el número de teléfono y añadir el usuario al grupo Operators, pero conservar inalterada el resto de la información del usuario, utilice la llamada de API REST siguiente:
```
PUT /instance/services/users/john.smith@host.com?update_mode=merge
...
{
  "groups": [
    {
      "name": "Operators"
    }
  ],
  "details": {
    "phone_number": "555-555-8321"
  }
}
```
Suprimir un usuario de una suscripción.
Por ejemplo, para suprimir a John Smith de la suscripción, utilice la llamada siguiente:
```
DELETE /instance/services/users/john.smith@host.com
```