Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Nutzerkonfigurationsdaten abrufen

Die Apps API wurde entwickelt, um Nutzerkonfigurationsdaten abzurufen. Sie können die aktuelle Nutzerkonfiguration für alle Nutzer oder für einen einzelnen Nutzer lesen, unabhängig von ihrer Rolle oder ihrem Status. Sowohl System- als auch benutzerdefinierte Rollen sind in dieser Ausgabe enthalten.

Dieser Endpunkt unterscheidet sich von den Endpunkten, die beim Bulk-Nutzer-Upload verwendet werden, und bietet die erforderlichen Informationen zur Unterstützung von Bulk-Vorgängen. Weitere Informationen zum Ausführen von Bulk-Nutzerverwaltungsvorgängen finden Sie unter Bulk User Management API.

API-Funktionen und -Beschränkungen

Beim Abrufen von Nutzerdaten können Sie Parameter einbeziehen, um die API-Antwort an Ihre Bedürfnisse anzupassen. Die folgenden Parameter werden unterstützt:

Bestimmte Nutzer
- ID-Optionen: E-Mail-Adresse, System-ID oder benutzerdefinierte Nutzer-ID. Nutzer können eine oder mehrere IDs angeben. Wenn mehrere Nutzer-IDs auf denselben Nutzer verweisen, sollte dieser Nutzer in der Antwort nur einmal dargestellt werden.
Seitenumbruch
- Nutzer können Ergebnisse in paginierten Sätzen abrufen, um große Datensätze zu verwalten. Die API-Antwort sollte angeben, ob weitere Seiten abgerufen werden können.
- Mit einem API-Parameter können Nutzer eine bestimmte Seite mit Ergebnissen anfordern.
- Nutzer können die Seitengröße angeben. Die Standardseitengröße ist 100 und die maximale Seitengröße ist 1.000. Wenn eine bestimmte Seitenzahl angegeben wird, können keine Nutzer-IDs in die Anfrage aufgenommen werden.

Die API-Antwort enthält alle Felder für Nutzerprofil und Konfiguration, mit Ausnahme des Felds „Status“. Statt des Felds „Status“ stellt die API das Feld deactivated_at bereit. Dieses Feld enthält:

Keinen Wert für aktive Nutzer.
Das Datum und die Uhrzeit, zu der ein Nutzer deaktiviert wurde.

In der folgenden Tabelle sind die Felder des Nutzerprofils aufgeführt, die in der API-Antwort enthalten sind:

Tabelle 1. Tabelle der Felder des Nutzerprofils

Order	Spaltentyp	Anzahl der Spalten	Spaltenname(n)	Zulässige Werte
1	E-Mail	1	E-Mail	E-Mail
2	Agent-ID	1	Agent-ID	String
3	Vorname	1	Vorname	String
4	Nachname	1	Nachname	String
5	Alias	1	Alias	String
6	Deaktiviert am	1	Deaktiviert am	Kein Wert, Datum/Uhrzeit
7	Standort	1	Standort	Ein String, der ein Standortname ist, leer (keine Änderung), null (aktuellen Standort entfernen).
8	Gleichzeitige Chats	1	Gleichzeitige Chats	1 bis X (wobei X der konfigurierte Wert ist), leer
9	Status der gleichzeitigen Chats	1	Status der gleichzeitigen Chats	0, 1, leer
10	Nicht eingeschränkte internationale Anrufe	1	Nicht eingeschränkte internationale Anrufe	(True/False)
11	Externer Nutzer	1	Externer Nutzer	(Ja/Nein)
12	Externer SIP-URI	1	Externer SIP-URI	String
13	UCaaS-Nutzername	1	UCaaS-Nutzername	String
14	Agent-Erweiterungen	1	Agent-Erweiterungen
15	Rollen	Mehrere	Rolle: Rollenname A Rolle: Rollenname B Rolle: Rollenname C usw.	0, 1, leer
16	Team	Mehrere	Team: Teamname A, Team: Teamname B, Team: Teamname C usw.	0, 1, leer
17	Telefonnummer	Mehrere	Direkte Durchwahlnummer: 1, Direkte Durchwahlnummer: 2, Direkte Durchwahlnummer: 3	Telefonnummer in E. 164-Format
18	Filter	Einzelner	Filter	String
19	Filter-Timeout	Einzelner	Filter-Timeout	Numerischer Wert zwischen 0 und 1.440

Beschränkungen

Pro Anfrage wird nur ein Typ von Nutzer-ID unterstützt.
Die maximale Anzahl von IDs pro API-Anfrage beträgt 1.000.
Nutzer können in einer einzigen API-Anfrage nicht sowohl Nutzer-IDs als auch eine Seitenzahlanfrage angeben. Die API gibt alle Nutzer basierend auf der Anfrage zurück, bis zu 1.000.

API-Fehlermeldungen

Die API gibt für bestimmte Szenarien die folgenden Fehlermeldungen aus:

Seitengröße: "Exceeded maximum page size request (1,000 is the maximum)" (Maximale Seitengröße überschritten (maximal 1.000))
Seitengröße (Anforderung für numerische Eingabe): "Invalid page size request; must be a numeric value" (Ungültige Seitengrößenanfrage; muss ein numerischer Wert sein)
Kombinierte Nutzer-ID- und Paginierungsanfrage: "Combination of user ID and pagination request is not supported" (Kombination aus Nutzer-ID- und Paginierungsanfrage wird nicht unterstützt)
Nutzer-ID (überschritten): "Exceeded maximum number of user IDs (1,000 is the maximum)" (Maximale Anzahl von Nutzer-IDs überschritten (maximal 1.000))

Beispiel für Anfrage und Antwort

In diesem Beispiel wird gezeigt, wie die erste Seite der Nutzer mit 100 Nutzern pro Seite abgerufen wird. Der Antworttext enthält ein Array von Nutzerobjekten, die jeweils detaillierte Nutzerkonfigurationsdaten enthalten.

Anfrage

Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/users?page=1&per_page=100

Antwort

[
  {
    "email": "email",
    "agent_number": "number",
    "first_name": "first",
    "last_name": "last",
    "status": "Active",
    "location": "location",
    "max_chat_limt": 3,
    "max_chat_limit_enabled": true,
    "deleted_at": "2024-07-16T15:57:12.000Z",
    "ucaas_user_name": "username",
    "external_user": true,
    "ucaas_sip_uri": "sip uri",
    "unrestricted_international_calling": false,
    "roles": [
      { "name": "Admin" },
      { "name": "Manager" }
    ],
    "teams": [
      { "name": "name" }
    ],
    "phone_numbers": [
      "123-456-7890",
      "098-765-4321"
    ]
  },
  ...
]

In diesem Beispiel wird gezeigt, wie die Details eines einzelnen Nutzers abgerufen werden, indem ein E-Mail-Parameter übergeben wird. Der Antworttext enthält ein Nutzerobjekt mit detaillierten Nutzerkonfigurationsdaten.