Zum Inhalt

CSW Schnittstelle

Allgemeines

Die CSW-Schnittstelle bietet Zugang zur InGrid-Suche über die OGC CSW 2.0.2 AP ISO 1.0 Schnittstellenspezifikation. Die Komponente bezieht die grundlegenden Daten aus einer oder mehreren Datenquellen. Die Datenquellen werden regelmäßig indexiert. Es wird ein lokaler Index vorgehalten, so dass eine CSW-Anfrage nicht zur Abfrage von den Datenquellen führt. Dies vermeidet Inkompatibilitäten zwischen der OGC CSW 2.0.2 AP ISO 1.0 eigenen Abfragesprache und der InGrid Query.

Die Schnittstelle bietet die Möglichkeit bestimmte Einschränkungen in der Anfrage vorzunehmen, um z.B. ausschließlich Anbieter-spezifische Daten auszuliefern.

InGrid Komponente CSW Schnittstelle

Die Schnittstelle bildet Daten aus dem InGrid Catalog Datenraum wie folgt ab:

InGrid Catalog Typ ISO hierarchyLevel ISO "hierarchyLevelName"
Geodatendienst service service
Geo-Information/Karte dataset
Dienst/Anwendung/Informationssystem application application
Dokument/Bericht/Literatur nonGeographicDataset document
Vorhaben/Projekt/Programm nonGeographicDataset project
Datensammlung/Datenbank nonGeographicDataset database
Organisationseinheit/Fachaufgabe nonGeographicDataset job

Systemvoraussetzungen

Systembestandteil Anforderung
Hardware Arbeitsspeicher 500 MB RAM
Festplattenspeicher 1 GB frei
Prozessor Dual Core CPU
Software Java Java 21

Installation

Docker

Info

Zugang zum Docker Repository

login: readonly
password: readonly

Beispiel für vollständige docker-compose.yml 
services:

ingrid-interface-csw:
    image: docker-registry.wemove.com/ingrid-interface-csw
    restart: unless-stopped
    environment:
    - TZ=Europe/Berlin
    volumes:
    - ./interface-csw/logs/interface-csw:/opt/ingrid/ingrid-interface-csw/logs
    - ./interface-csw/interface-csw/instances:/opt/ingrid/ingrid-interface-csw/instances
    - ./interface-csw/conf/config.override.properties:/opt/ingrid/ingrid-interface-csw/conf/config.override.properties
    - ./interface-csw/conf/csw-t.realm.properties:/opt/ingrid/ingrid-interface-csw/conf/csw-t.realm.properties
    deploy:
    resources:
        limits:
        memory: 512M
    networks:
    - informationgrid-network

From Installer

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

  • Java (>= v21)

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

Download

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

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-csw-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.

Konfiguration

Die Komponente besitzt eine Administrationsoberfläche.

http://localhost:PORT

Anstelle von localhost können Sie auch die IP-Adresse des Computers eingeben. Authentifizieren Sie sich als 'admin' mit dem von Ihnen vergebenen Passwort.

Nach der ersten Installation wird die Administrations-GUI unter

http://localhost:8082

aufgerufen und die Konfiguration vervollständigt.

Aktualisierung

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

Komponente stoppen.

sh start.sh stop

Aktuelles Installationsverzeichnis sichern:

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

Die Aktualisierung erfolgt über den Installer.

java -jar ingrid-interface-csw-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.

Der Zugang zur allgemeinen CSW-Schnittstelle ist über der folgenden URL erreichbar:

http://<csw-admin-url>/csw

Konfiguration CSW Schnittstelle

Über eine Konfigurationsdatei können bestimmte Parameter der CSW Schnittstelle eingestellt werden. Die Default-Konfigurationen können in der config.properties eingesehen werden.

Um die Werte zu überschreiben, muss im Verzeichnis conf eine Datei config.override.properties angelegt werden.

Info

Das Admin Passwort muss verschlüsselt abgelegt werden. Um ein Passwort direkt im config.override.properties zu setzen muss das Passwort zunächst verschlüsselt werden: 

sh start.sh calcPassword <clear-text-password>

# alternative via docker container
docker compose exec interface-csw sh start.sh calcPassword <clear-text-password>

Konfiguration CSW Schnittstelle - Admin GUI

