BPC Modul Instanzen erstellen

Voraussetzungen

OpenSearch muss installiert sein
Karaf mit den benötigten BPC Modulen/Bundles muss laufen

In den untenstehenden Beispielen verwendet OpenSearch den Standardport 9200 und Karaf den Standardport 8181.

Zusammenfassung

Die BPC-API kann entweder über Benutzer/Passwort (funktioniert nicht, wenn Keycloak verwendet wird) oder über einen API-Schlüssel (bevorzugte Methode) genutzt werden.
Die Einstellungen (JSON) der zu erstellenden BPC-Modulinstanzen müssen vorhanden sein (z. B. vorher exportiert).
Die BPC-Deployment-API wird verwendet, um Modulinstanzen (Dashboard, Monitor, Logdienst, …) zu erstellen.

Erstellen eines API-Schlüssels für BPC-API-Aufrufe (Version 1)

Dies muss im Voraus entweder über das BPC-Frontend → Core Services → API Keys erfolgen oder durch direktes Einfügen der Einstellung in OpenSearch (falls keine vorhanden sind; andernfalls wird die bestehende Einstellung überschrieben).

Direkt in OpenSearch einfügen:

curl -X POST \
     -H 'Content-Type: application/json' \
    "http://localhost:9200/bpc-configuration/bpc-setting/_core_noinstance_apiKeys" -d '
{
  "id": "_core_noinstance_apiKeys",
  "moduleId": "_core",
  "instanceId": "noinstance",
  "instanceType": "none",
  "name": "apiKeys",
  "type": "json",
  "value": {
    "1f697af5-c147-3d94-c529-e06f3f15bb87": {
      "issuedFor": "inubit",
      "issuedOn": "2020-03-16T07:00:00.000Z",
      "assignedRoles": [
        "bpcadmin"
      ],
      "assignedRights": [],
      "issuedBy": "bpcadmin",
      "assignedOrganisations": [],
      "expiresIn": "1 days"
    }
  }
}'

"1f697af5-c147-3d94-c529-e06f3f15bb87" ist ein zufälliger API-Schlüssel, der beim Aufruf der BPC-API als HTTP-Header gesetzt wird. Natürlich müssen Sie das Feld "issuedOn" auf das aktuelle Datum anpassen. Andernfalls wird Ihre Anfrage abgelehnt, da sie in diesem Beispiel nur einen Tag gültig ist.

Erstellen eines API-Schlüssels für BPC-API-Aufrufe (Version 2)

Diese Version verwendet den BPC-Login und einen BPC-API-Aufruf, um API-Schlüssel zu erstellen.

Login mit bpcadmin

curl -X POST \
     -c cookies.txt \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     "http://localhost:8181/cxf/bpc-core/authentication" \
     --data-urlencode "tenantname=DEFAULT" \
     --data-urlencode "username=bpcadmin" \
     --data-urlencode "password=bpcadmin"

Sie müssen die Cookies speichern und den X-Csrf-Token aus der Antwort behalten. Dieser wird im nächsten Schritt verwendet.

Überprüfen, ob die Sitzung gültig ist

curl -X GET \
     -b cookies.txt \
     "http://localhost:8181/cxf/bpc-core/authentication"

Sitzung prüfen: Erfolgsantwort

{
  "organisations": [
    "DEFAULT"
  ],
  "inactiveOrganisations": [],
  "roles": [
    "bpcadmin",
    "bpcuser"
  ],
  "rights": [
    "loadModule_blank"
  ],
  "principals": {
    "X-Csrf-Token": [
      "anQdpgq-aHCHHYCfAZmn0_B7Xr-CNIBb_c3qHJ9gLQyTCavo8CLygvPMl8jcsCF45NdOeEx9AipHpBx-4r7-bASxJgzk7vL-5PGXgMNzZXl7oT6njH4Tu62YW_ad23ckmOr05nq7jzecHaYkSMHMBHqqGcW8zV7rEDpm_CkqTUY"
    ],
    "org.apache.karaf.jaas.boot.principal.UserPrincipal": [
      "bpcadmin"
    ]
  },
  "loginContext": null,
  "customData": {},
  "expirationDate": 1589406354988,
  "firstName": "",
  "lastName": "bpcadmin",
  "loginName": "bpcadmin"
}

Sitzung prüfen: Fehlerantwort

{
  "error": {
    "messageKey": "CORE_ERROR_IDENTITY_PROVIDER_AUTHENTICATION_FAILED",
    "code": 540,
    "name": "AUTHENTICATION_UNAUTHORIZED",
    "message": "Authentication failed",
    "properties": {}
  }
}

Erstellen der API-Schlüssel-Einstellung

Verwenden Sie die zuvor gespeicherten Cookies und setzen Sie den X-Csrf-Token mit dem Wert der Login-Antwort.

curl -X POST \
    -b cookies.txt \
    -H 'Content-Type: application/json' \
    -H 'X-Csrf-Token: 3worAKpB4gLk5fLDbMesVPn76DbWdBvh_lQHYE0SbBzQtxGJfxVZqekxRe7MaFJ7Wj5mTsYtTX5evCM1T3rouVp89HO7_4fGZtm7gl1Zy407rjv_yZwrV8HXApJJovsFyixrf9U70Wd6qmy_BOfdlZSUG18l7cOALdTBR09u7J4' \
    "http://localhost:8181/cxf/bpc-core/configuration/_core" -d '
