Enterprise search-APP

Enterprise search-APP

Hinweis

Die App d.velop enterprise search ist noch nicht öffentlich verfügbar. Gerne stellen wir dir die App im Rahmen eins Early Adopter-Programms bereit. Wende dich dazu bitte an earlyadopter.enterprisesearch@d-velop.de.

 Funktionsumfang

Die App d.velop enterprise search ist die zentrale HTTP-Schnittstelle zur Durchsuchung deiner Systemlandschaft.

 Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle von d.velop enterprise search für deine eigenen Entwicklungen nutzen kannst.

 Authentifizierung

Einige Schnittstellen von d.velop enterprise search benötigen eine gültige Authentifizierung von d.ecs identity provider.

Wie du eine solche Authentifizierung erhälst, kannst du der API-Dokumentation von d.ecs identity provider entnehmen.

 Bereitstellen von Providern

Mit dieser Funktion kannst du Provider bereitstellen. Provider sind Systeme, die durchsucht werden können. Die Provider werden innerhalb von d.velop enterprise search dargestellt.

Folgende Anforderungen müssen erfüllt sein, damit die Provider deiner App in d.velop enterprise search angezeigt werden:

  • Die App muss an der http gateway-App registriert sein (nur On-Premises).
  • Die App muss eine Linkrelation (enterprisesearchfeatures) zu der Enterprise Search-Konfiguration ausliefern.
  • Die App muss für jeden Provider eine OpenSearch-Beschreibung ausliefern.

 Linkrelation (enterprisesearchfeatures) zu der Enterprise Search-Konfiguration ausliefern

Damit d.velop enterprise search die Provider deiner App anzeigt, muss deine App unter der Basisadresse auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" eine Linkrelation enterprisesearchfeatures ausliefern.

Repräsentation der Ressource:

   {
  "_links": {
    "enterprisesearchfeatures": {
      "href": string
    }
  }
}

EigenschaftTypBeschreibungPflicht
_linksObjektLinkrelationen zu den Ressourcen einer AppJa
_links.enterprisesearchfeaturesObjektObjekt, welches den Pfad zu der Enterprise Search-Konfiguration einer App enthältJa
_links.enterprisesearchfeatures.hrefStringPfad, unter dem die Enterprise Search-Konfiguration abgerufen werden sollJa

Nachfolgend findest du ein Beispiel für eine solche Antwort im JSON-Format:

   {
  "_links": {
    "enterprisesearchfeatures": {
      "href": "/exampleapp/enterprisesearchfeatures"
    }
  }
}

 Beschreibung der Enterprise Search-Konfiguration

Unter der URL href muss auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" ein JSON-Objekt mit folgenden Angaben ausgeliefert werden.

Repräsentation der Ressource:

   {
  "name": string,
  "iconUrl": string,
  "loginUrl": string,
  "loggedInUrl": string,
  "configUrl": string,
  "provider": [
    {
      "type": "OPENSEARCH",
      "iFrameCompatible": boolean,
      "description": string
    },
    {
      "type": "OPENSEARCH",
      "iFrameCompatible": boolean,
      "description": string
    }
  ]
}

EigenschaftTypBeschreibungPflichtAnmerkung
nameStringEnthält den übergeordneten Name für die Provider, z.B. d.3ecm, Google oder MicrosoftJa
iconUrlStringEnthält die URL zu einem Icon der AppJaURL zu einem Icon mit der Größe 32 x 32 Pixel im PNG- oder SVG-Format.
loginUrlStringEnthält die URL zu einer Ressource, die die Authentifizierung im Fremdsystem durchführtNein, optional
loggedInUrlStringEnthält die URL zu einer Ressource, die angibt, ob der aktuelle Benutzer am Fremdsystem authentifziert istNein, optional
configUrlStringEnthält die URL zu einer Ressource, die die Konfigurationseinträge zurückgibtNein, optional
provider[]ListeProvider enthält ein oder mehrere Provider-ObjekteJa
provider[].typeStringEnthält den Typ der Provider-BeschreibungJaFolgende Typen an Provider-Beschreibungen werden unterstützt: OPENSEARCH
provider[].iFrameCompatibleBooleanGibt an, ob die Suchergebnisse in einem iFrame (innerhalb der ShellApp) angezeigt werden können.Ja
provider[].descriptionStringEnthählt die URL zu der OpenSearch-Beschreibungsdatei (.osdx)JaWeitere Informationen zum Aufbau der OpenSearch-Beschreibungsdatei findest du hier

