GOV/Webservice
GOV-Hauptseite > GOV/Projekt > GOV-Webservice
Projekt GOV |
---|
hier: GOV/Webservice |
GOV-Datenbankabfrage: Infoseiten zum Projekt: Datenerfassung: Kontakt:
Kategorien: |
Zweck
Über Webservices erhält man einen maschinellen Zugriff auf die Daten des GOV, der inhaltlich dem Zugriff über das Webfrontend entspricht. Mit Webservices kann beispielsweise ein geübter Programmierer die Informationen aus GOV in ein genealogisches Programm einbinden. Für das Programm webtrees ist beispielsweise ein entsprechendes Erweiterungsmodul verfügbar ("vesta gov4webtrees").
Um die GOV-Webservices zu nutzen ist keine Authentifizierung nötig.
Lizenz
Das GOV darf unter den Bedingungen der Creative Commons Namensnennung - Weitergabe unter gleichen Bedingungen 4.0 International (CC BY-SA 4.0) Lizenz verwendet werden. |
REST API
Mit einem einfachen Web-Aufruf kann man per REST[1] in JSON[2] dargestellte Informationen zu einer GOV-ID abfragen.
- Man kann mit mit information=position die geografische Position einen Ortes erfragen: http://gov.genealogy.net/api?information=position&id=SCHERGJO54EJ
- Den Namen zu einer GOV-ID kann man mit information=name erfahren: http://gov.genealogy.net/api?information=name&id=SCHERGJO54EJ
- Bei Orten mit Namen in mehreren Sprachen kann mit Hilfe des lang-Parameters angegeben werden, welche Sprache man haben möchte: http://gov.genealogy.net/api?information=name&id=KETORFJO70XW&lang=pol
- Um die kompletten Informationen in JSON zu bekommen, kann man information=data verwenden: http://gov.genealogy.net/api?information=data&id=SCHERGJO54EJ
Eine formale Dokumentation dieser API ist probeweise unter https://gov-dev.genealogy.net/swagger-ui/index.html zu finden.
SOAP API
Es gibt drei Webservices, die auf SOAP[3] basieren
- SimpleService - als Suchergebnis werden Listen mit GOV-Kennungen zurück geliefert
- ComplexService - als Suchergebnis werden Listen zurück geliefert, die die Objekte selbst enthalten
- ChangeService - mit diesem Dienst können Daten im GOV verändert werden
Unter Listen sind hier XML-Strukturen zu verstehen, die mit beschreibenden Tags versehen sind. Die Bedeutung der Tags entspricht der englischen Bedeutung der korrespondierenden Quicktext-Elemente.
Derzeit (Juni 2017) entsteht eine Dokumentation im genealogy.net Forum: http://forum.genealogy.net/?page=Thread&postID=389371 Wenn alle Operationen beschrieben und Fragen geklärt sind, wird die Dokumentation hierher übernommen.
Lesezugriff
Die vom SimpleService und ComplexService zur Verfügung gestellten Funktionen sind (bis auf die Art des Rückgabewertes) identisch, so dass sie hier gemeinsam beschrieben werden.
- checkObjectId
- prüft, ob eine Objektkennung gültig ist. Wenn die abgefragte Objektkennung durch eine andere ersetzt wurde, wird die neue Kennung zurückgeliefert. Wird ein leerer String zurückgeliefert, ist die Objektkennung ungültig.
- getArchive
- lädt ein Archiv-Objekt
- getChildObjects
- untergeordnete Objekte
- getNameAtDate
- Name eines Objektes zu einem anzugebenden Datum in einer anzugebenden Sprache
- getObject
- lädt ein Ort-Objekt
- getObjectByExternalId
- Suche nach Objekt(en) mit Systemkürzel der externen Kennung und Referenznummer
- getParentObjectWithTypeAtDate
- getPositions
- getRecordsForObject
- getSource
- lädt ein Quellen-Objekt
- listTopLevelObjects
- Liste aller Orte, die keinem anderen Objekt zugeordnet sind
- lookupObject
- für FOKO
- searchByBoundingBox
- sucht Orte, die innerhalb einer geographischen Region liegen. Parameter: Breite der einen Ecke, Breite der anderen Ecke, Länge der einen Ecke, Länge der anderen Ecke
- searchByName
- Suche Orte anhand ihres Namens (wie die einfache Suche im Frontend)
- searchByNameAndType
- searchDescendantsByName
- Suche nach untergeordneten Objekten nach Name zu einer übergeordenten ID
- searchDescendantsByNameLanguage
- searchDescendantsByType
- Suche nach untergeordneten Objekten nach Typ zu einem übergeordneten Namen
- searchDescendantsByTypeAtDate
- searchRelatedByName
- Suche nach über-/untergeordneten Objekten nach Name
Die Beschreibung der Funktionen (wsdl:message) mit ihren Parametern (wsdl:part) wird beim Aufruf des jeweiligen Services im Browser angezeigt, z.B. https://gov.genealogy.net/services/ComplexService?wsdl
Schreibzugriff
Der Schreibzugriff beinhaltet Operationen zum Speichern von Orten, Quellen und Archiven. Als erster Parameter wird das zu speichernde Objekt übergeben, der zweite und dritte Parameter sind Benutzername und Passwort des Bearbeiters.
- saveObject
- saveSource
- saveArchive
Kompatibilität
Mit folgenden Frameworks wurde der GOV-Webserivce getestet:
Framework und Version | getestet | vollständig getestet | Bemerkungen | Benutzer |
Axis 1.1 | mit Java 1.4 | Jzedlitz | ||
Axis 1.4 | beim Klassen-Generieren Option "-w" | Jzedlitz | ||
Axis 2.0 | PLingnau | |||
PHP 5 und 7 | Jzedlitz | |||
Python ZSI 1.7.0 | bei mir hat es nur mit einfachen Rückgabewerten funktioniert | Jzedlitz | ||
Python 3.9 Suds | nur das Lesen getestet. | PLingnau |
Client
PHP 5
Mit PHP 5 ist ein Client für den SOAP-Webservice ganz schnell geschrieben:
<?php
$soapclient = new SoapClient('https://gov.genealogy.net/services/ComplexService?wsdl');
$list =$soapclient->searchByName(utf8_encode('Heidkate'));
/* Ausgabe des Arrays */
echo "<pre>";
print_r($list);
echo "</pre>";
?>
PHP 7
Falls der SOAP-Client nicht automatisch installiert ist, muss ein Paket nachinstalliert werden:
sudo apt-get install php-soap
Aufgrund der besseren Unicode-Unterstützung ist der Aufruf noch etwas einfacher geworden:
<?php
$soapclient = new SoapClient('https://gov.genealogy.net/services/ComplexService?wsdl');
$list =$soapclient->searchByName('Heidkate');
/* Ausgabe des Arrays */
echo "<pre>";
print_r($list);
echo "</pre>";
?>
Axis 1.3, Axis 1.4
WSDL2Java hat Probleme mit dem Element-Namen "last-modification". Komischerweise funktioniert es richtig, wenn man WSDL2Java die Option "-w" mitgibt.
Generieren der Java-Klassen:
java org.apache.axis.wsdl.WSDL2Java -w https://gov.genealogy.net/services/ComplexService?wsdl
Ein kleiner Test-Client:
import net.genealogy.gov.ws.ComplexService_PortType;
import net.genealogy.gov.ws.ComplexService_ServiceLocator;
public class Client {
public static void main(String[] args) throws Exception {
ComplexService_PortType cs = new ComplexService_ServiceLocator()
.getComplexService();
cs.searchByName("Heidkate");
}
}
Python Zeep
Für Python gibt es den SOAP-Client Zeep. Unter Ubuntu lässt er sich so installieren:
sudo apt-get install python3-zeep
Der Aufruf sieht dann folgendermaßen aus:
from zeep import Client
client = Client('https://gov.genealogy.net/services/ComplexService?wsdl')
result = client.service.getObject('SCHERGJO54EJ')
print(result)
Möchte man eine Liste von Zahlen als Parameter übertragen, dann geht das so.
from zeep import Client
client = Client('http://gov.genealogy.net/services/SimpleService?wsdl')
emptyArrayPlaceholder = client.get_type('{http://gov.genealogy.net/ws}ArrayOfInt')
interesting_types = emptyArrayPlaceholder()
interesting_types['int'].append(32)
interesting_types['int'].append(36)
interesting_types['int'].append(53)
result = client.service.getParentObjectWithTypeAtDate('SCHERGJO54EJ',interesting_types,2418703)
print(result)
Python Suds mit SQLite
Man kann GOV-Einträge als JSON in SQlite speichern und alle Details per SQL auswerten.
SAS 9.2 (DBCS) mit Axis 2
FILENAME REQUEST temp; FILENAME RESPONSE 'C:\temp\simpleTest_RESPONSE.xml'; data _null_; file request; input; put _infile_; datalines4; <searchByName xmlns="http://gov.genealogy.net/ws"> <placename xmlns="">Heidkate</placename> </searchByName> ;;;; run; proc soap in=REQUEST out=RESPONSE url="https://gov.genealogy.net/services/ComplexService#wsdl" ; run;
Man erhält eine XML-Datei mit dem Ergebnis. Sind Unicode-Zeichen im Ergebnis enthalten, kommt nur ein Response, wenn man mit der Version "English (DBCS)" arbeitet und die zugehörige SAS9.CFG mit dem Eintrag
-ENCODING "UTF-8"
versieht und darin die Einträge
-DBCSTYPE PCMS -DBCSLANG JAPANESE
auskommentiert. Somit erhält man immer einen Response in UTF-8.
Oracle Express Edition
- Installation von Oracle Express Edition 11g (XE), Oracle Application Express mit APEX_WEB_SERVICE 4.02
- ACLs definieren
- Der WebService Client kann mit einer PL/SQL Funktion geschrieben werden:
CREATE OR REPLACE FUNCTION gov_searchByName (p_name IN CHAR)
RETURN VARCHAR
AS
l_envelope CLOB;
l_xml XMLTYPE;
l_result VARCHAR2(32767);
BEGIN
l_envelope := '<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
<soap:Body>
<searchByName xmlns="http://gov.genealogy.net/ws">
<placename xmlns="">' || p_name || '</placename>
</searchByName>
</soap:Body>
</soap:Envelope>';
-- Request abschicken und XML-Response holen
l_xml := APEX_WEB_SERVICE.make_request(
p_url => 'https://gov.genealogy.net/services/SimpleService',
p_envelope => l_envelope
);
-- XML ausgeben (Trace)
DBMS_OUTPUT.put_line('l_xml=' || l_xml.getClobVal());
-- XML-Ergebnis parsen
l_result := APEX_WEB_SERVICE.parse_xml(
p_xml => l_xml,
p_xpath => '*',
p_ns => 'xmlns:ns2="http://gov.genealogy.net/data'
);
RETURN l_result;
END;
/
Aufruf der Funktion:
SET SERVEROUTPUT On; SELECT gov_searchByName ('Heidkate') FROM dual;
- weitere Beispiele: hier
SOAP-Nachrichten
Zum Debuggen sind hier die übertragenen SOAP-Nachrichten eingefügt, wie sie von verschiedenen Webservice-Frameworks generiert werden.
Axis 1.4
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<searchByName xmlns="http://gov.genealogy.net/ws">
<placename xmlns="">Heidkate</placename>
</searchByName>
</soapenv:Body>
</soapenv:Envelope>
PHP 5
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="http://gov.genealogy.net/ws">
<SOAP-ENV:Body>
<ns1:searchByName>
<placename>Heidkate</placename>
</ns1:searchByName>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Beispiele
- Position eines Ortes auslesen:
- Position eines Ortes setzen:
- GOV-Kennung prüfen
Allgemeine Hinweise
- Der Firewall auf dem Rechner mit dem Java-WDSL-Client muss entsprechend konfiguriert sein, um den Datenverkehr zuzulassen, z.B. als Ausnahme in Form einer vertrauenswürdigen Anwendung.
- Zur Programmierung ist eine passende Modellierung des nicht relationalen Datenmodells und der Objekttypen in der jeweiligen Programmiersprache notwendig.