Die CSW Schnittstelle lässt sich über eine Admin-GUI administrieren, die über den im Installer gesetzten Port erreichbar ist. Hier lassen sich Datenquellen hinzufügen und entfernen, das Scheduling für den Harvesting-Prozess definieren und eine Test-Suche ausführen.

Manage Harvester

Unter diesem Punkt können die Datenquellen der CSW Schnittstelle verwaltet werden. Je nach Harvester-Typ ist die Oberfläche unterschiedlich:

InGrid iBus harvester

Mit dem InGrid iBus harvester, können iPlugs aus eine InGrid System in der CSW Schnittstelle indexiert werden. Die iPlugs müssen das IDF Format unterstützen und im IDF Format ISO Daten liefern.

Ablauf:

  • Mit der Angabe der Kommunikations-Daten für den iBus werden alle iPlugs, die am iBus abgeschlossen sind gelistet
  • ein oder mehrere iPlugs können aktiviert werden
  • Bestimmte Eigenschaften, wie die abzusetzende InGrid-Query und Abfrage-Paraneter können in der Detailansicht des iPlugs editiert werden

GDI-DE test data harvester

Dieser Harvester dient ausschließlich zu Testzwecken. Testdaten werden indexiert, die für den Test gegen die GDI-DE Testsuite erforderlich sind. Der Harvester sollte im LIVE Betrieb nicht aktiviert werden.

Control Scheduler

Unter diesem Punkt kann festgelegt werden, wann und mit welcher Regelmäßigkeit das Harvesting durchgeführt werden soll.

Manually issue harvesting

Hier kann der Harvesting-Prozess manuell angestoßen werden.

Die Test-Suche erlaubt die Suche im Datenbestand. Als Suchbegriff wird ein Einzelnes Wort (mit * als Wildcard), oder ein kompletter GetRecords-Request (XML Format) akzeptiert.

Es werden jeweils nur die ersten 10 Treffer angezeigt. Ein Klick auf ein Suchergebnis öffnet die ISO Daten des Datensatzes.

Konfiguration CSW-T Schnittstelle

Die CSW-T Schnittstelle ermöglicht das schreiben von Daten in einen CSW Katalog. Die CSW-T Schnittstelle wird direkt vom InGrid Editor über die InGrid Editor Schnittstelle bereitgestellt.

Der Zugriff muss in der Proxy Konfiguration und in der CSW Capabilities entsprechend konfiguiert werden.

Info

Der Zugang zur CSW-T Schnittstelle ist über OAuth 2.0 geschützt. Credentials werden über einen Nutzer Account im InGrid Editor festgelegt.

FAQ

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

Info

Diese FAQ Bezieht sich nur auf die direkte Installation über den Installer.

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.

Die Schnittstelle liefert keine Ergebnisse.

Folgende Fehlerquellen können vorliegen:

  • Falsche CSW Querysyntax

Bitte überprüfen Sie zunächst das log file.

Wie können alle Dokumente angefragt werden?

Der Ablauf, um alle Dokumente aus der Schnittstelle zu erhalten, ist wie folgt. Mittels einer GetRecords-Anfrage (GET/POST), werden die ersten Dokumente (ungefiltert) angefragt. Danach verschiebt man mit Hilfe des startPosition Parameters den Cursor, um so die nachfolgenden Dokumente zu erhalten. Mit dem Parameter maxRecords gibt man an wieviele Dokumente mit einer Anfrage zurückgegeben werden sollen.

In der Antwort erhält man außerdem über den Parameter numberOfRecordsMatched die maximale Trefferanzahl, welche für das Ende einer Schleife verwendet werden kann. Dazu eignet sich aber auch der Parameter numberOfRecordsReturned, der ebenfalls in der Antwort enthalten ist. Ist dieser Wert kleiner als maxRecords, so wurden alle Dokumente geholt.

Wie kann eine CSW Schnittstelle getestet werden?

Zum Testen eignen sich Tools wie Postman oder Alternativen:

Weblinks:

Requests sind per GET und POST möglich. Bei POST kann als XML/SOAP angefragt werden. Bei SOAP muss zum XML noch der "SOAP Envelope" hinzugefügt werden. Im folgenden Beispiele für die verschiedenen Varianten:

GetCapabilities, GET

https://dev.informationgrid.eu/csw?REQUEST=GetCapabilities&SERVICE=CSW

GetCapabilities, POST XML

