ometha 2.0.2

OAI Metadata Harvester

Ometha (OaiMETadataHArvester)

Features

Die zentrale Anforderung für Workflow der Fachstelle Bibliothek ist, dass jeder OAI-Record in einer eigene Datei ist, mit eigenem OAI-Header. Das lässt sich theoretisch auch mit „normalem“ Harvesting erreichen (in dem man die XML Dateien nach dem Harvestingvorgang splittet), wir haben uns aber auch aus Gründen der Stabilität der Schnittstellen dafür entschieden, über das Verb ListIdentifiers zunächst alle relevanten OAI-IDs zu harvesten und dann per GetRecord die einzelnen Datensätze einen nach dem anderen anzuziehen.

Die zweite Anforderung an den Harvester ist der Spagat zwischen der Möglichkeit der Automatisierung und Benutzerfreundlichkeit. Daher umfasst Ometha drei Modi:

• einen „interaktiven“ Modus, der den Benutzer nach den Variablen fragt - nutzbar als Ometha.exe per Doppelklick unter Windows; keine Installation nötig
• Kommandozeilenmodus mit Parameter-Übergabe
• Kommandozeilenmodus per Konfigurationsdatei(en) inkl. vollautomatischem Update-Modus

Geschwindigkeit

Harvesting eines Sets mit 19999 Datensätzen von der OAI Schnittstelle der Deutschen Digitalen Bibliothek:

1. Ometha
   • ometha default -b https://oai.deutsche-digitale-bibliothek.de/ -s 10443700598299947xcYN -m ddb
   • 6:19 Minuten -> Log, ID List & jeder Record in einer XML Datei
2. Metha:
   • metha-sync https://oai.deutsche-digitale-bibliothek.de/ -set 10443700598299947xcYN -format ddb
   • 6:33 Minuten -> gzipped XMLs mit jeweils 300 Records pro File (Abruf über ListRecords) See https://github.com/Deutsche-Digitale-Bibliothek/ddblabs-ometha/issues/3 !
3. oai-pmh:
   • oai-pmh list-records -s 10443700598299947xcYN -p ddb https://oai.deutsche-digitale-bibliothek.de/ > ddbfiles.txt
   • 13:17 Minuten -> JSON statt XML Return
4. shell-oaiharvester:
   • ./oaiharvester -r ddb
   • 2:19:50 Stunden -> Plaintext Dateien ohne Dateiendung

Installation

Empfohlen: uvx

Kein vorheriges Installieren nötig – uv richtet automatisch eine isolierte Umgebung ein:

uvx ometha

Für dauerhafte Installation (einmalig, danach direkt als ometha aufrufbar):

uv tool install ometha
ometha --version

pip

pip install ometha

Ausführbare Datei (kein Python erforderlich)

Vorkompilierte .exe / Binaries für Windows, macOS und Linux: https://github.com/Deutsche-Digitale-Bibliothek/ddblabs-ometha/releases

Aus dem Quellcode

git clone [e-mail]:Deutsche-Digitale-Bibliothek/ddblabs-ometha.git
cd ddblabs-ometha
uv sync
uv run ometha --version

Windows: SmartScreen

Sollte Windows SmartScreen unter Windows 10 die Ausführung von Ometha.exe verhindern:

... klickt man auf den etwas unscheinbaren Link "Weitere Informationen" und dann erscheint ein kurzer Text und links neben dem Button "Nicht ausführen" der Button "Trotzdem ausführen". Letzterer startet das Programm.

Interaktiver Modus

Der Benutzer wird zur Eingabe der erforderlichen und optionalen Parameter gebeten, die Eingaben werden validiert, mehrere Sets werden kommagetrennt eingegeben: Seteins,Setzwei.

Die Sonderfunktion "Anzeige aller auf der Schnittstelle vorgandener Sets" parst ListSets und ListIdentifiers rekursiv, um eine Übersicht aller vorhandenen Sets und Metadata-Prefixe zu generieren:

Aufruf über die Kommandozeile (CLI Modus)

