API per la gestione collettiva degli utenti

L'API Bulk User Management ti consente di utilizzare i contenuti di un file JSON per creare o modificare più utenti in un'unica operazione.

Non esiste un limite al numero di record che possono essere caricati, ma è consigliabile eseguire le richieste in batch più piccoli.

Questa procedura può essere eseguita anche nel portale CCAI Platform seguendo le istruzioni riportate in Gestione collettiva degli utenti.

L'applicazione di riferimento Bulk User Sync Tool viene fornita per eseguire una sincronizzazione degli utenti tra una directory come i gruppi Google Workspace o Microsoft Entra ID e CCaaS. Questa applicazione di riferimento utilizza l'API di gestione collettiva degli utenti.

Ruoli e autorizzazioni

  • Utilizza l'API Apps creando un utente API.

  • L'utente API non dispone di ruoli e autorizzazioni, pertanto tutti gli utenti API possono eseguire bulk_user management.

  • Non puoi impostare autorizzazioni granulari quando utilizzi api_user, quindi api_user avrà accesso a tutti i campi utente.

Aggiungere una credenziale API

  1. Nel portale della piattaforma CCAI, vai a Impostazioni > Impostazioni sviluppatore > Gestione delle credenziali API.

  2. Fai clic su + Aggiungi credenziale API. Viene visualizzato un messaggio Aggiungi credenziale API.

  3. Inserisci un nome per la credenziale.

  4. Fai clic su Crea.

Utilizzare l'API di gestione collettiva degli utenti

L'utilizzo dell'API di gestione collettiva degli utenti richiede due chiamate API. Uno carica il file JSON e crea il job, l'altro lo elabora. Puoi anche utilizzare chiamate API facoltative per assicurarti che il job venga elaborato correttamente.

  1. (Facoltativo) Recupera il modello JSON. In questo modo viene recuperato il modello più recente, che include eventuali ruoli o team aggiuntivi creati dopo il recupero del modello precedente. Google consiglia questo passaggio.

  2. (Facoltativo) Recupera i dati di configurazione dell'utente. Viene recuperato un elenco di tutti gli utenti (o di un singolo utente, se specifichi un indirizzo email) da duplicare.

  3. Carica il file JSON. Puoi aggiungere o aggiornare uno o più utenti nel file. Assicurati di annotare l'ID job.

  4. Elaborazione della richiesta del file JSON. Viene avviato il job collettivo.

  5. (Facoltativo) Controlla lo stato. Fornisci l'ID job per esaminare lo stato di elaborazione.

  6. (Facoltativo) Recupera un elenco di job aggiornato. Viene recuperato l'elenco di tutti i job di gestione utenti collettiva.

  7. (Facoltativo) Recupera i log degli errori dello schema. Specifica l'ID job per ottenere i log degli errori dello schema.

  8. (Facoltativo) Recupera errori. Visualizzare gli errori.

Carica il file JSON

Utilizzo

Carica il file JSON

URL

apps/api/v1/bulk/users/upload

Metodo

POST / PUT

Richiesta

content-type: multipart/form-data

{
  "id" : {job_id} #optional. Required in case of PUT method.
  "file": {json file}
}

Risposta

Intestazione:

Link: http://ujet.co/apps/api/v1/bulk/users_jobs/12345

Corpo

{
  "id": 12345, # job_id
  "status": "created"
  "link": "http://ujet.co/apps/api/v1/bulk/users_jobs/12345"
}

Recupera modello JSON

Utilizzo

Modello

URL

apps/api/v1/bulk/users/template

Metodo

GET

Richiesta

(Vuoto)

Risposta

 
[
{
"email":"user1@yourcompany.co",
"new_email":user1@yourcompany.cx",
"agent_number":"A-001",
"first_name":"John",
"last_name":"aa",
"status":"Active",
"location":"Mexico",
"max_chat_limit":2,
"max_chat_limit_enabled":0,
"roles": [
{"name":"Admin","value": 0 },
{"name":"Manager","value": 1 },
{"name":"Agent","value": 0 },
{"name":Developer","value": 1 }
]
},
 ...
]

Disattivare un utente

Per disattivare un utente, modifica il valore di status in Inactive, ad esempio "status":"Inactive".

Richiedi l'elaborazione del file JSON corrente

Utilizzo

Richiedi l'elaborazione del file JSON corrente

URL

/v1/bulk/users/proceed

Metodo

POST

Richiesta

 
{
   "id": 12345  # job_id
}

Risposta

Intestazione:

Link: http://ujet.co/apps/api/v1/bulk/users_jobs/12345

Corpo

1{"id": 12345 # job_id3 "status": "valid_scheme",4 "link": "http://ujet.co/apps/api/v1/bulk/users_jobs/12345"5}

Ottenere un controllo dello stato

Utilizzo

Ottenere un controllo dello stato

URL

apps/api/v1/bulk/users/jobs/#{job_id}

Metodo

GET

Richiesta

Variabile di percorso - job_id

Risposta

 
{
    "id": 12345,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:45:34.000Z",
    "filename": "100row.json",
    "total_rows": 100,
    "affected_rows": 52,
    "failed_rows": 0,
    "status": "in_progress",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "api_user_name_1",
    "proceed_api_user_name": "api_user_name_2",
    "scheme_errors": []
    "update_errors": []
}

Recuperare l'elenco dei job aggiornato

Utilizzo

Recupera l'elenco dei job di aggiornamento

URL

apps/api/v1/bulk/users/jobs

Metodo

GET

Richiesta

 
{
  "page": 1,
  "per_page": 20
}

Risposta

Intestazione

Link: <next link>
Total: 12345
Per-Page: 201

Corpo

[
    {
        "id": 12345,
        "created_at": "2022-01-07T06:21:10.000Z",
        "process_requested_at": "2022-01-07T06:22:25.000Z",
        "filename": "100row.json",
        "total_rows": 100,
        "affected_rows": 52,
        "failed_rows": 0,
        "status": "in_progress",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "api_user_name_1",
        "proceed_api_user_name": "api_user_name_2",
        "scheme_errors": [],
        "update_errors": []
    },
    ...
]

Nota

L'output è ordinato in ordine inverso di job_id, in modo che i dati più recenti vengano visualizzati per primi.

Recuperare i log degli errori dello schema

Utilizzo

Recuperare i log degli errori dello schema

URL

/v1/bulk/users/errors/scheme/#{job_id}

Metodo

GET

Richiesta

Variabile di percorso - job_id

Risposta

content-type: application/json

[
  {
    "message": "Must be a valid email",
    "column": 1,
    "row": null
  },
  {
    "message": "Non-empty string",
    "column": 10,
    "row": 10
  }
]

Recuperare gli errori

Utilizzo

Recuperare i log degli errori di aggiornamento

URL

/v1/bulk/users/errors/update/#{job_id}

Metodo

GET

Richiesta

Variabile di percorso - job_id

Risposta

content-type: application/json

1[2 {3 "message": "Must be a valid email",4 "column": 1,5 "row": null,6 "error_type": "warning"7 },8 {9 "message": "Non-empty string",10 "column": 10,11 "row": 10,12 "error_type": "error"13 } 14]