Java SDK BellaDatiはJavaを使用してREST APIにアクセスするための使いやすい実装です。すべてのデータはJavaオブジェクトで使用可能になり、手動で解析する必要性を排除して、サーバーからのJSON応答を解釈します。
SDK設定
SDKはいくつかの部分で構成されています。
- SDKのインタフェース宣言を含むAPI（Javadoc onlineとJavadoc download）
- 通常のJava VMで使用できるJava標準の実装
- Androidアプリを構築する際に使用するAndroid実装
SDKを使用するには、API jarをダウンロードして、使用環境にマッチしてください。アップグレードする場合には両方のjarファイルのバージョンが一致していることを確認します
依存関係
SDKの依存関係は、使用ために計画している実装に依存します。あなたは依存関係を手動で設定またはMavenを設定できます。
通常のJava VM
Maven使用
次の依存関係と依存関係管理エントリを追加します。
手動設定
ダウンロードして、あなたのクラスパスに次のライブラリを追加します。
- Jackson 2.2.x 核、注釈とデータバインドライブラリ
- Signpost 1.2.x核及びコモンズのHTTP実装
- Apache HttpClient 4.3.xおよびその依存関係（jars fluent-hcとhttpmimeが必要としない）
Android
Maven使用
あなたのbuild.gradleファイルでは、以下のリポジトリと依存関係のエントリを追加します
手動設定
ダウンロードして、プロジェクトに次のライブラリを追加する。
- Jackson 2.2.x核、注釈とデータバインドライブラリ
- Signpost 1.2.x核
- BellaDatiによって提供された再パッケージ化Android用のApache HttpClient
サーバー設定
BellaDatiからのデータにアクセスするには、ドメイン内のAPIアクセスを有効にする必要があります。そうするために、ドメインの設定を開いて、「Oauth設定」下の「構成」をクリックします。
このダイアログでは、コンシューマキーとコンシューマシークレットを入力します。これらは、SDKの認証時に使用されます。
ユーザーがOAuthリクエストを正常に承認したときに開かれるコールバックURLを任意設定できます。詳細は以下の例をご参考してください。最後、アプリケーション環境は認証のためのWebブラウザを使用することを許可しない場合、クライアントアプリケーション内からユーザ名とパスワードで認証するためXAUTHを有効にすることができます。
使用例
この例では、SDKを使用してOAuthまたはxAuthを使用して認証し、サンプルユーザーに表示されるデータを取得します。
認証
SDKを介してデータを読み取ることができる前に、有効なユーザとして認証する必要があります。この例では、コンシューマキーsdkKeyとコンシューマシークレットsdkSecretを使用してドメインを設定したと仮定します。最初のステップは、サーバーに接続することです。
BellaDatiConnection connection = BellaDati.connect(); // connect to the BellaDati cloud server
あるいは、使用できます：
BellaDatiConnection connection = BellaDati.connect("https://belladati.example.com"); // connect to a custom BellaDati server
OAuth
認証の推奨フォームはOAuthです。このプロトコルを使用すると、SDKは、ユーザーがWebブラウザを使用して承認する必要のあるサーバーからトークンを要求します。このメカニズムの利点は、ユーザがSDKを実行しているコンピュータ上で制限させるリスクを低減し、サーバーに直接に資格情報を送信することです。
最初のステップでは、SDKにサーバからのリクエストトークンを取得させます。
OAuthRequest oauth = connection.oAuth("sdkKey", "sdkSecret"); // request an OAuth request token
今、私たちはこのトークンを許可するユーザーに依頼する必要があります。
System.out.println("Please open the following URL in your browser and authenticate: "
+ oauth.getAuthorizationUrl()); // ask the user to authorize our request using their browser
ここは上記のようにコールバックURLが入るところです： Webアプリケーションを記述する場合は、コールバックを使用して、アクセスを承認した後にユーザーをアプリケーションにリダイレクトすることができます。
ユーザがアプリケーションを正常に認可された後、サーバーからのアクセスを要求できます。
BellaDatiService service = oauth.requestAccess(); // request access from the server
xAuth
いくつかのアプリケーションでは、認証のためにウェブブラウザを使用することが可能または不可能です。このような状況では、xAuthを使用すると、ユーザーがアプリケーションに直接資格情報を入力し、次のように使用できるようになります。
BellaDatiService service = connection.xAuth( "sdkKey", "sdkSecret", "user@example.com", "reallysecurepassword"); // directly request access using xAuth
データの取得
認証が成功した後、今BellaDatiServiceインタフェースのインスタンスを持っています。このインターフェイスは、サーバーからデータを取得するためにいくつかの方法を提供しています。この例では、最初にサムネイル画像とともにレポートのリストを取得してユーザーに表示しましょう。
PaginatedList<ReportInfo> reports = service.getReportInfo().load(); // load an overview of all reports
この呼び出しは、複数のステップで構成されています。getReportInfo()は最初が空でレポートのPaginatedList（特に、PaginatedIdList）を提供します。サーバーに問い合わせload（）を呼び出し、レポートの最初のページをフェッチします。PaginatedListはIterableであり、その内容について調べるためにsize()、 get(),、contains()などのメソッドとともにページネーション自体を操作するいくつかの方法を提供しています。最後、ご利用の場合は通常のListを必要とすれば、簡単にtoList()呼び出すことによってそれを変換できます。
リストの内にReportInfoオブジェクトは、名前、説明、所有者などレポートに関する一般的な情報が含まれています。サムネイルをロードするために、我々はロードしたい各レポートのサーバーへ個別の要求を行う必要がります。これらの要求は、サーバーの待ち時間に応じていくつかの時間がかかる場合がありますので、当社のサムネイルを並行してロードしたいです。例えば：
ExecutorService executor = Executors.newCachedThreadPool();
final Map<String, BufferedImage> thumbnails = Collections.synchronizedMap(new HashMap<String, BufferedImage>());
for (final ReportInfo reportInfo : reports) {
executor.submit(new Runnable() {
@Override
public void run() {
try {
// load a thumbnail and store it in our map of thumbnails
thumbnails.put(reportInfo.getId(), (BufferedImage) reportInfo.loadThumbnail());
} catch (IOException e) {
// handle exception
}
}
});
}
executor.shutdown();
executor.awaitTermination(1, TimeUnit.MINUTES);
loadThumbnailは、上記の例でBufferedImageにキャストされているObjectを返却します。異なる実装をサポートし、代わりにAndroidでのBitmapAndroidを取得します（BufferedImageを持っていない）
いくつかの状況では、おそらくWebアプリケーションで最初のレポート自体をロードすることなく、与えられたレポートにIDのサムネイルをロードできます。これを行うには、代わりに使用できます。
service.loadReportThumbnail("my_report_id"); // directly load thumbnail
次に、ユーザーに表示できるサムネイル画像を含むレポートのリストを表示し、どの画像を表示するかを選択するよう求めます。
ユーザーがリストの3番目のレポートを選択したとします。 私たちはその内容を得ることができます：
Report report = reports.get(2).loadDetails(); // load details of a specific report
このReportオブジェクトは、、レポートについての詳細、特にそのViewsのリストが含まれています。レポート内の各チャート、テーブル、KPIなどは、このようなViewによって表されます。ビューを繰り返して表示することができます。
for (View view : report.getViews()) {
switch (view.getType()) {
case CHART: // this means we're getting a JSON chart
displayChart((JsonNode) view.loadContent());
break;
case KPI: // this means we're getting JSON KPI
displayKPI((JsonNode) view.loadContent());
break;
case TEXT: // this means we're getting JSON text
displayText((JsonNode) view.loadContent());
break;
case TABLE: // this tells us that we're getting a Table object
displayTable((TableView.Table) view.loadContent());
break;
}
}
ご覧のように、ビューは異なるレンダリングされた異なるタイプを持つことができる。ほとんどのビューは、ジャクソンライブラリからJsonNodeとして返却されるJSONコンテンツが含まれます。しかし、テーブルオブジェクトを含むテーブルがテーブルの内容を追加ロードするための3つの方法がある。テーブルをロードする方法の詳細については、TableViewをご参照してください。
この例では、時間がかかることがあり、単一のスレッドによってすべてのビューをロードしています。簡単に上記のサムネイル画像にしたものと同様のメカニズムを使用することで並行して行われますが、明確にするためにここでそれを省略することに決定できます。
一般的助言
ユーザーの読み込み時間が長くなることを避けるために、サーバーを何度も呼び出さないようにしてください。複数の項目をロードする場合、それらを並行してロードすることを検討してください。これは、より良い並列で実行されるべき方法を認識するのは簡単です：loadSomething()という名前の任意の方法は、サーバーへの呼び出しを行っています。
BellaDatiServiceインターフェイスを使用すると、そのIDを知っているときに、オブジェクトに直接アクセスできるいくつかのショートカットメソッドが用意されています。たとえば、レポートリストを最初に取得したり、最初にレポートをロードせずにレポートをロードすることができます。
BellaDatiServiceインスタンスをシリアル化してアプリケーションに保存することで、後で使用できるようにユーザーのアクティブなセッションを保存できます。ユーザがアプリケーションで作業を継続したい場合は、インスタンスを復元することができ、SDKで使用されるアクセストークンが期限切れになるまでユーザーは再度認証する必要はありません。
SDKはいくつかの部分で構成されています。
Overview
Content Tools