Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core support tool > Einführung in das agorum core support tool

Eigenen (custom) JavaScript-API-Service erstellen

Diese Dokumentation beschreibt das Erstellen eines eigenen API-Services über JavaScript.

Anstatt einzelne REST-API-Aufrufe zu senden, können Sie über einen CustomeService und dessen Parametern einen Aufruf erstellen. Dieser fasst einzelne REST-API-Aufrufe zusammen.

Ein CustomService wird von der REST-API angesprochen und startet eine Aktion innerhalb von agorum core.

Ablauf einer REST-API

Um von außen Aktionen innerhalb von agorum core anzustoßen, stellen Sie eine Kommunikation zwischen der externen Client-Applikation und agorum core mit folgendem HTTPS-Befehl her:

https://<IP-Adresse | ag-test.docker.agorum.com>/api/rest/

Die Kommunikation mit der API muss in einem bestimmten Datenformat erfolgen (derzeit meist JSON):

https://<IP-Adresse | ag-test.docker.agorum.com>/api/rest/.../user?type=json

Aktionen des CustomServices kennenlernen

Öffnen Sie links in der Seitenleiste Weitere Apps und dann API-Dokumentation.

Das Modul API-Dokumentation basiert auf einem Swagger-Framework. Das Swagger-Framework ist eine Open-Source-Software, die es erlaubt, RESTful-Webservices zu entwerfen, zu erstellen, zu dokumentieren und (für Sie) zu verwenden.

Session.json

Klicken Sie auf Session.json.

Ergebnis: Die Bedienoberfläche erweitert sich.

Im Einleitungstext erfahren Sie, wozu die Session verwendet wird, welche Fehlermeldungen entstehen können und welche Informationen im JSON-Format zurückgegeben werden.
Tragen Sie im Abschnitt Parameter das Passwort und den Anmeldenamen eines Benutzers ein.
Klicken Sie auf Try it out!

Ergebnis: Sie sehen, welche Request-URL vom System benötigt wird, um sich einzuloggen, und welche Antwort Sie vom System erhalten. Dazu gehört auch die SessionID.
Kopieren Sie die SessionID, um weitere Funktionen auszuprobieren.

POST, GET, PUT, DELETE stehen auf der linken Seite eines Attributs und sind HTTP-Anfragemethoden.

Methode	Beschreibung
GET	Datensatz abrufen / sich Informationen ausgeben lassen.
POST	Etwas neu anlegen.
PUT	Lädt ein Objekt auf dem Zielserver hoch oder aktualisiert es.
DELETE	Löscht ein angegebenes Objekt auf dem Server.

Übersicht vorhandener Funktionen

Funktion	Funktion kann gefunden werden unter
create a folder	Object.json: POST /object
create a user	Administration.json: POST /object
list users/groups	Administration.json: GET /object
create a note	Note.json: POST /object
download a preview image	Preview.json: GET /object/preview/{ticket}

Alle fett hervorgehobenen Informationen stellen eine Erweiterung der URL dar.

Ein Skript in der MetaDB registrieren

Um einen eigenen CustomService zu erstellen, benötigen Sie ein Skript, das in der MetaDB des Moduls Administration registriert wurde.

Empfohlene Methode

Installieren Sie den agorum core template manager über den agorum core plugin manager.
Legen Sie in Ihrem Konfigurationsprojekt im Ordner js einen neuen Ordner an, etwa:
```
custom service
```
Erstellen Sie in diesem Ordner über das Kontextmenü eine neue JavaScript-Datei.
Klicken Sie mit der rechten Maustaste auf die JavaScript-Datei.
Wählen Sie im Kontextmenü Register custom service.

Ergebnis: Das System nimmt die MetaDB-Einträge selbstständig vor.

Veraltete Methode

Hinweis: Wenn Sie den agorum core template manager über den agorum core plugin manager installieren können, setzen Sie die hier vorgestellte Variante nicht um.

