Such-Schnittstelle

Allgemeines¶

Die REST-Schnittstelle beinhaltet alle Schnittstellen, die Anfragen direkt an die InGrid Recherche stellen. Dabei werden die Anfragen in InGrid Queries transformiert, an den iBus versendet und die Antworten in das jeweils geforderte Format umgewandelt.

Unterstützte Schnittstellen:

• OpenSearch Schnittstelle
• ATOM Download Service
• GOVDATA Schnittstelle

Systemvoraussetzungen¶

Installation¶

Docker¶

docker login docker-registry.wemove.com

  ingrid-interface-search:
    image: docker-registry.wemove.com/ingrid-interface-search
    restart: unless-stopped
    environment:
      - TZ=Europe/Berlin
    volumes:
      - ./interface-search/logs/interface-search:/opt/ingrid/ingrid-interface-search/logs
      - ./interface-search/interface-search.properties:/opt/ingrid/ingrid-interface-search/conf/interface-search.properties
      - ./interface-search/descriptor.xml:/opt/ingrid/ingrid-interface-search/conf/descriptor.xml
      - ./interface-search/communication.xml:/opt/ingrid/ingrid-interface-search/conf/communication.xml
    deploy:
      resources:
        limits:
          memory: 512M
    networks:
      - informationgrid-network

From Installer¶

Um die InGrid Search Schnittstelle direkt auf einem System zu installieren, müssen folgende Vorbedingungen erfüllt sein:

• Java (>= v21)

Die Installation der InGrid Search Schnittstelle (z.B. nach /opt/ingrid/interface-search) erfolgt dann mit diesen Schritten:

Download¶

Download: https://distributions.informationgrid.eu/ingrid-interface-search/

Install¶

Um die Installationsroutine zu starten, doppel-klicken Sie auf das Installationsprogramm oder geben Sie folgenden Befehl auf der Kommandozeile ein:

java -jar ingrid-interface-search-VERSION-installer.jar

Der Installer ist sowohl per graphischer Oberfläche als auch Kommandozeileneingabe ausführbar. Bitte folgen Sie den Anweisungen des Installationsprogrammes. Das Installationsprogramm installiert die Komponente im gewünschten Verzeichnis und passt die Konfigurationsdateien an.

Sie können nun die Komponente mit

sh start.sh start

starten.

Aktualisierung¶

Neues Release von https://distributions.informationgrid.eu/ingrid-interface-search/ herunterladen.

Komponente stoppen.

sh start.sh stop

Aktuelles Installationsverzeichnis sichern:

cp -r /opt/ingrid/ingrid-interface-search BACKUP_DIRECTORY

Die Aktualisierung erfolgt über den Installer.

java -jar ingrid-interface-search-NEW-VERSION-installer.jar

Während der Installation bitte "Upgrade" auswählen und das Installationsverzeichnis Verzeichnis angeben.

Komponente starten.

sh start.sh start

Betrieb¶

start.sh [start|stop|restart|status]

Die LOG Ausgaben finden sich in der Datei log.log und console.log.

Konfiguration¶

Parameter der Schnittstelle¶

Wesentliche Parameter sind über das ingrid-search.properties im Unterverzeichnis "conf" zu konfigurieren. Alle möglichen Werte können hier eingesehen werden:

https://github.com/informationgrid/ingrid-interface-search/blob/master/src/main/resources/interface-search.properties

# port of the opensearch interface
server.port=8183

# max. number of returned hits per page for the opensearch interface
opensearch.max.requested.hits=10000

# opensearch descriptor file
opensearch.descriptor.file=conf/descriptor.xml

# interface url displayed in opensearch results
# use this in case of application is behind a reverse-proxy
opensearch.proxy.url=http://dev.informationgrid.eu/search/opensearch

# url to display detailed view of metadata results
# use this in case of providing links to details of metadata results
# only makes sence, if the query has the parameter xml=0
metadata.details.url=http://dev.informationgrid.eu/trefferanzeige

# enable/disable caching during bus queries
enable.caching=false

# max timeout for ibus search queries.
# After timeout milliseconds the ibus must interrupt iplug search processes.
ibus.search.max.timeout=60000

