API de gestion globale des utilisateurs

L'API Bulk User Management vous permet d'utiliser le contenu d'un fichier JSON pour créer ou modifier plusieurs utilisateurs en une seule opération.

Vous pouvez importer un nombre illimité d'enregistrements, mais nous vous recommandons d'effectuer les requêtes par petits lots.

Vous pouvez également effectuer ce processus dans le portail CCAI Platform en suivant les instructions de la section Gestion groupée des utilisateurs.

L'application de référence Bulk User Sync Tool est fournie. Elle permet de synchroniser les utilisateurs entre un annuaire tel que les groupes Google Workspace ou Microsoft Entra ID et CCaaS. Cette application de référence exploite l'API Bulk User Management.

Rôles et autorisations

  • Utilisez l'API Apps en créant un api_user.

  • L'api_user ne dispose pas de rôles ni d'autorisations. Par conséquent, tous les api_users peuvent effectuer la bulk_user management.

  • Vous ne pouvez pas définir d'autorisations précises lorsque vous utilisez un api_user. Par conséquent, l'api_user aura accès à tous les champs utilisateur.

Ajouter des identifiants d'API

  1. Dans le portail CCAI Platform, accédez à Settings > Developer Settings > API Credential management (Paramètres > Paramètres du développeur > Gestion des identifiants d'API).

  2. Cliquez sur + Add API Credential (+ Ajouter des identifiants d'API). Un message Add API Credential (Ajouter des identifiants d'API) s'ouvre.

  3. Saisissez un Name (Nom) pour les identifiants.

  4. Cliquez sur Create (Créer).

Utiliser l'API Bulk User Management

L'utilisation de l'API Bulk User Management nécessite deux appels d'API. L'un importe le fichier JSON et crée la tâche, et l'autre la traite. Vous pouvez également utiliser des appels d'API facultatifs pour vous assurer que votre tâche est traitée correctement.

  1. Facultatif : Récupérez le modèle JSON. Cette opération récupère le dernier modèle, qui inclut tous les rôles ou équipes supplémentaires créés depuis que vous avez récupéré le modèle précédent. Google recommande cette étape.

  2. Facultatif : Obtenez les données de configuration de l'utilisateur. Cette opération récupère une liste de tous les utilisateurs (ou d'un seul utilisateur, si vous spécifiez une adresse e-mail) à dupliquer.

  3. Importez le fichier JSON. Vous pouvez ajouter ou modifier un ou plusieurs utilisateurs dans le fichier. Veillez à noter l'ID de la tâche.

  4. Demandez le traitement du fichier JSON. Cette opération démarre la tâche groupée.

  5. Facultatif : Vérifiez l'état. Fournissez l'ID de la tâche pour consulter l'état du traitement.

  6. Facultatif : Récupérez une liste de tâches mise à jour. Cette opération récupère la liste de toutes les tâches de gestion groupée des utilisateurs.

  7. Facultatif : Récupérez les journaux d'erreurs de schéma. Spécifiez l'ID de la tâche pour obtenir les journaux d'erreurs de schéma.

  8. Facultatif : Récupérez les erreurs. Obtenez les erreurs.

Importer le fichier JSON

Utilisation

Importer le fichier JSON

URL

apps/api/v1/bulk/users/upload

Méthode

POST / PUT

Requête

content-type: multipart/form-data

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

Réponse

En-tête :

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

Body

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

Récupérer le modèle JSON

Utilisation

Modèle

URL

apps/api/v1/bulk/users/template

Méthode

GET

Requête

(Vide)

Réponse

 
[
{
"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 }
]
},
 ...
]

Désactiver un utilisateur

Pour désactiver un utilisateur, remplacez la valeur status par Inactive (Inactif), par exemple "status":"Inactive".

Demander le traitement du fichier JSON actuel

Utilisation

Demander le traitement du fichier JSON actuel

URL

/v1/bulk/users/proceed

Méthode

POST

Requête

 
{
   "id": 12345  # job_id
}

Réponse

En-tête :

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

Body

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

Vérifier l'état

Utilisation

Vérifier l'état

URL

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

Méthode

GET

Requête

Variable de chemin d'accès : job_id

Réponse

 
{
    "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": []
}

Récupérer la liste de tâches mise à jour

Utilisation

Récupérer la liste de tâches mise à jour

URL

apps/api/v1/bulk/users/jobs

Méthode

GET

Requête

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

Réponse

En-tête

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

Body

[
    {
        "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": []
    },
    ...
]

Remarque

La sortie est triée par ordre inverse de job_id, de sorte que les données les plus récentes apparaissent en premier.

Récupérer les journaux d'erreurs de schéma

Utilisation

Récupérer les journaux d'erreurs de schéma

URL

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

Méthode

GET

Requête

Variable de chemin d'accès : job_id

Réponse

content-type: application/json

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

Récupérer les erreurs

Utilisation

Récupérer les journaux d'erreurs de mise à jour

URL

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

Méthode

GET

Requête

Variable de chemin d'accès : job_id

Réponse

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]