Legen Sie unter folgendem Pfad einen MetaDB-Entry mit dem gewünschten Servicenamen an, etwa TestService.
```
MAIN_MODULE_MANAGEMENT/api/control/Services/Custom/Services
```
Hinweis: Der Wert zeigt auf ein JavaScript-File innerhalb von agorum core, etwa:
```
MAIN_MODULE_MANAGEMENT/api/control/Services/Custom/Services
```
Dieser CustomService kann ausschließlich mit vorheriger Authentifizierung oder mit einer sessionID aufgerufen werden. Wenn Sie einen CustomService erstellen möchten, der ohne Authentifizierung funktioniert, hängen Sie hinten an den CustomServicenamen .noauth an. Sie übergeben dann eine Admin-Session, der CustomService muss sich dann selbst um die Authentisierung kümmern.

Den CustomService aufrufen

Sie rufen den CustomService über seinen Servicenamen auf. Unterstützt werden die Methoden:

GET
PUT
POST
DELETE

Beispiel

https://adresse/api/rest/custom/TestService

ohne auth:

https://adresse/api/rest/custom/TestService.noauth

Inhalt der JavaScript-Datei

Die in diesem Beispiel genannte JavaScript-Datei /agorum/roi/customers/test/js/TestService.js hat folgenden Inhalt:

/* global Packages, sessionController, sessionControllerAdmin, request */

let response = {
  answer: 'Hallo Welt zurück'
};

response;

In diesem Beispiel wird ein JSON-Text mit answer='Hallo Welt zurück' geliefert.

Parameter der Variable „request“

Parameter	Beschreibung
method	Definiert die Methode: GET PUT POST DELETE
path	Definiert den Pfad, der hinter dem CustomService steht. Im obigen Beispiel existiert kein Pfad, Sie können jedoch einen beliebigen mit / hinten an die URL anfügen.
params	Definiert die URL-Parameter, die dem CustomService übergeben wurden (die mit ? und & an die URL gehängt werden).
body	Definiert den Body des Requests, etwa JSON.
header	Definiert den Header der Anfrage.

Dateien über den CustomService herunterladen

Dateien können Sie über den CustomService zum Download bereitstellen.

Methode	Header
GET	Accept: application/octet-stream

Beispiel

/* global request */

let objects = require('common/objects');

let obj = objects.find('id-eines-dokumentes');

let response = {
  body: obj.contentStream,
  name: obj.name,
  size: obj.contentSize,
  type: obj.format.mimeType
};

response;

Element	Beschreibung
body	Definiert den InputStream, der heruntergeladen werden soll. stream anstatt body wird aus Kompatibilitätsgründen weiterhin unterstützt.
name	Definiert den Namen der Datei für den Download.
size	Definiert die Größe der Datei.
type	Liefert optional den MIME-Type (Standard: application/octet-stream).

Dateien über den CustomService hochladen

Dateien können Sie über den CustomService hochladen.

Methode	Header
POST	Accept: application/json

Hinweis: Das System lädt die Dateien mit form-data-multipart hoch (Standard-Verfahren für Uploads).

Beispiel

Dieser Upload empfängt Dateien und legt diese in einen Ordner in agorum core:

/* global request */

let objects = require('common/objects');

let folder = objects.find('folder-to-store-files');

let ids = request.attachments.map(attachment => {
  let file = objects.create('file', {
    name: attachment.parameters.filename,
    target: folder
  });
  file.setContent(attachment.stream);
  return file.ID;
});

let response = {
  ids: ids
};

response;

Element	Beschreibung
attachments	Definiert ein Array von Anhängen.
stream	Definiert den Stream des jeweiligen Anhangs.
type	Definiert den Contenttype des Anhangs.
parameters	Definiert zusätzliche Parameter des Anhangs.
filename	Definiert den Dateinamen.

Beliebige HTTP-Status-Codes und beliebigen Inhalt setzen

Den HTTP-Status-Code und den Inhalt der CustomService-Antwort können Sie beliebig setzen.

Beispiel

/* global request */

let objects = require('common/objects');

let download = id => {
  let object = objects.tryFind(id);

  if (object) {
    return {
      body: object.contentStream,
      name: object.name,
      size: object.contentSize,
      type: object.format.mimeType
    };
  }
  else {
    return {
      status: 404,
      body: 'Object not found: ' + id
    };
  }
};

download(request.params.id[0]);

