JavaScript アダプター

improve this page | report issue

概説

JavaScript アダプターは、HTTP および SQL のバックエンドに接続するためのテンプレートを提供します。このアダプターは、プロシージャーと呼ばれるサービスのセットを提供します。モバイル・アプリケーションで AJAX 要求を発行することで、これらのプロシージャーを呼び出すことができます。

前提条件: 最初に必ず、 Java アダプターおよび JavaScript アダプターの作成チュートリアルをお読みください。

ファイル構造

mvn-adapter

adapter-resources フォルダー

adapter-resources フォルダーには、XML 構成ファイルが含まれています。この構成ファイルでは、接続オプションが記述され、アプリケーションまたは他のアダプターに公開されるプロシージャーがリストされています。

<?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: 必須。 アダプターの名前。この名前は MobileFirst Server 内で固有でなければなりません。 英数字およびアンダースコアーを含めることができ、先頭は文字である必要があります。 アダプターを定義してデプロイした後に、その名前を変更することはできません。
  • <displayName>: オプション。 MobileFirst Operations Console に表示されるアダプターの名前。このエレメントが指定されない場合は、代わりに name 属性の値が使用されます。
  • <description>: オプション。 アダプターに関する追加情報。MobileFirst Operations Console に表示されます。
  • <connectivity>: 必須。 アダプターがバックエンド・アプリケーションに接続するときのメカニズムを定義します。これには、<connectionPolicy> サブエレメントが含まれています。
  • <procedure>: 必須。 バックエンド・アプリケーションによって公開されるサービスにアクセスするためのプロセスを定義します。
    • name: 必須。 プロシージャーの名前。この名前はアダプター内で固有でなければなりません。 英数字およびアンダースコアーを含めることができ、先頭は文字である必要があります。
    • audit: オプション。 プロシージャーへの呼び出しを監査ログに記録するかどうかを定義します。 以下の値が有効です。
      • true: プロシージャーへの呼び出しが監査ログに記録されます。
      • false: デフォルト。プロシージャーへの呼び出しは監査ログに記録されません。
    • scope: オプション。 アダプター・リソース・プロシージャーを保護するセキュリティー・スコープ。スコープは、スペースで区切った 1 つ以上のスコープ・エレメントからなるストリングにすることも、ヌルにしてデフォルトのスコープを適用することもできます。スコープ・エレメントは、セキュリティー検査にマップされたキーワード、または、セキュリティー検査の名前です。デフォルトのスコープは RegisteredClient で、これは予約済みの MobileFirst キーワードです。デフォルトの保護では、リソースにアクセスするためにアクセス・トークンが必要です。
      MobileFirst OAuth リソース保護と、JavaScript アダプター・リソースのリソース保護を構成する方法について詳しくは、アダプター・リソースの保護を参照してください。
      secured 属性の値が false の場合、scope 属性は無視されます。
    • secured: オプション。 アダプター・プロシージャーが MobileFirst セキュリティー・フレームワークによって保護されるかどうかを定義します。以下の値が有効です。
      • true: デフォルト。プロシージャーは保護されます。プロシージャーの呼び出しには、有効なアクセス・トークンが必要です。
      • false: プロシージャーは保護されません。プロシージャーの呼び出しにアクセス・トークンは不要です。 保護されていないリソース (Unprotected resources) を参照してください。この値が設定されている場合、scope 属性は無視されます。
  • <securityCheckDefinition>: オプション。 セキュリティー検査オブジェクトを定義します。セキュリティー検査の作成チュートリアルで、セキュリティー検査についての詳細を参照してください。
  • property: オプション。 ユーザー定義プロパティーを宣言します。このチュートリアルの『カスタム・プロパティー』セクションで詳細を参照してください。

カスタム・プロパティー

adapter.xml ファイルには、ユーザー定義のカスタム・プロパティーを含めることもできます。開発者がアダプターの作成中にそれらのプロパティーに割り当てた値は、アダプターを再デプロイせずに、MobileFirst Operations Console → 「[ご使用のアダプター]」→「構成」タブでオーバーライドすることができます。ユーザー定義プロパティーは、getPropertyValue API を使用して読み取り、実行時にさらにカスタマイズできます。

注: 構成プロパティー・エレメントは、必ず <procedure> エレメントの下に 配置する必要があります。上の例では、デフォルト値を使用して <displayName> プロパティーを定義し、このプロパティーを後で使用できるようにしてあります。

<property> エレメントには以下の属性があります。

  • name: 構成クラスで定義されている、プロパティーの名前。
  • defaultValue: 構成クラスで定義されたデフォルト値をオーバーライドします。
  • displayName: オプション。コンソールに表示される分かりやすい名前。
  • description: オプション。コンソールに表示される説明。
  • type: オプション。プロパティーが確実に、特定タイプ (integerstringboolean など) または有効な値のリスト (例えば type="['1','2','3']") になるようにします。

コンソール・プロパティー

構成のプルとプッシュ

カスタマイズしたアダプター・プロパティーは、「構成ファイル」タブに表示されるアダプター構成ファイルを使用して共有できます。
共有するためには、Maven または MobileFirst CLI を使用して、以下で説明する pull コマンドと push コマンドを使用します。共有するプロパティーについては、そのプロパティーに対して指定されたデフォルト値を変更する 必要があります。

アダプター Maven プロジェクトのルート・フォルダーから以下のコマンドを実行します。

Maven

  • 構成ファイルをプルする場合
    mvn adapter:configpull -DmfpfConfigFile=config.json
    
  • 構成ファイルをプッシュする場合
    mvn adapter:configpush -DmfpfConfigFile=config.json
    

MobileFirst CLI

  • 構成ファイルをプルする場合
    mfpdev adapter pull
    
  • 構成ファイルをプッシュする場合
    mfpdev adapter push
    