Der Endpoint für den XML Request ergibt sich aus der Capabilities Antwort. Als Content Type des Requests muss application/xml angegeben werden.

<?xml version="1.0" encoding="UTF-8"?>
<GetCapabilities xmlns="http://www.opengis.net/cat/csw/2.0.2" service="CSW" version="2.0.2" outputSchema="http://www.opengis.net/cat/csw/2.0.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2" />

GetCapabilities, POST SOAP

Der Endpoint für den XML Request ergibt sich aus der Capabilities Antwort. Als Content Type des Requests muss application/soap+xml angegeben werden.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
    <GetCapabilities xmlns="http://www.opengis.net/cat/csw/2.0.2" service="CSW" version="2.0.2" outputSchema="http://www.opengis.net/cat/csw/2.0.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2" />
</soapenv:Body>
</soapenv:Envelope>

GetRecords, GET

Der Endpoint für den GET Request ergibt sich aus der Capabilities Antwort.

https://dev.informationgrid.eu/csw?REQUEST=GetRecords&SERVICE=CSW&elementSetName=full&startPosition=1&maxRecords=10&resultType=results

Mit Constraints:

http://metaver.de/csw?service=CSW&version=2.0.2&request=GetRecords&resultType=results&outputFormat=application/xml&outputSchema=http://www.isotc211.org/2005/gmd&startPosition=1&maxRecords=1&typeNames=gmd:MD_Metadata&elementSetName=full&CONSTRAINTLANGUAGE=Filter&constraint_language_version=1.1.0&constraint=%3Cogc:Filter+xmlns%3Aogc%3D%22http%3A%2F%2Fwww.opengis.net%2Fogc%22%3E%3Cogc:PropertyIsEqualTo%3E%3Cogc:PropertyName%3Eapiso:ResourceIdentifier%3C/ogc:PropertyName%3E%3Cogc:Literal%3E7988c147-7523-45bb-8f18-7f39d0d20541%3C/ogc:Literal%3E%3C/ogc:PropertyIsEqualTo%3E%3C/ogc:Filter%3E

oder

http://metaver.de/csw?service=CSW&version=2.0.2&request=GetRecords&resultType=results&outputFormat=application/xml&startPosition=1&maxRecords=1&typeNames=gmd:MD_Metadata&elementSetName=full&CONSTRAINTLANGUAGE=Filter&constraint_language_version=1.1.0&constraint=<ogc:Filter xmlns:ogc="http://www.opengis.net/ogc"><ogc:PropertyIsEqualTo><ogc:PropertyName>apiso:partner</ogc:PropertyName><ogc:Literal>hb</ogc:Literal></ogc:PropertyIsEqualTo></ogc:Filter>

GetRecords, POST XML

Der Endpoint für den XML Request ergibt sich aus der Capabilities Antwort. Als Content Type des Requests muss application/xml angegeben werden.

<?xml version="1.0" encoding="UTF-8"?>
<GetRecords  xmlns="http://www.opengis.net/cat/csw/2.0.2" xmlns:ogc="http://www.opengis.net/ogc" xmlns:gmd="http://www.isotc211.org/2005/gmd" xmlns:apiso="http://www.opengis.net/cat/csw/apiso/1.0" xmlns:ows="http://www.opengis.net/ows" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dct="http://purl.org/dc/terms/"  xmlns:gml="http://www.opengis.net/gml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2" service="CSW" version="2.0.2" resultType="results" outputFormat="application/xml" outputSchema="http://www.isotc211.org/2005/gmd" startPosition="1" maxRecords="10">
<Query typeNames="gmd:MD_Metadata">
    <ElementSetName typeNames="">full</ElementSetName>
    <Constraint version="1.1.0">
    <ogc:Filter>
        <ogc:PropertyIsLike escapeChar="\" singleChar="?" wildCard="*">
            <ogc:PropertyName>AnyText</ogc:PropertyName>
            <ogc:Literal>wasser</ogc:Literal>
        </ogc:PropertyIsLike>
    </ogc:Filter>
    </Constraint>
</Query>
</GetRecords>

GetRecordById, GET

https://dev.informationgrid.eu/csw?SERVICE=CSW&REQUEST=GetRecordById&VERSION=2.0.2&ID=98E56BC3-20EC-43A7-8270-1352F0A53AD4

GetRecordById, POST XML

Der Endpoint für den XML Request ergibt sich aus der Capabilities Antwort. Als Content Type des Requests muss application/xml angegeben werden.

<GetRecordById xmlns="http://www.opengis.net/cat/csw/2.0.2"
service="CSW" version="2.0.2"
outputSchema="http://www.opengis.net/cat/csw/2.0.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2" >
<Id>98E56BC3-20EC-43A7-8270-1352F0A53AD4</Id>
<ElementSetName>full</ElementSetName>
</GetRecordById>

DescribeRecord, GET

https://dev.informationgrid.eu/csw?SERVICE=CSW&REQUEST=DescribeRecord&VERSION=2.0.2

DescribeRecord, POST XML

Der Endpoint für den XML Request ergibt sich aus der Capabilities Antwort. Als Content Type des Requests muss application/xml angegeben werden.

<?xml version="1.0" encoding="UTF-8"?>
<DescribeRecord xmlns="http://www.opengis.net/cat/csw/2.0.2"
xmlns:gmd="http://www.isotc211.org/2005/gmd"
schemaLanguage="http://www.w3.org/XML/Schema"
service="CSW" version="2.0.2">
</DescribeRecord>
Die Queryeinschränkungen PropertyEqualsTo und PropertyIsLike angewendet auf den Titel liefern gleiche Ergebnismengen, bzw. Suche nach exakten Titel ist nicht möglich.

Die Anfrage wird umgesetzt in eine "title:" Lucene Query (z.B. "title:wasser"), die tatsächlich alle Titel zurück gibt, die den Literal enthalten.

Eine Query auf exakte Übereinstimmung ist im Feld title nicht zu formulieren, weil das Feld im Index tokenized vorliegt. Das macht auch Sinn, damit Teile des Titels durch Anfragen gefunden werden. Dies ist der Grund, dass PropertyEquals und PropertyIsLike in diesem Fall gleiche Ergebnismengen zurückliefern.

Der Unterschied zwischen PropertyEqualsTo zu PropertyIsLike wird bei title:* klar. In diesem Fall werden auch zusammengesetzte Worte im Titel, die mit dem Literal beginnen gefunden.

Partner-spezifische Auslieferung von Capabilities Dokumenten.

Über einen Query-Parameter partner kann die partner-spezifische Auslieferung von Capability Dokumenten gesteuert werden. Für jeden Partner muss dazu ein File im conf Verzeichnis mit entsprechender Kennung erzeugt werden:

INSTALL_DIRECTORY/conf/csw_capabilities_<partner>.xml

Bsp:

conf/csw_capabilities_test.xml

kann über die URL

http://dev.informationgrid.eu/csw?REQUEST=GetCapabilities&SERVICE=CSW&partner=test

abgerufen werden. Existiert keine Datei mit entsprechender Erweiterung, wird die Standard-Capabilities conf/csw_capabilities.xml ausgeliefert

Einschränkung der Ergebnismenge auf Partner, Anbieter oder iPlug.

Die Einschränkung auf Partner, Anbieter oder iPlug in der CSW Schnittstelle kann über die CSW Service URL vorgenommen werden.

Dazu wird der Service URL per GET Parameter die entsprechende Einschränkung mitgegeben.

z.B. liefert

http://dev.informationgrid.eu/csw202?partner=ni

ausschließlich Ergebnisse des Partners "ni" zurück. Weitere gültige Parameter sind

  • provider Filterung nach einem bestimmten Anbieter(kürzel)
  • iplug Filterung nach einer bestimmten iPlug-ID

Bei entsprechender Konfiguration eines vorgeschalteten Web-Servers (URL-rewrite) kann die Einschränkung auch in den Pfad integriert werden. Die Service-URL könnte dann auch so aussehen:

http://dev.informationgrid.eu/csw/partner/bund

Konfigurationsbeispiel Apache Konfiguration:

RewriteEngine on
# Die folgende Regel schreibt die Anfragen an csw um und leitet sie wie
# einen Proxy-Request an 8083:csw weiter:

RewriteRule ^/csw/partner/(.*) http://127.0.0.1:8083/csw?%{QUERY_STRING}&partner=$1 [P]
RewriteRule ^/csw/provider/(.*) http://127.0.0.1:8083/csw?%{QUERY_STRING}&provider=$1 [P]

