01Was eine Datenquelle ist
Eine Datenquelle ist eine Webadresse, die du einmal speicherst. Wenn ein Zuschauer einen Befehl ausführt, der sie zitiert, ruft der Bot diese Adresse auf, holt einen Wert aus der Antwort heraus und sagt ihn im Chat. Wetter, eine Spielstatistik, die Länge der Warteschlange auf deinem eigenen Server: Wenn es über https antwortet und JSON oder Text liefert, kann ein Befehl es lesen.
PrincessBarney !weather
ItsBagelBot Es hat gerade 21°C in Montreal.
Hinter dieser Zeile steckt ein gewöhnlicher eigener Befehl. Seine Antwort, so wie sie im Editor eingetippt ist:
Es hat gerade {urlfetch:weather}°C in Montreal.
Der Platzhalter nennt die Quelle, nicht den Wert. Welchen Wert der Bot herausholt, ist an der Quelle selbst gespeichert, als
Pfad: eine Adresse innerhalb der Antwort. Die Antwort ist das Gebäude, current ist das Stockwerk,
temperature_2m ist die Tür. Mit Punkten geschrieben ergibt das current.temperature_2m. Abschnitt drei
übernimmt das Klicken für dich, und die Analogie darf jetzt Feierabend machen.
02Eine Quelle aus dem Befehlseditor hinzufügen
Alles passiert in Befehle, im Editor, der sich neben deiner Befehlsliste andockt.
- Setze den Cursor dorthin, wo der Wert hingehört
Öffne einen Befehl, klicke in Antwort und lass den Cursor genau an der Stelle im Satz stehen, an der der Wert erscheinen soll.
- Öffne die Palette
Unter der Antwort, neben den Chips
{user}und{args}, sitzt ein Chip Datenquelle. - Erstelle eine neue
+ Neue Datenquelle öffnet das Fenster Datenquelle hinzufügen: „Gib eine Web-API an, rufe eine echte Antwort ab und klicke dann auf den Wert, den du im Chat anzeigen möchtest.“
- Benenne sie und füge die Adresse ein
Anzeigename ist für dich. Er wird automatisch zum Namen der Datenquelle, dem Wort, das in den Platzhalter kommt: „Kleinbuchstaben, Ziffern und Unterstriche. Wird in {urlfetch:name} verwendet.“ Dann die Webadresse, https, bis zu 512 Zeichen.
- Hol dir eine echte Antwort
Beispiel abrufen ruft deine API echt auf, etwa einmal alle 10 Sekunden. Wenn die Antwort in einer Form kommt, die das Fenster nicht lesen kann, klicke auf oder eine Antwort einfügen und füge von Hand eine ein.
- Klicke den Wert an und füge dann die Quelle hinzu
Die Antwort wird zu einem Baum unter „Klicke auf den Wert, den du im Chat anzeigen möchtest.“ Klicke
temperature_2m, und das Fenster zeigt Angezeigt wird current.temperature_2m. Quelle hinzufügen speichert alles, und die Zeile der Palette fügt{urlfetch:weather}an deinem Cursor ein.
Datenquelle hinzufügen
Gib eine Web-API an, rufe eine echte Antwort ab und klicke dann auf den Wert, den du im Chat anzeigen möchtest.
Kleinbuchstaben, Ziffern und Unterstriche. Wird in {urlfetch:name} verwendet.
Klicke auf den Wert, den du im Chat anzeigen möchtest.
- 01 Der Anzeigename ist der, den du in Listen liest. Er wird automatisch zum Namen der Datenquelle darunter.
- 02 Der Name der Datenquelle ist das Wort im Platzhalter: Kleinbuchstaben, Ziffern und Unterstriche, bis zu 32 Zeichen.
- 03 Webadresse: https, absolut, bis zu 512 Zeichen. Der Bot sendet sie jedes Mal genau so, wie sie eingetippt wurde.
- 04 Beispiel abrufen sendet eine echte Anfrage an deine API. Etwa ein Test alle 10 Sekunden.
- 05 Einen Wert anzuklicken speichert seinen Pfad an der Quelle. „Stattdessen die gesamte Antwort verwenden“ schaltet auf Klartext um.
Sobald die Quelle erstellt ist, listet derselbe Chip sie auf. Jede gespeicherte Quelle zeigt ihren Pfad, sodass du zwei Wetterquellen auf einen Blick unterscheiden kannst, und ein Klick auf eine Zeile setzt den Platzhalter dorthin, wo dein Cursor war.
Variable einfügen
- 01 Der Chip Datenquelle sitzt unter Antwort zusammen mit den Platzhalter-Chips, neben Zähler.
- 02 Jede Zeile zeigt den an der Quelle gespeicherten Pfad oder „Klartext“, wenn die gesamte Antwort angezeigt wird.
- 03 „+ Neue Datenquelle“ öffnet das Fenster, ohne den Befehl zu verlieren, den du gerade schreibst.
03Den Wert wählen
Hier ist derselbe Baum wie im Dashboard, mit denselben Regeln. Nur die Werte sind anklickbar; ein Zweig wie current
enthält andere Dinge, daher kann er keinen Pfad abschließen. Ändere die Antwort links, und der Baum folgt. Das bleibt der schnellste
Weg, mit deiner eigenen API zu üben, bevor du etwas speicherst.
An der Quelle gespeichert
Platzhalter, den du eintippst
Im Platzhalter gesetzter Pfad
Der Chat würde anzeigenhier abgeschnitten, 100 Byte
Der Klartext-Modus speichert keinen Pfad. Der Bot bereinigt die Antwort und zeigt deren erste 100 Byte.
| Regel | Was es bedeutet |
|---|---|
| Punkte zwischen den Schritten | current.temperature_2m öffnet current und holt daraus temperature_2m heraus. |
| Listen verwenden nackte Ziffern | items.0.name ist der erste Eintrag. Eckige Klammern gehören nicht zur Grammatik. |
| Tiefe | Bis zu 8 Schritte. Darüber verweigert der Baum den Wert: „Tiefer als 8 Ebenen. Wähle etwas näher an der obersten Ebene.“ |
| Jeder Schritt | Buchstaben, Ziffern, Unterstrich und Bindestrich, bis zu 64 Zeichen je Schritt. |
| Das Ende des Pfads | Endet auf einem Wert: Text, eine Zahl, true oder false. Auf einem Objekt, einer Liste oder einem leeren Feld zu enden gilt als kaputte Datenquelle, und der Chat zeigt dein |default oder den rohen Platzhalter, wenn es keins gibt. |
| Ein Pfad im Platzhalter | Hat Vorrang vor dem an der Quelle gespeicherten. {urlfetch:weather.current.wind_speed_10m} liest einen anderen Wert von derselben Adresse. |
| Der Name | Groß- und Kleinschreibung egal. {URLFETCH:Weather} und {urlfetch:weather} meinen dieselbe Quelle. |
| Der Wert | Bereinigt, gekürzt und dann auf 100 Byte beschnitten, bevor er im Chat ankommt. |
{urlfetch:weather} auf
current.temperature_2m für !weather, und schreibe dann
{urlfetch:weather.current.wind_speed_10m} in !wind. Dieselbe Quelle, dasselbe Budget von
20 Datenquellen, zwei verschiedene Antworten.04APIs, die einen Schlüssel verlangen
Manche APIs verlangen einen Schlüssel, bevor sie antworten. Füge ihn einmal in Einstellungen im Bereich API-Schlüssel hinzu: eine Bezeichnung mit bis zu 32 Zeichen, damit du ihn später erkennst, und den geheimen Wert selbst, bis zu 512 Zeichen, dann Schlüssel hinzufügen. Der Hinweis im Bereich sagt es besser als wir: „API-Schlüssel, die deine Datenquellen bei jeder Anfrage senden. Personen mit gemeinsamem Zugriff können sie verwenden, aber nie sehen.“
Der geheime Wert wird verschlüsselt, bevor er gespeichert wird, und nie wieder angezeigt. Du behältst die
Bezeichnung und die letzten 4 Zeichen, was reicht, um zwei Schlüssel auseinanderzuhalten, wenn du einen
änderst. Trägt eine Datenquelle einen Schlüssel, sendet der Bot ihn bei jedem Abruf in einem
Authorization: Bearer-Header, und die Adresse bleibt sauber.
Im Fenster „Datenquelle hinzufügen“ wählst du den Schlüssel im Feld API-Schlüssel. „Kein Schlüssel nötig“ ist die richtige Wahl für die meisten öffentlichen APIs. Ist noch kein Schlüssel gespeichert, zeigt das Feld „Noch keine API-Schlüssel. Füge in den Einstellungen einen hinzu und wähle ihn dann hier aus.“ und ein Link API-Schlüssel öffnen führt zu den Einstellungen.
05Grenzen und Zeitlimits
Die Zahlen unten gelten im Produktivbetrieb. Der Cache ist das, worauf du zuerst stößt: Eine akzeptierte Antwort wird 30 Sekunden lang wiederverwendet, daher ruft ein Befehl, der 40-mal in einer Minute läuft, deine API nur zweimal auf.
| Grenze | Die Zahl |
|---|---|
| Datenquellen pro Kanal | 20. |
| Datenquellen in einer Antwort | 3. Der Editor verweigert eine vierte. |
| Webadresse | Nur https, absolut, bis zu 512 Zeichen. |
| Abgelehnte Adressen | Literale IP-Adressen, localhost und alles, was auf .local oder .internal endet. Wird beim Speichern und bei jedem Abruf geprüft. |
| Größe der Antwort | Der Bot liest bis zu 1 MiB einer Antwort, gemessen nach dem Entpacken. |
| Größe des Beispiels | Der Editor zeigt einen Baum nur für ein lesbares Textbeispiel von höchstens 128 KB. Eine größere oder unlesbare Antwort ergibt „Die API hat geantwortet, aber ihre Antwort konnte nicht automatisch gelesen werden. Füge unten eine ein.“ Ein eingefügtes Beispiel über 128 KB ergibt „Dieses Beispiel ist größer als 128 KB. Füge ein kürzeres ein.“ |
| Inhaltstyp | application/json oder text/*. |
| Zeitlimits | Die API hat 2,5 Sekunden, der Abrufdienst 3 Sekunden, und der Bot hört bei 3,5 Sekunden auf zu warten. |
| Cache | Eine gute Antwort wird 30 Sekunden lang behalten. Eine Ablehnung, etwa ein 404 oder ein Pfad, der nichts findet, wird 15 Sekunden lang behalten. Ein Ausfall wird nicht gecacht. |
| Anfragen pro Kanal | 6 pro Minute, über alle Datenquellen hinweg. |
| Anfragen pro Datenquelle | 30 pro Minute. |
| Anfragen pro API-Host | 120 pro Minute, gezählt über alle Kanäle, die auf diesen Host zeigen. |
| Weiterleitungen | Bis zu 3 Sprünge, jeder bleibt bei https. |
| Ein Host, der wiederholt fehlschlägt | Fünf Transportfehler hintereinander, und dieser Host wird 60 Sekunden ruhiggestellt. |
| „Beispiel abrufen“ | Etwa ein Test alle 10 Sekunden: „Zu viele Tests. Jeder ruft die echte API auf. Warte etwa 10 Sekunden und versuche es erneut.“ |
- Tatsächlich bei deiner API eingegangene Anfragen
- 2 pro Minute
- Aus dem 30-Sekunden-Cache beantwortet
- 10 pro Minute
- Vom Limit von 6 pro Minute abgelehnt
- 0 pro Minute
Diese Ausführungen zeigen anstelle des Werts nichts, oder deinen Fallback.
Der Cache dient deinem API-Kontingent. Ohne ihn würde ein einziger Raid die Aufrufe eines ganzen Monats an einem Abend verbrauchen, und jeder andere Kanal, der auf denselben Host zeigt, würde es ebenfalls spüren.
06Was der Chat bei einem Fehler anzeigt
Ein Befehl wird wegen einer Datenquelle nie stumm. Der Rest des Satzes wird trotzdem gesendet und der
Wert bleibt leer, außer du hast nach einem senkrechten Strich einen Fallback geschrieben:
{urlfetch:weather|nicht verfügbar} sagt „nicht verfügbar“, wenn der Abruf fehlschlägt.
Eine pausierte, fehlende oder keinen Wert liefernde Quelle funktioniert genauso: Chat und Timer zeigen den Wert
|default des Platzhalters. Ohne |default zeigt der Chat den rohen Platzhalter so, wie er eingetippt wurde,
und deshalb heißt ein rohes {urlfetch:weather} im Chat: „prüfe diese Datenquelle“.
| Was passiert ist | Was der Chat anzeigt |
|---|---|
| Die API hat abgelehnt, sie hat dich gedrosselt, einen Fehler zurückgegeben, länger gebraucht als der Bot wartet, der Pfad hat nichts gefunden, oder die Nachricht ist die Wiedergabe einer alten | Nichts anstelle des Werts, oder der Text deines |fallback. |
| Die Quelle ist pausiert, fehlt, wurde nie gespeichert oder konnte keinen Wert liefern | Der Text deines |fallback. Ohne |fallback der Platzhalter so, wie er ist: {urlfetch:weather}. |
PrincessBarney!weather
ItsBagelBotEs hat gerade °C in Montreal.
Dein Schlüssel wurde abgelehnt, oder der Endpunkt hat die Anfrage verworfen. Teste im Dashboard, und du bekommst dasselbe Urteil: „Die API hat die Anfrage abgelehnt. Prüfe die URL und wähle unter API-Schlüssel den richtigen Schlüssel aus, falls diese API einen benötigt.“
Ein Limit wurde erreicht: 6 Abrufe pro Minute für den Kanal, 30 für diese Datenquelle oder 120 pro Minute für diese API, kanalübergreifend gezählt. Nichts ist kaputt, und in der nächsten Minute funktioniert es wieder.
Der Bot wartet 3,5 Sekunden und spricht dann ohne den Wert. Eine langsame API unter Last ist dafür der übliche Grund.
Der Pfad war korrekt, aber die Antwort hatte an dieser Stelle nichts, meist weil die API ein Feld umbenannt hat. Öffne die Quelle, rufe ein Beispiel ab und klicke den Wert erneut an.
Eine pausierte oder fehlende Quelle hat nichts, was sie auflösen könnte. Ein Platzhalter mit |default zeigt diesen Wert. Ein Platzhalter ohne |default, wie dieser hier, wird so angezeigt, wie er eingetippt wurde. Das Dashboard sagt es, wenn eine Quelle keinen Wert liefern kann: „Diese Datenquelle konnte keinen Wert liefern. Bis dahin zeigt der Chat den |default-Wert des Platzhalters, falls er einen hat, sonst {urlfetch:name} unverändert. Prüfe die Webadresse und den API-Schlüssel und klicke erneut auf Beispiel abrufen.“
Drei Datenquellen pro Antwort ist die Grenze des Editors, und er verweigert eine vierte. Der Bot hat seine eigene Obergrenze bei acht und zeigt jeden Platzhalter darüber unverändert an, so wie diesen hier.
{urlfetch:weather|nicht verfügbar}. Eine langsame API wird dann als
„nicht verfügbar“ gelesen statt als Lücke im Satz.Wenn etwas nicht stimmt
| Was du siehst | Was es bedeutet | Was zu tun ist |
|---|---|---|
| Die API hat die Anfrage abgelehnt. Prüfe die URL und wähle unter API-Schlüssel den richtigen Schlüssel aus, falls diese API einen benötigt. | Die API hat den Test verworfen: Schlüssel falsch oder fehlend, oder falsche Adresse. | Prüfe die Webadresse. Verlangt die API einen Schlüssel, füge ihn unter Einstellungen bei den API-Schlüsseln hinzu, wähle ihn im Feld API-Schlüssel aus und teste erneut. |
| Anfragelimit erreicht. Warte kurz und teste erneut. | Eine Anfragegrenze wurde erreicht. | Warte eine Minute und teste erneut. |
| Die API hat einen Fehler zurückgegeben. Der Chat sieht nichts, außer der Platzhalter enthält einen |default: {urlfetch:name|default}. | Die API hat mit einem Fehler geantwortet. | Prüfe den Status der API oder füge nach einem senkrechten Strich einen Fallback hinzu. |
| Zeitüberschreitung bei der API. Der Chat sieht nichts, außer der Platzhalter enthält einen |default: {urlfetch:name|default}. | Die API hat länger gebraucht, als der Bot wartet. | Versuch es erneut und füge nach einem senkrechten Strich einen Fallback hinzu. |
| Diese Datenquelle konnte keinen Wert liefern. Bis dahin zeigt der Chat den |default-Wert des Platzhalters, falls er einen hat, sonst {urlfetch:name} unverändert. Prüfe die Webadresse und den API-Schlüssel und klicke erneut auf Beispiel abrufen. | Die Quelle ist pausiert, oder ihr Pfad oder ihre Adresse liefert keinen Wert. | Aktiviere die Quelle wieder, falls sie pausiert ist. Sonst korrigiere Adresse oder Schlüssel, rufe ein Beispiel ab und klicke den Wert erneut an. |
| Der Abrufdienst hat nicht geantwortet. Versuch es gleich erneut. | Der Dienst, der deine API aufruft, hat nicht rechtzeitig geantwortet. | Warte kurz und teste erneut. |
| Die API hat geantwortet, aber ihre Antwort konnte nicht automatisch gelesen werden. Füge unten eine ein. | Die Antwort ist kein lesbarer Text oder größer als 128 KB. | Klicke auf „oder eine Antwort einfügen“ und füge eine echte Antwort von Hand ein. |
| Das ist kein gültiges JSON. Korrigiere es, dann erscheint der Baum hier. | Das eingefügte Beispiel ist kein JSON. | Füge die Antwort erneut ein, von der ersten geschweiften Klammer bis zur letzten. |
| Dieses Beispiel ist größer als 128 KB. Füge ein kürzeres ein. | Das eingefügte Beispiel ist zu groß für den Baum. | Füge einen kleineren Ausschnitt der Antwort ein. |
| Zu viele Tests. Jeder ruft die echte API auf. Warte etwa 10 Sekunden und versuche es erneut. | Beispiel abrufen erlaubt etwa einen Test alle 10 Sekunden. | Warte 10 Sekunden. |
| Du hast das Limit von 20 Datenquellen für deinen Kanal erreicht. Lösche eine, um Platz zu schaffen. | Ein Kanal behält 20 Datenquellen. | Lösche eine Quelle, die du nicht mehr brauchst. |
| Eine Datenquelle namens „name“ existiert bereits. | Eine andere Quelle trägt diesen Namen bereits. | Wähle einen anderen Namen oder bearbeite die bestehende Quelle. |
| Eine Timer-Nachricht darf höchstens 3 verschiedene abgerufene Werte referenzieren ({urlfetch:…}). | Timer-Nachrichten sind auf 3 Datenquellen begrenzt. | Zitiere in der Timer-Nachricht weniger Quellen. |
| Ein rohes {urlfetch:name} im Chat | Die Quelle ist pausiert, fehlt oder kann keinen Wert liefern, und der Platzhalter hat keinen |default. Platzhalter über der Grenze pro Nachricht bleiben ebenfalls roh. | Öffne den Befehl, prüfe, dass der Name zu einer gespeicherten Quelle passt, und aktiviere sie wieder, falls sie pausiert ist. Füge ein |default hinzu, damit der Chat einen Fallback zeigt. |
07Was eine Quelle nicht tut
-
Die Adresse wird beim Speichern festgeschrieben.
{args}und{user}bleiben in einer Webadresse unangetastet, daher kann ein Zuschauer die Anfrage an deine API nicht steuern. -
Anfragen sind
GET, und die Header musst du nicht selbst einstellen. Der einzige, den der Bot hinzufügt, istAuthorization: Bearer, und nur wenn die Quelle einen Schlüssel trägt. - Platzhalter werden in Antworten eigener Befehle aufgelöst, nach den Prüfungen für Berechtigung, Live-Status und Abklingzeit, und in Timer-Nachrichten, bei jeder Auslösung. Eine Timer-Nachricht kann bis zu 3 verschiedene Datenquellen zitieren. Zähler lassen den Platzhalter in Ruhe.
- Eine wiederholte Chatnachricht ruft nie zweimal ab. Spielt der Bot ein altes Ereignis erneut ab, bekommt der Chat eine Lücke (oder deinen Fallback) statt eines zweiten Aufrufs deiner API.
- Private und lokale Adressen werden an beiden Enden abgelehnt: beim Speichern und dann erneut beim Abruf.
{urlfetch:weather}
in den Satz und direkt danach {urlfetch:weather.current.wind_speed_10m}: zwei Werte, ein Aufruf, eine Zeile deines Kontingents.