Element	Beschreibung
status	Definiert den zu sendenden HTTP-Status-Code (Standard: 200).
body	Definiert den Inhalt der Antwort auf die CustomService-Anfrage. Unterstützt werden: InputStreams Strings byte-Arrays
json	Dieses Element kann statt body verwendet werden. Das hier übergebene Objekt wird automatisch im JSON-Format serialisiert gesendet.
type	Definiert den MIME-Type der Antwort. Wenn Sie nichts angeben, ist der Standardwert wie folgt: Bei Verwendung eines Strings für body: text/plain Bei Verwendung eines InputStreams für body: application/octet-stream Bei Verwendung des Felds json: application/json

Beispiel eines CustomServices

Weitere Beispiele zum CustomUploadService siehe JavaScript-Bibliothek common-jwt (JSON Web Token).

Definition des CustomServices in agorum core

Dieser CustomService erhält verschiedene Parameter und gibt diese wieder zurück.

/* global Packages, sessionController, sessionControllerAdmin, request */

// http://roihost/api/rest/custom/DemoCustom Service/xxx/yyy?param1=value1&sessionId=234235423
let body = request.body;
let response = {
  myMethod: request.method,
  myPath: request.path,
  myParams: request.params,
  myBody: request.body,
  myTest: body ? body.test : '',
  myTestDateYear: body ? new Date(body.testDate).getFullYear() : '',
  myTestDate: body ? new Date(body.testDate) : '',
  myTestLong: body ? '' + body.testLong : '',
  myTestDouble: body ? body.testDouble : '',
  myTestBoolean: body ? body.testBoolean : ''
};

response;

Beispielaufruf des CustomServices aus agorum heraus

Dieser CustomServices wird aus agorum core pro aufgerufen. Im Normalfall wird solch ein CustomService aus einem anderen System heraus aufgerufen, ggf. auch über eine andere Programmiersprache wie PHP, C++, vb. Das vorgestellte Beispiel verwendet die JavaScript-API von agorum core pro.

Aufruf

let apiClient = require('client/json');

let url = 'http://roihost';

function login(user, password) {
  let sessionService = apiClient(url, { 
    type: 'application/x-www-form-urlencoded', 
    accept: 'application/json' 
  })('/api/rest/session');

  let login = sessionService.post('username=' + user + '&password=' + password);
  return login.sessionId;
}

function logout(sessionId) {
  let sessionService = apiClient(url, { 
    type: 'application/x-www-form-urlencoded', 
    accept: 'application/json' 
  })('/api/rest/session');

  sessionService.delete({ sessionId: sessionId });
}

let sessionId = login('roi', 'agorum');

// POST Sample
let customService = apiClient(url, { 
  type: 'application/json',    // Was liefern wir
  accept: 'application/json'   // Was wollen wir
})('/api/rest/custom/DemoCustom Service/xxx/yyy');

// add parameters
customService.query({
  param1: [
    'value1',
    'value2'
  ]
});

// define body
let body = {
  test: 'test123',
  sessionId: sessionId,
  testDate: new Date(),
  testLong: 1234567890123456,
  testDouble: 12345.9876,
  testBoolean: true
};

let postResponse = customService.post(body);

// GET Sample
let customService = apiClient(url, { 
  type: 'application/json', 
  accept: 'application/json' 
})('/api/rest/custom/DemoCustom Service/xxx/yyy');

// add parameters
customService.query({
  param1: [
    'value1',
    'value2'
  ],
  sessionId: sessionId
});

let getResponse = customService.get();

logout(sessionId);

postResponse;
//getResponse;

Open Source DokumentenmanagementDokumentation

Eigenen (custom) JavaScript-API-Service erstellen

Ablauf einer REST-API

Aktionen des CustomServices kennenlernen

Session.json

Übersicht vorhandener Funktionen

Ein Skript in der MetaDB registrieren

Empfohlene Methode

Veraltete Methode

Den CustomService aufrufen

Beispiel

Inhalt der JavaScript-Datei

Parameter der Variable „request“

Dateien über den CustomService herunterladen

Beispiel

Dateien über den CustomService hochladen

Beispiel

Beliebige HTTP-Status-Codes und beliebigen Inhalt setzen

Beispiel

Beispiel eines CustomServices

Definition des CustomServices in agorum core

Beispielaufruf des CustomServices aus agorum heraus

Open Source Dokumentenmanagement
Dokumentation