Endpunkte für die Bulk-Nutzerverwaltung

Mit den Bulk Management API-Endpunkten können Sie eine große Anzahl von Nutzern über die Sammlung für die Bulk-Nutzerverwaltung erstellen oder aktualisieren.

Die API unterstützt die Verwendung von JSON-Dateien. Sie können JSON-Daten über die Vorlagen-API abrufen.

Es wird nur die api_user-Authentifizierung unterstützt. Sie müssen das API-Nutzer-Token in die Passwortvariable eingeben. Die ältere Authentifizierung mit einem Unternehmensgeheimnis wird nicht unterstützt.

Wenn eine JSON-Datei über die Upload API hochgeladen wird, wird ein Job erstellt, der das Schema der JSON-Datei validiert.

Die für die Massenverwaltung von Nutzern unterstützten Endpunkte umfassen Folgendes:

So fügen Sie Nutzer in großen Mengen hinzu oder aktualisieren sie in großen Mengen mithilfe der Bulk User API:

  1. Rufen Sie die Methode Template auf, um das JSON-Vorlagenobjekt abzurufen, mit dem Sie die JSON-Datei generieren.

  2. Rufen Sie entweder die Methode Bulk add users from file (Nutzer per Datei im Bulk hinzufügen) oder die Methode Bulk update users from file (Nutzer per Datei im Bulk aktualisieren) auf, je nachdem, ob Sie Nutzer im Bulk hinzufügen oder aktualisieren möchten. Dadurch wird das Schema der von Ihnen bereitgestellten JSON-Datei überprüft.

  3. Rufen Sie nach der Überprüfung des JSON-Dateischemas die Methode Proceed auf. Dadurch wird der Job gestartet.

  4. Rufen Sie die Methode Jobs auf, um den Status des Jobs zu ermitteln.

JSON-Dateiformat

Sie können das JSON-Dateiformat abrufen, indem Sie die Vorlagenmethode aufrufen.

Name des Felds/der Felder Werte Erforderlich Validierung
E-Mail String(Email) Ja Muss eine gültige E-Mail-Adresse sein. Muss innerhalb der Datei in der Spalte „E-Mail“ eindeutig sein (keine Duplikate). Es ist also nur eine Aktualisierung pro E-Mail-Adresse und Datei möglich.
new_email String(Email) Nein Muss eine gültige E-Mail-Adresse sein. Muss in der Spalte „Neue E‑Mail-Adresse“ in der Datei eindeutig sein (keine Duplikate), also nur eine Aktualisierung pro E‑Mail-Adresse und Datei.
agent_number String Nein Ein String ohne Validierung
first_name String Ja Nicht leerer String
last_name String Ja Nicht leerer String
Status Aktiv, Inaktiv, Leer Nein Muss „Aktiv“, „Inaktiv“ oder leer sein
Standort Ein String, der einen Ortsnamen darstellt, leer oder null Nein Muss genau mit einem der vorhandenen Standorte übereinstimmen (ohne Berücksichtigung der Groß-/Kleinschreibung) oder „Null“ oder leer sein.
max_chat_limit 1 bis X (wobei X der konfigurierte Wert ist), leer Nein Muss zwischen 1 und X (einschließlich) liegen oder leer sein
max_chat_limit_enabled 0, 1, Leer Nein Muss 0, 1 oder leer sein
Rollen Name: Rollenname / Wert: 0, 1, leer Nein Muss 0, 1 oder leer sein
benutzerdefinierter Anrufgruppen name: Team name / value: 0, 1, Empty Nein Muss 0, 1 oder leer sein

Sobald die API-Methode zum Hochladen von JSON-Dateien erfolgreich ausgeführt wurde, kann die Proceed API-Methode aufgerufen werden. Die Erstellung oder Änderung von Nutzern wird dann verarbeitet.

Die Methoden „upload“ und „proceed“ werden asynchron von der Contact Center AI Platform (CCAI Platform) ausgeführt. Sie können den Status prüfen, indem Sie die Methode jobs aufrufen und job_id angeben.

Statusfeld

Das Feld „job“ status kann einen der folgenden Werte haben:

Jobstatus Beschreibung
erstellt Ein Job wird erstellt und wartet auf die Validierung.
valid_scheme Die Schemavalidierung war erfolgreich und die Fortsetzung ist möglich.
invalid_scheme Fehler bei der Schemavalidierung. Detaillierte Informationen können über die Scheme Error Log API abgerufen werden.
in_progress Mehrere Nutzer gleichzeitig aktualisieren oder erstellen.
finished Bulk-Update/Bulk-Erstellung von Nutzern abgeschlossen.

