JavaScript-Adapter

improve this page | report issue

Übersicht

JavaScript-Adapter sind Schablonen für die Verbindung zu HTTP- und SQL-Back-Ends, die eine Reihe von Services bereitstellen, die als Prozeduren bezeichnet werden, sowie mobile Apps, die diese Prozeduren durch das Absetzen von Ajax-Anforderungen aufrufen können.

Voraussetzung: Arbeiten Sie zuerst das Lernprogramm Java- und JavaScript-Adapter erstellen durch.

Dateistruktur

mvn-adapter

Ordner ‘adapter-resources’

Der Ordner adapter-resources enthält eine XML-Konfigurationsdatei. Diese Konfigurationsdatei beschreibt die Konnektivitätsoptionen und listet die Prozeduren auf, die für die Anwendung oder andere Adapter zugänglich gemacht werden.

<?xml version="1.0" encoding="UTF-8"?>
<mfp:adapter name="JavaScriptAdapter">
    <displayName>JavaScriptAdapter</displayName>
    <description>JavaScriptAdapter</description>
    
    <connectivity>
        <connectionPolicy>
        ...
        </connectionPolicy>
    </connectivity>

    <procedure name="procedure1"></procedure>
    <procedure name="procedure2"></procedure>

    <property name="name" displayName="username" defaultValue="John"  />
</mfp:adapter>
  • name: Dieses obligatorische Attribut gibt den Namen des Adapters an. Dieser Name muss innerhalb von MobileFirst Server eindeutig sein. Er kann aus alphanumerischen Zeichen und Unterstreichungszeichen bestehen und muss mit einem Buchstaben beginnen. Den Namen eines definierten und implementierten Adapters können Sie nicht mehr ändern.
  • <displayName>: Dieses optionale Attribut gibt den Namen des Adapters an, der in der MobileFirst Operations Console angezeigt wird. Wenn dieses Element nicht angegeben ist, wird stattdessen der Wert des Attributs name verwendet.
  • <description>: Dieses optionale Attribut gibt zusätzliche Informationen zum Adapter an. Die Informationen werden in der MobileFirst Operations Console angezeigt.
  • <connectivity>: Dieses obligatorische Attribut definiert den Mechanismus, über den der Adapter eine Verbindung zur Back-End-Anwendung herstellt. Es enthält das Unterelement <connectionPolicy>.
  • <procedure>: Dieses obligatorische Attribut definiert einen Prozess für den Zugriff auf einen Service, der über eine Back-End-Anwendung zugänglich gemacht wird.
    • name: Dieses obligatorische Element gibt den Namen der Prozedur an. Dieser Name muss innerhalb des Adapters eindeutig sein. Er kann aus alphanumerischen Zeichen und Unterstreichungszeichen bestehen und muss mit einem Buchstaben beginnen.
    • audit: Dieses optionale Element definiert, ob Aufrufe der Prozedur im Prüfprotokoll erfasst werden. Folgende Werte sind gültig:
      • true: Aufrufe der Prozedur werden im Prüfprotokoll erfasst.
      • false: Standardwert. Aufrufe der Prozedur werden nicht im Prüfprotokoll erfasst.
    • scope: Dieses optionale Element gibt den Sicherheitsbereich, der die Adapterressourcenprozedur schützt, an. Der Bereich kann eine Zeichenfolge mit null oder mehr Bereichselementen ("scope") sein, die jeweils durch ein Leerzeichen getrennt sind, oder auf null gesetzt werden, damit der Standardbereich angewendet wird. Ein Bereichselement kann ein Schlüsselwort sein, das einer Sicherheitsüberprüfung zugeordnet ist, oder der Name einer Sicherheitsüberprüfung. Der Standardbereich ist RegisteredClient, wobei es sich um ein reserviertes MobileFirst-Schlüsselwort handelt. Nach Standardschutz ist ein Zugriffstoken für den Zugriff auf die Ressource erforderlich.
      Weitere Informationen zum MobileFirst-OAuth-Ressourcenschutz und zum Konfigurieren des Ressourcenschutzes für JavaScript-Adapterressourcen finden Sie unter Adapterressourcen schützen.
      Wenn das Attribut secured den Wert false hat, wird das Attribut scope ignoriert.
    • secured: Dieses optionale Element definiert, ob die Adapterprozedur vom Sicherheitsframework der MobileFirst geschützt wird. Folgende Werte sind gültig:
      • true: Standardwert. Die Prozedur wird geschützt. Zum Aufrufen der Prozedur ist ein gültiges Zugriffstoken erforderlich.
      • false: Die Prozedur wird nicht geschützt. Zum Aufrufen der Prozedur ist kein Zugriffstoken erforderlich (siehe Ungeschützte Ressourcen). Wenn dieser Wert festgelegt ist, wird das Attribut scope ignoriert.
  • <securityCheckDefinition>: Dieses optionale Attribut definiert ein Sicherheitsüberprüfungsobjekt. Weitere Informationen zu Sicherheitsüberprüfungen enthält das Lernprogramm Sicherheitsüberprüfungen erstellen.
  • property: Dieses optionale Attribut deklariert eine benutzerdefinierte Eigenschaft. Weiteres erfahren Sie im Abschnitt Angepasste Eigenschaften dieses Lernprogramms.

