5
Bearbeitungen
Änderungen
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 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.
=== Ablauf einer Abfrage ==Couvertgenerator=====# LoginDas Tool [https://github.com/lucidBrot/cevi-versand cevi-Anfrage versand] erstellt nach einmaligem einrichten mit eMail und Passwort sendenminimalem 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.# Aus Antwort <code>user token</code> auslesen* Personen die zusammen wohnen in ein gemeinsames Couvert bringen. Das bedeutet weniger Arbeit beim Verpacken.# Anfrage für Gruppen* Fehlerhafte Einträge in der DB finden - oder Personendaten senden (mit eMail und <code>user token</code>)beispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohnt.# Aus Antwort gewünschte Daten auslesen'''Wichtig''': Passwörter dürfen * Cevinamen und dazugehörige Stufennamen aufdrucken. Das vereinfacht das verteilen, wenn man nicht hardcoded im Programmcode hinterlegt werdenalle Empfänger gut kennt. Passwörter * Aufdrucken wie viele Leiter/Teilnehmer im Programmcode Umschlag 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 vereinfacht das Token auszulesenverpacken, so erhält er nur eingeschränkte Lese-Rechtewenn man nicht alle Empfänger gut kennt. Ein gestohlenes Passwort würde ihm erlauben, sich mit den vollen Benutzerrechten des Besitzers einzuloggen. Bitte informiert [mailtohttps:cevidb@//github.com/lucidBrot/cevi.ch cevidb@-versand cevi.ch-versand]ist open-source und gratis zu benutzen, wenn ihr ein Skript erstellt und ein <code>user token</code> hinterlegt.aber Spenden werden geschätzt :)===Ablauf einer Abfrage===
#Login-Anfrage mit Email und Passwort senden#Aus Antwort <code>user token</code> auslesen#Anfrage für Gruppen- oder Personendaten senden (mit 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 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>
'''Shell:'''
<syntaxhighlight lang="bash" line="line1">wget --post-data 'person[email]=ceviname@cevi.ch&person[password]=PASSWORT123456' -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"
|}
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=123456</code>* 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 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="line1">
import requests
# vor diesem Teil muss natürlich das Token ausgelesen und gespeichert werden
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:
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]]