APIs und Skripte

Sie können in Ihren Studio-Skripten eine Verbindung mit Webdiensten herstellen, die SOAP- oder RESTful-API-Standards verwenden.

Unterstützte Optionen

Studio unterstützt die folgenden Methoden für die Verbindung mit Webdiensten:

Optionen	Details
REST API Studio-Aktion	Mithilfe der REST API Studio -Aktion können Sie in Ihren Skripten RESTful-API-Aufrufe tätigen. Diese Methode: Kann höhere Lasten als RESTful-Aufrufe in einer SNIPPET-Aktion verarbeiten, insbesondere bei umfangreichen Datenmengen. Ist die bevorzugte Methode für API-Aufrufe in Skripten. Muss verwendet werden, wenn Ihre Aufrufe JSON enthalten.
CXone API Studio-Aktionen	Studio bietet zahlreiche API-Aktionen, mit denen Sie in Ihren Skripten Aufrufe an CXone-APIs tätigen können. Nicht jede CXone-API ist als Aktion verfügbar, aber wenn eine Aktion verfügbar ist, sollten Sie sie anstelle von anderen Methoden verwenden. Sie finden die API-Aktionen im Bereich „API“ der Registerkarte „Framework“ in Desktop Studio und auf der Palette „API-Aktionen“ in CXone Studio.
SNIPPET-Aktionen	Sie können in einer SNIPPET-Aktion Code schreiben, um in Ihrem Skript eine Verbindung mit RESTful- oder SOAP-Webdiensten herzustellen. Für REST-Aufrufe ist dies nicht die bevorzugte Methode, da die Kontaktverarbeitung dadurch verlangsamt werden kann. In den folgenden Fällen müssen Sie jedoch diese Methode verwenden: Ihre Aufrufe umfassen XML. Sie stellen eine Verbindung mit einem SOAP-Dienst her.

Optionen

Details

REST API Studio-Aktion

Mithilfe der REST API Studio -Aktion können Sie in Ihren Skripten RESTful-API-Aufrufe tätigen. Diese Methode:

Kann höhere Lasten als RESTful-Aufrufe in einer SNIPPET-Aktion verarbeiten, insbesondere bei umfangreichen Datenmengen.
Ist die bevorzugte Methode für API-Aufrufe in Skripten.
Muss verwendet werden, wenn Ihre Aufrufe JSON enthalten.

CXone API Studio-Aktionen

Studio bietet zahlreiche API-Aktionen, mit denen Sie in Ihren Skripten Aufrufe an CXone-APIs tätigen können. Nicht jede CXone-API ist als Aktion verfügbar, aber wenn eine Aktion verfügbar ist, sollten Sie sie anstelle von anderen Methoden verwenden. Sie finden die API-Aktionen im Bereich „API“ der Registerkarte „Framework“ in Desktop Studio und auf der Palette „API-Aktionen“ in CXone Studio.

SNIPPET-Aktionen

Sie können in einer SNIPPET-Aktion Code schreiben, um in Ihrem Skript eine Verbindung mit RESTful- oder SOAP-Webdiensten herzustellen. Für REST-Aufrufe ist dies nicht die bevorzugte Methode, da die Kontaktverarbeitung dadurch verlangsamt werden kann. In den folgenden Fällen müssen Sie jedoch diese Methode verwenden:

Ihre Aufrufe umfassen XML.
Sie stellen eine Verbindung mit einem SOAP-Dienst her.

Einschränkungen bei der Größe der zurückgegebenen Daten

In der CXone-Plattform können REST-APIs eine Datenmenge von 32 KB zurückgeben. Dieses Limit verhindert Cluster-Instabilität und Ausfälle. Es wird streng erzwungen.

Dieses Limit gilt für jede Methode zum Verbinden mit Webdiensten, wie für die REST API-Aktion und für das Tätigen von Aufrufen mit der SNIPPET-Aktion. Verwenden Sie nach Möglichkeit die REST API-Aktion anstelle der SNIPPET-Aktion für Ihre REST-APIs. REST API hat ein Rückgabelimit von 32 KB, kann aber eine höhere Last verarbeiten als die SNIPPET-Methode.

So verringern Sie die Größe Ihrer zurückgegebenen Daten:

Filtern Sie die Daten in der API-Antwort. Wenn Sie zum Beispiel die NICE-API für Berichte verwenden, um Kontakte abzurufen, können Sie die Ergebnisse nach startDate und endDate des Kontakts filtern. Mit diesem API-Aufruf können Sie auch eine Obergrenze für die Anzahl der zurückgegebenen Elemente festlegen. Einzelheiten zu den verfügbaren Filtern finden Sie in der Dokumentation der jeweiligen API.
Aktualisieren Sie die API-Anforderung so, dass nur die von Ihnen benötigten Daten zurückgegeben werden. Wenn Sie zum Beispiel die NICE-API für Berichte verwenden, um Kontakte abzurufen, können Sie die Felder contactId oder agentId so festlegen, dass nur relevante Daten zurückgegeben werden. Einzelheiten zu den möglichen Datenlimits finden Sie in der Dokumentation der jeweiligen API.

