Kommandozeilenwerkzeug (CLI)
Das smart.finder CLI ist ein Werkzeug, um über die Kommandozeile Indexierungsjobs zu verwalten.
Verwendung
$ finderctl <Kommando> [Optionen]Übersicht der Kommandos
smart.finder CLI stellt folgende Kommandos bereit:
-
generate-token: Erzeugung eines Tokens für die Anmeldung -
login: Authentifizierung mit Session-Cookie -
logout: Beendigung einer Session -
jobs get: Download von Indexierungsjobs -
jobs put: Ändern von Indexierungsjobs -
jobs query: Abfrage von Indexierungsjobs -
help: Anzeigen der Hilfe
Kommandos
generate-token
Erzeugt ein Authentifizierungstoken für smart.finder Server mit dem INTEGRATED Authentifizierungsmodus.
Verwenden Sie für den Authentifizierungsmodus ONLY_AUTHN bitte die Kommandos login und logout.
Geben Sie Ihren Namen und Ihr Passwort ein, wenn Sie in der Kommandozeile dazu aufgefordert werden. Anschließend wird Ihnen ein Token angezeigt.
Mit diesem Token können Sie sich sowohl bei lesenden als auch bei schreibenden Anfragen beim Server authentifizieren.
Ergänzen Sie dazu bei jedem Kommando, das eine Authentifizierung voraussetzt, das erzeugte Token mithilfe des Parameters -t <your-token>.
|
Das mit diesem Kommando erzeugte Token enthält Ihren Namen und Ihr Passwort in Base64-kodierter Form. Aus dem Token können diese Daten sehr einfach wieder ausgelesen werden. Das Token ist so lange gültig, wie auch Ihr Benutzername und Passwort. Halten Sie das Token deshalb geheim und bewahren Sie es sicher auf. Wir empfehlen aus Sicherheitsgründen nach Möglichkeit die Verwendung von |
login
Meldet Sie in smart.finder an, falls smart.finder Server mit dem ONLY_AUTHN Authentifizierungsmodus konfiguriert ist.
Wenn smart.finder Server mit dem INTEGRATED Modus konfiguriert ist, nutzen Sie stattdessen generate-token.
Geben Sie in der Kommandozeile Ihren Namen und Passwort ein, wenn Sie in der Kommandozeile dazu aufgefordert werden.
Bei diesem Kommando erhält das CLI ein Session-Cookie vom Server. Alle folgenden Kommandos verwenden automatisch dieses Cookie für die Authentifizierung, sodass für die Laufzeit der Session keine neue Authentifizierung erforderlich ist.
Beispiel
$ finderctl login -u https://mysmartfinder-url.de
Please enter your credentials to login to smart.finder.
? Username: admin
? Password: [hidden]Optionen
-c,--configfile <configfile>-
Pfad zu einer JSON-Konfigurationsdatei
In dieser Konfigurationsdatei können Parameter für dieses und andere Kommandos voreingestellt werden.
-u,--auth-url <auth-url>-
URL zur Authentifizierung
Gebe die URL zu smart.finder oder zu map.apps, in dem die smart.finder Bundles installiert sind, zur Abfrage eines Session-Cookies. Wenn dieser Parameter nicht in der Kommandozeile angegeben wird, werden Sie während der Ausführung des Login-Kommandos nach dieser URL gefragt.
logout
Beendet die Session, die mit dem login-Kommando begonnen wurde.
Das Kommando löscht das Session-Cookie aus dem lokalen Speicher.
Wenn Sie auch eine URL per -u angeben, werden Sie zudem am Server abgemeldet.
Ansonsten bleibt die serverseitige Session so lange bestehen, bis diese von alleine ausläuft.
Beispiel
$ finderctl logout -u https://mysmartfinder-url.de
Successfully logged out from 'https://mysmartfinder-url.de'.Optionen
-c,--configfile <configfile>-
Pfad zu einer JSON-Konfigurationsdatei
In dieser Konfigurationsdatei können Parameter für dieses und andere Kommandos voreingestellt werden.
-u,--auth-url <auth-url>-
URL zur Authentifizierung/Logout
Die URL zu smart.finder oder map.apps (in dem die smart.finder Bundles installiert sind) zur Beendigung der serverseitigen Session. Wenn nicht angegeben, werden nur die temporären Anmeldedateien auf Ihrem Rechner gelöscht. Die serverseitige Sitzung bleibt bestehen, bis diese von selbst abläuft.
jobs
Mithilfe des jobs-Kommandos kann mit den in smart.finder verwalteten Jobs interagiert werden.
Dieses Kommando verfügt über folgende Unterkommandos:
get und put
Die beiden Unterkommandos get und put ermöglichen den Download beziehungsweise Upload der Jobs zwischen smart.finder Server und einem lokalem Verzeichnis.
Mittels jobs get lassen sich die Indexierungsjobs als JSON Datei vom Server abfragen und lokal speichern.
jobs put erzeugt beziehungsweise aktualisiert vorhandene Indexierungsjobs auf dem Server mithilfe der lokalen JSON-Datei.
Beispiel
$ finderctl jobs get -t YWRtaW46YWRtaW4= -u http://smartfinder.conterra.de/server -d c:/temp/jobs (1)
$ finderctl jobs get -u http://smartfinder.conterra.de/server -d c:/temp/jobs -q coreName:core0 (2)
$ finderctl jobs get -u http://smartfinder.conterra.de/server -d c:/temp/jobs -f title,timestamp (3)
$ finderctl jobs put -u http://smartfinder.conterra.de/server -d c:/temp/jobs (4)| 1 | Jobs abfragen, smart.finder Server mit INTEGRATED Sicherheitsmodus |
| 2 | Jobs mit Index core0 abfragen |
| 3 | Jobs abfragen; nur bestimmte Felder werden ausgegeben |
| 4 | Jobs erzeugen/aktualisieren |
Optionen
-u,--url <url>-
URL auf die smart.finder-Serverschnittstelle
Die URL ist identisch mit der URL, die für die Konfigurationseigenschaft
finder.service.urlin denapplication.propertiesvon smart.finder eingetragen wurde. -d,--directory <directory>-
Lokales Verzeichnis der JSON-Datei mit den Jobs
Verwenden Sie im Verzeichnispfad immer den Schrägstrich als Trennsymbol.
-c,--configfile <configfile>-
Pfad zu einer JSON-Konfigurationsdatei
In dieser Konfigurationsdatei können Parameter für dieses und andere Kommandos voreingestellt werden.
-q,--query <query>-
Abfrageausdruck zum Filtern der Jobs
Um mögliche Abfrage zu ermitteln können Sie das
jobs query-Kommando nutzen.Format:
feld1:wert1,feld2:wert2 -f,--fields <fields>-
Felder, die für jeden Job abgefragt werden sollen
Wenn nicht angegeben, werden alle Felder berücksichtigt.
-t,--token <token>-
Das Authentifizierungstoken für Abfragen gegen einen smart.finder Server mit INTEGRATED Sicherheitsmodus.
query
Das Unterkommando query ermöglicht es Ihnen Informationen über die Jobs abzufragen.
Diese Informationen können Sie auch für die query-Optionen der einzelnen Kommandos nutzen.
Beispiel
$ finderctl jobs query -s inactive -u http://localhost:8080/ct-finder-server-webapp-2.0.9
1 inactive job found.
{ id: 'AEaLrhyj2UhxO2mh', title: 'Demoportal CSW', state: 'inactive' }$ finderctl jobs query -id AEaLrhyj2UhxO2mh -u http://localhost:8080/ct-finder-server-webapp-2.0.9
{ id: 'AEaLrhyj2UhxO2mh', title: 'Demoportal CSW', state: 'inactive' }$ finderctl jobs query -id AEaLrhyj2UhxO2mh -d -u http://localhost:8080/ct-finder-server-webapp-2.0.9
{
id: 'AEaLrhyj2UhxO2mh',
count: '70',
source: 'https://demos.conterra.de/ct-smartfinder-csw-1.0.3/api',
title: 'Demoportal CSW',
creator: 'admin',
email: '',
created: '2021-08-02T15:19:39Z',
modified: '2021-08-03T13:14:50Z',
state: 'inactive',
cronstring: '',
context: '{"type":"csw","version":"2.0.2"}',
lastSuccess: '2021-08-03T11:14:20.543Z',
lastExecutionResult: 'success',
executionCount: 2,
targetState: 'inactive',
coreName: 'core0',
_version_: '1707070497780400128',
timestamp: '2021-08-03T11:14:50.010Z'
}Optionen
-s,--state <state>-
Filtert die Jobs nach ihrem Status
Erlaubte Werte:
scheduled,pending,inactive,executing -t,--token <token>-
Das Authentifizierungstoken für Abfragen gegen einen smart.finder Server mit INTEGRATED Sicherheitsmodus.
-d,--detail-
Ausgabe der detailierten Informationen
Ohne diese Option wird lediglich die ID, der Titel sowie der Status der Jobs ausgegeben.
-id,--identifier <id>-
Filtert die Jobs entsprechend der ID
-c,--configfile <path to configuration file>-
Pfad zu einer JSON-Konfigurationsdatei
In dieser Konfigurationsdatei können Parameter für dieses und andere Kommandos voreingestellt werden.
-u,--url <url>-
URL auf die smart.finder-Serverschnittstelle
Die URL ist identisch mit der URL, die für die Konfigurationseigenschaft
finder.service.urlin denapplication.propertiesvon smart.finder eingetragen wurde.
Verwendung einer Konfigurationsdatei
Bei den meisten Kommandos können Sie eine Konfigurationsdatei verwenden, um Einstellungen zu speichern.
Insbesondere bei häufig genutzten Eigenschaften sparen Sie sich das wiederholte Eingeben der gleichen Werte.
Stattdessen geben Sie die Konfigurationsdatei mittels -c Option in der Kommandozeile an und ergänzen optional noch fehlende Einstellungen.
Außerdem sind sicherheitsrelevante Informationen wie ein Token oder Passwort so besser geschützt, weil diese bei Ausführung nicht direkt einsehbar sind und nicht in der Kommandozeilen-Historie auftauchen.
Aufbau
In der Konfigurationsdatei im JSON Format werden für jedes Kommando ein Objekt mit den entsprechenden Optionen aufgelistet.
Unterkommandos, zum Beispiel das Unterkommando get des jobs-Kommandos, werden in der Konfigurationsdatei als Unterobjekte des übergeordneten Kommandos angegeben.
{
"commandA": {
"subCommand": {
"option": "value"
}
},
"commandB":{
"option": "value"
}
}Eine zentrale Angabe von mehrfach verwendeten Optionen, wie token, ist nicht möglich.
Diese können sich in den Werten bei den verschiedenen Kommandos unterscheiden, aufgrund unterschiedlicher Serverinstanzen.
Schreibweise der Parameternamen
In der Datei müssen die ausgeschriebenen Parameternamen verwendet werden.
Die in der Kommandozeile meist verwendeten Abkürzungen werden nicht unterstützt.
Verwenden Sie deshalb beispielsweise directory statt -d.
Die Schreibweise der Parameter können Sie über die Hilfefunktion in der Kommandozeile abfragen.
Beispiel für das jobs put Kommando:
$ finderctl jobs put -h
Usage: finderctl jobs put [options]
Create/update indexing jobs from local files.
Options:
-c, --configfile <configfile> Path to a JSON configuration file.
-t, --token <token> Optional. Base64-encoded token for HTTP Basic
authentication.
-u, --url <url> URL to the smart.finder server endpoint.
-d, --directory <directory> Path to the directory where the indexing job files
are located.
-q, --query <query> A query expression to filter the jobs. Format:
field1:value1,field2:value2
-f, --fields <fields> The fields of a job to include. If not specified,
all fields are considered.
-h, --help display help for commandDie Parameternamen, die wie --directory mit zwei Bindestrichen beginnen, können Sie in der Konfigurationsdatei ohne die anführenden Bindestriche verwenden.
Mit Bindestrich getrennte Parameternamen wie --auth-url werden in der Konfigurationsdatei in der camelCase-Schreibweise verwendet.
Aus --auth-url wird somit authUrl.
Zusätzliche Parameter für das login Kommando
Für das Kommando login können Sie zusätzlich zu den oben genannten Optionen des Kommandos noch den Namen und das Passwort für die Anmeldung angeben.
Aus Sicherheitsgründen können Sie diese nur in der Konfigurationsdatei, nicht aber in der Kommandozeile verwenden.
username-
Der Anmeldename am Server.
password-
Das Passwort für die Anmeldung.
Beispiel
Im Folgenden sehen Sie ein Beispiel einer Konfigurationsdatei.
{
"login": {
"authUrl": "https://smartfinder.conterra.de", (1)
"username": "admin" (2)
},
"jobs": { (3)
"get": {
"url": "https://smartfinder.conterra.de/server",
"directory": "c:/temp/smartfinder"
},
"put": { (4)
"directory": "c:/temp/smartfinder"
}
}
}| 1 | aus --auth-url wird authUrl |
| 2 | username ist ein Parameter exklusiv für die Verwendung in der Konfigurationsdatei |
| 3 | jobs besteht aus den Unterkommandos get und pull, diese müssen als Objekte innerhalb von jobs angegeben werden |
| 4 | da hier lediglich das directory definiert ist, nicht aber die url, muss diese beim Ausführen in der Kommandozeile angeben werden |