# metadata access URL pattern
# used by the ATOM download service
metadata.access.url=http://dev.informationgrid.eu/csw?REQUEST=GetRecordById&SERVICE=CSW&VERSION=2.0.2&id={uuid}&elementSetName=full

# atom download service access url
atom.download.service.url=http://dev.informationgrid.eu/search/dls

# atom download service feed access url extension pattern
atom.download.service.feed.extension=/service/{servicefeed-uuid}

# atom download service feed list access url extension pattern
atom.download.service.feedlist.extension=/service-list?q={searchTerms}

# atom download dataset feed access url extension pattern
atom.download.dataset.feed.extension=/dataset/{servicefeed-uuid}/{datasetfeed-uuid}

# atom download opensearch definition url extension pattern
atom.download.opensearch.definition.extension=/opensearch-description/{servicefeed-uuid}

# atom download service: opensearch get result url template
atom.download.opensearch.get.results.template=/service/{servicefeed-uuid}?q={searchTerms}

# atom download service: opensearch describe spatial dataset url template
atom.download.opensearch.describe.spatial.dataset.template=/dataset/{servicefeed-uuid}/?spatial_dataset_identifier_code={inspire_dls:spatial_dataset_identifier_code?}&spatial_dataset_identifier_namespace={inspire_dls:spatial_dataset_identifier_namespace?}&language={language?}

# atom download service: opensearch get spatial dataset url template
atom.download.opensearch.get.spatial.dataset.template=/get-dataset/{servicefeed-uuid}/?spatial_dataset_identifier_code={inspire_dls:spatial_dataset_identifier_code?}&spatial_dataset_identifier_namespace={inspire_dls:spatial_dataset_identifier_namespace?}&crs={inspire_dls:crs?}&language={language?}

# atom download service: comma separated supported languages other languages will be ignored
atom.download.opensearch.supported.languages=de

# atom download service: connect timeout for external http calls
atom.url.connect.timeout=1000

# atom download service: read timeout for external http calls
atom.url.read.timeout=1000

# opensearch channel title
opensearch.channel.title=

# opensearch channel description
opensearch.channel.description=

# opensearch channel language
opensearch.channel.language=

# opensearch channel copyright
opensearch.channel.copyright=

# opensearch channel link
opensearch.channel.link=

opensearch.dcat.contributor_id=http://dcat-ap.de/def/contributors/NUMIS

opensearch.dcat.catalog.publisher.name=MU_Niedersachsen

opensearch.dcat.catalog.publisher.url=https://numis.niedersachsen.de

opensearch.dcat.catalog.description=Das niedersächsiche Umweltportal

opensearch.dcat.catalog.title=NUMIS

Benutzung mit Apache mod_proxy¶

Um die Schnittstelle über Port 80 erreichen zu können, bietet sich die Verwendung eines proxys an. Dies kann einfach mit dem Apache-Modul mod_proxy realisiert werden. Im Apache müssen folgende Module installiert sein:

• mod_proxy
• mod_proxy_connect
• mod_proxy_http

In der Apache Konfiguration muss folgendes eingetragen werden:

#
# ProxyEngine
#
ProxyRequests Off
ProxyPass /search http://localhost:8183
ProxyPassReverse /search http://localhost:8183

ProxyPass /opensearch http://localhost:8183/opensearch
ProxyPassReverse /opensearch http://localhost:8183/opensearch

Der angegebene Port muss mit dem Port der Schnittstelle übereinstimmen.

Nun ist die Schnittstelle auch über http://SERVER_DOMAIN/search/... erreichbar.

Die Schnittstelle kann sowohl per HTTPS als auch per HTTP benutzt werden. Wichtig ist bei der oben beschriebenen Proxy Weiterleitung, dass Anfragen, die per HTTPS an den Proxy gestellt werden, auch so an die Schnittstelle weitergeleitet werden, dass diese den HTTPS Aufruf erkennt. Die kann durch folgende Ergänzung im der Apache Konfiguration erfolgen:

RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"

InGrid Communication¶

Die Datei conf/communication.xml enthält die Konfigurationen der InGrid Kommunikationsschicht.

