105
Bearbeitungen
Änderungen
Zur Navigation springen
Zur Suche springen
Service-Tokens
Die CeviDB bietet eine <abbr>API</abbr>, mit der Personen- und Gruppen-Daten aus der Datenbank ausgelesen werden können. Die <abbr>API</abbr> erlaubte es aber '''nicht''', Daten in der CeviDB zu verändern. Es gibt zwei Methoden, um Daten automatisiert auszulesen. Beide sind hier kurz erklärt.
=== User-Tokens ===Dies ist ein Token, dass persönlich ist. Das heisst, es hat den gleichen Zugriff (lesen) wie der Ersteller. Auf lange Sicht wird diese Art eventuell auch wieder abgeschaltet. === Service-Tokens ===Dies ist die neue Version der Abfragen. Sie ändern momentan recht schnell, aus diesem Grund verweisen wir hier nur auf die "ofizielle" Dokumentation auf Github: [https://github.com/hitobito/hitobito/blob/master/doc/development/07_service_accounts.md]. Für die Service Tokens kann ganz genau eingestellt werden, welche Berechtigungen sie haben. Sie können auf einer Gruppe erstellt werden (auf der Gruppe im Menu oben auf "Api-Keys", <nowiki>https://db.cevi.ch/groups/GRUPPE/service_tokens</nowiki>) ====Allgemeine Hinweise====
Die Schnittstelle wird über POST- und GET-Anfragen angesteuert und verwendet [http://de.wikipedia.org/wiki/JavaScript_Object_Notation JSON] als Datenformat. Der Zugriff über die Schnittstelle erfordert die Zugangsdaten eines registrierten Benutzers. Die Rechte der Schnittstelle entsprechen dann denn Rechten des verwendeten Nutzers. Beim Login wird ein <code>user token</code> generiert, das danach bei jeder Anfrage mitgesendet werden muss.
=== API ===Die API wird von beiden, User-Tokens und Service-Tokens verwendet. Die offizielle Dokumentation finded ihr auch auf Github: [https://github.com/hitobito/hitobito/blob/master/doc/development/05_rest_api.md]. Untenstehend sind doch noch einige kurze Anleitungen und Informationen gesammelt. Sie sind für die User-Tokens geschrieben. Für den Gebrauch von Service-Tokens ändern sich die Endpunkte nicht, nur die Parameter ändern sich von <syntaxhighlight lang="bash">user_email=info@cevi.ch&user_token=AABBCC</syntaxhighlight>hin zu<syntaxhighlight lang="bash">token=DDEEFF</syntaxhighlight> =====Tools===========Spender-Tool des RV======
Die API wird vom Spender-Tool des RVs verwendet. Das Tool ist in Python geschrieben und ist freie Software. Es kann von [https://github.com/nchiapol/cevidbtool Github] heruntergeladen werden.
======Couvertgenerator======
Das Tool [https://github.com/lucidBrot/cevi-versand cevi-versand] erstellt nach einmaligem einrichten mit minimalem manuellen Aufwand PDFs um Couverts für den Versand zu drucken. Dafür verwendet es auch die API. Unter anderem kann man damit:
[https://github.com/lucidBrot/cevi-versand cevi-versand] ist open-source und gratis zu benutzen, aber Spenden werden geschätzt :)
====Ablauf einer Abfrage====
#Login-Anfrage mit Email und Passwort senden
'''Wichtig''': Passwörter dürfen nicht hardcoded im Programmcode hinterlegt werden. Passwörter im Programmcode sind ein Sicherheitsrisiko. Soll ein Programm ohne Interaktion mit einem Benutzer ausgeführt werden, so kann das <code>user token</code> im Programmcode hinterlegt werden. Gelingt es einem Angreifer, das Token auszulesen, so erhält er nur eingeschränkte Lese-Rechte. Ein gestohlenes Passwort würde ihm erlauben, sich mit den vollen Benutzerrechten des Besitzers einzuloggen. Bitte informiert [mailto:cevidb@cevi.ch cevidb@cevi.ch], wenn ihr ein Skript erstellt und ein <code>user token</code> hinterlegt.
====Erstes Login====
Um sich anzumelden, muss ein POST-Request an https://db.cevi.ch/users/sign_in.json gesendet werden. Als Parameter müssen <code>person[email]</code> und <code>person[password]</code> übergeben werden.
=====Beispiele=====
'''Python:'''
<syntaxhighlight lang="python" line="line">
</syntaxhighlight>
'''Wichtig''': Damit die https-Verbindung klappt, müssen die CA-Zertifikate verfügbar sein. In Python kann die Zertifikatdatei mit dem verify Keyword-Argument der post-Funktion definiert werden.
====User Token verwalten====
Das <code>user token</code> ist über mehrere Logins konstant. Dadurch kann das Token in Programmen hinterlegt werden, die ohne Benutzer-Interaktion funktionieren sollen. Um ein bestehendes Token zu löschen oder ein neues Token zu generieren, können folgende Anfragen verwendet werden:
{| class="wikitable"
|}
Als Parameter müssen wie beim Login <code>person[email]</code> und <code>person[password]</code> übergeben werden.
====Daten abfragen====
Sobald das Authentication Token bekannt ist, können verschiedene Endpunkte abgefragt werden. Die URL entspricht dabei der URL im Browser, endet aber auf <code>.json</code>
Bei jeder Abfrage müssen zudem die Email-Adresse und das <code>user token</code> mitgesendet werden. Dazu bestehen zwei Möglichkeiten:
Weiter können weitere GET-Parameter (analog zur “richtigen” CeviDB) angehängt werden. Am besten führt man das Gewünschte in der CeviDB aus (zum Beispiel Sortieren nach Rollen) und kopiert die URL, ändert die Endung zu <code>.json</code>.
=====Beispiele=====
Normale Abfrage mit Python:
<syntaxhighlight lang="python" line="1">
</syntaxhighlight>
Anfrage mit Rollenauswahl mit Python:
<syntaxhighlight lang="python" line="line1">
# nach Login, Variable token ist definiert
# gewünscht ist eine Sortierung nach Rollen und eine Auswahl (nur AL)
data = res.json()['people'] #ist hier leer, da auf der Geschäfsstelle (Gruppe 5) keine Abteilungsleiter erfasst sind.
</syntaxhighlight>
====Endpunkte====
{| class="wikitable"
!Endpunkt