Angepasste Eigenschaften

Die Datei adapter.xml kann auch benutzerdefinierte Eigenschaften enthalten. Die Werte, die Entwickler diesen Eigenschaften während der Adaptererstellung zuweisen, können in der MobileFirst Operations Console auf der Registerkarte Konfigurationen für Ihren Adapter überschrieben werden, ohne dass der Adapter neu implementiert werden muss. Benutzredefinierte Eigenschaften können mit der API getPropertyValue gelesen und später zur Laufzeit weiter angepasst werden.

Hinweis: Die Elemente für die Konfigurationseigenschaften müssen sich immer unterhalb der <procedure>-Elemente befinden. Im obigen Beispiel wurde eine Eigenschaft <displayName> mit einem Standardwert definiert, sodass sie später verwendet werden kann.

Das Element <property> wird mit folgenden Attributen verwendet:

  • name: Name der Eigenschaft, wie er in der Konfigurationsklasse definiert ist
  • defaultValue: Setzt den in der Konfigurationsklasse definierten Wert außer Kraft
  • displayName: Anzeigename, der in der Konsole erscheint (optional)
  • description: Beschreibung, die in der Konsole angezeigt wird (optional)
  • type: Stellt sicher, dass die Eigenschaft einen bestimmten Typ hat, z. B. integer, string oder boolean bzw. eine Liste mit gültigen Werten wie type="['1','2','3']" (optional)

Eigenschaften in der Konsole

Pull- und Push-Konfiguration

Angepasste Adaptereigenschaften können über die auf der Registerkarte Konfigurationsdateien angezeigte Adapterkonfiguraionsdatei gemeinsam genutzt werden.

Verwenden Sie dazu die nachfolgend beschriebenen Befehle pull und push in Maven oder in der MobileFirst CLI. Damit die Eigenschaften gemeinsam genutzt werden können, müssen Sie die Standardwerte der Eigenschaften ändern.

Führen Sie die Befehle im Stammordner des Maven-Adapterprojekts aus.

Maven

  • Konfigurationsdatei mit pull übertragen
    mvn adapter:configpull -DmfpfConfigFile=config.json
    
  • Konfigurationsdatei mit push übertragen
    mvn adapter:configpush -DmfpfConfigFile=config.json
    

MobileFirst CLI

  • Konfigurationsdatei mit pull übertragen
    mfpdev adapter pull
    
  • Konfigurationsdatei mit push übertragen
    mfpdev adapter push
    

Konfigurationen per Push-Operation auf mehrere Server übertragen

Die Befehle pull und push können helfen, diverse DevOps-Abläufe zu erstellen, die je nach Umgebung (DEV, QA, UAT, PRODUCTION) unterschiedliche Werte für Adapter erfordern.

Maven
Oben ist beschrieben, wie standardmäßig eine Datei config.json angegeben wird. Erstellen Sie Dateien mit unterschiedlichen Namen für verschiedene Ziele.

MobileFirst CLI
Verwenden Sie die Option –configFile oder -c, um eine von der Standarddatei abweichende Konfigurationsdatei anzugeben.

mfpdev adapter pull -c [adapterProject]/alternate_config.json

Weitere Informationen erhalten Sie, wenn Sie mfpdev help adapter pull/push eingeben.

Ordner ‘js’

Dieser Ordner enthält die JavaScript-Implementierungsdatei für alle Prozeduren, die in der Datei adapter.xml deklariert sind. Außerdem kann der Ordner XSL-Dateien mit einem Umwandlungsschema für abgerufene XML-Rohdaten enthalten. Von einem Adapter abgerufene Daten können als Rohdaten oder als vom Adapter vorverarbeitete Daten zurückgegeben werden. In beiden Fällen werden die Daten der Anwendung als JSON-Objekt präsentiert.

Prozeduren von JavaScript-Adaptern

Prozeduren werden in XML deklariert und mit serverseitigem JavaScript für folgende Zwecke implementiert:

  • Bereitstellung von Adapterfunktionen für die Anwendung
  • Aufruf von Back-End-Services zum Abrufen von Daten oder Ausführen von Aktionen

Für jede in der Datei adapter.xml deklarierte Prozedur muss es eine entsprechende Funktion in der JavaScript-Datei geben.

Durch serverseitiges JavaScript kann eine Prozedur die Daten vor oder nach dem Aufrufen des Service verarbeiten. Sie können auf abgerufene Daten mit einfachem XSLT-Code weitere Filter anwenden.
Prozeduren von JavaScript-Adaptern werden in JavaScript implementiert. Da ein Adapter jedoch eine serverseitige Entität ist, besteht die Möglichkeit, Java im Adaptercode zu verwenden.

