GOV/Webservice

GOV-Hauptseite > GOV/Projekt > GOV-Webservice

Projekt GOV
hier: GOV/Webservice
GOV-Datenbankabfrage: Einfache Suche Erweiterte Suche Infoseiten zum Projekt: GOV/Projekt GOV/Datenmodell Datenerfassung: GOV/Anleitung GOV/Quicktext GOV/Objekttypen GOV/Datenerfassungen GOV/Mehrfachkennungen Kontakt: <email>gov-support@genealogy.net</email> Online-Bereich für technische Fragen Kategorien: Kategorie:GOV Kategorie:GOV-Newsletter Kategorie:GOV-Intern Kategorie:GOV-Quelle

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 sehr geübter Programmierer in einer passenden Programmiersprache einen automatisierten Datenabgleich zwischen bereits erfassten oder noch zu erfassenden Daten entwickeln.

Lizenz

Kommerzielle Nutzung

Auf Beschluss der Mitgliederversammlung vom März 2015 erteilen wir, der Verein für Computergenealogie e.V., auf Nachfrage Herstellern von Genealogieprogrammen auch Genehmigungen zur kommerziellen Nutzung der Daten im Rahmen Ihres Genealogieprogramms. Den Blanco-Lizenzvertrag finden Sie hier: Linzenzvertrag Mini-GOV

Bei Interesse und für Rückfragen zum Vertrag wenden Sie sich bitte an <email>vorstand@compgend.e</email>

Webservices

Es gibt drei Webservices:

• SimpleService - als Suchergebnis werden Listen mit GOV-Kennungen zurückgeliefert
• ComplexService - als Suchergebnis werden Listen zurückgeliefert, 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.

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

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 Suche im Frontend)

searchDescendantsByName

Suche nach untergeordneten Objekten nach Name zu einer übergeordenten ID

searchDescendantsByName1

searchDescendantsByType

Suche nach untergeordneten Objekten nach Typ zu einem übergeordneten Namen

searchRelatedByName

Suche nach über-/untergeordneten Objekten nach Name

getObjectByExternalId

Suche nach Objekt(en) mit Systemkürzel der externen Kennung und Referenznummer

Die Beschreibung der Funktionen (wsdl:message) mit ihren Parametern (wsdl:part) wird beim Aufruf des jeweiligen Services im Browser angezeigt.

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				Jzedlitz
Python ZSI 1.7.0			bei mir hat es nur mit einfachen Rückgabewerten funktioniert	Jzedlitz

Client

PHP 5

Mit PHP 5 ist ein Client für den GOV-Webservice ganz schnell geschrieben:

<?php
$soapclient = new SoapClient('http://gov.genealogy.net/services/ComplexService?wsdl');
$list =$soapclient->searchByName(utf8_encode('Heidkate'));
/* Ausgabe des Arrays */
echo "<pre>";
print_r($list);
echo "</pre>";
?>

Ja, das ist alles! :-)

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 http://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 ZSI 1.7.0

So richtig stabil scheint das noch nicht zu sein, mehr als einfache Rückgabewerte (einzelne Texte) habe ich nicht empfangen können.

Zunächst muß man sich Python Quellcode generieren:

wsdl2py -u http://gov.genealogy.net/services/SimpleService?wsdl

Dadurch bekommt man zwei Dateien:

• SimpleServiceImpl_services.py
• SimpleServiceImpl_services_types.py

Ein Client (hier zum Überprüfen einer GOV-Kennung) sieht dann z.B. so aus:

from SimpleServiceImpl_services import *

loc = SimpleServiceImplLocator()
proxy = loc.getSimpleServiceImplPortType()

request = checkObjectIdRequestWrapper()
request._itemId= "SCHERGJO54EJ"
response = proxy.checkObjectId(request)
print response._out

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="http://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      => 'http://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 habe ich 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:
  • PHP
  • .NET
• Position eines Ortes setzen:
  • Java
  • PHP
• GOV-Kennung prüfen
  • PHP
  • Python ZSI
  • .NET

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.