Aufruf des @RollButlers API
Die Schnittstelle des @RollButlers wird über https://rollbutler.net/index.php angesprochen. Es ist dabei zu beachten, dass der Aufruf ausschließlich über die SSL verschlüsselte Verbindung erfolgt.
Es wird empfohlen, dass die Anfragen an den @RollButler via POST Requests gesendet werden. Auf diese Weise wird sichergestellt, dass die API Zugangsdaten geheim bleiben.
Die folgenden Parameter müssen dabei übermittelt werden:
Feldbezeichnung | Wert | Beispiel | Beschreibung |
api_key * | hexadezimal | 055dbbce6a1d… | Eindeutiger Identifier für die API Verbindung. Zu finden in den Einstellungen des @RollButler Accounts. 32 Bytes |
api_pass | hexadezimal | 51bf63dd8e6a… | Passwort für die API Verbindung. Wird einmalig per E-Mail auf Anfrage in den Einstellungen des @RollButler Accounts zugesandt. 60 oder mehr Bytes |
job * | string | api | Dieses Feld muss den Wert “api” beinhalten |
source * | string | MeineApp | Bezeichnung der aufrufenden Anwendung |
usr * | string | Max | Bezeichnung (Name) des Endnutzers. Diese Bezeichnung wird unter anderem für die textuelle Rückantwort “… hat … gewürfelt und das Ergebnis ist …” verwendet. |
usr_id | string | 4711 | Eindeutige Kennung (Nummer) des Endnutzers in der eigenen Anwendung |
roll * | string | /r 3d6 | Kommando an den @RollButler gemäß Spezifikation. |
lang | string | EN | Sprache der Ausgabe (DE oder EN, Englisch ist default) |
format | string | json | Format der Antwort. Gültige Werte sind json: detaillierte Rückmeldung im JSON Format (default) text: textuelle Antwort colortext: textuelle Antwort mit Farbmarkierungen markdown: textuelle Antwort im Markdown Format extended: wie markdown, allerdings im JSON Format mit zusätzlichen Feldern |
logit | boolean | false | Kennzeichnet, ob der Wurf in der Datenbank gespeichert und mit einem Verifizierungscode versehen werden soll. Diese Option erfordert zwingend einen Aufruf mit gültigem api_pass. default: false. |
Die in der Tabelle mit “*” gekennzeichneten Felder sind zwingend erforderlich.
Der folgende PHP Code verdeutlicht den Aufruf.
$curl = curl_init('https://rollbutler.net/index.php'); $curl_options = [ CURLOPT_POST => 1, CURLOPT_RETURNTRANSFER => 1, CURLOPT_HTTPHEADER => [ 'Authorization: Bot ' . $api_key, 'User-Agent: ' . $source, ], CURLOPT_POSTFIELDS => 'job=api&usr=' . urlencode($usr) . '&user_id=' . urlencode($user_id) . '&roll=' . urlencode($roll) . '&source=' . urlencode($source) . '&api_key=' . urlencode($api_key) . '&api_pass=' . urlencode($api_pass), ]; curl_setopt_array($curl, $curl_options); $result = curl_exec($curl); curl_close($curl); if (!empty($result)) $result = json_decode($result, true);
Die Variablen $api_key, $api_pass, $source, $usr, $usr_id und $roll sind dann entsprechend zuvor zu füllen.