Esempio: API REST User Management

Prima di invitare un utente, è possibile verificare che l'utente non esista già nel sistema. Per semplificare la scansione dell'elenco di utenti, è possibile aggiungere criteri di ordinamento alla chiamata. La seguente chiamata visualizza gli utenti nella sottoscrizione in ordine alfabetico in ordine decrescente in base al cognome:

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

In alternativa, se si sa che l'utente che si desidera invitare è chiamato John Smith, è possibile includere un termine di ricerca per filtrare l'elenco in modo da mostrare solo gli utenti con John nel nome:

GET /instance/services/users?search_term=John

Se nessun utente corrisponde al termine di ricerca, l'oggetto JSON restituito dalla chiamata contiene un elenco vuoto.

Per visualizzare ulteriori informazioni relative agli utenti, come i gruppi a cui appartengono, aggiungere il valore corrispondente al parametro optional_parts alla chiamata. Separare più parti facoltative con una virgole. Tenere presente che questo parametro può influire in modo significativo sulle prestazioni della chiamata ed è necessario utilizzarlo in combinazione con i termini di ricerca o la paginazione. Ad esempio:

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

POST /instance/services/users

Le informazioni utente vengono trasmesse come oggetto JSON nel corpo della richiesta della chiamata. Ad esempio, per invitare un nuovo utente, il corpo della chiamata deve contenere almeno l'ID utente:

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

È possibile includere ulteriori informazioni utente impostando le proprietà corrispondenti nell'oggetto JSON. Ad esempio:

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"
  }
}

È possibile personalizzarla in diversi modi. Di seguito sono riportati alcuni esempi:

• Ignora inviti email
  Per impostazione predefinita, quando gli utenti vengono invitati alla sottoscrizione cloud, ricevono automaticamente un'email di invito per attivare il proprio account utente. È possibile ignorare l'invio di queste email, ad esempio, in modo da poter assegnare i ruoli e le autorizzazioni di cui gli utenti hanno bisogno prima di attivare i propri account. Per ignorare le email, aggiungere il parametro skip_email alla chiamata:

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

  Una volta terminata la configurazione degli account utente, puoi inviare le e-mail di attivazione emettendo nuovamente la chiamata API con il parametro skip_email impostato su false.
• Attiva automaticamente gli account utente
  A seconda di come è stata impostata la sottoscrizione cloud, questa potrebbe essere abilitata per l'autenticazione SAML (Security Assertion Markup Language). Con l'autenticazione SAML, è possibile attivare automaticamente gli account utente. Se scegli l'attivazione automatica, devi anche saltare l'invio delle email di attivazione come mostrato nella seguente chiamata:

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

• Aggiungi informazioni sul gruppo
  A seconda di come è stata impostata la sottoscrizione, gli utenti vengono assegnati automaticamente ai gruppi predefiniti, ad esempio Partecipanti per l'ambiente di produzione. Se gli utenti non vengono assegnati automaticamente ai gruppi, puoi aggiungere le informazioni sul gruppo nella chiamata API:

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

  Se non sai a quali gruppi devono appartenere gli utenti, puoi assegnarli in seguito utilizzando l'API Group Management .
• Invita diversi utenti
  Per invitare diversi utenti, utilizza la seguente chiamata e includi gli utenti nell'oggetto JSON nel corpo della chiamata. Questa chiamata è utile se si desidera importare in massa gli utenti dal registro utenti installato in loco al registro utenti della piattaforma cloud. Ad esempio:

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

È possibile aggiornare le informazioni utente nei modi seguenti:

• Inviare l'oggetto JSON completo, incluse le proprietà modificate, con la chiamata. Ad esempio, se si desidera modificare il numero di telefono di John Smith, è possibile utilizzare la seguente chiamata:

  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"
    }
  }

  Le informazioni utente memorizzate vengono completamente sostituite con le informazioni inviate nel corpo della richiesta. Se si omettono le proprietà dall'oggetto JSON, ad esempio, se la proprietà dei gruppi non è inclusa nel corpo, l'utente verrà rimosso da tutti i gruppi.
• Unire le proprietà aggiornate con le informazioni utente memorizzate. Ad esempio, per modificare il numero di telefono e aggiungere l'utente al gruppo Operatori, ma mantenere invariate tutte le altre informazioni utente, utilizzare la seguente chiamata API REST:

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

Ad esempio, per eliminare John Smith dalla sottoscrizione, utilizzare la chiamata seguente:

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