Ä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ändern. Es gibt zwei Methoden, um Daten automatisiert auszulesen. Beide sind hier kurz erklärtmöglich.

===User-Tokens=OAuth Provider==Die Cevi.DB kann als OAuth Provider genutzt werden. Dies ist ein Token, dass persönlich istbenötigt allerdings eine Konfiguration seitens Cevi.DB Steuergruppe. Das heisst, es hat den gleichen Zugriff Melde Dich dafür bei cevidb(lesenat) wie der Erstellercevi. Auf lange Sicht wird diese Art eventuell auch wieder abgeschaltetch.

===Service-Tokens=API Nutzung==Dies ist die neue Version der AbfragenDie REST-Schnittstelle wird über POST- und GET-Anfragen angesteuert und verwendet [http://de.wikipedia.org/wiki/JavaScript_Object_Notation JSON] als Datenformat. Sie ändern momentan recht schnell, aus diesem Grund verweisen wir hier nur auf die "ofizielle" Die offizielle Dokumentation findet ihr auch auf Github: [https://github.com/hitobito/hitobito/blob/master/doc/development/07_service_accounts05_rest_api.md]. Für die Service Tokens kann ganz genau eingestellt werden, welche Berechtigungen sie haben. Sie können auf einer Gruppe erstellt werden (auf der Gruppe im Menu oben auf "Api-Keys", <nowiki>https://db.cevi.ch/groups/GRUPPE/service_tokens</nowiki>)

'''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<br /code> hinterlegt.

===APIAuthentifizierung===Die Zur Nutzung der API wird von beiden, User-Tokens und Service-Tokens verwendet. Die offizielle Dokumentation finded ihr auch auf Github: [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 geschriebenist ein Token notwendig. Für den Gebrauch Momentan gibt es zwei Arten von Service-Tokens ändern sich die Endpunkte nicht, nur die Parameter ändern sich von <syntaxhighlight lang="bash">user_email=info@cevi.ch&user_token=AABBCC</syntaxhighlight>hin zu<syntaxhighlight lang="bash">token=DDEEFF</syntaxhighlight>

====Allgemeine HinweiseUser-Tokens====Die Schnittstelle wird über POST'''============== !! User-Token wurden mit dem Update vom 2024- und GET01-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.09 deaktiviert!! ============== '''

=====Tools===========Spender-Tool des RV======Die API wird vom Spender-Tool des RVs verwendet. Das Tool Dies ist in Python geschrieben und ist freie Software. Es kann von [https://github.com/nchiapol/cevidbtool Github] heruntergeladen werdenein persönliches Token.======Couvertgenerator======Das Tool [https://github.com/lucidBrot/cevi-versand cevi-versand] erstellt nach einmaligem einrichten mit minimalem manuellen Aufwand PDFs um Couverts für heisst, es hat den Versand zu druckengleichen Zugriff (lesen) wie der Ersteller. Dafür verwendet es Auf lange Sicht wird diese Art eventuell auch die APIwieder abgeschaltet. 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.Token erhältst du mit folgendem Request:<syntaxhighlight lang="bash" line="1">*Fehlerhafte Einträge in der DB finden wget -O- beispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohnthttps://db.*Cevinamen und dazugehörige Stufennamen aufdruckencevi. Das vereinfacht das verteilen, wenn man nicht alle Empfänger gut kenntch/users/sign_in.json --post-data 'person[email]=<YOURUSERNAME>&person[password]=<YOURPASSWORD>'*Aufdrucken wie viele Leiter</Teilnehmer syntaxhighlight>Das User-Token ist im Umschlag sindProperty "authentication_token" im JSON der Antwort enthalten. Das vereinfacht das verpacken, wenn man nicht alle Empfänger gut kenntToken bleibt konstant und kann daher auch über längere Zeit verwendet werden.

[https:Das Token muss bei den Abfragen entweder als Query Parameter (<code><URL>?user_email=<YOURUSERNAME>&user_token=<YOURTOKEN><//github.com/lucidBrot/cevicode>) oder im HTTP Header (bevorzugt da sicherer, <code>X-User-versand Email: ceviname@cevi.ch, X-versand] ist openUser-source und gratis zu benutzen, aber Spenden werden geschätzt Token:123456</code>)====Ablauf einer Abfrage====übergeben werden.

#Login====Service-Anfrage mit Email und Passwort sendenTokens (empfohlen)====#Aus Antwort <code>user token<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: [https://github.com/hitobito/hitobito/blob/master/doc/code> auslesen#Anfrage für Gruppen- oder Personendaten senden (mit Email und <code>user token<development/code>)#Aus Antwort gewünschte Daten auslesen07_service_accounts.md].

'''Wichtig''': Passwörter dürfen nicht hardcoded im Programmcode hinterlegt werden. Passwörter Das Token kann jeweils von den Abteilungsleitern auf der Ortsgruppe im Programmcode sind ein Sicherheitsrisiko. Soll ein Programm ohne Interaktion Reiter Einstellungen mit einem Benutzer ausgeführt der Schaltfläche "API-Keys" erstellt werden, so kann das (<codenowiki>user tokenhttps://db.cevi.ch/groups/GRUPPENID/service_tokens</codenowiki> im Programmcode hinterlegt werden). Dabei kann sowohl der Scope (z. B. aktuelle Ebene oder auch darunterliegende) wie auch die Rechte (z. B. Gelingt es einem AngreiferGruppen lesen, das Token auszulesenPersonen lesen, so erhält er nur eingeschränkte Lese-Rechte. Ein gestohlenes Passwort würde ihm erlaubenAnlässe lesen, 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) definiert werden.

====Erstes Login====Um sich anzumelden, Das Token muss ein POST-Request an httpsbei den Abfragen jeweils wie folgt übergeben werden://db.cevi.ch/users/sign_in.json gesendet werden. Als Parameter müssen <code>person[email]</codeURL> und <code>person[password]</code> übergeben werden.=====Beispiele====='''Python:'''<syntaxhighlight lang="python" line="line">import requestsemail = "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"]</syntaxhighlightYOURTOKEN>'''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</syntaxhighlightcode>'''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.===Endpunkte=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:

!Request TypEndpunkt

|postDetails zu Person <code><pid></code>|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people/<pid>.json|<nowiki>https://db.cevi.ch/usersgroups/1/people/token2.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-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. 

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=====

==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://db.cevigithub.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]]