Information: Es können sowohl die ausführbare Datei als auch das Python-Script ausgeführt werden, zunächst muss aber in der Kommandozeile per cd Befehl in den Ordner gewechselt werden, in dem die Datei liegt (es sei denn, die Ausführbare Datei ist im PATH, also unter Linux bspw. in /usr/bin). Dann beginnt der Aufruf entweder mit Ometha.exe (Windows) oder mit python Ometha.py (Python Aufruf) bzw. mit Ometha (Unix). In den folgenden Beispielen muss also der Beginn ggf. ausgetauscht werden.

Der Aufruf von Ometha kennt vier "positional arguments", die die Modi unterscheiden: default, conf, auto und ids. Je nach Modus werden dann weitere Argumente benötigt bzw. sind möglich.

default Harvesting

• Der "normale" (=default) Kommandozeilenmodus erwartet default als erstes Argument
• Die Angabe der URL der Schnittstelle per -b ist dabei immer zwingend notwendig
• Ebenso die Angabe des Metadata-prefixes per -m.
• Alle anderen Parameter sind optional

Ein Kommandozeilenaufruf sieht dann bspw. so aus:

ometha default -b https://oai.schnittstelle.de -m metadataprefix -d ordnername -s set1 set2 -o /home/harvesting/

Optionale Parameter:

• -s/--set: Angabe von Set(s): Mehrere Sets werden getrennt durch ein Leerzeichen eingegeben: -s Seteins Setzwei
• -t/--timeout: Timeout zwischen den GetRecord Anfragen in Sekunden (nur für wirklich instabile Schnittstellen)
• -o/--outputfolder: Angabe des Ordners, in dem der beim Harvesting angelegte Datenpartner-Ordner erzeugt wird
• -d/--datengeber: Name des Datenpartner-Ordners
• -f/--fromdate: From-Date: ISO8601 Zeitangabe (YYYY-MM-DD), Harvesting von OAI Records ab diesem Zeitpunkt
• -u/--untildate: Until-Date: ISO8601 Zeitangabe (YYYY-MM-DD), Harvesting von OAI Records bis zu diesem Zeitpunkt
• --resumptiontoken: ResumptionToken, falls das Identifier Harvesting abgebrochen war und wieder aufgenommen werden soll (keine Kurzform!)
• -p/--parallel: Angabe der parallelen Downloads via GetRecord - default ist 16, wird auf maximal 100 begrenzt. Kann je nach Schnittstelle extreme GEschwindigkeitsvorteile bringen oder zu vielen Fehlern führen, in diesem Fall ist der Wert zu verringern.
• --debug: Schalter (ohne weitere Angabe von Argumenten) um Debugging zu aktivieren (verboser Output)

Harvesten mit Konfigurationsdateien (config)

Ometha unterstützt Harvesting über Konfigurationsdateien. So können Harvestingvorgänge komplett automatisiert werden und auch per cronjob o. ä. aufgerufen werden. Beim Aufruf mit dem positional Argument conf und dem Argument -c mit dem Pfad zu einer entsprechenden Konfigurationsdatei (ometha conf -c /pfad/zur/konfigurationsdatei.yaml) werden alle Parameter aus einer YAML Datei gelesen:

ometha conf -c saarland.yaml

Mit dem optionalen Parameter -a bzw. --auto wird der Automatikmodus für die Angaben des from- und until-Datums aktiviert: Dabei wird beim Start der until-Wert auf das aktuelle Datum gesetzt und somit der Zeitraum vom angegebenen from-Date bis zum aktuellen Zeitpunkt geharvestet, nach erfolgreichem Harvesting wird dann der from-Wert auf das aktuelle Datum gesetzt. Beim nächsten Harvesting Vorgang wird wieder zunächst das until-Datum aktualisiert, so dass immer der Zeitraum seit dem letzten Harvesting Vorgang eingestellt ist.

Beispiel für eine Konfigurationsdatei:

baseurl: https://digital.sulb.uni-saarland.de/viewer/oai/
metadataPrefix: mets
datengeber: SULB
sets:
  - hk
# Mehrere Sets:
# sets:
#   - Seteins
#   - Setzwei
fromdate: '2020-02-13'
untildate: null
timeout: 0
outputfolder: null
debug: false
# Anzahl paralleler Downloads (optional, default: automatisch basierend auf ID-Anzahl):
# numberofprocesses: 8

