Bulk User Management API

Mit der Bulk User Management API können Sie den Inhalt einer JSON-Datei verwenden, um mehrere Nutzer in einem Vorgang zu erstellen oder zu ändern.

Die Anzahl der Datensätze, die hochgeladen werden können, ist nicht begrenzt. Es wird jedoch empfohlen, Anfragen in kleineren Batches auszuführen.

Dieser Vorgang kann auch im CCAI Platform-Portal ausgeführt werden. Folgen Sie dazu der Anleitung unter Bulk User Management.

Die Referenzanwendung für das Bulk User Sync Tool führt eine Synchronisierung von Nutzern zwischen einem Verzeichnis wie Google Workspace-Gruppen oder Microsoft Entra ID und CCaaS durch. Diese Referenzanwendung nutzt die Bulk User Management API.

Rollen und Berechtigungen

• Erstellen Sie einen api_user, um die Apps API zu verwenden.

• Der api_user hat keine Rollen und Berechtigungen, daher können alle api_user die bulk_user management ausführen.

• Sie können keine detaillierten Berechtigungen festlegen, wenn Sie einen api_user verwenden. Daher hat der api_user Zugriff auf alle Nutzerfelder.

API-Anmeldedaten hinzufügen

1. Rufen Sie im CCAI Platform-Portal Einstellungen > Entwicklereinstellungen > API-Anmeldedatenverwaltung auf.

2. Klicken Sie auf + API-Anmeldedaten hinzufügen. Die Meldung API-Anmeldedaten hinzufügen wird geöffnet.

3. Geben Sie einen Namen für die Anmeldedaten ein.

4. Klicken Sie auf Erstellen.

Bulk User Management API verwenden

Für die Verwendung der Bulk User Management API sind zwei API-Aufrufe erforderlich. Mit dem einen wird die JSON-Datei hochgeladen und der Job erstellt, mit dem anderen wird sie verarbeitet. Sie können auch optionale API-Aufrufe verwenden, um sicherzustellen, dass Ihr Job korrekt verarbeitet wird.

1. Optional: Rufen Sie die JSON-Vorlage ab. Dadurch wird die neueste Vorlage abgerufen, die alle zusätzlichen Rollen oder Teams enthält, die seit dem Abrufen der vorherigen Vorlage erstellt wurden. Google empfiehlt diesen Schritt.

2. Optional: Rufen Sie die Nutzerkonfigurationsdaten ab. Dadurch wird eine Liste aller Nutzer (oder eines einzelnen Nutzers, wenn Sie eine E-Mail-Adresse angeben) abgerufen, die gespiegelt werden sollen.

3. Laden Sie die JSON-Datei hoch. Sie können in der Datei einen oder mehrere Nutzer hinzufügen oder aktualisieren. Notieren Sie sich die Job-ID.

4. Fordern Sie die Verarbeitung der JSON-Datei an. Dadurch wird der Bulk-Job gestartet.

5. Optional: Führen Sie eine Statusprüfung durch. Geben Sie die Job-ID an, um den Verarbeitungsstatus zu prüfen.

6. Optional: Rufen Sie eine aktualisierte Jobliste ab. Dadurch wird die Liste aller Bulk User Management-Jobs abgerufen.

7. Optional: Rufen Sie Protokolle mit Schemfehlern ab. Geben Sie die Job-ID an, um die Protokolle mit Schemfehlern abzurufen.

8. Optional: Rufen Sie Fehler ab. Fehler abrufen.

JSON-Datei hochladen

Nutzung	JSON-Datei hochladen
URL	apps/api/v1/bulk/users/upload
Methode	POST / PUT
Anfrage	content-type: multipart/form-data { "id" : {job_id} #optional. Required in case of PUT method. "file": {json file} }
Antwort	Header: Link: http://ujet.co/apps/api/v1/bulk/users_jobs/12345 Text { "id": 12345, # job_id "status": "created" "link": "http://ujet.co/apps/api/v1/bulk/users_jobs/12345" }

JSON-Vorlage abrufen

Nutzung	Vorlage
URL	apps/api/v1/bulk/users/template
Methode	GET
Anfrage	(Leer)
Antwort	[ { "email":"[e-mail]", "new_email":[e-mail]", "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 } ] }, ... ]

Nutzer deaktivieren

Wenn Sie einen Nutzer deaktivieren möchten, ändern Sie den status Wert in Inactive, z. B. "status":"Inactive".

Verarbeitung der aktuellen JSON-Datei anfordern

Nutzung	Verarbeitung der aktuellen JSON-Datei anfordern
URL	/v1/bulk/users/proceed
Methode	POST
Anfrage	{ "id": 12345 # job_id }
Antwort	Header: Link: http://ujet.co/apps/api/v1/bulk/users_jobs/12345 Text 1{"id": 12345 # job_id3 "status": "valid_scheme",4 "link": "http://ujet.co/apps/api/v1/bulk/users_jobs/12345"5}

Statusprüfung durchführen

Nutzung	Statusprüfung durchführen
URL	apps/api/v1/bulk/users/jobs/#{job_id}
Methode	GET
Anfrage	Pfadvariable: job_id
Antwort	{ "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": [] }

Aktualisierte Jobliste abrufen

Nutzung	Aktualisierte Jobliste abrufen
URL	apps/api/v1/bulk/users/jobs
Methode	GET
Anfrage	{ "page": 1, "per_page": 20 }
Antwort	Header Link: <next link> Total: 12345 Per-Page: 201 Text [ { "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": [] }, ... ]
Community-Anmerkung	Die Ausgabe ist in umgekehrter Reihenfolge der Job-ID sortiert, sodass die neuesten Daten zuerst angezeigt werden.

Protokolle mit Schemfehlern abrufen

Nutzung	Protokolle mit Schemfehlern abrufen
URL	/v1/bulk/users/errors/scheme/#{job_id}
Methode	GET
Anfrage	Pfadvariable: job_id
Antwort	content-type: application/json [ { "message": "Must be a valid email", "column": 1, "row": null }, { "message": "Non-empty string", "column": 10, "row": 10 } ]

Fehler abrufen

Nutzung	Fehlerprotokolle abrufen
URL	/v1/bulk/users/errors/update/#{job_id}
Methode	GET
Anfrage	Pfadvariable: job_id
Antwort	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]