一.概要
FR11.0はオープン・プラットフォームを提供します。FineReportをベースに、開発者がセントラルシステム以外のシステムでも安全、柔軟性と効率の高く、規範化されたwebサービスを提供できるように役に立ちます。
統一したプラットフォーム設定を提供し、クライアントのAPIの権限管理と認証規範の管理を実現させます。
注意：オープン・プラットフォームのプラグインをアップグレードしたい時、もし同シリーズのプラグインを利用しているなら、まずは同シリーズのプラグインを無効にしてからオープン・プラットフォームのプラグインのアップグレードを進めてください。或いはアップグレード完了後サーバを再起動してください。
同シリーズのプラグイン：
オープン・プラットフォーム-FineBI API
オープン・プラットフォーム-FineReport API
オープン・プラットフォーム-オープン・プラットフォームログインの認証API
二.機能紹介
1.機能へのアクセス方法
管理者としてFineReportポータルにログインした後、システム-オープンプラットフォームを順にクリックして機能利用の画面に入ります。
2.API管理
[すべてのAPI]は、サード・パーティー・システムとFRとの資料相互閲覧サービスに対する設定です。
サービス用APIをグループ分けして管理できます。画面の左側が各グループ名です。システムはグループ分けの一般ルールに従ってグループをいくつか設けてあります。
グループに対して利用者は追加、編集、削除という管理操作を行えます。一方、すでに組み込まれたグループに対しては編集不可と削除不可となっています。
一つのグループを選んだ後、画面の右側には同グループのサービス用APIのリストが表示されます。システムはよく使われるいくつかのサービス用APIを作りました。
サービス用APIに対して利用者は追加、編集、無効、一つだけを削除、複数を削除、グループ変更、という操作を行えます。
注：すでに組み込まれたグループに対しては編集不可と削除不可となっています。
3.アプリ管理
APIの登録操作のため、一つ一つのアプリにIDと暗号鍵を配布します。
オープン・プラットフォームではクライアントに対する追加、編集、コピー、無効、一つだけを削除、複数を削除、グループ変更という管理操作がサポートされています。
異なるアプリケーションに区別をつけるよう、アプリの設定では【アプリケーション名】、【アプリ詳細】と【候補認証】のカスタム設定がサポートされています。
アプリケーション追加後、【アプリケーションID】と【暗号鍵】は自動的に生成され、カスタム設定不可と編集不可となっています。
編集操作では暗号鍵のリセット操作がサポートされています。
4.認証方法
認証方法は外部サービスの利用の安全性を保障する方法です。オープン・プラットフォームではデフォルトとして三つの認証方法があります。ユーザー自ら展開することもできます。
認証方法に対して利用者は追加、編集、無効、一つだけを削除、複数を削除という管理操作を行えます。
利用者が各認証方法を混同しないよう、認証方法の設定では[認証名称]と[認証説明]がカスタム設定可能となっています。
認証方法の設定にある[API種類]とは、実現させる必要のあるAPI認証のオブジェクトのことです（同じ種類なら設定の変更によって複数の認証方法に変更させることができます）。
認証方法の設定にある[設定]とは、当認証に必要な設定のことです。例えば、ダイジェスト・署名認証には[ダイジェストのアルゴリズム]と[有効期限]を定義する必要があります。これらの設定は暗号化項目として設定できます。保存後、暗号化された情報はフロントグラウンドで読み取られなくなります。
5.組込み認証方法
自己署名token認証
候補認証として選ぶかに関わらず、この認証はどのアプリケーションのAPIをもサポートしています。
自己署名token認証は、access_tokenを通してログインの情報を認証します。先にクライアントのIDと暗号鍵を使ってaccess_tokenを取得しておくことが必要です。
以下はアプリケーションがクライアントのIDと暗号鍵を使ってtokenの取得をリクエストするアドレスです。
$HOST/sp/client/API/token
パラメータ：client_id = クライアントID secret= 暗号鍵
QueryかHeaderでパラメータを入力できます。
client_token={access_token}というパラメータを利用して希望のAPIにアクセスすることができます。
アクセスキー/シークレットアクセスキーによる直接認証
この方法は、クライアントIDと暗号鍵をそのまま認証の要素としてサービスを呼び出す方法です。一方、安全性から考えるとこの方法の利用をおすすめしません。この方法では設定項目が要らなく、編集不可となっています。
つまり、リクエストヘッダーにclient_id={アプリID} secret={暗号鍵}を付けるだけでアプリに直接アクセスできます。
ダイジェスト・署名認証
この方法はtoken認証を使えない場合、ハッシュアルゴリズム（例えば、SM3、MD5とSHA256など）を利用し、クライアントID、キー及びタイムスタンプに署名を付した後、署名とクライアントIDを通して認証を行います。安全性が比較的に高いため、この認証方法の利用をおすすめします。
[ダイジェスト・署名認証]における[署名]＝ハッシュアルゴリズム（クライアントID+暗号鍵＋タイムスタンプ）＋タイムスタンプ。例えば：
【client_id=203bc7b8db1d423fb55824150327ef98，secret=98ffd41b86db4868a6875f57e6974bbc， timestamp=1600166180321、署名アルゴリズムにMD5が使われ、タイムアウト時間を300秒に設定】->
【署名 = MD5(client_id+secret+timestamp)+timestamp = EE6E14BCEC5724C3BC6FC08AFC5C2B111600166180321】
SM暗号化 SM2署名認証
SM暗号化SM2（楕円暗号）を利用して暗号化・復号化を行う場合、標準的な楕円パラメータを使って署名します。
_sign_=sm2(clientId+secret+timestamp),
設定項目：priKey=秘密鍵、timeout=タイムアウト時間（秒）
API設定
区別をつけるよう、利用者は【API名称】と【API説明】を好きなようにカスタマイズすることができます。
【API種類】とは、APIサービスが実現できる機能のことを指します。
【APIパス】と【API方法】とは、HTTPリクエストでこのAPIを呼び出すパスと方法のことです。パスの前に「/」をつける必要がありません。追加されたAPIの【APIパス】にて、利用者はパスを自ら定められます（既存のAPIパスと異なるパスに定めてください）。
実際のリクエストアドレスは $HOST/sp/client/API/{APIパス} です。
$HOST = http://localhost:8075/webroot/decision の場合、リクエストアドレスはhttp://localhost:8075/webroot/decision/sp/client/API/{APIパス} となります。
注：すでに組み込まれたAPIの内容は編集不可となっております。編集されても再起動後は元の内容に戻ります。
6.クライアント権限
非公開APIを呼び出すには権限の認証が必要となっています。異なるシーンにおける異なるアプリでは呼び出せるAPIの範囲も異なります。この画面で割り当てることができます（公開APIなら好きなように呼び出せるためここの範疇に入っていません）。
注：当面グループ分けの権限がありません。つまり、グループ分けの権限を持ったとしても、同グループにあるAPIの権限をあるクライアントに割り当てただけです。今後APIが異なるグループに入ったり、または同グループに新しいAPIが入ったりすると、その権限に変わりがありません。
7.リクエスト・ログ
この画面ではAPIのリクエストの頻度、またはAPIのリクエストの詳細記録を確認することができます。
三.呼び出し例
権限設定完了後、APIを呼び出すことができるようになります。
1.SQLデータサービス
SQLをデータサービスに変えてサードパーティに提供し、利用してもらう、という一番簡単なシーンをこのdemoの例を以て説明します。
[demo]SQLデータサービス、というAPIを使うこととします。
二つの設定項目が含まれています。
connection：SQLを実行するデータソース接続名（FRDemoなど）
sql：データソースのSQL
このAPIは主に外部に向けて基本的かつ簡単なデータサービスを提供するために使われています。SQLを書けるだけで操作できるため、テンプレートに依存することがありません。
以下のテストを例にします。
データソース接続= FRDemo SQL = SELECT * FROM `販売量` where 地域 = '${地域}'
このクエリでは地域というパラメータが使われています。
呼び出してパラメータを渡す二種の方法を確認します。
2.テンプレートデータセットのデータサービス
作成済みテンプレート内のデータセットのデータをどのようにサードパーティに提供するか、というシーンをこのdemoの例を以て説明します。
帳票データセットサービス、というAPI例を使うこととします。
二つの設定項目が含まれています。
report：データセットの出所（reportletsに対して）
dsName：データセットの名称
テンプレートにすでに作成済みのデータセットのデータをサードパーティが必要とする、データがSQLのデータセットからのものではない、或いはサードパーティに向けてソースデータ接続のデータサービスを直接開発することが適切ではない場合、このAPIは適用します。
以下のテストを例にします。
テンプレートパス = GettingStarter.cpt データセット名称 = ds1
このクエリでは地区というパラメータが使われています。
呼び出して【パラメータを渡す二種の方法】を確認します。
3.書き込みAPIの呼び出し
サードパーティに向けてデータ入力・承認という業務サービスを提供する場合、どのようにテンプレートを活用して簡単に実現させるか、この書き込みAPIのdemoを以て説明します。
すでに開発済みのAPI例を使う必要があります：com.tptj.plugin.hg.client.center.API.data.WriteReport
二つの設定項目がサポートされています。
report :とある書き込みテンプレートのパス（reportletsディレクトリに対して）
sheet：実行する必要のある具体的なsheet名が対応するsheetのテンプレート書き込み属性における書き込み内容を選べます。
このパラメータに何も記入しないと、あらゆるsheetのテンプレートの書き込み属性内の書き込み内容を実行することになります。
注1：この書き込みはJS関連イベントを起動させることがありません。
注2：ここではbodyというパラメータが使われます。このパラメータは直接URLを通して渡すことができるし、リクエストのbodyを通して渡すこともできます（APIサービスの呼び出しを通しての場合に限ります）。
もしhttpがリクエストするbodyがjsonの場合、計算の帳票には二種の参照があります。
1.直接$bodyか${body}というパラメータ名を通してjson文字列を取得します。
2.{ key1:xxxx,key2:ffffff,...,keyN:fsss }という形のbodyの場合、直接$key1,$key2,....$keyNを通してこれらのパラメータを帳票に使うことができます。
4.簡単な帳票行列式データサービス
一つのデータセットから簡単に取り出せないデータについて、簡単な帳票の形にしてデータサービスを提供する、というやり方をこのdemo例を以て説明します。
次のAPIを使う必要があります：com.tptj.plugin.hg.client.center.API.data.GetListByReport
二つの設定項目が含まれています。
report：データソースの帳票パス（reportletsに対して）
tag：データソースのsheet名
テンプレートにすでに作成済みのデータセットのデータをサードパーティが必要とする、データがSQLのデータセットからのものではない、或いはサードパーティに向けてソースデータ接続のデータサービスを直接開発することが適切ではない場合、このAPIは適用します。
以下のテストを例にします。
テンプレートパス= WorkBook12.cpt sheet名=sheet1
このクエリではareaというパラメータが使われています。
二つのデータセットの関連付けを通して実現させます。
定義するdemoのAPIの設定詳細は次の通りです。
実際のテスト効果は次の通りです。
注：これはどの場合でも使えるAPI例ではありません。このAPI例を使うなら、作成するテンプレートは次のように制限されています。
データしかないテーブルのみサポートされています。
一つのsheetを簡単に次の形に分けられます。
データ行：上から下へ、左から右へ一つ一つの行を確認し、「下へ展開」可能なセル、それに同セルの所在行が非表示行ではないなら、その行をデータの先頭行とします。その下の全ての内容は出力するデータエリアと見なされます（そのため、一つのsheet内に一つのデータエリアしか持たないと制限されています）。
タイトル行：データ行の上の全ての行の中に、一つのセルにしか値がなく、それに非表示行ではない行がタイトル行と見なされます。複数のタイトル行が存在することが許可されています。行番号の順で出力されます（詳細データではタイトルが出力されません）。
リストヘッド行：データ行の上の全ての行の中に、一つ以上のセルに値が入り、それに非表示行ではない行がリストヘッド行と見なされます。複数のリストヘッド行が存在することが許可されています。一方、列ごとのリストヘッドについて、データ行に一番近いリストヘッドのセルの値をその列のリストヘッドとします。
空白行：すべての行の高さは0、あるいは行全体にデータが入っていない行を指します。空白行は出力されません。
空白列：すべての列の幅は0、あるいはその列のリストヘッドの値はNULLの場合、空白列は出力されません。
合併行のデータは再小合併行に基づいて出力されます。
注：複雑、または大きなデータ量が入ったテンプレートを使わないでください。
5.簡単な帳票グループ分け式データサービス
一つのデータセットから簡単に取り出せないデータについて、簡単な帳票の形にしてデータサービスを提供する、というやり方をこのdemo例を以て説明します。
次のAPI例を使う必要があります。
二つの設定項目が含まれています。
report：データソースの帳票パス（reportletsに対して）
tag：データソースのsheet名
以下のテストを例にします。
テンプレートパス= WorkBook12.cpt sheet名= sheet1
このクエリではareaというパラメータが使われています。
二つのデータセットの関連付けを通して実現させます。
定義するdemoのAPIの設定詳細は次の通りです。
注1：これはどの場合でも使えるAPI例ではありません。このAPI例を使うなら、作成するテンプレートは、簡単な帳票行列式データサービスと同じような制限事項を受けることになります。
注2：複雑、または大きなデータ量が入ったテンプレートを使わないでください。
前：スマート検出