[ {
    "id" : "_core_noinstance_apiKeys",
    "name" : "apiKeys",
    "moduleId" : "_core",
    "instanceId" : "noinstance",
    "instanceType" : "none",
    "type" : "json",
    "value" : {
      "1f697af5-c147-3d94-c529-e06f3f15bb87" : {
        "expiresIn" : "1 days",
        "issuedFor" : "inubit-installer",
        "assignedRoles" : [ "bpcadmin" ],
        "assignedOrganisations" : [ ],
        "issuedBy" : "bpcadmin",
        "assignedRights" : [ ],
        "issuedOn" : "2020-05-07T13:19:19.544Z"
      }
    },
    "_group" : "core",
    "_readableByRoles" : [ "bpcadmin" ],
    "_writeableByRoles" : [ "bpcadmin" ],
    "_label" : "CORE_SETTING_LABEL_API_KEYS"
} ]'

"1f697af5-c147-3d94-c529-e06f3f15bb87" ist ein zufälliger API-Schlüssel, der als HTTP-Header beim Aufruf der BPC-API gesetzt wird. Natürlich müssen Sie das Feld "issuedOn" auf das aktuelle Datum anpassen. Andernfalls wird Ihre Anfrage abgelehnt, da sie - in diesem Beispiel - nur einen Tag gültig ist.

Anfordern einer neuen Modulinstanz-ID

Es gibt jetzt (12.05.2020) einen zusätzlichen API-Endpunkt, um eine neue Instanz-ID anzufordern:

/cxf/bpc-core/configuration/{moduleId}/{instanceType}/newInstanceId

Sie müssen {moduleId} auf die ID des Moduls setzen, für das die Instanz erstellt werden soll.
Sie müssen {instanceType} auf den korrekten Instanztyp der Modulinstanz setzen. Setzen Sie es auf 'none', falls das Modul keine Instanztypen unterstützt.

Sie erhalten erweiterte Fehlermeldungen (eine Liste der unterstützten Modul-IDs und Instanztypen), falls die angegebene Modul-ID oder der Instanztyp falsch ist.

Beispiel für eine Fehlermeldung, wenn Sie eine falsche Modul-ID angeben (in diesem Fall 'unknown'):

curl -X GET \
     -H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
     'localhost:8181/cxf/bpc-core/configuration/unkonwn/none/newInstanceId'

{
  "error" : {
    "code" : 20,
    "name" : "MODULE_NOT_FOUND",
    "message" : "Please use the ID of one of the loaded and instantiable modules: backendconnection, externalContent, webtsm, logservice, collaboration, documentation, globalsearch, monitor, analysis, dashboard",
    "properties" : {
      "loadedInstantiableModules" : "backendconnection, externalContent, webtsm, logservice, collaboration, documentation, globalsearch, monitor, analysis, dashboard"
    }
  }
}

Beispiel für eine Fehlermeldung, wenn Sie einen falschen Instanztyp angeben (in diesem Fall 'xyz'):

curl -X GET \
     -H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
     'localhost:8181/cxf/bpc-core/configuration/httpproxy/xyz/newInstanceId'

{
  "error" : {
    "code" : 20,
    "name" : "MODULE_NOT_FOUND",
    "message" : "Please use one of the instance types the module 'backendconnection' supports: http_proxy, identity_provider, deployment_system, data_source",
    "properties" : {
      "instanceTypes" : "http_proxy, identity_provider, deployment_system, data_source",
      "moduleId" : "backendconnection"
    }
  }
}

Beispiel, wenn Sie korrekte Daten angeben (eine Backend-Verbindung vom Instanztyp 'deployment_system'):

curl -X GET \
     -H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
     'localhost:8181/cxf/bpc-core/configuration/backendconnection/deployment_system/newInstanceId'

{
  "instanceId" : "1589263141954",
  "instanceType" : "deployment_system",
  "moduleId" : "backendconnection"
}

Historisch bezogen ist die Modul-ID einer Backend-Verbindung 'httproxy'. Dies ist der einzige Fall, in dem wir eine falsche Bezeichnung verwenden.

Einstellungen der zu erstellenden Modulinstanzen

Wenn Sie wissen, welche Modulinstanzen erstellt werden sollen und diese bereits in einer anderen BPC-Installation existieren, ist der einfachste Weg, diese Einstellungen zu "exportieren".

Beispiel, um die Einstellungen einer 'logservice'-Modulinstanz mit der ID '1496037736378' abzurufen.

curl -X GET \
     -H 'Content-Type: application/json' \
     -H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
     "http://localhost:8181/cxf/bpc-core/configuration/logservice/1496037736378?format=json"

Aus der JSON-Antwort benötigen Sie den Array-Inhalt des 'settings'-Elements.

{
  "moduleName" : "Log Service",
  "moduleId" : "1496037736378",
  "instanceType" : "none",
  "instancesDefaultConfiguration" : null
  "instances" : null,
  "settings" : [ {
    ...
  }, {
    ...
  }, {
    ...
  } ]
}

Verwendung der Deployment-API zur Erstellung von Modulinstanzen

curl -X POST \
     -H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
     -H 'Content-Type: application/json' \
     "http://localhost:8181/cxf/bpc-deployment/deployment/import?enableMaintenanceMode=false" -d '
{
  "settings": {
    "updateOrCreate": [
      {
        ...
      },
      {
        ...
      },
      {
        ...
      }
    ]
  }
}'

Der Array-Inhalt von "updateOrCreate" muss durch den Inhalt des oben genannten 'settings'-Elements ersetzt werden.

Nun sollte die Modulinstanz erstellt werden! :-)

Keywords: