CSW Schnittstelle¶

Allgemeines¶

Die CSW-Schnittstelle stellt Metadaten im InGrid-System über den OGC CSW 2.0.2 AP ISO 1.0-Standard bereit und eignet sich als eigenständiger Metadatenkatalog innerhalb einer InGrid-Infrastruktur. Umgesetzt wird sie mit pycsw, einem quelloffenen CSW-Server auf Python-Basis.

In der InGrid-Umgebung dient pycsw als zentrales Katalog-Ziel für einliefernde Komponenten (Editor, Harvester) und stellt Metadaten via CSW-Schnittstelle für abfragende Komponenten wie das Portal bereit.

Systemvoraussetzungen¶

Installation¶

Docker¶

Für den Betrieb wird eine PostgreSQL-Datenbank empfohlen.

services:

    pycsw:
        image: geopython/pycsw
        restart: unless-stopped
        environment:
            - TZ=Europe/Berlin
            - PYCSW_CONFIG=/etc/pycsw/pycsw.yml
            - PYCSW_SERVER_URL=${SERVICE_URL_APACHE}/pycsw
            - DB_URL=postgresql://${DB_USER}:${DB_PASSWORD}@db/pycsw
        volumes:
            - ./pycsw/pycsw.yml:/etc/pycsw/pycsw.yml
            - ./pycsw/traceability-filter.xsl:/etc/pycsw/traceability-filter.xsl
        ports:
            - "8000:8000"
        depends_on:
            db:
                condition: service_healthy
        networks:
            - ingrid-network

    db:
        image: postgres:15
        restart: unless-stopped
        environment:
            - POSTGRES_DB=pycsw
            - POSTGRES_PASSWORD=${DB_PASSWORD}
            - POSTGRES_USER=${DB_USER}
        healthcheck:
            test: ["CMD-SHELL", "pg_isready -U ${DB_USER} -d pycsw"]
            interval: 10s
            timeout: 5s
            retries: 5
        volumes:
            - pycsw-data:/var/lib/postgresql/data
        networks:
            - ingrid-network

volumes:
    pycsw-data:

networks:
    ingrid-network:

Konfiguration¶

pycsw wird über eine YAML-Konfigurationsdatei (pycsw.yml) konfiguriert. Eine vollständige Referenz aller Parameter ist in der offiziellen Konfigurationsdokumentation verfügbar.

server:
  url: ${PYCSW_SERVER_URL}
  mimetype: application/xml; charset=UTF-8
  encoding: UTF-8
  language: de-DE
  maxrecords: 10
  timeout: 30
  #ogc_schemas_location: http://foo
  #pretty_print: true
  gzip_compresslevel: 9
  #domainquerytype: range
  #domaincounts: true
  #spatial_ranking: true
  #workers=2
  templates:
    path: /etc/pycsw/templates



logging:
  level: WARNING  # zur Fehlersuche: DEBUG
  # logfile: /tmp/pycsw.log

profiles:
  - apiso

manager:
  transactions: true
  allowed_ips:
    - 127.0.0.1
  # csw_harvest_pagesize: 10

metadata:
  identification:
    title: pycsw Geospatial Catalogue
    description: pycsw is an OARec and OGC CSW server implementation written in Python
    keywords:
      - catalogue
      - discovery
      - metadata
    keywords_type: theme
    fees: None
    accessconstraints: None
    terms_of_service: https://creativecommons.org/licenses/by/4.0
    url: https://example.org
  license:
    name: CC-BY 4.0 license
    url: https://creativecommons.org/licenses/by/4.0
  provider:
    name: Organization Name
    url: https://pycsw.org
  contact:
    name: Lastname, Firstname
    position: Position Title
    address: Mailing Address
    city: City
    stateorprovince: Administrative Area
    postalcode: Zip or Postal Code
    country: Country
    phone: +xx-xxx-xxx-xxxx
    fax: +xx-xxx-xxx-xxxx
    email: you@example.org
    url: Contact URL
    hours: Mo-Fr 08:00-17:00
    instructions: During hours of service. Off on weekends.
    role: pointOfContact

inspire:
  enabled: true
  languages_supported:
    - ger
    - eng
  default_language: ger
  date: YYYY-MM-DD
  gemet_keywords:
    - Utility and governmental services
  conformity_service: notEvaluated
  contact_name: Organization Name
  contact_email: Email Address
  temp_extent:
    begin: YYYY-MM-DD
    end: YYYY-MM-DD

repository:
  database: ${DB_URL}
  table: records
  facets:
    - type
    - title

xslt:
  - input_os: http://www.isotc211.org/2005/gmd
    output_os: http://www.isotc211.org/2005/gmd
    transform: /etc/pycsw/traceability-filter.xsl

Die wichtigsten Einstellungen im Überblick:

Authentifizierung¶

pycsw bietet keine eingebaute Benutzerauthentifizierung. Die Absicherung erfolgt auf zwei Ebenen:

• CSW-T (Schreibzugriff): Über manager.allowed_ips werden nur explizit erlaubte IP-Adressen zum Schreiben zugelassen.
• CSW (Lesezugriff): Für einen komplett nicht-öffentlichen Katalog empfiehlt sich ein vorgeschalteter Reverse Proxy mit HTTP Basic Auth.

Reverse Proxy mit HTTP Basic Auth (Apache)¶

Eine Passwortdatei kann mit htpasswd erstellt werden:

htpasswd -c /etc/apache2/.htpasswd <benutzername>

Beispielkonfiguration für Apache:

<VirtualHost *:80>
    ServerName <pycsw-host>

    ProxyPass        / http://pycsw:8000/
    ProxyPassReverse / http://pycsw:8000/

    <Location />
        AuthType Basic
        AuthName "CSW Katalog"
        AuthUserFile /etc/apache2/.htpasswd
        Require valid-user
    </Location>
</VirtualHost>

Erforderliche Apache-Module:

a2enmod proxy proxy_http auth_basic authn_file

XSLT-Transformation¶

pycsw kann CSW-Antworten vor der Auslieferung per XSLT transformieren. Dies wird über den Konfigurationsblock xslt gesteuert (siehe Beispiel pycsw.yml):

xslt:
  - input_os: http://www.isotc211.org/2005/gmd
    output_os: http://www.isotc211.org/2005/gmd
    transform: /etc/pycsw/traceability-filter.xsl

• input_os / output_os legen fest, für welches outputSchema die Transformation angewendet wird (hier: ISO 19139).
• transform verweist auf die XSLT-Datei im Container, die auf jede passende Antwort angewendet wird.

Traceability-Filter¶

Einliefernde InGrid-Komponenten (Editor, Harvester) hinterlegen Herkunfts- und Zuordnungsinformationen als strukturierte Schlagwörter im Feld apiso:Subject (z. B. organisation:, sub_organisation:, source:, transaction:, catalog:). Diese Traceability-Keywords werden benötigt, um Datensätze intern nach Partner, Anbieter oder Quelle filtern zu können (siehe FAQ Filterabfragen), sollen jedoch nicht in den nach außen ausgelieferten Metadatensätzen sichtbar sein. Diese Keywords sind kein Bestandteil des CSW- oder ISO-Standards, sondern eine InGrid-Konvention.

Die Datei traceability-filter.xsl entfernt diese internen Schlagwörter aus der CSW-Antwort, bevor sie an abfragende Komponenten (z. B. das Portal) ausgeliefert wird. Sie muss unter dem in xslt.transform angegebenen Pfad im pycsw-Container bereitgestellt werden (z. B. per Volume-Mount siehe Docker Compose Beispiel).

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:gmd="http://www.isotc211.org/2005/gmd"
                xmlns:gco="http://www.isotc211.org/2005/gco">

    <!-- Identity: copy everything by default -->
    <xsl:template match="@*|node()">
        <xsl:copy>
            <xsl:apply-templates select="@*|node()"/>
        </xsl:copy>
    </xsl:template>

    <!-- Suppress individual traceability keywords -->
    <xsl:template match="gmd:keyword[gco:CharacterString[
        starts-with(., 'source:')          or
        starts-with(., 'transaction:')     or
        starts-with(., 'catalog:')         or
        starts-with(., 'organisation:')    or
        starts-with(., 'sub_organisation:')
    ]]"/>

    <!-- Suppress the whole descriptiveKeywords block if only traceability keywords remain -->
    <xsl:template match="gmd:descriptiveKeywords[not(
        gmd:MD_Keywords/gmd:keyword[not(gco:CharacterString[
            starts-with(., 'source:')          or
            starts-with(., 'transaction:')     or
            starts-with(., 'catalog:')         or
            starts-with(., 'organisation:')    or
            starts-with(., 'sub_organisation:')
        ])]
    )]"/>

</xsl:stylesheet>

Anbindung von Komponenten¶

pycsw stellt einen einzigen CSW-Endpunkt bereit, über den sowohl lesende (CSW) als auch schreibende (CSW-T) Zugriffe erfolgen:

http://<pycsw-host>:<port>/csw

Ist ein Reverse Proxy vorgeschaltet, entspricht die Basis-URL dem Wert von server.url. Diese URL wird in der jeweiligen Komponente als CSW-Endpunkt hinterlegt.

Welche Voraussetzungen in pycsw erfüllt sein müssen, hängt von der Rolle der angebundenen Komponente ab:

Für alle Komponenten gilt:

• Netzwerk: Die Komponente muss den pycsw-Endpunkt erreichen können, z. B. über ein gemeinsames Docker-Netzwerk (siehe Docker Compose Beispiel) oder über die öffentliche URL.
• Ausgabeformat: Im InGrid-Kontext wird ISO 19139 (http://www.isotc211.org/2005/gmd) als outputSchema verwendet.
• Authentifizierung: Ist ein Reverse Proxy mit Basic Auth vorgeschaltet (siehe Authentifizierung), müssen die Credentials in der Verbindungskonfiguration der Komponente hinterlegt werden.

Die Einrichtung des Endpunkts auf Seite der jeweiligen Komponente ist in deren Dokumentation beschrieben, z. B. im Leitfaden Harvester-Katalog. Beispielanfragen für Lese- und Schreibzugriffe finden sich in den FAQ.

FAQ¶

Grundlegende Abfragen¶

http://<pycsw-host>/csw?SERVICE=CSW&REQUEST=GetCapabilities&VERSION=2.0.2

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

http://<pycsw-host>/csw?service=CSW&version=2.0.2&request=GetRecords&elementSetName=full&resultType=results&outputSchema=http://www.isotc211.org/2005/gmd&startPosition=1&maxRecords=10&typeNames=csw:Record

<?xml version="1.0" encoding="UTF-8"?>
<csw:GetRecords xmlns:csw="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"
    service="CSW" version="2.0.2"
    resultType="results"
    outputFormat="application/xml"
    outputSchema="http://www.isotc211.org/2005/gmd"
    startPosition="1" maxRecords="10">
    <csw:Query typeNames="csw:Record">
        <csw:ElementSetName>full</csw:ElementSetName>
    </csw:Query>
</csw:GetRecords>

http://<pycsw-host>/csw?service=CSW&version=2.0.2&request=GetRecordById&outputSchema=http://www.isotc211.org/2005/gmd&elementSetName=full&id=<UUID>

<?xml version="1.0" encoding="UTF-8"?>
<csw:GetRecordById xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    service="CSW" version="2.0.2"
    outputSchema="http://www.isotc211.org/2005/gmd"
    elementSetName="full">
    <csw:Id><UUID></csw:Id>
</csw:GetRecordById>

Filterabfragen¶

http://<pycsw-host>/csw?service=CSW&version=2.0.2&request=GetRecords&elementSetName=full&resultType=results&outputSchema=http://www.isotc211.org/2005/gmd&startPosition=1&maxRecords=100&typeNames=csw:Record&constraint=apiso:Subject like '%organisation:bund%'&constraintLanguage=CQL_TEXT

<csw:GetRecords xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    xmlns:ogc="http://www.opengis.net/ogc"
    service="CSW" version="2.0.2"
    resultType="results"
    outputSchema="http://www.isotc211.org/2005/gmd">
    <csw:Query typeNames="csw:Record">
        <csw:ElementSetName>full</csw:ElementSetName>
        <csw:Constraint version="1.1.0">
            <ogc:Filter>
                <ogc:PropertyIsLike wildCard="%" singleChar="_" escapeChar="\">
                    <ogc:PropertyName>apiso:Subject</ogc:PropertyName>
                    <ogc:Literal>%organisation:bund%</ogc:Literal>
                </ogc:PropertyIsLike>
            </ogc:Filter>
        </csw:Constraint>
    </csw:Query>
</csw:GetRecords>

http://<pycsw-host>/csw?service=CSW&version=2.0.2&request=GetRecords&elementSetName=full&resultType=results&outputSchema=http://www.isotc211.org/2005/gmd&startPosition=1&maxRecords=100&typeNames=csw:Record&constraint=apiso:Subject like '%sub_organisation:ni%'&constraintLanguage=CQL_TEXT

<csw:GetRecords xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    xmlns:ogc="http://www.opengis.net/ogc"
    service="CSW" version="2.0.2"
    resultType="results"
    outputSchema="http://www.isotc211.org/2005/gmd">
    <csw:Query typeNames="csw:Record">
        <csw:ElementSetName>full</csw:ElementSetName>
        <csw:Constraint version="1.1.0">
            <ogc:Filter>
                <ogc:PropertyIsLike wildCard="%" singleChar="_" escapeChar="\">
                    <ogc:PropertyName>apiso:Subject</ogc:PropertyName>
                    <ogc:Literal>%sub_organisation:ni%</ogc:Literal>
                </ogc:PropertyIsLike>
            </ogc:Filter>
        </csw:Constraint>
    </csw:Query>
</csw:GetRecords>

http://<pycsw-host>/csw?service=CSW&version=2.0.2&request=GetRecords&elementSetName=full&resultType=results&outputSchema=http://www.isotc211.org/2005/gmd&startPosition=1&maxRecords=10&typeNames=csw:Record&constraint=apiso:ResourceIdentifier='7988c147-7523-45bb-8f18-7f39d0d20541'&constraintLanguage=CQL_TEXT

<csw:GetRecords xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    xmlns:ogc="http://www.opengis.net/ogc"
    service="CSW" version="2.0.2"
    resultType="results"
    outputSchema="http://www.isotc211.org/2005/gmd"
    startPosition="1" maxRecords="10">
    <csw:Query typeNames="csw:Record">
        <csw:ElementSetName>full</csw:ElementSetName>
        <csw:Constraint version="1.1.0">
            <ogc:Filter>
                <ogc:PropertyIsEqualTo>
                    <ogc:PropertyName>apiso:ResourceIdentifier</ogc:PropertyName>
                    <ogc:Literal>7988c147-7523-45bb-8f18-7f39d0d20541</ogc:Literal>
                </ogc:PropertyIsEqualTo>
            </ogc:Filter>
        </csw:Constraint>
    </csw:Query>
</csw:GetRecords>

Schreibzugriffe (CSW-T)¶

curl --request POST \
  --url 'http://<pycsw-host>/csw' \
  --header 'content-type: application/xml' \
  --data '<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<csw:Transaction service="CSW" version="2.0.2"
    xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    xmlns:gmd="http://www.isotc211.org/2005/gmd"
    xmlns:gco="http://www.isotc211.org/2005/gco"
    xmlns:ogc="http://www.opengis.net/ogc"
    xmlns:apiso="http://www.opengis.net/cat/csw/apiso/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2 http://schemas.opengis.net/csw/2.0.2/CSW-publication.xsd">
    <csw:Insert>
        <!-- ein vollständiges Dokument im Format ISO 19139 (2007)-->
    </csw:Insert>
</csw:Transaction>'

curl --request POST \
  --url 'http://<pycsw-host>/csw' \
  --header 'content-type: application/xml' \
  --data '<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<csw:Transaction service="CSW" version="2.0.2"
    xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    xmlns:gmd="http://www.isotc211.org/2005/gmd"
    xmlns:gco="http://www.isotc211.org/2005/gco"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2 http://schemas.opengis.net/csw/2.0.2/CSW-publication.xsd">
    <csw:Update>
        <!-- ein vollständiges Dokument im Format ISO 19139 (2007)-->
    </csw:Update>
</csw:Transaction>'

curl --request POST \
  --url 'http://<pycsw-host>/csw' \
  --header 'content-type: application/xml' \
  --data '<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<csw:Transaction service="CSW" version="2.0.2"
    xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    xmlns:ogc="http://www.opengis.net/ogc"
    xmlns:dc="http://purl.org/dc/elements/1.1/">
    <csw:Delete>
        <csw:Constraint version="2.0.0">
            <ogc:Filter>
                <ogc:PropertyIsEqualTo>
                    <ogc:PropertyName>dc:identifier</ogc:PropertyName>
                    <ogc:Literal>8ab590a216f7f05f01185fd222071e45</ogc:Literal>
                </ogc:PropertyIsEqualTo>
            </ogc:Filter>
        </csw:Constraint>
    </csw:Delete>
</csw:Transaction>'

Migration¶