<?xml version="1.0" encoding="UTF-8"?>
<communication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="communication.xsd">
    <client name="/ingrid-group:iplug-management-'Ihr-Name'">
        <connections>
            <server name="/ingrid-group:ibus-'Ihr-Name'">
                <socket port="9900" timeout="10" ip="127.0.0.1" />
                <messages maximumSize="1048576" threadCount="100" />
            </server>
        </connections>
    </client>
    <messages queueSize="2000" handleTimeout="10"/>
</communication>

Die einzelnen Parameter haben folgende Bedeutung:

Schnittstellen¶

OpenSearch Schnittstelle¶

Die OpenSearch Schnittstelle basiert auf der OpenSearch Spezifikation https://github.com/dewitt/opensearch. Sie dient vor allem der Integration der InGrid Suche in andere Systeme.

Die Definition der Schnittstelle wurde erweitert, um die Besonderheiten der Ingrid-Suche abbilden zu können.

Die Schnittstelle wird per HTTP/GET angefragt. Sie hat 2 Methoden:

• Anfordern des OpenSearch descriptors (descriptor)
• Absetzen einer Suche (query)

Über die query-Methode ist es auch möglich Detailinformationen über den oder die Datensätze zu bekommen. Diese werden dann für jeden Hit in die Antwort (RSS2.0 kompatibles XML-Format) geschrieben.

Request¶

Folgende Parameter sind zulässig:

Bsp:

https://dev.informationgrid.eu/interface-search/opensearch/descriptor

... liefert den OpenSearch Descriptor, der die Schnittstelle beschreibt.

https://dev.informationgrid.eu/interface-search/opensearch/query?q=wasser+boden+datatype:default+ranking:score&p=1&h=20

... fordert 20 Ergebnisse aus den 'default' Datenquellen (all datenliefernden iPlugs) der ersten Seite für die query "wasser boden" an, sortiert nach Relevanz. Der Link zum Detail von Metadaten verweist auf die Portal-Darstellung (Parameter xml=0 oder nicht angegeben).

https://dev.informationgrid.eu/interface-search/opensearch/query?q=boden+datatype:metadata+ranking:score&p=1&h=20&ingrid=1&xml=1

... fordert 20 Ergebnisse aus den 'metadata' Datenquellen (z.B. InGrid Editor oder CSW iPlugs) der ersten Seite für die query "boden" an, sortiert nach Relevanz. Zusätzliche InGrid Informationen werden je Ergebnis mit ausgegeben (Parameter ingrid=1 ). Der Link zum Detail von Metadaten verweist auf die OpenSearch-Darstellung (Parameter xml=1 ).

https://uvp-verbund.de/interface-opensearch/query?q=datatype:default+ranking:date&uvp=1

... fordert die 10 aktuellesten UVP-Datensätze, sortiert nach Änderungsdatum an. Die Ausgabe wird UVP-spezifisch dargestellt und enthält Felder wie "guid", "pubDate", "uvp:latest-phase" und "author".

Deskriptor-Response¶

Der Deskriptor der Opensearch-Schnittstelle gibt an, wie die Schnittstelle angefragt werden kann. Als Antwort erhält man eine oder mehrere URLs mit Platzhaltern, mit der man individuelle Anfragen stellen kann. Kommen mehrere URLs in einer Antwort vor, dann werden verschiedene Ausgabetypen unterstützt, wie z.B. rss und atom. Die Platzhalter sind im folgenden aufgeführt:

Ein Beispiel-Deskriptor sieht folgendermaßen aus:

<?xml version="1.0" encoding="utf-8"?>
<openSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
     xmlns:georss="http://www.georss.org/georss"
     xmlns:ingridsearch="http://www.portalu.de/opensearch/extension/1.0"
     xmlns:geo="http://a9.com/-/opensearch/extensions/geo/1.0/">
  <ShortName>InGrid OpenSearch</ShortName>
  <Description>Here you can search inside the InGrid-Portal.</Description>
  <Tags>ingrid opensearch web</Tags>
  <Contact>contact@wemove.com</Contact>
  <Url type="application/rss+xml" template="http://harrison.its-technidata.de/opensearch/query?q={searchTerms}+datatype:default+ranking:score&amp;bbox={geo:box?}&amp;p={startPage?}&amp;h={count?}&amp;xml={ingridsearch:xml?}&amp;detail={ingridsearch:detail?}&amp;georss={ingridsearch:georss?}&amp;ingrid={ingridsearch:ingrid?}&amp;format=rss" />
 </OpenSearchDescription>

