https://wiki.cevi.ch/api.php?action=feedcontributions&user=Levanzo&feedformat=atomCeviWiki - Benutzerbeiträge [de]2024-03-29T05:17:30ZBenutzerbeiträgeMediaWiki 1.33.0https://wiki.cevi.ch/index.php?title=Cevi.DB_API&diff=6749Cevi.DB API2020-01-17T17:25:09Z<p>Levanzo: Information zum Tool "cevi-versand" (Ich denke, das passt hier rein, da das RV Spender-Tool ja auch hier erwähnt wird?)</p>
<hr />
<div>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.<br />
<br />
===Allgemeine Hinweise===<br />
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.<br />
====Tools====<br />
=====Spender-Tool des RV=====<br />
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.<br />
=====Couvertgenerator=====<br />
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:<br />
* Ein Cevi-Logo auf den Umschlag drucken.<br />
* Personen die zusammen wohnen in ein gemeinsames Couvert bringen. Das bedeutet weniger Arbeit beim Verpacken.<br />
* Fehlerhafte Einträge in der DB finden - beispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohnt.<br />
* Cevinamen und dazugehörige Stufennamen aufdrucken. Das vereinfacht das verteilen, wenn man nicht alle Empfänger gut kennt.<br />
* Aufdrucken wie viele Leiter/Teilnehmer im Umschlag sind. Das vereinfacht das verpacken, wenn man nicht alle Empfänger gut kennt.<br />
[https://github.com/lucidBrot/cevi-versand cevi-versand] ist open-source und gratis zu benutzen, aber Spenden werden geschätzt :)<br />
===Ablauf einer Abfrage===<br />
<br />
#Login-Anfrage mit Email und Passwort senden<br />
#Aus Antwort <code>user token</code> auslesen<br />
#Anfrage für Gruppen- oder Personendaten senden (mit Email und <code>user token</code>)<br />
#Aus Antwort gewünschte Daten auslesen<br />
<br />
'''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.<br />
<br />
===Erstes Login===<br />
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.<br />
====Beispiele====<br />
'''Python:'''<br />
<syntaxhighlight lang="python" line="line"><br />
import requests<br />
email = "ceviname@cevi.ch"<br />
passwort = "123456"<br />
res = requests.post('https://db.cevi.ch/users/sign_in.json?person[email]='+email+'&person[password]='+passwort)<br />
token = res.json()["people"][0]["authentication_token"]<br />
</syntaxhighlight><br />
'''Shell:'''<br />
<syntaxhighlight lang="bash" line="1"><br />
wget --post-data 'person[email]=ceviname@cevi.ch&person[password]=123456' -o result.json https://db.cevi.ch/users/sign_in.json<br />
cat result.json<br />
</syntaxhighlight><br />
'''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.<br />
===User Token verwalten===<br />
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:<br />
{| class="wikitable"<br />
!Request Typ<br />
!URL<br />
|-<br />
|post<br />
|https://db.cevi.ch/users/token.json<br />
|-<br />
|delete<br />
|https://db.cevi.ch/users/token.json<br />
|}<br />
Als Parameter müssen wie beim Login <code>person[email]</code> und <code>person[password]</code> übergeben werden.<br />
===Daten abfragen===<br />
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><br />
Bei jeder Abfrage müssen zudem die Email-Adresse und das <code>user token</code> mitgesendet werden. Dazu bestehen zwei Möglichkeiten:<br />
<br />
*als URL-Parameter: <code>.json?user_email=ceviname@cevi.ch&user_token=123456</code><br />
*als Headers: <code>X-User-Email: ceviname@cevi.ch, X-User-Token: 123456</code> und <code>Accept: application/json</code><br />
<br />
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>.<br />
====Beispiele====<br />
Normale Abfrage mit Python:<br />
<syntaxhighlight lang="python" line="1"><br />
import requests<br />
# vor diesem Teil muss natürlich das Token ausgelesen und gespeichert werden<br />
email = "ceviname@cevi.ch"<br />
token= "1a2b3c"<br />
res = requests.post('https://db.cevi.ch/groups/5/people.json?user_email='+email+'&user_token='+token)<br />
data = res.json()["people"]<br />
</syntaxhighlight><br />
Normale Anfrage mit der Shell:<br />
<syntaxhighlight lang="bash" line="line"><br />
wget --header "X-User-Email: ceviname@cevi.ch" --header "X-User-Token: 1a2b3c" \<br />
--header "Accept: application/json" https://db.cevi.ch/groups/5/people.json -O people.json<br />
cat people.json<br />
</syntaxhighlight><br />
Anfrage mit Sortierung mit Python:<br />
<syntaxhighlight lang="python" line="line"><br />
# nach Login, Variable token ist definiert<br />
# gewünscht ist eine Sortierung nach Rollen<br />
# 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.<br />
res = requests.get('https://db.cevi.ch/groups/5/people.json?sort=roles&sort_dir=asc&user_email=ceviname@cevi.ch&user_token='+token)<br />
data = res.json()['people']<br />
</syntaxhighlight><br />
Anfrage mit Rollenauswahl mit Python:<br />
<syntaxhighlight lang="python" line="line"><br />
# nach Login, Variable token ist definiert<br />
# gewünscht ist eine Sortierung nach Rollen und eine Auswahl (nur AL)<br />
# der Teil sort=roles&sort_dir=asc sortiert nun nach den Rollen.<br />
# der Teil filters[role][finish_at]=&filters[role][role_type_ids]=35&filters[role][start_at]=&name=&range=deep grenzt die Rollen ein.<br />
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)<br />
data = res.json()['people'] #ist hier leer, da auf der Geschäfsstelle (Gruppe 5) keine Abteilungsleiter erfasst sind.<br />
</syntaxhighlight><br />
===Endpunkte===<br />
{| class="wikitable"<br />
!Endpunkt<br />
!URL<br />
!Beispiel (gid=1, pid=2)<br />
|-<br />
|Gruppen <code><gid></code><br />
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>.json<br />
|<nowiki>https://db.cevi.ch/groups/1.json</nowiki><br />
|-<br />
|Personen in Gruppe <code><gid></code><br />
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people.json<br />
|<nowiki>https://db.cevi.ch/groups/1/people.json</nowiki><br />
|-<br />
|Details zu Person <code><pid></code><br />
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people/<pid>.json<br />
|<nowiki>https://db.cevi.ch/groups/1/people/2.json</nowiki><br />
|}<br />
'''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 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.<br />
[[Kategorie:CeviDB]]</div>Levanzohttps://wiki.cevi.ch/index.php?title=Diskussion:Cevi.DB_API&diff=5441Diskussion:Cevi.DB API2019-09-23T17:48:19Z<p>Levanzo: Die Seite wurde neu angelegt: „Inkonsistenzen in den request endpoint URLs: Die Tabelle am Schluss spricht von https://db.cevi.ch/1/people.json, das codebeispiel spricht von https://db.cevi.…“</p>
<hr />
<div>Inkonsistenzen in den request endpoint URLs: Die Tabelle am Schluss spricht von https://db.cevi.ch/1/people.json, das codebeispiel spricht von https://db.cevi.ch/groups/1/people.json .<br />
Ersteres existiert nicht, letzteres existiert (und funktioniert im browser auch, wenn man eingeloggt ist) -[[Benutzer:Levanzo|Levanzo]] ([[Benutzer Diskussion:Levanzo|Diskussion]])</div>Levanzohttps://wiki.cevi.ch/index.php?title=Benutzer:Levanzo&diff=706Benutzer:Levanzo2018-08-03T10:36:31Z<p>Levanzo: Formatierung</p>
<hr />
<div>Eric Mink<br />
<br />
v/o Levanzo<br />
<br />
Abteilung Pfäffikon-Fehraltorf-Russikon Hittnau (PFA)<br />
<br />
Stufe Holon</div>Levanzohttps://wiki.cevi.ch/index.php?title=Benutzer:Levanzo&diff=705Benutzer:Levanzo2018-08-03T10:35:54Z<p>Levanzo: Die Seite wurde neu angelegt: „Eric Mink v/o Levanzo Abteilung Pfäffikon-Fehraltorf-Russikon Hittnau (PFA) Stufe Holon“</p>
<hr />
<div>Eric Mink<br />
v/o Levanzo<br />
Abteilung Pfäffikon-Fehraltorf-Russikon Hittnau (PFA)<br />
Stufe Holon</div>Levanzohttps://wiki.cevi.ch/index.php?title=CeviWiki_Diskussion:Guidelines&diff=704CeviWiki Diskussion:Guidelines2018-08-03T10:35:14Z<p>Levanzo: Diskussion: Macht Guideline zu Dateien hochladen Sinn?</p>
<hr />
<div><blockquote><br />
Externe Dokumente, welche bereits online vorhanden sind, sollen verlinkt statt neu hochgeladen werden.<br />
</blockquote><br />
Macht diese Guideline Sinn? Das fördert die Chancen auf [https://en.wikipedia.org/wiki/Link_rot Link-rot], also dass die Seiten und Links mit der Zeit nicht mehr funktionieren wegen externen Änderungen. [[Benutzer:Levanzo|Levanzo]] ([[Benutzer Diskussion:Levanzo|Diskussion]])</div>Levanzo