5
Bearbeitungen
Änderungen
Zur Navigation springen
Zur Suche springen
=== Ablauf einer Abfrage ===# Login-Anfrage mit eMail Email und Passwort senden# Aus Antwort <code>user token</code> auslesen# Anfrage für Gruppen- oder Personendaten senden (mit eMail Email und <code>user token</code>)# Aus Antwort gewünschte Daten auslesen'''Wichtig''': Passwörter dürfen nicht hardcoded im Programmcode hinterlegt werden. Passwörter im Programmcode sind eine 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.
Information zum Tool "cevi-versand" (Ich denke, das passt hier rein, da das RV Spender-Tool ja auch hier erwähnt wird?)
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.
=== Allgemeine Hinweisee 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.
====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:
* Ein Cevi-Logo auf den Umschlag drucken.
* Personen die zusammen wohnen in ein gemeinsames Couvert bringen. Das bedeutet weniger Arbeit beim Verpacken.
* Fehlerhafte Einträge in der DB finden - beispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohnt.
* Cevinamen und dazugehörige Stufennamen aufdrucken. Das vereinfacht das verteilen, wenn man nicht alle Empfänger gut kennt.
* Aufdrucken wie viele Leiter/Teilnehmer im Umschlag sind. Das vereinfacht das verpacken, wenn man nicht alle Empfänger gut kennt.
[https://github.com/lucidBrot/cevi-versand cevi-versand] ist open-source und gratis zu benutzen, aber Spenden werden geschätzt :)
===Ablauf einer Abfrage===
'''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">
import requests
email = "ceviname@cevi.ch"
passwort = "123456"
res = requests.post('https://db.cevi.ch/users/sign_in.json?person[email]='+email+'&person[password]='+passwort)
token = res.json()["people"][0]["authentication_token"]
</syntaxhighlight>
'''Shell:'''
<syntaxhighlight lang="bash" line="1">
wget --post-data 'person[email]=ceviname@cevi.ch&person[password]=123456' -o result.json https://db.cevi.ch/users/sign_in.json
cat result.json
</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"
!Request Typ
!URL
|-
|post
|https://db.cevi.ch/users/token.json
|-
|delete
|https://db.cevi.ch/users/token.json
|}
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:
*als URL-Parameter: <code>.json?user_email=ceviname@cevi.ch&user_token=== Beispiele ====123456</code>TODO*als Headers: <code>X-User-Email: ceviname@cevi.ch, X-User-Token: 123456</code> und <code>Accept: application/json</code>
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">import requests# vor diesem Teil muss natürlich das Token ausgelesen und gespeichert werdenemail = "ceviname@cevi.ch"token= "1a2b3c"res = requests.post('https://db.cevi.ch/groups/5/people.json?user_email='+email+'&user_token='+token)data = res.json()["people"]</syntaxhighlight>Normale Anfrage mit der Shell:<syntaxhighlight lang="bash" line="line">wget --header "X-User-Email: ceviname@cevi.ch" --header "X-User-Token: 1a2b3c" \ --header "Accept: application/json" https://db.cevi.ch/groups/5/people.json -O people.jsoncat people.json</syntaxhighlight>Anfrage mit Sortierung mit Python:<syntaxhighlight lang="python" line="line"># nach Login, Variable token ist definiert# gewünscht ist eine Sortierung nach Rollen# der Teil sort=roles&sort_dir=asc sortiert nun nach den Rollen, die höchste (z.B. AL) ist dann auch im json-File zuerst drin.res = requests.get('https://db.cevi.ch/groups/5/people.json?sort=roles&sort_dir=asc&user_email=ceviname@cevi.ch&user_token='+token)data = res.json()['people']</syntaxhighlight>Anfrage mit Rollenauswahl mit Python:<syntaxhighlight lang="python" line="line"># nach Login, Variable token ist definiert# gewünscht ist eine Sortierung nach Rollen und eine Auswahl (nur AL)# der Teil sort=roles&sort_dir=asc sortiert nun nach den Rollen.# der Teil filters[role][finish_at]=&filters[role][role_type_ids]=35&filters[role][start_at]=&name=&range=deep grenzt die Rollen ein.res = requests.get('https://db.cevi.ch/groups/5/people.json?filters[role][finish_at]=&filters[role][role_type_ids]=35&filters[role][start_at]=&name=&range=deep&sort=roles&sort_dir=asc&user_email=ceviname@cevi.ch&user_token='+token)data = res.json()['people'] #ist hier leer, da auf der Geschäfsstelle (Gruppe 5) keine Abteilungsleiter erfasst sind.</syntaxhighlight>=== Endpunkte ====
{| class="wikitable"
!Endpunkt
|Gruppen <code><gid></code>
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>.json
|<nowiki>https://db.cevi.ch/groups/1.json</nowiki>
|-
|Personen in Gruppe <code><gid></code>
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people.json
|<nowiki>https://db.cevi.ch/groups/1/people.json</nowiki>
|-
|Details zu Person <code><pid></code>
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people/<pid>.json
|<nowiki>https://db.cevi.ch/groups/1/people/2.json</nowiki>
|}
'''Hinweis: '''Wird versucht ohne Gruppen-Angabe auf eine Person zuzugreifen (<code><nowiki>https://db.cevi.ch/people/</nowiki><pid>.json</code>) so wird die Anfrage auf die Haubtgruppe Hauptgruppe der Person weitergeleitet. Allerdings wird bei dieser Weiterleitung der Query-String ignoriert, so dass ein <code>401 Authorization Required</code> Fehler resultiert. Aus der Fehlermeldung kann jedoch die korrekte <abbr>URL</abbr> bestimmt werden.[[Kategorie:CeviDB]]