Die anzufragende URL befindet sich im Attribut template des Tags Url. Der Typ des Ausgabeformats verbirgt sich hinter type und ist in diesem Fall application/rss+xml. Ein Fragezeichen ? in einem Platzhalter bedeutet, dass dieser Parameter optional ist. In diesem Beispiel wird nur verlangt, dass {searchTerms} mit einem entsprechenden Wert ersetzt wird. Mehr Informationen über den Deskriptor findet man hier https://github.com/dewitt/opensearch.

Response¶

Die Antwort der Schnittstelle erfolgt im RSS 2.0 kompatiblen XML-Format. Die Schnittstelle erweitert das RSS2.0 Format um bestimmte Elemente. Das folgende XML Schema beschreibt die Erweiterungen.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.wemove.com/ingrid/opensearchextension/0.1/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:idf="http://www.portalu.de/IDF/1.0" xmlns:ingridsearch="http://www.wemove.com/ingrid/opensearchextension/0.1/">
  <xs:import schemaLocation="ingrid-opensearch.xsd"/>
  <xs:import namespace="http://a9.com/-/spec/opensearch/1.1/" schemaLocation="opensearch.xsd"/>
  <xs:element name="plugid" type="xs:string"/>
  <xs:element name="docid" type="xs:integer"/>
  <xs:element name="altdocid" type="xs:string"/>
  <xs:element name="provider" type="xs:string"/>
  <xs:element name="provider-name" type="xs:string"/>
  <xs:element name="partner" type="xs:string"/>
  <xs:element name="partner-name" type="xs:string"/>
  <xs:element name="source" type="xs:string"/>
  <xs:element name="udk-class" type="xs:integer"/>
  <xs:element name="udk-addr-class" type="xs:integer"/>
  <xs:element name="wms-url" type="xs:anyURI"/>
  <xs:element name="details">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="idf:html"/>
        <xs:element maxOccurs="unbounded" ref="ingridsearch:detail"/>
        <xs:element ref="ingridsearch:detail-subrecord" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="detail-subrecord">
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs="unbounded" ref="ingridsearch:detail"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="detail">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="ingridsearch:detail-key"/>
        <xs:element ref="ingridsearch:detail-key-localized" minOccurs="0"/>
        <xs:element ref="ingridsearch:detail-value"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="detail-key" type="xs:string">
  </xs:element>
  <xs:element name="detail-key-localized" type="xs:string">
  </xs:element>
  <xs:element name="detail-value" type="xs:string">
  </xs:element>
</xs:schema>

Request vom MapClient¶

Die Suche nach Diensten im MapClient erfolgt über die OpenSearch Schnittstelle. Die Suche nach "Wasser" im MapClient setzt z.B. folgenden Request ab.

https://dev.informationgrid.eu/ingrid-webmap-client/rest/search/query?q=Wasser&lang=de&type=services&searchUrl=https://dev.informationgrid.eu/interface-opensearch/query?q=Wasser+t011_obj_serv_op_connpoint.connect_point:http*+t011_obj_serv.type:view+cache:off+datatype:metadata+ranking:score&ingrid=1&h=100

der folgende Open Search Query auslöst

https://dev.informationgrid.eu/interface-opensearch//query?q=Wasser+t011_obj_serv_op_connpoint.connect_point:http*+t011_obj_serv.type:view+cache:off+datatype:metadata+ranking:score&ingrid=1&h=100

Das Ergebnis liefert Kartendienste mit "Wasser", die im MapClient hinzugefügt werden können.

ATOM Download Service Feed Schnittstelle¶

INSPIRE-relevante Daten, welche durch Daten-Metadaten beschrieben sind, müssen über Download-Dienste verfügbar gemacht werden. Wie ein Download Dienst realisiert sein kann, ist in “Technical Guidance for the implementation of INSPIRE Download Services” beschrieben.

Folgende Kopplungen können im InGrid Editor angegeben werden:

