Änderungen

Die CeviDB 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 CeviDB zu verändernmöglich.

==OAuth Provider=Allgemeine Hinweise=Die Cevi.DB kann als OAuth Provider genutzt werden. Dies benötigt allerdings eine Konfiguration seitens Cevi.DB Steuergruppe. Melde Dich dafür bei cevidb(at)cevi.ch. ==API Nutzung==Die REST-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 offizielle Dokumentation findet ihr auch auf Github: [https://github.com/nchiapolhitobito/hitobito/cevidbtool Github] heruntergeladen werden.=====Couvertgenerator=====Das Tool [https:blob/master/github.comdoc/lucidBrotdevelopment/cevi-versand cevi-versand05_rest_api.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 '''Wichtig''':* Ein Cevi-Logo auf den Umschlag druckenPasswörter dürfen nicht hardcoded im Programmcode hinterlegt werden.* Personen die zusammen wohnen in Passwörter im Programmcode sind ein gemeinsames Couvert bringenSicherheitsrisiko. Das bedeutet weniger Arbeit beim VerpackenSoll ein Programm ohne Interaktion mit einem Benutzer ausgeführt werden, so kann das <code>user token</code> im Programmcode hinterlegt werden.* Fehlerhafte Einträge in der DB finden - beispielsweise warnt Gelingt es einem Angreifer, das ToolToken auszulesen, wenn jemand in keiner Ortschaft wohntso erhält er nur eingeschränkte Lese-Rechte.* Cevinamen und dazugehörige Stufennamen aufdrucken. Das vereinfacht das verteilenEin gestohlenes Passwort würde ihm erlauben, wenn man nicht alle Empfänger gut kenntsich mit den vollen Benutzerrechten des Besitzers einzuloggen.* Aufdrucken wie viele Leiter/Teilnehmer im Umschlag sindBitte informiert cevidb(at)cevi. Das vereinfacht das verpackench, wenn man nicht alle Empfänger gut kenntihr ein Skript erstellt und ein <code>user token</code> hinterlegt.[https://github.com/lucidBrot/cevi-versand cevi-versand] ist open-source und gratis zu benutzen, aber Spenden werden geschätzt :)===Ablauf einer AbfrageAuthentifizierung===Zur Nutzung der API ist ein Token notwendig. Momentan gibt es zwei Arten von Tokens.

#Login====User-Anfrage mit Email und Passwort sendenTokens====#Aus Antwort <code>user token</code> auslesen#Anfrage für Gruppen'''============== !! User- oder Personendaten senden (Token wurden mit Email und <code>user token</code>)#Aus Antwort gewünschte Daten auslesendem Update vom 2024-01-09 deaktiviert!! ============== '''

'''Wichtig''': Passwörter dürfen nicht hardcoded im Programmcode hinterlegt werden. Passwörter im Programmcode sind Dies ist ein Sicherheitsrisikopersönliches Token. Soll ein Programm ohne Interaktion mit einem Benutzer ausgeführt werdenDas heisst, 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 hat den vollen Benutzerrechten des Besitzers einzuloggen. Bitte informiert [mailto:cevidb@cevi.ch cevidb@cevigleichen Zugriff (lesen) wie der Ersteller.ch], wenn ihr ein Skript erstellt und ein <code>user token</code> hinterlegtAuf lange Sicht wird diese Art eventuell auch wieder abgeschaltet.

===Erstes Login===Um sich anzumelden, muss ein POST-Das Token erhältst du mit folgendem 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="pythonbash" line="line1">import requestsemail = "ceviname@cevi.ch"passwort = "123456"res = requests.post('wget -O- https://db.cevi.ch/users/sign_in.json?--post-data 'person[email]='+email+'<YOURUSERNAME>&person[password]=<YOURPASSWORD>'+passwort)token = res.json()["people"][0]["authentication_token"]

'''Shell:'''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><syntaxhighlight langURL>?user_email="bash" line<YOURUSERNAME>&user_token="1"<YOURTOKEN></code>) oder im HTTP Header (bevorzugt da sicherer, <code>wget X-User-post-data 'person[email]=Email: ceviname@cevi.ch&person, X-User-Token: 123456</code>) übergeben werden. ====Service-Tokens (empfohlen)====Dies ist die neue Art der Authentifizierung. Sie ändern momentan recht schnell, aus diesem Grund verweisen wir hier nur auf die "offizielle" Dokumentation auf Github: [passwordhttps://github.com/hitobito/hitobito/blob/master/doc/development/07_service_accounts.md]=123456' . Das Token kann jeweils von den Abteilungsleitern auf der Ortsgruppe im Reiter Einstellungen mit der Schaltfläche "API-o result.json Keys" erstellt werden (<nowiki>https://db.cevi.ch/usersgroups/GRUPPENID/sign_in.jsoncat result.jsonservice_tokens</syntaxhighlightnowiki>'''Wichtig''': Damit ). Dabei kann sowohl der Scope (z. B. aktuelle Ebene oder auch darunterliegende) wie auch die https-Verbindung klapptRechte (z. B. Gruppen lesen, Personen lesen, Anlässe lesen, 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 Token muss bei den Abfragen jeweils wie folgt übergeben werden: <code>user <URL>?token=<YOURTOKEN></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:===Endpunkte===

!Request TypEndpunkt

|postEvents <code><eid></code>|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/events/<eid>/participations.json|<nowiki>https://db.cevi.ch/usersgroups/1/events/token3/participations.json</nowiki>|Über den Events-Endpunkt können auch die Fragen, welche beim Anlass/Kurs erfasst sind, abgefragt werden. Diese sind im json zu finden.

|deleteUser Token verwalten

Als Parameter müssen wie beim Login ===Beispiele (mit User Tokens)=== ====User Token ermitteln====Python:<codesyntaxhighlight lang="python" line="line">import requestsemail = "ceviname@cevi.ch"passwort = "123456"res = requests.post('https://db.cevi.ch/users/sign_in.json?person[email]</code> und <code>='+email+'&person[password]='+passwort)token = res.json()["people"][0]["authentication_token"]</codesyntaxhighlight> übergeben '''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. ====Daten abfragen====

Weiter können weitere GET-Parameter (analog zur “richtigen” CeviDBCevi.DB) angehängt werden. Am besten führt man das Gewünschte in der CeviDB Cevi.DB aus (zum Beispiel Sortieren nach Rollen) und kopiert die URL, ändert die Endung zu <code>.json</code>.====Beispiele====

<syntaxhighlight lang="python" line="line1">

==Tools=Endpunkte==={| class="wikitable"!Endpunkt!URL!Beispiel Spender-Tool des RV (gidcevidbtool)==1, pid=2)|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://dbgithub.cevi.chcom/groupsnchiapol/1cevidbtool Github] heruntergeladen werden.json</nowiki>|===Couvertgenerator (cevi-versand)===|Personen in Gruppe <code><gid></code>|<nowiki>Das Tool [https://dbgithub.com/lucidBrot/cevi-versand cevi-versand] erstellt nach einmaligem einrichten mit minimalem manuellen Aufwand PDFs um Couverts für den Versand zu drucken.ch/groups/</nowiki><gid>/peopleDafür verwendet es auch die API.jsonUnter anderem kann man damit:|<nowiki>https://db*Ein Cevi-Logo auf den Umschlag drucken.cevi*Personen die zusammen wohnen in ein gemeinsames Couvert bringen.ch/groups/1/peopleDas bedeutet weniger Arbeit beim Verpacken.json</nowiki>|*Fehlerhafte Einträge in der DB finden -beispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohnt.|Details zu Person <code><pid></code>|<nowiki>https://db*Cevinamen und dazugehörige Stufennamen aufdrucken.ceviDas vereinfacht das verteilen, wenn man nicht alle Empfänger gut kennt.ch/groups/</nowiki><gid>/people/<pid>.json|<nowiki>https:*Aufdrucken wie viele Leiter//dbTeilnehmer im Umschlag sind.cevi.ch/groups/1/people/2Das vereinfacht das verpacken, wenn man nicht alle Empfänger gut kennt.json</nowiki>|}'''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:CeviDBCevi.DB]]