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

Globale Optionen

-v, --version

Gibt die Version des finderctl-Werkzeugs aus.

-h, --help

Gibt Informationen zur Verwendung eines Kommandos, finderctl <Kommando> --help, oder für das Werkzeug selbst, finderctl --help, aus.

Beispiel:

$ finderctl login -h

Hilfe zu Befehlen erhalten

Um schnelle Hilfe zu einem bestimmten Befehl zu erhalten, geben Sie den Befehl gefolgt von der -h-Option ein:

$ finderctl jobs -h

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 ONLY_AUTHN als Authentifizierungsmethode.

Verwendung

$ finderctl generate-token

Beispiel

$ finderctl generate-token
Generate an authentication token for managing indexing jobs.

✔ Username: · admin
✔ Password: ·

Your authentication token is:
YWRtaW46YWRtaW4=

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.

Verwendung

$ finderctl login [Optionen]

Beispiel

$ finderctl login -u http://smartfinder-host.example.com/server

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.

Verwendung

$ finderctl logout [Optionen]

Beispiel

$ finderctl logout -u http://smartfinder-host.example.com/server
Successfully logged out from 'http://smartfinder-host.example.com/server'.

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.

Verwendung
$ finderctl jobs {get|put} [Optionen]
Beispiel
$ finderctl jobs get -t YWRtaW46YWRtaW4= -u http://smartfinder-host.example.com/server -d c:/temp/jobs (1)
$ finderctl jobs get -u http://smartfinder-host.example.com/server -d c:/temp/jobs -q coreName:core0 (2)
$ finderctl jobs get -u http://smartfinder-host.example.com/server -d c:/temp/jobs -f title,timestamp (3)
$ finderctl jobs put -u http://smartfinder-host.example.com/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.url in den application.properties von 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.

Verwendung
$ finderctl jobs query [Optionen]
Beispiel
Informationen über die Jobs gefiltert nach Jobs mit inaktivem Status
$ 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' }
Informationen über die Jobs gefiltert nach der ID
$ finderctl jobs query -id AEaLrhyj2UhxO2mh -u http://localhost:8080/ct-finder-server-webapp-2.0.9
{ id: 'AEaLrhyj2UhxO2mh', title: 'Demoportal CSW', state: 'inactive' }
Detailerte Informationen über die Jobs
$ finderctl jobs query -id AbcDef12345abcdef -d -u http://localhost:8080/ct-finder-server-webapp
{
id: 'AbcDef12345abcdef',
count: '70',
source: 'https://www.example.com/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.url in den application.properties von 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 command

Die 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.example.com", (1)
    "username": "admin" (2)
  },
  "jobs": { (3)
    "get": {
      "url": "https://smartfinder.example.com/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