Globale Variablen verwenden

MobileFirst Server ist nicht auf HTTP-Sitzungen angewiesen, und jede Anforderung kann von einem anderen Knoten empfangen werden. Sie sollten nicht darauf setzen, dass Daten von einer Anforderung zur nächsten durch globale Variablen erhalten bleiben können.

Schwellenwert für Adapterantwort

Adapteraufrufe sind nicht dafür gedacht, riesige Datenblöcke zurückzugeben, weil die Adapterantwort als Zeichenfolge im MobileFirst-Server-Speicher gespeichert wird. Wenn die Datenmenge daher nicht in den verfügbaren Speicher passt, kann der Adapteraufruf fehlschlagen. Konfigurieren Sie vorbeugend einen Schwellenwert, ab dem MobileFirst Server mit gzip komprimierte HTTP-Antworten zurückgibt. Das HTTP-Protokoll hat Standardheader zur Unterstützung der gzip-Komprimierung. Die Clientanwendung muss auch in der Lage sein, gzip-Inhalte in HTTP zu unterstützen.

Serverseite

Legen Sie in der MobileFirst Operations Console unter Laufzeiten > Einstellungen > GZIP-Komprimierungsschwellenwert für Adapterantworten den gewünschten Schwellenwert fest. Der Standardwert ist 20 KB.
Hinweis: Wenn Sie die Änderung in der MobileFirst Operations Console speichern, tritt sie sofort in der Laufzeit in Kraft.

Clientseite

Sie müssen den Client so konfigurieren, dass er eine gzip-Antwort analysieren kann. Setzen Sie dazu in jeder Clientanforderung den Wert des Headers Accept-Encoding auf gzip. Verwenden Sie die Methode addHeader mit Ihrer Anforderungsvariablen, z. B. request.addHeader("Accept-Encoding","gzip");.

Serverseitige APIs

JavaScript-Adapter können serverseitige APIs verwenden, um Operationen im Zusammenhang mit MobileFirst Server auszuführen: Aufrufen anderer JavaScript-Adapter, Anmeldung beim Serverprotokoll, Abrufen der Werte von Konfigurationseigenschaften, Melden von Aktivitäten an Analytics, Abrufen der Identität des Anforderungsausstellers.

getPropertyValue

Verwenden Sie die API MFP.Server.getPropertyValue(propertyName), um in der Datei adapter.xml oder in der MobileFirst Operations Console definierte Eigenschaften abzurufen:

MFP.Server.getPropertyValue("name");

getTokenIntrospectionData

Verwenden Sie die API MFP.Server.getTokenIntrospectionData(), um die aktuell verwendete Benutzer-ID abzurufen:

function getAuthUserId(){
   var securityContext = MFP.Server.getTokenIntrospectionData();
   var user = securityContext.getAuthenticatedUser();
 
   return "User ID: " + user.getId;
}

getAdapterName

Verwenden Sie die API getAdapterName(), um den Adapternamen abzurufen.

invokeHttp

Verwenden Sie die API MFP.Server.invokeHttp(options) in HTTP-Adaptern.
Verwendungsbeispiele enthält das Lernprogramm JavaScript-HTTP-Adapter.

invokeSQL

Verwenden Sie die APIs MFP.Server.invokeSQLStatement(options) und MFP.Server.invokeSQLStoredProcedure(options) in SQL-Adaptern.
Verwendungsbeispiele enthält das Lernprogramm JavaScript-SQL-Adapter.

addResponseHeader

Verwenden Sie die API MFP.Server.addResponseHeader(name,value), um neue Header zur Antwort hinzuzufügen:

MFP.Server.addResponseHeader("Expires","Sun, 5 October 2014 18:00:00 GMT");

getClientRequest

Verwenden Sie die API MFP.Server.getClientRequest(), um einen Verweis auf das Java-Objekt HttpServletRequest zu erhalten, mit dem eine Adapterprozedur aufgerufen wurde:

var request = MFP.Server.getClientRequest();
var userAgent = request.getHeader("User-Agent");

invokeProcedure

Verwenden Sie MFP.Server.invokeProcedure(invocationData), um andere JavaScript-Adapter aufzurufen.
Verwendungsbeispiele enthält das Lernprogramm Erweiterte Nutzung von Adaptern und Adapterkombinationen.

Protokollierung

Die JavaScript-API stellt über die Klasse MFP.Logger Protokollierungsfunktionen bereit. Es gibt vier Funktionen, die vier Standardprotokollierungsstufen entsprechen.
Weitere Informationen enthält das Lernprogramm Serverseitige Protokollerfassung.

Beispiele für JavaScript-Adapter

Last modified on April 25, 2017