Vorlage

Endpunkt:

Method: GET
Type: 
URL: https://{​subdomain}​.{​domain​}/apps/api/v1/bulk/users/template

Beispielanfrage und -antworten

In den folgenden Abschnitten finden Sie Beispielanfragen an den Endpunkt.

Vorlage abrufen

In diesem Beispiel wird gezeigt, wie die Vorlagen abgerufen werden.

Anfrage

Body: None

Antwort: Vorlage
[
    {
        "email": "user1@somedomain.com",
        "new_email": "user1@somedomain.com",
        "agent_number": "A-001",
        "first_name": "James",
        "last_name": "Bond",
        "status": "Active",
        "location": "Mexico",
        "max_chat_limit": "2",
        "max_chat_limit_enabled": "0",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user2@somedomain.com",
        "new_email": "user3@somedomain.com",
        "agent_number": "A-002",
        "first_name": "John",
        "last_name": "Doe",
        "status": "Inactive",
        "location": "",
        "max_chat_limit": "",
        "max_chat_limit_enabled": "1",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user3@somedomain.com",
        "new_email": "user2@somedomain.com",
        "agent_number": "A-003",
        "first_name": "Jane",
        "last_name": "Doe",
        "status": "",
        "location": "null",
        "max_chat_limit": "1",
        "max_chat_limit_enabled": "",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    }
]

Statuscode:200

Jobs

Endpunkt:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/{job_id}​

Beispielanfrage und -antworten

In den folgenden Abschnitten finden Sie Beispielanfragen an den Endpunkt.

Jobdetail

In diesem Beispiel wird gezeigt, wie Sie die Jobdetails für einen bestimmten Job abrufen. In diesem Beispiel lautet die Job-ID 1.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type application/json

Suchanfrage

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Antwort: Jobdetail
{
    "id": 1,
    "created_at": "2022-01-07T06:06:45.000Z",
    "process_requested_at": null,
    "filename": "100row.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Statuscode:200

Jobliste

In diesem Beispiel wird gezeigt, wie alle Jobs abgerufen werden.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type application/json

Suchanfrage

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
Antwort: Jobliste
[
    {
        "id": 3,
        "created_at": "2022-01-07T06:21:10.000Z",
        "process_requested_at": "2022-01-07T06:22:25.000Z",
        "filename": "100row_new.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "in_progress",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": "zdco_admin",
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 2,
        "created_at": "2022-01-07T06:17:09.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 1,
        "created_at": "2022-01-07T06:06:45.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    }
]

Statuscode:200

Job erstellt

In diesem Beispiel wird gezeigt, wie Sie die erstellten Bulk-Nutzeranfragejobs abrufen.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type application/json

Suchanfrage

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Antwort: Job erstellt
{
    "id": 1,
    "created_at": "2022-01-07T06:39:59.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Statuscode:200

Jobvalidierung erfolgreich

In diesem Beispiel wird gezeigt, wie Sie prüfen, ob ein Job erfolgreich war.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type application/json

Suchanfrage

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Antwort: Jobvalidierung erfolgreich
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "valid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Statuscode:200

Jobvalidierung fehlgeschlagen

In diesem Beispiel wird gezeigt, wie Sie feststellen, dass ein Job fehlgeschlagen ist.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type application/json

Suchanfrage

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Antwort: Jobvalidierung fehlgeschlagen
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "invalid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [
        "scheme error detail 1",
        "scheme error detail 2",
        "scheme error detail 3"
    ],
    "update_errors": []
}

Statuscode:200

Job aktualisieren

In diesem Beispiel wird gezeigt, wie Sie ermitteln, ob ein Job aktualisiert wird.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type application/json

Suchanfrage

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Antwort: Job wird aktualisiert
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 52,
    "failed_rows": 0,
    "status": "in_progress",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

Statuscode:200

Job-Update ohne Fehler abgeschlossen

In diesem Beispiel wird gezeigt, wie Sie einen Job identifizieren, der ohne Fehler abgeschlossen wurde.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type application/json

Suchanfrage

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Antwort: Job-Update ohne Fehler abgeschlossen
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

Statuscode:200

Job-Update mit Fehlern abgeschlossen

In diesem Beispiel wird gezeigt, wie Sie einen Job identifizieren, der mit Fehlern abgeschlossen wurde.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type application/json

Suchanfrage

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Antwort: Job-Update mit Fehlern abgeschlossen
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": [
        "update error detail 1",
        "update error detail 2",
        "update error detail 3"
    ]
}

