Im Integration Builder können Sie mithilfe von Anfrageparametern Daten (Konversationsparameter) aus AI Agent-Konversationen abrufen und an externe Endpunkte weiterleiten. In manchen Fällen müssen Sie diese Daten transformieren oder neu formatieren, bevor Sie sie in einer API-Query entweder als URL-Anfrage oder im Anfragetext senden. Hierzu können Sie die leistungsstarke Query- und Transformationssprache JSONata verwenden.
In diesem Beitrag werden folgende Themen behandelt:
- Neuformatieren des Wertes eines Anfrageparameters
- Häufige Anwendungsfälle für das Neuformatieren von Werten
Verwandte Beiträge:
Neuformatieren des Wertes eines Anfrageparameters
Sie können den Wert eines Anfrageparameters mit JSONata neu formatieren.
So formatieren Sie den Wert eines Anfrageparameters neu
- Wählen Sie im Arbeitsbereich für AI Agents oben rechts im Dropdownfeld „AI Agent“ den gewünschten AI Agent aus.
- Klicken Sie im Hauptmenü auf der linken Seite auf API-Integrationen.
- Erstellen Sie eine Integration oder wählen Sie eine Integration aus.
- Wählen Sie auf der Seite Anfrageparameter den Anfrageparameter aus, dessen Wert Sie neu formatieren möchten, oder erstellen Sie den gewünschten Anfrageparameter.
- Klicken Sie im Feld Testwert auf das Symbol Wert neu formatieren (
).
- Transformieren oder neuformatieren Sie im Dialogfeld Wert neu formatieren unter Neuformatierung von JSONata den Wert des ausgewählten Anfrageparameterschlüssels.
Verwenden Sie in der JSONata-Query den Platzhalter '$' für den Schlüssel, dessen Wert Sie neu formatieren möchten.
Im Feld Vorschau des Testwerts können Sie die Ergebnisse der Query in Echtzeit überprüfen.
- Klicken Sie auf Fertig.
- (Optional) Wenn Sie den Anfrageparameter zum Hauptteil einer API-Anfrage hinzufügen:
- Wählen Sie links unter der Kopfzeile Umgebung die entsprechende Umgebung aus.
- Wählen Sie die Registerkarte Text aus.
- Fügen Sie das JSON-Objekt mit dem Anfrageparameter als Wert in doppelten geschweiften Klammern hinzu.
Häufige Anwendungsfälle für das Neuformatieren von Werten
Im Integration Builder können Sie Anfrageparameter definieren, indem Sie sie bestimmten Schlüsseln zuweisen. Obwohl diese Werte in vielen Fällen unverändert übernommen werden können, gibt es auch Szenarien, in denen sie transformiert oder neu formatiert werden müssen, damit sie den Anforderungen des externen Systems entsprechen.
Auf diese Weise können Sie zum Beispiel:
- Datumswerte neu formatieren: Ändern Sie das Format eines Datums von MM/TT/JJJJ in JJJJ-MM-TT oder ISO 8601, um den Anforderungen der API zu entsprechen.
- Zeichenfolgenoperationen durchführen: Manipulieren Sie Zeichenfolgen, indem Sie Zeichen hinzufügen oder entfernen, mehrere Felder kombinieren oder sie in HTML-Code transformieren.
- Konditionale Logik anwenden: Wenden Sie Bedingungen an, um beispielsweise zu prüfen, ob ein Feld leer ist, oder bei Bedarf einen Standardwert zuzuweisen.
Dieser Abschnitt enthält folgende Beispiele:
- Szenario: Neuformatieren von Datumswerten
- Szenario: Neuformatieren von URLs zum Einrichten anklickbarer Links
- Szenario: Neuformatieren eines Chatprotokolls zur Verbesserung der Lesbarkeit
Szenario: Neuformatieren von Datumswerten
In diesem Szenario muss der Endpunkt ein Datum im Format JJJJ-MM-TT oder in einem ISO 8601-Format überprüfen. In der Konversation sollen Datumsangaben aber im benutzerfreundlichen Format TT/MM/JJJJ angezeigt werden.
In diesem Fall würden Sie die folgende JSONata-Query verwenden:
$substring($, 6, 10) & "-" & $substring($, 3, 2) & "-" & $substring($, 0, 2)
Szenario: Neuformatieren von URLs zum Einrichten anklickbarer Links
In diesem Szenario möchten Sie URLs in anklickbare Links transformieren, indem Sie nach einer Zeichenfolge (Substring) ohne Leerzeichen suchen, die mit http:// oder https:// beginnt, und diese dann mit der JSONata-Funktion „$replace“ durch eine Zeichenfolge ersetzen, die aus der URL mit vorangestellten und nachgestellten <a>-Tag besteht.
In diesem Fall würden Sie die folgende JSONata-Query verwenden:
(
$text := "Chat transcript unavailable. Here is a link:https://www.zendesk.com. Here is another link: https://www.w3schools.com.";
$replace($text, /(https?:\/\/[^\s]+)/, '<a href="$1">$1</a>'
)
Szenario: Neuformatieren eines Chatprotokolls zur Verbesserung der Lesbarkeit
In diesem Szenario möchten Sie ein Chatprotokoll zu einem Ticket hinzufügen. Allerdings ist das Standardformat des Chatprotokolls nicht besonders gut lesbar.
- Chatprotokoll - 2024-10-12 (13:04:10) AI Agent: Willkommen beim Customer Engineering AI Agent! (13:04:10) AI Agent: Wählen Sie die Integration aus, die Sie testen möchten. (13:04:10) Besucher: test c.id: d501304d-da09-4485-a4c7-1c708ec0005d Alle Zeitangaben in UTC
Um die Lesbarkeit des Protokolls zu verbessern, möchten Sie jede Nachricht in einer eigenen Zeile darstellen. Da jede neue Nachricht mit einer linken Klammer ( ( ) beginnt, können Sie JSONata verwenden, um jedes Vorkommen von „(“ durch einen Zeilenumbruch mit nachfolgender Klammer zu ersetzen.
Die neu formatierte Konversation würde dann so aussehen:
- Chatprotokoll - 2024-10-12
(13:04:10) AI Agent: Willkommen beim Customer Engineering AI Agent!
(13:04:10) AI Agent: Wählen Sie die Integration aus, die Sie testen möchten.
(13:04:10) Besucher: test c.id: d501304d-da09-4485-a4c7-1c708ec0005d Alle Zeitangaben in UTC
In diesem Fall würden Sie die folgende JSONata-Query verwenden:
$replace($, “(“, “\n(“)
Außerdem müssen Sie den folgenden Parameter zum Textabschnitt in Ihrer Umgebung hinzufügen, damit er mit der Anfrage gesendet wird:
{
"chatTranscript": "{{chatTranscript}}"
}