Nachfolgend findest du ein Beispiel für eine Enterprise Search-Konfiguration mit einem Provider.

   {
   "name": "Awesome App",
   "iconUrl": "/exampleapp/path/to/icon-thumbsup.png",
   "loginUrl": "/exampleapp/oauth2/login",
   "loggedInUrl": "/exampleapp/oauth2/loggedIn",
   "configUrl": "/exampleapp/config/features",
   "provider": [
      {
         "type": "OPENSEARCH",
         "iFrameCompatible": true,
         "description": "/exampleapp/opensearch/description"
      }
   ]
}

 Beschreibung der Login-Ressource

Unter der URL loginUrl muss auf eine GET-Anfrage der Benutzer zu einer Anmeldung an dem Fremdsystem umgeleitet werden. Die Authentifzierungsinformationen müssen in der jeweiligen App für den aktuellen Benutzer gespeichert und bei einer Suche entsprechend verwendet werden.

Hinweis

Die URL wird nur aufgerufen, wenn die LoggedIn-Ressource mit dem HTTP-Statuscode 401 (UNAUTHORIZED) antwortet.

 Beschreibung der LoggedIn-Ressource

Unter der URL loggedInUrl muss auf eine GET-Anfrage geprüft werden, ob der aktuelle Benutzer Zugriff auf das Fremdsystem hat. Folgende Rückgabewerte sind zulässig:

HTTP-StatuscodeBeschreibung
200Der Benutzer ist authentifziert und kann eine Suche im Fremdsystem durchführen
401Der Benutzer ist nicht authentifziert

 Beschreibung der Config-Ressource

Unter der URL ConfigUrl muss auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" ein JSON-Objekt mit folgenden Angaben ausgeliefert werden.

Repräsentation der Ressource:

   [
   {
      "caption": string,
      "description": string,
      "href": string,
      "keywords": [string, string, ...],
      "configurationState": number
   }
]

EigenschaftTypBeschreibungPflichtAnmerkung
root[]ListListe aller MenüpunkteJa
root[].captionStringÜberschrift des MenüpunktesJa
root[].descriptionStringBeschreibung des MenüpunktesJa
root[].hrefStringLink zu der Konfiguration hinter dem MenüpunktJa
root[].keywordsString[]Liste von Schlüsselwörtern, die den Menüpunkt beschreiben, um eine Suche nach dem Menüpunkt zu ermöglichenNein, optional
root[].configurationStateNumberStatus der KonfigurationJa0: Die Konfiguration ist vollständig. 1: Die Konfiguration ist unvollständig und sollte vervollständigt werden.

Nachfolgend findest du ein Beispiel für eine Config-Ressource.

   [
   {
      "caption": "Awesome App configuration",
      "description": "Short description of the configuration",
      "href": "/exampleapp/oauth2/config",
      "keyWords": ["oauth2", "awesome", "login"],
      "configurationState": 0
   }
]

Hinweis

Damit die Konfigurationseinträge unterhalb der Konfiguration von d.velop enterprise search angezeigt werden, muss die Konfiguration Suchprovider verwalten einmalig aufgerufen werden.

 Suche durchführen

Mit dieser Funktion kannst du eine Suche gegen alle in d.velop enterprise search bekannten Provider absetzen und die Ergebnisse in deiner App verwenden. Die Suche wird über das Format OpenSearch durchgeführt. Im Folgenden wird aufgezeigt, wie du die OpenSearch-Beschreibungsdatei erhältst.

 OpenSearch-Beschreibungsdatei

Die URL /enterprisesearch/opensearch gibt eine HTML-Seite zurück, über die zwei OpenSearch-Beschreibungsdateien heruntergeladen werden können.

Beschreibungsdatei herunterladen
Der Link führt zu einer OpenSearch-Beschreibungsdatei, die du gemäß dem Format OpenSearch verwenden können. Alternativ kann die Beschreibungsdatei auch direkt durch den Aufruf der folgenden URL abgerufen werden:

   /enterprisesearch/opensearch/description

Beschreibungsdatei für Windows herunterladen
Der Link führt zu einer OpenSearch-Beschreibungsdatei, der d.ecs identity tunnel für die Zwischenspeicherung des Cookies verwendet. Die Beschreibungsdatei kann gemäß des Formats OpenSearch verwendet werden. Verwende diese Beschreibungsdatei, um d.velop enterprise search in deinen lokalen Dateiexplorer zu integrieren. Alternativ kann die Beschreibungsdatei auch direkt durch den Aufruf der folgenden URL abgerufen werden:

   /enterprisesearch/opensearch/description?identitytunnel=true