Die Einschränkungen können auch direkt in der CSW Anfrage formuliert werden. Intern ist es tatsächlich so, dass die Einschränkungen in der URL in eine Einschränkung innerhalb der Filter-Query der CSW Anfrage umgesetzt werden.

Beispiel einer GetRecords Anfrage mit Filterung nach iplug per POST XML. Als Content Type des Requests muss application/xml angegeben werden. Auf die gleiche Art und Weise kann auch per partner oder provider gefiltert werden.

<csw:GetRecords xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    xmlns="http://www.opengis.net/cat/csw/2.0.2" xmlns:dc="http://purl.org/dc/elements/1.1/"
    xmlns:ogc="http://www.opengis.net/ogc" xmlns:dct="http://purl.org/dc/terms/"
    xmlns:ows="http://www.opengis.net/ows" xmlns:gml="http://www.opengis.net/gml" xmlns:gmd="http://www.isotc211.org/2005/gmd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" service="CSW" version="2.0.2"
    maxRecords="10" startPosition="1" resultType="results" outputFormat="application/xml"
    outputSchema="http://www.isotc211.org/2005/gmd"
    xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2 http://schemas.opengis.net/csw/2.0.2/CSW-discovery.xsd">
    <csw:Query typeNames="gmd:MD_Metadata">
        <csw:ElementSetName typeNames="">full</csw:ElementSetName>
        <Constraint version="1.1.0">
            <ogc:Filter>
                <ogc:PropertyIsEqualTo>
                    <ogc:PropertyName>iplug</ogc:PropertyName>
                    <ogc:Literal>/ingrid-group:ige-iplug-HH</ogc:Literal>
                </ogc:PropertyIsEqualTo>
            </ogc:Filter>
        </Constraint>
    </csw:Query>
</csw:GetRecords>

Eine Filterung mehrerer iPlugs ist dann wie folgt möglich:

    <csw:Query typeNames="gmd:MD_Metadata">
        <csw:ElementSetName typeNames="">full</csw:ElementSetName>
        <Constraint version="1.1.0">
            <ogc:Filter>
                <ogc:Or>
                    <ogc:PropertyIsEqualTo>
                        <ogc:PropertyName>iplug</ogc:PropertyName>
                        <ogc:Literal>/ingrid-group:ige-iplug-HH</ogc:Literal>
                    </ogc:PropertyIsEqualTo>
                    <ogc:PropertyIsEqualTo>
                        <ogc:PropertyName>iplug</ogc:PropertyName>
                        <ogc:Literal>/ingrid-group:ige-iplug-HB</ogc:Literal>
                    </ogc:PropertyIsEqualTo>
                </ogc:Or>
            </ogc:Filter>
        </Constraint>
    </csw:Query>

Hinweis

Um die GetRecords-Ergebnisse in einer GET-Anfrage auf einen Partner einzuschränken, braucht man das über das constraint-Parameter machen. Die GET Abfrage sieht dann so aus:

http://metaver.de/csw?service=CSW&version=2.0.2&request=GetRecords&resultType=results&outputFormat=application/xml&outputSchema=http://www.isotc211.org/2005/gmd&startPosition=1&maxRecords=1&typeNames=gmd:MD_Metadata&elementSetName=full&CONSTRAINTLANGUAGE=Filter&constraint_language_version=1.1.0&constraint=%3Cogc:Filter%20xmlns:ogc=%22http://www.opengis.net/ogc%22%3E%3Cogc:PropertyIsEqualTo%3E%3Cogc:PropertyName%3Epartner%3C/ogc:PropertyName%3E%3Cogc:Literal%3Ehb%3C/ogc:Literal%3E%3C/ogc:PropertyIsEqualTo%3E%3C/ogc:Filter%3E

oder

http://metaver.de/csw?service=CSW&version=2.0.2&request=GetRecords&resultType=results&outputFormat=application/xml&startPosition=1&maxRecords=1&typeNames=gmd:MD_Metadata&elementSetName=full&CONSTRAINTLANGUAGE=Filter&constraint_language_version=1.1.0&constraint=<ogc:Filter xmlns:ogc="http://www.opengis.net/ogc"><ogc:PropertyIsEqualTo><ogc:PropertyName>apiso:partner</ogc:PropertyName><ogc:Literal>hb</ogc:Literal></ogc:PropertyIsEqualTo></ogc:Filter>