Wenn Sie keine der vorher angegebenen Optionen durchführen können, erstellen Sie eine Middleware.

Fehlercode -1

-1 ist ein interner Fehlercode, der darauf hinweist, dass bei einem API-Aufruf ein Fehler aufgetreten ist. Der Code tritt insbesondere in Situationen auf, wenn kein HTTP-Statuscode zurückgegeben wird oder wenn ein HTTP-Statuscode zwar zurückgegeben wird, aber nicht an das Skript übergeben werden kann.

Anhand der Statusbeschreibung des Fehlercodes -1 können Sie das Problem eingrenzen. Der Code kann die folgenden Statusbeschreibungen haben:

Die Anforderung wurde abgebrochen: Beim Vorgang ist eine Zeitüberschreitung aufgetreten. Es ist nicht ersichtlich, ob die Anforderung verarbeitet wurde oder nicht. Vor der Einrichtung einer Schleife als Reaktion auf einen Statuscode -1 sollte eine Validierung durchgeführt werden. Möglicherweise müssen Sie die Einstellung für die Zeitüberschreitung für den Aufruf in der Eigenschaft ProxyTimeoutSeconds ändern.
Ungültiger JSON-Primitivwert Der JSON-Parser hat die Antwort nicht eindeutig erkannt. Möglicherweise enthielt die Antwort ungültige Zeichen oder hatte nicht das JSON-Format. Dieser Fehler tritt häufig auf, wenn die Antwort als HTML gesendet wird. Sie können die Antwort im Snippet-Debugger testen. Ziehen Sie den Artikel REST-API-Antwort hat kein gültiges JSON- oder XML-Format in der Wissensdatenbank zurate.
Die Daten auf der Stammebene sind ungültig. Der XML-Parser hat die Antwort nicht eindeutig erkannt. Möglicherweise enthielt die Antwort ungültige Zeichen oder hatte nicht das XML-Format. Dieser Fehler tritt häufig auf, wenn die Antwort als HTML gesendet wird. Ziehen Sie den Artikel REST-API-Antwort hat kein gültiges JSON- oder XML-Format in der Wissensdatenbank zurate.
'doctype' ist ein unerwartetes Token. Das erwartete Token ist 'DOCTYPE'. Lesen Sie den Abschnitt Die Daten auf der Stammebene sind ungültig in dieser Liste.
Das Start-Tag 'br' auf Zeile x an Position x stimmt nicht mit dem End-Tag von 'body' überein. Lesen Sie den Abschnitt Die Daten auf der Stammebene sind ungültig in dieser Liste.
Die zugrunde liegende Verbindung wurde geschlossen: Beim Senden ist ein unerwarteter Fehler aufgetreten. Häufig weist dies darauf hin, dass ein Problem beim TLS-Handshake vorliegt. Weitere mögliche Fehlerursachen sind: IP oder Port ist auf einer Firewall nicht geöffnet; eine alte, nicht unterstützte TLS-Version wird verwendet; ungültige oder abgelaufene Zertifikate; Verwendung einer IP-Adresse in Kombination mit HTTPS; ähnliche Probleme. Führen Sie mithilfe der Firewall-Protokolle auf dem empfangenden Server eine Fehlerbehebung für diese Antwort durch.
Die zugrunde liegende Verbindung wurde geschlossen: Es konnte keine Vertrauensbeziehung für den sicheren SSL/TLS-Kanal hergestellt werden. Weitere Informationen finden Sie in dieser Liste unter Die zugrunde liegende Verbindung wurde geschlossen: Beim Senden ist ein unerwarteter Fehler aufgetreten.
Die Anforderung wurde abgebrochen: Es konnte kein sicherer SSL/TLS-Kanal erstellt werden. Weitere Informationen finden Sie in dieser Liste unter Die zugrunde liegende Verbindung wurde geschlossen: Beim Senden ist ein unerwarteter Fehler aufgetreten.
Antwort ist zu groß. (> 32 KB). Die Antwort enthält mehr als 32 KB Daten. In diesem Fall wird die Antwort verworfen, da das System nicht mehr als 32 KB in einer Variablen speichern kann. Die Antwort muss geändert oder gefiltert werden, um die Menge der zurückgegebenen Daten zu reduzieren.