複数のサーバーへの構成のプッシュ

pull コマンドと push コマンドは、使用している環境 (DEV、QA、UAT、PRODUCTION) に応じてアダプターで異なる値が必要となる各種の DevOps フローを作成する場合に役立ちます。

Maven
上記の説明で、デフォルトでの config.json ファイルの指定方法を確認してください。異なるターゲットを処理するには、異なる名前のファイルを作成します。

MobileFirst CLI
デフォルトとは異なる構成ファイルを指定するには、–configFile フラグまたは -c フラグを使用します。

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

mfpdev help adapter pull/push を使用して、詳細を参照してください。

js フォルダー

このフォルダーには、adapter.xml ファイルで宣言されているプロシージャーのすべての JavaScript 実装ファイルが含まれています。また、取得した生の XML データの変換スキームを含む、ゼロまたは 1 つ以上の XSL ファイルも含まれています。アダプターによって取得したデータは、生データとして返すことも、アダプター自体で前処理することもできます。いずれの場合も、JSON オブジェクトとしてアプリケーションに提示されます。

JavaScript アダプター・プロシージャー

プロシージャーは、XML で宣言され、サーバー・サイド JavaScript を使用して以下の目的で実装されます。

  • アダプター関数をアプリケーションに提供する
  • データを取得するため、またはアクションを実行するために、バックエンド・サービスを呼び出す

adapter.xml ファイルで宣言される各プロシージャーに対応する関数を JavaScript ファイルで指定する必要があります。

サービスを呼び出す前または後に、サーバー・サイド JavaScript を使用してデータを処理することができます。簡単な XSLT コードを使用して、取得したデータにさらにフィルタリングを適用することができます。
JavaScript アダプター・プロシージャーは、JavaScript で実装されます。しかし、アダプターはサーバー・サイド・エンティティーであるため、アダプター・コードで Java を使用することが可能です。

グローバル変数の使用

MobileFirst Server は HTTP セッションに依存しないため、各要求が異なるノードに到達する可能性があります。データをある要求から次の要求に保持するためには、グローバル変数に依存しないようにする必要があります。

アダプター応答しきい値

アダプター応答は MobileFirst Server メモリーにストリングとして保管されるため、アダプター呼び出しは、大容量データを返すようには設計されていません。したがって、使用可能メモリー量を超えるデータの場合、メモリー不足例外が発生してアダプター呼び出しが失敗することがあります。そういった失敗を防止するため、しきい値を構成して、それを超えると MobileFirst Server が HTTP 応答を gzip して返すようにします。HTTP プロトコルには、gzip 圧縮をサポートするための標準ヘッダーがあります。クライアント・アプリケーションでも HTTP の gzip コンテンツをサポートできる必要があります。

サーバー・サイド

MobileFirst Operations Console で、「ランタイム」>「設定」>「アダプター応答の GZIP 圧縮しきい値」の下で、適切なしきい値を設定します。デフォルト値は 20 KB です。
注: MobileFirst Operations Console で変更を保存すると、変更はすぐにランタイムで有効になります。

クライアント・サイド

すべてのクライアント要求で Accept-Encoding ヘッダーの値を gzip に設定することで、クライアントが gzip 応答を構文解析できるようにします。 要求変数を指定した addHeader メソッドを使用します。例えば、次のようにします。request.addHeader("Accept-Encoding","gzip");

サーバー・サイド API

JavaScript アダプターは、サーバー・サイド API を使用して、MobileFirst Server に関連する操作 (他の JavaScript アダプターの呼び出し、サーバー・ログへの記録、構成プロパティーの値の取得、Analytics へのアクティビティーの報告、要求の発行者の ID の取得など) を実行できます。

getPropertyValue

MFP.Server.getPropertyValue(propertyName) API を使用して、adapter.xml または MobileFirst Operations Console で定義されているプロパティーを取得します。

MFP.Server.getPropertyValue("name");```

### getTokenIntrospectionData
{: #gettokenintrospectiondata }

`MFP.Server.getTokenIntrospectionData()` API を使用して、以下のことを実行します。

現行のユーザー ID を取得するには、以下を使用します。

```js
function getAuthUserId(){
   var securityContext = MFP.Server.getTokenIntrospectionData();
   var user = securityContext.getAuthenticatedUser();

   return "User ID: " + user.getId;
}

getAdapterName

getAdapterName() API を使用してアダプター名を取得します。

invokeHttp

HTTP アダプターで MFP.Server.invokeHttp(options) API を使用します。
JavaScript HTTP アダプターチュートリアルで使用例を参照できます。

invokeSQL

SQL アダプターで MFP.Server.invokeSQLStatement(options) API および MFP.Server.invokeSQLStoredProcedure(options) API を使用します。
JavaScript SQL アダプターチュートリアルで使用例を参照できます。

addResponseHeader

MFP.Server.addResponseHeader(name,value) API を使用して、新規ヘッダーを応答に追加します。

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

getClientRequest

MFP.Server.getClientRequest() API を使用して、アダプター・プロシージャーの呼び出しに使用した Java HttpServletRequest オブジェクトへの参照を取得します。

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

invokeProcedure

MFP.Server.invokeProcedure(invocationData) を使用して、その他の JavaScript アダプターを呼び出します。
拡張アダプターの使用法とマッシュアップチュートリアルで使用例を参照できます。

ロギング

JavaScript API は、MFP.Logger クラスによってロギング機能を提供します。これには、4 つの標準ロギング・レベルに対応した 4 つの関数が含まれています。
詳細については、サーバー・サイドのログ収集チュートリアルを参照してください。

JavaScript アダプターの例

Last modified on August 23, 2017