Hauptmenü öffnen
CeviWiki

Änderungen

Cevi.DB API

804 Bytes entfernt, 15:30, 12. Feb. 2023
Ich habe versucht die bestehenden Inhalte etwas klarer zu strukturieren. Dabei habe ich auch die Authentifizierung als eigenes Kapitel extrahiert. Ausgangslage war dabei meine Situation. Ich bin ein Softwareentwickler der die Cevi.DB API nicht kennt. Als ich die Seite zum ersten Mal aufrief war es für mich etwas unklar. So wie diese jetzt strukturiert ist glaube ich das der Einstieg deutlich einfacher ist.
Die Cevi.DB bietet eine <abbr>API</abbr>, mit der Personen- und Gruppen-Daten aus der Datenbank ausgelesen werden können. Die <abbr>Datenveränderungen sind über die API</abbr> erlaubte es aber hingegen '''nicht''', Daten in der Cevi.DB zu verändern. Es gibt zwei Methoden, um Daten automatisiert auszulesen. Beide sind hier kurz erklärtmöglich.
===User-Tokens=API Nutzung ==Dies ist ein Token, dass persönlich istDie REST-Schnittstelle wird über POST- und GET-Anfragen angesteuert und verwendet [http://de. Das heisst, es hat den gleichen Zugriff (lesen) wie der Erstellerwikipedia. Auf lange Sicht wird diese Art eventuell org/wiki/JavaScript_Object_Notation JSON] als Datenformat. Die offizielle Dokumentation findet ihr auch wieder abgeschaltetauf Github: [https://github.com/hitobito/hitobito/blob/master/doc/development/05_rest_api.md].
===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'''Wichtig''': [https://githubPasswörter dürfen nicht hardcoded im Programmcode hinterlegt werden.com/hitobito/hitobito/blob/master/doc/development/07_service_accountsPasswörter im Programmcode sind ein Sicherheitsrisiko.md]. Für die Service Tokens Soll ein Programm ohne Interaktion mit einem Benutzer ausgeführt werden, so kann ganz genau eingestellt das <code>user token</code> im Programmcode hinterlegt werden. Gelingt es einem Angreifer, das Token auszulesen, welche Berechtigungen sie habenso erhält er nur eingeschränkte Lese-Rechte. Sie können auf einer Gruppe erstellt werden (auf der Gruppe im Menu oben auf "Api-Keys"Ein gestohlenes Passwort würde ihm erlauben, <nowiki>https://dbsich mit den vollen Benutzerrechten des Besitzers einzuloggen.Bitte informiert cevidb(at)cevi.ch/groups/GRUPPE/service_tokens, wenn ihr ein Skript erstellt und ein <code>user token</nowikicode>) hinterlegt.
<br />=== Authentifizierung ===Zur Nutzung der API ist ein Token notwendig. Momentan gibt es zwei Arten von Tokens.
===API=User-Tokens====Die API wird von beidenDies ist ein persönliches Token. Das heisst, User-Tokens und Service-Tokens verwendetes hat den gleichen Zugriff (lesen) wie der Ersteller. Die offizielle Dokumentation finded ihr Auf lange Sicht wird diese Art eventuell auch auf Githubwieder abgeschaltet. Das Token erhältst du mit folgendem Request: [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" line="1">user_email=info@wget -O- https://db.cevi.ch&user_token/users/sign_in.json --post-data 'person[email]=AABBCC</syntaxhighlightYOURUSERNAME>hin zu&person[password]=<syntaxhighlight lang="bash"YOURPASSWORD>token=DDEEFF'
</syntaxhighlight>
Das User-Token ist im Property "authentication_token" im JSON der Antwort enthalten. Das Token bleibt konstant und kann daher auch über längere Zeit verwendet werden.
Das Token muss bei den Abfragen entweder als Query Parameter (<code><URL>?user_email=<YOURUSERNAME>&user_token===Allgemeine Hinweise====Die Schnittstelle wird über POST<YOURTOKEN></code>) oder im HTTP Header (bevorzugt da sicherer, <code>X- und GETUser-Anfragen angesteuert und verwendet [httpEmail://deceviname@cevi.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 tokench, X-User-Token: 123456</code> generiert, das danach bei jeder Anfrage mitgesendet ) übergeben werden muss.
=====Tools===========SpenderService-Tool des RV==Tokens (empfohlen)====Die API wird vom Spender-Tool des RVs verwendet. Das Tool Dies ist in Python geschrieben und ist freie Softwaredie neue Art der Authentifizierung. Es kann von Sie ändern momentan recht schnell, aus diesem Grund verweisen wir hier nur auf die "offizielle" Dokumentation auf Github: [https://github.com/nchiapolhitobito/hitobito/cevidbtool Github] heruntergeladen werden.======Couvertgenerator======Das Tool [https:blob/master/github.comdoc/lucidBrotdevelopment/cevi-versand cevi-versand07_service_accounts.md] 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 CeviDas Token kann jeweils von den Abteilungsleitern auf der Ortsgruppe im Reiter Einstellungen mit der Schaltfläche "API-Logo auf den Umschlag druckenKeys" erstellt werden (<nowiki>https://db.*Personen die zusammen wohnen in ein gemeinsames Couvert bringencevi. Das bedeutet weniger Arbeit beim Verpackench/groups/GRUPPENID/service_tokens</nowiki>).*Fehlerhafte Einträge in Dabei kann sowohl der DB finden - beispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohntScope (z. B. aktuelle Ebene oder auch darunterliegende) wie auch die Rechte (z.*Cevinamen und dazugehörige Stufennamen aufdruckenB. Das vereinfacht das verteilenGruppen lesen, Personen lesen, Anlässe lesen, 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.) definiert werden.
[Das Token muss bei den Abfragen jeweils wie folgt übergeben werden: <code><URL>?token=<YOURTOKEN></code>===Endpunkte==={| class="wikitable"!Endpunkt!URL!Beispiel (gid=1, pid=2, eid=3)!Hinweise|-|Gruppen <code><gid></code>|<nowiki>https://githubdb.comcevi.ch/lucidBrotgroups/</nowiki><gid>.json|<nowiki>https://db.cevi.ch/groups/1.json</nowiki>||-versand |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>||-versand] ist open|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>|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.|-|Events <code><eid></code>|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/events/<eid>/participations.json|<nowiki>https://db.cevi.ch/groups/1/events/3/participations.json</nowiki>|Über den Events-source und gratis Endpunkt können auch die Fragen, welche beim Anlass/Kurs erfasst sind, abgefragt werden. Diese sind im json zu benutzenfinden.|-|User Token verwalten|https://db.cevi.ch/users/token.json||Bei einem post request wird ein neues erstellt, aber Spenden bei einem delete Request wird das bestehende gelöscht. Als Parameter müssen wie beim Login <code>person[email]</code> und <code>person[password]</code> übergeben werden geschätzt :).|}====Ablauf einer Abfrage=Beispiele (mit User Tokens)===
#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 cevidb(at)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=User Token ermitteln ===='''Python:'''<syntaxhighlight lang="python" line="line">
import requests
email = "ceviname@cevi.ch"
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.jsoncat 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>
Weiter können weitere GET-Parameter (analog zur “richtigen” Cevi.DB) angehängt werden. Am besten führt man das Gewünschte in der Cevi.DB 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">
data = res.json()['people'] #ist hier leer, da auf der Geschäfsstelle (Gruppe 5) keine Abteilungsleiter erfasst sind.
</syntaxhighlight>
==Tools==Endpunkte===={| class="wikitable"!Endpunkt!URL!Beispiel Spender-Tool des RV (gidcevidbtool)=1, pid=2, eid=3)|Die API wird vom Spender-|Gruppen <code><gid></code>|<nowiki>https://dbTool des RVs verwendet.ceviDas Tool ist in Python geschrieben und ist freie Software.ch/groups/</nowiki><gid>.json|<nowiki>Es kann von [https://db.cevigithub.chcom/groupsnchiapol/1cevidbtool Github] heruntergeladen werden.json</nowiki>|===Couvertgenerator (cevi-versand)===|Personen in Gruppe <code><gid></code>|<nowiki>Das Tool [https://dbgithub.cevi.chcom/groupslucidBrot/</nowiki><gid>/people.json|<nowiki>https://db.cevi-versand cevi-versand] erstellt nach einmaligem einrichten mit minimalem manuellen Aufwand PDFs um Couverts für den Versand zu drucken.ch/groups/1/peopleDafür verwendet es auch die API.json</nowiki>Unter anderem kann man damit: |*Ein Cevi-|Details zu Person <code><pid></code>|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people/<pid>Logo auf den Umschlag drucken.json|<nowiki>https://db*Personen die zusammen wohnen in ein gemeinsames Couvert bringen.ceviDas bedeutet weniger Arbeit beim Verpacken.ch/groups/1/people/2.json</nowiki>|*Fehlerhafte Einträge in der DB finden -|Events <code><eid></code>|<nowiki>https://dbbeispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohnt.cevi.ch/groups/</nowiki><gid>/events/<eid>/participations.json|<nowiki>https://db*Cevinamen und dazugehörige Stufennamen aufdrucken.cevi.ch/groups/1/events/3/participationsDas vereinfacht das verteilen, wenn man nicht alle Empfänger gut kennt.json</nowiki>|}Über den Events-Endpunkt können auch die Fragen, welche beim Anlass*Aufdrucken wie viele Leiter/Kurs erfasst Teilnehmer im Umschlag sind. Das vereinfacht das verpacken, abgefragt werden. Diese sind im json zu findenwenn man nicht alle Empfänger gut kennt.
'''Hinweis: '''Wird versucht ohne Gruppen-Angabe auf eine Person zuzugreifen (<code><nowiki>[https://dbgithub.cevi.chcom/peoplelucidBrot/</nowiki><pid>.json</code>) so wird die Anfrage auf die Hauptgruppe der Person weitergeleitet. Allerdings wird bei dieser Weiterleitung der Querycevi-versand cevi-versand] ist open-String ignoriertsource und gratis zu benutzen, so dass ein <code>401 Authorization Required</code> Fehler resultiert. Aus der Fehlermeldung kann jedoch die korrekte <abbr>URL</abbr> bestimmt aber Spenden werden.geschätzt :)
[[Kategorie:CeviDB]]
Abgerufen von „https://wiki.cevi.ch/index.php/Spezial:Mobiler_Unterschied/7392“