• Auswahl eines entsprechenden Daten Objektes über Dargestellte Daten
• Erstellen eines GetRecordByID CSW Request als "Datendownload" Verweis (Der Verweis wird von der ATOM Schnittstelle automatisch verfolgt.)

Im InGrid Editor kann dies über einen Eintrag in "Dargestellte Daten" im der Datensatzklasse Geodatendienst erfolgen.

Eine weitere Anforderung an die dynamisch generierten Download-Services ist die Bereitstellung eines OpenSearch-Interfaces mit einem fest definierten Satz an Operationen.

Methoden¶

Die unterschiedlichen Methoden der Schnittstelle werde über unterschiedliche Zugriffs-Pfade abgebildet:

dls/service/{service-uuid}?q=<query>

dls/dataset/{service-uuid}/{dataset-uuid}

dls/service/{service-uuid}?q=<query>

dls/dataset/{servicefeed-uuid}/?spatial_dataset_identifier_code={inspire_dls:spatial_dataset_identifier_code?}&spatial_dataset_identifier_namespace={inspire_dls:spatial_dataset_identifier_namespace?}&language={language?}

dls/get-dataset/{servicefeed-uuid}/?spatial_dataset_identifier_code={inspire_dls:spatial_dataset_identifier_code?}&spatial_dataset_identifier_namespace={inspire_dls:spatial_dataset_identifier_namespace?}&crs={inspire_dls:crs?}&language={language?}

dls/opensearch-description/{servicefeed-uuid}

dls/

dls/#?partner={PARTNER ID: bb, be, ni, ...}

dls/#?serviceId={SERVICE UUID}&partner={PARTNER ID: bb, be, ni, ...} 

dls/#?serviceId={SERVICE UUID}&partner={PARTNER ID: bb, be, ni, ...}&serviceOnly

Abbildung der Datenfelder¶

Im folgenden wird die Abbildung der verwendeten ISO Felder auf die Felder im ATOM Feed Format dokumentiert:

Endpoint für GOVDATA¶

Für die Weitergabe von Opendata-Metadaten an GOV.DATA.DE oder andere Opendata Portale, können die Metadaten auch im RDF/XML Format abgegeben werden.

Die Opensearch-Schnittstelle wurde dazu um einen Export im RDF/XML erweitert. Der RDF-Export kann über den Parameter format=rdf angesteuert werden.

Bsp: https://dev.informationgrid.eu/interface-search/opensearch/query?format=rdf

Der Export ist Kompatibel zur DCAT-AP.de Version 2.0. Die Paginierung erfolgt über die PagedCollection aus dem Hydra-Namespace des W3C (https://www.w3.org/ns/hydra/spec/latest/core/) die Einstellmöglichkeiten der Datensätze pro Seite entspricht den Möglichkeiten der Items pro Seite im OpenSearch-Schnittstelle.

Der Export der Opendata-Metadaten erfolgt aus den IDF-Daten auf Basis der Mapping-Tabelle für GDI-DE, Stand 16.02.2022.

Lizenzen werden gemäß der Tabelle unter https://www.dcat-ap.de/def/licenses/ (Stand 20210721) auf DCAT-AP.de URIs gemapped. Sollte keine Lizenz URL gefunden werden oder keine Abbildung auf eine URI möglich sein wird eine Default-Lizenz angegeben (Sofern nicht anders konfiguriert http://dcat-ap.de/def/licenses/other-open).

Für die Periodizität werden gängige Bezeichnungen und Codelist-Values auf das Vokabular in http://publications.europa.eu/resource/authority/frequency gemapped. Alle Varianten kürzer als eine Stunde werden auf CONT (Kontinuierlich) abgebildet.

Das Distribution-Format wird entsprechend der Mapping-Übersicht übernommen, sofern das Format im Vokabular unter http://publications.europa.eu/resource/authority/file-type vorkommt. Ein Mapping von abweichenden Bezeichnungen kann über ein JSON-File im Classpath ergänzt werden.

Folgende Eigenschaften können über die Konfiguration interface-search.properties eingestellt werden.

Die Werte müssen mit GOV.DATA abgestimmt werden.

FAQ¶