Durchsuchbare Dokumentation aufrufen

Zurück zur Dokumentationsübersicht

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

  1. Ö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

  1. 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.
  2. Tragen Sie im Abschnitt Parameter das Passwort und den Anmeldenamen eines Benutzers ein.
  3. 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.
  4. 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

  1. Installieren Sie den agorum core template manager über den agorum core plugin manager.
  2. Legen Sie in Ihrem Konfigurationsprojekt im Ordner js einen neuen Ordner an, etwa: 
    custom service
  3. Erstellen Sie in diesem Ordner über das Kontextmenü eine neue JavaScript-Datei.
  4. Klicken Sie mit der rechten Maustaste auf die JavaScript-Datei.
  5. 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.

  1. 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:

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;