Pflichtfelder sind baseurl und metadataPrefix. Der Key debug nimmt nur die Werte true und false an, der Key timeout nur Zahlen. From- und until-date können als String (mit Anführungszeichen) oder als Datum (ohne Anführungszeichen) eingegeben werden. Alle anderen Keys sind optional und können null sein.

Kommandozeilen Parameter für den conf Modus:

usage: Ometha conf [-h] --conf CONF [--auto] [--debug]

optional arguments:
  -h, --help            show this help message and exit
  --conf CONF, -c CONF  relativer oder absoluter Pfad zur YAML Konfigurationsdatei
  --auto, -a            Automatischer Modus zum Harvesten des Zeitraums vom from-date bis heute. Passt die Daten in der Konfigurationsdatei automatisch an.
  --debug               Gibt den Return der ListIdentifiers aus

auto-Modus

Versucht, die Parameter aus einer kompletten OAI-URL auszulesen. Einziger Parameter ist -u für die URL:

ometha auto -u https://digital.sulb.uni-saarland.de/viewer/oai/?verb=ListIdentifiers&metadataPrefix=mets&until=2021-01-01&set=saarlandica

usage: ometha auto [-h] --url URL [--outputfolder OUTPUTFOLDER]

optional arguments:
  -h, --help            show this help message and exit
  --url URL, -u URL     URL
  --outputfolder OUTPUTFOLDER, -o OUTPUTFOLDER
                        Output Ordner

ids: Harvesten einer ID-Liste

Für den Fall, dass eine bereits mit Ometha erstellte ID Liste geharvestet werden soll, nutzt man den ids Modus:

usage: ometha ids [-h] --idfile IDFILE [--datengeber DATENGEBER] [--debug]

optional arguments:
  -h, --help            show this help message and exit
  --idfile IDFILE, -i IDFILE
                        Path to ID YAML File
  --parallel PARALLEL, -p PARALLEL
                        Number of parallel downloads (default: 16)
  --datengeber DATENGEBER, -d DATENGEBER
                        Datengeber (Ordnername)
  --outputfolder OUTPUTFOLDER, -o OUTPUTFOLDER
                        Output Ordner
  --debug               Gibt den Return der ListIdentifiers aus

Errorhandling: Abbruch beim Harvesten der OAI-Identifier

Während des ID-Harvestings speichert Ometha automatisch alle 1000 IDs einen Checkpoint: Die aktuelle resumptionToken wird in resumption_token_latest.txt im Ausgabeordner geschrieben. Bei einem Verbindungsabbruch wird zusätzlich eine zeitgestempelte Datei resumption_token_<timestamp>.txt angelegt.

Falls beim Harvesten der OAI-IDs etwas schief geht, reicht es, sich den letzten angezeigten Resumption-Token zu notieren (bzw. in der Checkpoint-Datei oder Log-Datei zu schauen) und Ometha dann mit dem zusätzlichen Parameter --resumptiontoken=resumptiontoken auszuführen bzw. beim interaktiven Modus die Option [R] zu wählen:

ometha default -b https://oai.schnittstelle.de -m metadataprefix -d ordnername --resumptiontoken=nEk0tn0itpmuser

(Hier ist darauf zu achten, dass man immer --resumptiontoken= nutzt, da es durchaus ResumptionTokens gibt, die mit einem Bindestrich anfangen und somit im Kommandozeilenmodus als neuer Parameter verstanden würden, wenn man --resumptiontoken -1dsada-2wdss eingeben würde. Die verkürzte Option -r ist daher auch deaktiviert.)

Konfigurationsdatei

Beim Start von Ometha wird überprüft, ob eine ometha.yaml Einstellungsdatei vorhanden ist. Ist das nicht der Fall, kann diese von Ometha erzeugt werden. Bislang (Version 1.8) wird darüber nur der User-Agent konfiguriert.

Die Datei wird unter Windows neben der ausgefürten Ometha Datei abgelegt, in Linux und macOS als versteckte Datei direkt im Home-Verzeichnis des Benutzers (~/.ometha.yaml).