Integration mit APIs von Drittanbietern

Sie können Bots erstellen, die mit anderen Ressourcen über eine API interagieren. Beispielsweise können Bots Anfragen bearbeiten, um zu prüfen, ob ein Termin an einem bestimmten Datum möglich ist, oder ein Produkt in einem Online-Shop finden.

Wie man eine Drittanbieter-API am Beispiel von DaData handhabt

Nehmen wir als Beispiel API-Tipps von https://dadata.ru/api/suggest/address

Lesen Sie die Dokumentation von Drittanbieter-APIs sorgfältig durch

Öffnen Sie Ihr Projekt in Mavibot und öffnen Sie die erweiterten Einstellungen in den Einstellungen eines Blocks; dort müssen Sie den Anfragetyp auf POST-json ändern.

Geben Sie im Feld „URL-Anfrage“ die folgende URL ein: https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address

Geben Sie im Feld „Anfrage-Header“ den Header im JSON-Format ein:

{ "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }

Fügen Sie in den „JSON-Parametern“ die Anfrage selbst ein - { "query": "#{CurrencyType}" }

Um die Ergebnisse zu erhalten, müssen Sie auch den Reiter „Gespeicherte Werte“ ausfüllen.

Ein Beispiel für die Anfrage finden Sie unten:

Wie man Werte aus Variablen speichert

Nicht jeder versteht es sofort, bis man es selbst ausprobiert.

Geben Sie zunächst #{custom_answer} in das Antwortfeld ein. (Die Variable #{custom_answer} enthält die Antwort vom Server, die im Feld „URL für eine Antwort vom Server“ erwähnt wurde)

Starten Sie den Block mit der Anfrage, um die Anfrage zu senden und eine Antwort zu erhalten. Sie müssen die Antwort analysieren und den Zugriff auf die darin enthaltenen Variablen einrichten. Dazu müssen Sie mit dem Reiter „Gespeicherte Werte“ arbeiten.

Schauen wir uns ein Beispiel an, um den Prozess besser zu verstehen.

Als Ergebnis unserer Anfrage #{custom_answer} kam eine Antwort im folgenden Format:

{"suggestions": [{"value": "Britisches Pfund", "unrestricted_value": "Britisches Pfund", "data": {"code": "826", "strcode": "GBP", "name": "Britisches Pfund", "country": "Vereinigtes Königreich"}}]}

Schreiben wir nun im Feld „Gespeicherte Werte“ unseren WERT->VARIABLE

suggestions - der Schlüssel des Arrays [{"value": "Britisches Pfund", "unrestricted_value": "Britisches Pfund", "data": {"code": "826", "strcode": "GBP", "name": "Britisches Pfund", "country": "Vereinigtes Königreich"}}]

suggestions|0 - der Schlüssel des ersten Elements im Array {"value": "Britisches Pfund", "unrestricted_value": "Britisches Pfund", "data": {"code": "826", "strcode": "GBP", "name": "Britisches Pfund", "country": "Vereinigtes Königreich"}}

suggestions|0|value - der Schlüssel zum Wert „Britisches Pfund“

Der längste Schlüssel in diesem JSON:

suggestions|0|data|strcode - der Schlüssel zum Wert „GBP“

Schlüssel werden durch den senkrechten Strich (|) getrennt. Wenn es ein Array in JSON gibt, wird der Zugriff auf sein Element nummeriert, beginnend mit der Zahl 0, und ebenfalls mit dem senkrechten Strich geschrieben.

Es ist notwendig, die gesamte Verschachtelung zu wiederholen. Zur Vereinfachung können Sie JSON in einer App wie JSON-Viewer visualisieren.

Verschachtelungsebenen werden durch senkrechte Striche getrennt. Sie müssen also alle Schlüssel, getrennt durch den Strich, auflisten, um zum Wert zu gelangen.

Wenn es ein Array in JSON gibt, müssen Sie anstelle des Schlüssels die Nummer des Elements beginnend mit 0 angeben.

Trennen Sie die Phrasen zum Abrufen von Variablen durch das Semikolon (;). Die Phrasen bestehen aus dem Link zu den Daten in der Antwort und dem Namen der Variable, in der sie gespeichert werden sollen, getrennt durch die Symbole -> (Bindestrich + spitze Klammer).

Die Suchanfrage ist sozusagen ein Pfad im JSON zum benötigten Wert.

Entwicklung einer API für Bots

Um eine API zu entwickeln, benötigen Sie ein Hosting, auf dem sie basiert. Wenn Sie keines haben oder kein Programmier-Ass sind, können Sie uns kontaktieren, und wir entwickeln die API für Ihren Bot und hosten sie auf unserem. Das Hosting selbst ist kostenlos, Sie zahlen nur für die Entwicklung.

Aber zunächst ein wenig Theorie.

Der Bot unterstützt die GET- und POST-Anfragen, die wichtigsten Typen, die in den meisten öffentlichen APIs verwendet werden.

GET ist eine Anfrage, die beim Klicken auf einen Link oder beim Öffnen eines Links im Browser erfolgt. Parameter in einer solchen Anfrage werden in der URL übertragen.

Die Syntax der übertragenen Parameter: Nach der URL folgt ein Fragezeichen (?), dann wird jeder Parameter durch das kaufmännische Und (&) getrennt. Ein Parameter besteht aus dem Namen und seinem Wert nach dem Gleichheitszeichen (=). Ein Beispiel für eine URL mit einem Parameter:

Hier sehen Sie, dass ein Parameter mit dem Namen „search_query“ übergeben wird und sein Wert „queen live aid“ ist. Das ‚+‘ steht hier für das Leerzeichen zwischen den Wörtern; bei der Arbeit mit der Bearbeitungssoftware können Sie einfach Leerzeichen lassen – der Bot ändert es selbst.

POST ist ein Anfragetyp, der am häufigsten beim Ausfüllen eines Formulars auf einer Website gesendet wird. Die Anfrage überträgt die Parameter im Body; sie können natürlich genauso wie bei GET übergeben werden, aber das wird selten so gemacht. Der Parameter im Body kann im JSON-Format oder als Schlüssel-Wert-Paar sein. Als Schlüssel-Wert-Paare teilen Parameter Formulare, das JSON-Format wird am häufigsten für APIs verwendet.

Anfrage-Header. Jeder Anfrage kann ein Header/Titel hinzugefügt werden. Das Format der geteilten Daten und Zugriffsschlüssel wird meistens darin geschrieben. Normalerweise lassen wir diesen Reiter leer, aber es ist gelegentlich notwendig, den API-Token oder den Anfragetyp „Content-type“: „application/json“ einzufügen.

JSON - (JavaScript Object Notation) ist ein offenes Standard-Dateiformat und Datenübertragungsformat, das menschenlesbaren Text verwendet, um Datenobjekte zu speichern und zu übertragen, die aus Attribut-Wert-Paaren und Arrays bestehen. Um mit der API in Bots zu arbeiten, müssen Sie dieses Format kennen, alles basiert darauf.

Lesen Sie vor dem Fortfahren die folgenden Artikel:

https://www.json.org/json-en.html
https://developer.mozilla.org/en-US/docs/learn/javascript/objects/json

Und versuchen Sie auch, Ihre eigene JSON-Datei auf dieser Website zu erstellen:

https://jsoneditoronline.org

Praxis

Blöcke und Bedingungen können Anfragen ausführen. Die Bedingungsanfragen werden erstellt, um auf der Website zu verstehen, ob der Dialog einem bestimmten Pfad folgen kann oder nicht. Die Anfrage erfolgt in diesem Fall jedes Mal, wenn die Bedingung des Pfades überprüft wird. Die Blockanfragen hingegen werden nur ausgeführt, wenn der Wechsel in den Block erfolgt.

Bevor Sie eine Anfrage erstellen, müssen Sie ihren Typ auswählen:

POST-data und POST-json unterscheiden sich durch die Methode der Parameterübertragung wie oben erwähnt (JSON-Format oder als Schlüssel-Wert-Paar). Wenn Sie JSON wählen, können die Parameter nur in der Anfrage übertragen werden. Ein zusätzliches Feld öffnet sich für den Post: JSON-POST-Parameter. Wichtig! Die Parameter müssen nur im JSON-Format geschrieben werden, der Bot funktioniert nur so.

Die Antwort vom Server kann analysiert und in Variablen gespeichert werden.

Sie können die Antwort nur auswerten, wenn sie im JSON-Format vorliegt.

Die gespeicherten Variablen werden in der letzten nicht ausgefüllten Übermittlung geschrieben; wenn die Übermittlung durch einen roten Block übertragen wird, werden die Variablen annulliert. Wenn Sie also Daten speichern müssen, müssen Sie Variablen durch den gelben Block übertragen.

Übrigens können Sie sehen, was der Bot in den Variablen im Bereich Leads geschrieben hat:

Datenübertragung nicht als Zeile

Standardmäßig kommt der Variablenwert im Format #{} an, aber dann als Zeile. Damit die Variable als Zahl übertragen wird, müssen Sie die Überprüfung des Formats der Post-Json-Parameter deaktivieren.

Dann können Sie einfach den Namen der Variable erwähnen, wie {"key": #{variable_name}}, variable_name ist die Variable, also ohne Klammern.

Nach dem Einrichten der Parameter wird empfohlen, die Überprüfung wieder zu aktivieren.