Such-Schnittstelle

Allgemeines

Die Such-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

Systemvoraussetzungen

• 256 MB RAM

• 500 MB Harddrive

• JAVA 8
• Cygwin (unter Windows)

Installation

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

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.

OpenSearch Schnittstelle

Die OpenSearch Schnittstelle basiert auf der OpenSearch Spezifikation http://www.opensearch.org. 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 (z.B. iPlug-SE, iPlug-UDK-DB) 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. iPlug-UDK-DB) 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 ).

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 http://www.opensearch.org/Specifications/OpenSearch/1.1.

Response

Die Antwort der Schnittstelle erfolgt im RSS2.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 REST-Request ab, der folgende Open Search Query auslöst.

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”, derzeit in der Version 3.0 vorliegend, beschrieben.

Die Grundidee dabei ist, dass vom Metadaten-Erfasser im InGridCatalog/IGE Serivce-Metadaten für einen oder mehrere Download-Dienste angelegt werden. Mit diesen Objekten werden Daten-Metadaten als gekoppelte Resourcen verknüpft. Für jeden dieser Download-Service-Metadatensätze wird durch einen Webservice (bzw. eine Service-Fassade) ein solcher Download-Dienst automatisch bereitgestellt. Hierzu wird dynamisch der Service-Feed erzeugt. Dieser entspricht einem Capabilities-Dokument bei OGC-Webservices.

Alle an dieses Dienste-Metadatenobjekt gekoppelten Daten-Metadaten werden im Service-Feed eingetragen. Für jeden Daten-Metadatensatz kann sodann ein Daten-Feed abgerufen werden, dessen URL als entry-Element des Service-Feeds annonciert wird. Im Daten-Feed werden alle Download-Optionen für diesen Datensatz eingetragen.

Folgende Kopplungen können im InGrid Catalog (Editor) angegeben werden:

• Auswahl eines entsprechenden Daten Objektes über “Dargestellte Daten”
• Erstellen eines getRecordByID CSW Requested als “Datendownload” Verweis (Der Verweis wird von der ATOM Schnittstelle automatisch verfolgt.)

Im InGrid Catalog/InGrid Editor kann dies entweder über einen Eintrag in “gekoppelte Daten” im Geodatenservice

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:

Konfiguration

Parameter der Schnittstelle

Wesentliche Parameter sind über das ingrid-search.properties im Unterverzeichnis “conf” zu konfigurieren.

# 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 hiding via an 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

# atom download service client source directory
atom.download.service.client.path=client

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:

FAQ

Wie kann ich ein Überschreiben der Datei env.sh bei einer Aktualisierung verhindern.

In der Datei env.sh können Systemvariablen komponenten-spezifisch angepasst werden (z.B. Proxy oder Heap Einstellungen). Um die Einstellungen nach einer Aktualisierung nicht zu verlieren, muss die Datei env.sh nach user.env.sh kopiert werden. Die Änderungen in user.env.sh werden nicht überschrieben.

Unter welchen Bedingungen werden die Dienste im ATOM-Feed Client angezeigt?

Folgende Bedingungen müssen erfüllt sein, so dass ein Dienst mit seinen Download-Referenzen angezeigt wird:

Kopplung mit Geodatensatz

1. Der anzuzeigende Service muss von der Art “Download-Dienste” sein.
2. Es muss die Option “Als ATOM-Download Dienst bereitstellen” aktiviert sein.
3. Es muss mindestens eine Referenz auf ein Objekt vom Typ “Geodatensatz” vorhanden sein.
4. Dieser Geodatensatz muss mindestens einen Verweis vom Typ “Download” besitzen.
5. Ein angeschlossenes iPlug-DSC muss die Daten des IGC indexiert haben.

Kopplung mit externem Datensatz (ab Version 3.5.1)

1. wie oben
2. wie oben
3. Es muss mindestens ein externer Datensatz in den “gekoppelten Daten” hinzugefügt werden
4. Dieser Datensatz muss als URL die Zeichenkette “REQUEST=GetRecordById” enthalten
5. Ein angeschlossenes iPlug-DSC muss die Daten des IGC indexiert haben.

Direkter Verweis auf externem Datensatz

1. wie oben
2. wie oben
3. Es muss mindestens ein Verweis vom Typ “Datendownload” hinzugefügt werden
4. Dieser Verweis muss als URL die Zeichenkette “REQUEST=GetRecordById” enthalten
5. Ein angeschlossenes iPlug-DSC muss die Daten des IGC indexiert haben.