Statuscode:200

Fehler: Ungültige Job-ID

In diesem Beispiel wird eine Fehleranfrage mit einer ungültigen Job-ID gezeigt.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type application/json

Suchanfrage

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Antwort: Fehler: Ungültige Job-ID
{
    "message": "Not Found"
}

Statuscode:404

Nutzer per Datei hinzufügen und bearbeiten

Überschriften:

Schlüssel Wert Beschreibung
Content-Type multipart/form-data

Endpunkt:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/upload

Text:

Schlüssel Wert Beschreibung
Datei

Beispielanfrage und -antworten

In den folgenden Abschnitten finden Sie Beispielanfragen an den Endpunkt.

Job erstellt

In diesem Beispiel wird gezeigt, wie ein Job gesendet wird.

Anfrage

Text:

Schlüssel Wert Beschreibung
Datei
Antwort: Job erstellt
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Statuscode:200

Fortfahren

Dieser API-Endpunkt wird verwendet, um einen gestarteten ipport-Job fortzusetzen.

Endpunkt:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/proceed

Überschriften:

Schlüssel Wert Beschreibung
Content-Type multipart/form-data

Text:

Schlüssel Wert Beschreibung
id `[job_id}`

Beispielanfrage und -antworten

In den folgenden Abschnitten finden Sie Beispielanfragen an den Endpunkt.

Vorgang erfolgreich

In diesem Beispiel wird ein erfolgreicher Jobvorgang gezeigt.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type multipart/form-data

Suchanfrage

Schlüssel Wert Beschreibung
id `[job_id}`
Antwort: Proceed success
{
    "id": 1,
    "status": "valid_scheme",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Statuscode:200

Fehler: Vor der Validierung fortfahren

In diesem Beispiel wird gezeigt, wie Sie vorgehen, bevor die Validierung abgeschlossen ist.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type multipart/form-data

Suchanfrage

Schlüssel Wert Beschreibung
id `[job_id}`
Antwort: Fehler: Vor der Validierung fortfahren
{
    "message": "This job cannot proceed update. status: created"
}

Statuscode:400

Fehler: „Fortfahren, wenn in Bearbeitung“

In diesem Beispiel wird gezeigt, wie vorgegangen wird, wenn der Job bereits in Bearbeitung ist.

Anfrage

Überschriften:

Schlüssel Wert Beschreibung
Content-Type multipart/form-data

Suchanfrage

Schlüssel Wert Beschreibung
id `[job_id}`
Antwort: Fehler: Fortfahren, wenn in Bearbeitung
{
    "message": "Update is already in progress."
}

Statuscode:400

Schemafehler

Endpunkt:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/scheme/​{job_id}​

Beispielanfrage und -antworten

In den folgenden Abschnitten finden Sie Beispielanfragen an den Endpunkt.

Schemafehler

In diesem Beispiel wird gezeigt, wie Sie die Schemafehler abrufen.

Anfrage

Body: None

Antwort: Schemfehler
[
    {
        "message": "scheme error message 1",
        "column": null,
        "row": 1
    },
    {
        "message": "scheme error message 2",
        "column": null,
        "row": 2
    }
]

Statuscode:200

Keine Fehler

In diesem Beispiel wird gezeigt, wie Sie die Schemafehler abrufen, wenn keine Fehler vorhanden sind.

Anfrage

Body: None

Antwort: Keine Fehler
[]

Statuscode:200

Fehler beim Aktualisieren

Endpunkt:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/update/{job_id}​

Beispielanfrage und -antworten

In den folgenden Abschnitten finden Sie Beispielanfragen an den Endpunkt.

Fehler beim Aktualisieren

In diesem Beispiel wird gezeigt, wie Sie die Schemafehler mit den Aktualisierungsfehlern abrufen.

Anfrage

Body: None

Antwort: Fehler beim Aktualisieren
[
    {
        "message": "update error message 1",
        "column": 1,
        "row": 1,
        "error_type": "error"
    },
    {
        "message": "update error message 2",
        "column": null,
        "row": 2,
        "error_type": "error"
    },
    {
        "message": "update warning message 1",
        "column": 3,
        "row": 3,
        "error_type": "warning"
    },
    {
        "message": "update warning message 2",
        "column": null,
        "row": 4,
        "error_type": "warning"
    }
]

Statuscode:200

Keine Fehler

In diesem Beispiel wird gezeigt, wie Sie die Schemafehler abrufen, wenn keine Fehler vorhanden sind.

Anfrage

Body: None

Antwort: Keine Fehler
[]

Statuscode:200