Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core für Entwickler > agorum core JavaScript-API

JavaScript-Bibliothek client/json

Diese JavaScript-Bibliothek bietet Funktionen zum Lesen von JSON-Daten von einem WebStream und Wandeln von JSON-Daten in JavaScript-Objekte.

Verwendung

Binden Sie die Bibliothek stets am Anfang eines Skripts ein:

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

Eine Verbindung zum REST-Service aufbauen

// Aufruf von http://url-to-service/path/to/service
let json = require('client/json');
let service = json('http://url-to-service', { 
  type: 'application/json', // Was liefern wir 
  accept: 'application/json' // Was wollen wir 
})('/path/to/service');

Funktionen

get

// Parameter hinzufügen (URL-Parameter)
service.query({ 
  param1: [ 'value1', 'value2' ], 
  sessionId: sessionId 
}); 

// Liefert JSON oder ein gewandeltes JavaScript-Objekt.
let getResponse = service.get();

post

// Parameter hinzufügen (URL-Parameter)
service.query({ 
  param1: [ 'value1', 'value2' ], 
  sessionId: sessionId 
}); 

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

// Liefert JSON oder ein gewandeltes JavaScript-Objekt.
let postResponse = service.post(body);

put

// Parameter hinzufügen (URL-Parameter)
service.query({ 
  param1: [ 'value1', 'value2' ], 
  sessionId: sessionId 
}); 

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

// Liefert JSON oder ein gewandeltes JavaScript-Objekt.
let postResponse = service.put(body);

Header

Sie können Header vor einer Verbindung (get, post) einsetzen, die das System bei jeder Verbindung mitgibt.

// Header hinzufügen.
service.header('X-Auth-Token', 123);

// Weitere Header mit gleichem key hinzufügen. -> Beide Header werden mitgeschickt.
service.header('X-Auth-Token', 'abc');

// Direkt ein Array mit mehreren Werten übergeben.
let tokens = ['123', 'abc'];
service.header('X-Auth-Token', tokens);

basicAuth

Dient als eine Art von Header zur Authentifizierung über Basic Auth.

// basicAuth hinzufügen.
service.basicAuth('username', 'password');

Timeout

Sie können bei der Initialisierung optional die Time-outs connectionTimeout und receiveTimeout setzen.

let json = require('client/json');
let service = json('http://url-to-service', {
  type: 'application/json',
  accept: 'application/json',
  connectionTimeout: 60000,
  receiveTimeout: 30000
})('/path/to/service');

Antwort-Header

Im Normalfall liefert das System den Antwort-Body als Ergebnis. Sind im Header der Antwort auch relevante Informationen, so können Sie die Service-Referenz stattdessen im Raw-Modus erzeugen:

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

let getHeaderString = (result, name) => {
  let header = result.headers[name] || [];

  return header[0];
};

let service = json('http://url-to-service', {
  raw: true
});

let result = service('/path/to/call').get();

let myHeader = getHeaderString(result, 'my-header');
let body = result.body;

Folgende Felder stehen in dem zurückgegebenen Ergebnis-Objekt zur Verfügung:

Feld Beschreibung
headers Definiert ein Objekt, das alle Antwort-Header als Array enthält.
body Definiert den Antwort-Body als String oder JSON (wie im nicht-Raw-Modus).
stream Definiert den Antwort-Body als Stream bei Verwendung von getStream() statt get().

Beispiel anhand eines Logins an der agorum core JavaScript API

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

const SERVER = 'http://localhost';
const USERNAME = 'roi';
const PASSWORD = 'agorum';

let urlEncode = params =>
  Object.entries(params)
    .map(([key, value]) => encodeURIComponent(key) + '=' + encodeURIComponent(value))
    .join('&');

let service = json(SERVER, {
  accept: 'application/json',
  type: 'application/x-www-form-urlencoded',
});

let sessionId = service('/api/rest/session').post(urlEncode({ username: USERNAME, password: PASSWORD })).sessionId;

Sie erhalten die sessionId, die Sie bei jedem weiteren Aufruf der API mitgeben müssen.

Objekte in ein anderes System hochladen

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

const SERVER = 'http://localhost';
const USERNAME = 'roi';
const PASSWORD = 'agorum';

let urlEncode = params =>
  Object.entries(params)
    .map(([key, value]) => encodeURIComponent(key) + '=' + encodeURIComponent(value))
    .join('&');

let service = json(SERVER, {
  accept: 'application/json',
  type: 'application/x-www-form-urlencoded',
});

let sessionId = service('/api/rest/session').post(urlEncode({ username: USERNAME, password: PASSWORD })).sessionId;

let upload = (object, target) =>
  service('https://agorumdocproxy.agorum.com/api/rest/object/upload').query({ sessionId: sessionId, target: target }).postForm({
    file: object,
  });

upload(objects.find('...'), 'home:MyFiles');

Beispiel um über eine URL eine Datei binär in agorum core zu speichern

let json = require('client/json');
let objects = require('common/objects');
let transaction = require('common/transaction');

/**
 * Uploads a file from an external URL and saves it into the agorum core system as a file object.
 *
 * <p>
 * This function fetches a given document from an external URL (binary), detects the extension
 * from the URL, creates a new file in the target folder, and sets the content of the file to the
 * downloaded binary data.
 * <p>
 * Required modules: client/json (for HTTP request), common/objects (object handling), common/transaction (ensures atomic write)
 *
 * @param {Object} params Parameters for the upload
 * @param {string} params.url The external URL of the file to be downloaded.
 * @param {string} params.targetId Target folder (id or path) in agorum core to which the file will be uploaded.
 * @param {string} [params.basename] Optional base name for the uploaded file (without extension). Defaults to 'logo'.
 * @returns {GlobalObject} The newly created file object.
 *
 */
exports.upload = params => {
  // Parse parameters
  /** @type {string} External URL to retrieve the file from. */
  let url = params.url;
  /** @type {string} agorum core folder where the file is uploaded. */
  let targetId = params.targetId;
  /** @type {string} Base name for uploaded file (without extension). Defaults to 'logo'. */
  let basename = params.basename || 'logo';

  // Fetch document from URL as binary with raw=true for binary stream.
  let imageReq = json(url, {
    accept: '*/*', // accept all MIME types
    raw: true,     // get raw binary body
  })();
  let imageResult = imageReq.getStream(); // getBody in original format (Stream)
  //console.log('imageResult', imageResult.headers);

  // Detect file extension from URL
  let ext;
  let path = url.split('?')[0];  // Remove query string for extension eval
  let dot = path.lastIndexOf('.');
  if (dot > -1 && dot > path.lastIndexOf('/')) {
    ext = path.substring(dot + 1); // Get extension, without dot
  }

  // Create file in agorum core under transaction for atomicity
  let targetFolder = objects.tryFind(targetId);
  let newFile;
  transaction(() => {
    newFile = objects.create('file', {
      name: basename + '.' + ext, // Full filename with extension
      target: targetFolder,
    });
    // Set file content from the binary stream
    newFile.setContent(imageResult.stream); // body is Buffer/Stream
  });
  return newFile;
};

// Example call: Download an SVG file into a specific folder
exports.upload({
  url: 'https://www.agorum.com/bundles/agorumbasic/images/favicons/favicon.svg',
  targetId: '/agorum/roi/customers/agorum.demo.color.logo/doc',
  basename: 'logo',
});