OBKV-HBaseクライアントを使用してクラスタに接続する

OBKV-HBaseは、OBKV-HBaseクライアントを使用してOBKV-HBaseクラスタに接続し、HBase互換のAPIを用いてデータ処理を行うことをサポートしています。既存の業務でネイティブHBaseのデータ操作ロジックを使用している場合、OceanBaseデータベースクラスタをデプロイし、OBServerサーバー側にHBaseテーブルを作成した上で、OBKV-HBaseクライアントを通じてデータ操作を実行できます。本記事では、クライアントの設定、OBServerへの接続、および基本的な追加・削除・変更・検索操作の手順について説明します。

OBKV-HBaseクライアント

OBKV-HBaseクライアントは、OBKV-HBaseが提供する基本インターフェースに基づき、クライアント側でHBase互換のAPIをカプセル化したものです。現在、HBase 0.94バージョンの機能と互換性があります。

前提条件

OBKV-HBaseクライアントを使用してOBKV-HBaseクラスタに接続し、データ処理を行う前に、以下の準備作業を完了していることを確認してください：

• OBKVクラスタを作成済みであること。サポートされているデプロイメントプラン、デプロイ方法、および詳細なデプロイ操作については、クラスタの作成をご参照ください。
• OBKVテナントを作成済みであること。テナント作成の詳細な操作については、テナントの作成をご参照ください。
• データベースを作成済みであること。
• OBKV-HBaseデータテーブルを作成済みであること。OBKV-HBaseデータテーブルの作成手順の詳細については、データベーススキーマ設計をご参照ください。

テーブル作成例：

-- まず、テーブルグループhtable1を作成します
CREATE TABLEGROUP htable1;

-- htable1テーブルグループにバインドされたテストテーブルhtable1$family1を作成します
 CREATE TABLE htable1$family1 (
       K varbinary(1024),
       Q varbinary(256),
       T bigint,
       V varbinary(1048576) NOT NULL,
       PRIMARY KEY(K, Q, T))
       TABLEGROUP =  htable1;

ステップ1：クライアント依存関係の追加

OBKV-HBaseクライアントのJARパッケージ依存関係を、ローカルJavaプロジェクトのpom.xmlファイルに追加します（または、OBKV-HBase使用デモを参照してください）。

<dependency>
    <groupId>com.oceanbase</groupId>
    <artifactId>obkv-hbase-client</artifactId>
    <version>0.1.4</version>
</dependency>

ステップ2：クライアント接続パラメータの設定

OBKV-HBaseはパブリッククラウドとプライベートデプロイメント方式によって異なり、設定が必要なクライアント接続パラメータも異なります。OceanBaseクラスタをプライベートデプロイメントしている場合は、直接接続モードの設定をご参照ください。パブリッククラウドのOBKVサービスを使用している場合は、クラウド上モードをご参照ください。

直接接続モードの設定 (プライベートデプロイメント)

## 現在のクラスタの設定を仮定します
## ClusterName：obkvcluster
## TenantName：obkv
## DataBaseName: test
## UserName：root
## SYS_USER_NAME : sysroot

#### 必須項目
Configuration conf = new Configuration();

## フォーマットはuserName@tenantName#clusterNameです
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root@obkv#obkvcluster");

## fullUserNameのuserNameはOceanBaseへのパスワードです
conf.set(HBASE_OCEANBASE_PASSWORD, "");

## obconfig serverからRSlistのURLを取得します。詳細については、Config URLの取得に関する内容をご参照ください。
conf.set(HBASE_OCEANBASE_PARAM_URL, "");

## システムテナント内のユーザー名です。ルーティングテーブルにアクセスできるのはシステムテナント内のユーザーのみです。
conf.set(HBASE_OCEANBASE_SYS_USER_NAME, "sysroot");

## システムテナント内のユーザーパスワード
conf.set(HBASE_OCEANBASE_SYS_PASSWORD, "");

#### オプション
## リクエストの実行タイムアウト時間（ビジネス特性に基づいて選択）。単位はmsです。以下はタイムアウト時間1秒を示します。
conf.set("rpc.execute.timeout", "1000");

以下の方法でConfig URLを取得できます。

• OCPからConfig URLを取得する

  OCPを使用している場合は、OCPからConfig URLを取得できます。

  1. OceanBaseクラウドプラットフォームにログインします。
  2. 左側のナビゲーションペインで**クラスタを選択し、下にスクロールしてクラスタリスト**を見つけます。
  3. アクセスしたいクラスタ名をクリックして開きます。
  4. クラスタの詳細ページで**ConfigURL**パラメータを見つけます。このパラメータはクライアントの初期化時に設定する必要があります。

• OBDを使用してConfig Serverをデプロイし、Config URLを取得する

  OCPを使用していない場合は、コマンドラインを使用してConfig Serverをデプロイする必要があり、ObRootServiceInfoUrlを取得する必要があります。

クラウドモードの設定（パブリッククラウド）

## 現在のクラスタは以下のように仮定します
## DataBaseName: test
## UserName：root

#### 必須項目
Configuration conf = new Configuration();

## データベースの新規ユーザー名、3段階ではなく、usernameを使用
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");

## ユーザーパスワード
conf.set(HBASE_OCEANBASE_PASSWORD, "");

## ODP Addressの備考を参照
conf.set(HBASE_OCEANBASE_ODP_ADDR,、

## OBKVのポートは3307（固定）
conf.setInt(HBASE_OCEANBASE_ODP_PORT, "3307");

## クラウドでODPモードを使用する（固定）
conf.setBoolean(HBASE_OCEANBASE_ODP_MODE, true);

## データベースのデータベース名
conf.set(HBASE_OCEANBASE_DATABASE, "test");

#### 任意項目
## リクエストの実行タイムアウト時間（業務特性に基づいて設定）
conf.set("rpc.execute.timeout", "1000");

ODP Addressは以下の方法で取得できます。OB Cloudテナントのダッシュボードにアクセスし、デプロイメント関係図を確認します。

OceanBaseクラスタへの接続

クライアント接続パラメータの設定が完了したら、クライアントの初期化を開始します。現在、OHTableClientとOHTablePoolの2つの方法がサポートされています。その違いは以下の通りです：

• OHTableClient：非スレッドセーフで、内部には1つのOHTableハンドルしかありません。複数のスレッドが同じOHTableに同時にアクセスすると予測不可能な問題が発生する可能性があります（単一スレッドシナリオで使用）。
• OHTablePool：OHTableプールで、必要な場合にプールから対応するテーブルのOHTableインスタンスを取得して使用します（マルチスレッドシナリオで使用）。

OHTableを介した接続

// configurationの設定は前のセクションをご参照ください。ここでは詳述しません。
Configuration conf = new Configuration(); // 設定パラメータの作成
conf.set(xxx); // 各種設定パラメータの設定
OHTableClient hTable = new OHTableClient("test1", conf); // htableオブジェクトの作成
hTable.init(); // hTableの初期化
// 関連するロジックの実行
hTable.close(); // htableオブジェクトのクローズ

OHTablePoolによる接続

OBKV-HBaseは、テーブルプールモードを提供し、複数のテーブルを管理する操作インスタンスをサポートしています。現在、リソースプールにはReusable、RoundRobin、ThreadLocalの3つの方式が含まれています。テーブルプールをインスタンス化する際に、使用するモードを指定できます。

使用方法はHBaseのHTablePoolと同じです。特定のテーブルのHTableが必要な場合は、pool.getTable("xx") を使用して対応するHTableを取得します。注意点は以下の通りです：

• パラメータの使用優先順位：テーブル専用パラメータ（例：pool.setOdpAddr()など）> Conf設定のパラメータ > デフォルトパラメータ。
• HTableの使用後は必ずclose()を行い、OHTableをプールに返却してください。try/finallyを使用してHTableを返却することを推奨します。

// configurationの設定は前のセクションをご参照ください。ここでは詳述しません。
Configuration conf = new Configuration(); // 設定パラメータの作成
conf.set(xxx);  // 各種設定パラメータの設定

// maxSizeの初期化。pool内の各テーブルの最大HTable参照数を表すために使用されます。
int maxSize = 100;
// poolTypeの初期化。Reusable、ThreadLocal、RoundRobinの3種類があります。ThreadLocalの使用を推奨します。
PoolMap.PoolType poolType = PoolMap.PoolType.ThreadLocal;
OHTablePool pool = new OHTablePool(conf, maxSize, poolType);
HTableInterface hTable = pool.getTable("test"); // 対応するテーブルのHTableを取得
// 関連するロジックの実行
hTable.close(); // retrun table to the pool

OBKV-HBaseクライアントの構成パラメータ

接続パラメータに加えて、Configurationを通じてその他のパラメータを設定することもできます。以下の例では、クライアントのRPCタイムアウト時間を3秒に設定しています。

conf.set("rpc.execute.timeout", "3000");

よく使われるパラメータの一覧

OHTableの設定

Configurationに加えて、OHTableのインターフェースを通じて個々のOHTableのパラメータを設定することもできます。

対応するHBase操作

上記の手順でクライアントを初期化した後、操作を開始できます。この記事では、一部のOHTableインターフェース操作について説明します。より詳細なインターフェース情報については、OHTable.javaをご参照ください。

関連するOBKV-HBaseの使用デモについては、OBKV-HBase使用デモをご参照ください。

次のステップ

• OBKV-HBaseクライアントをデプロイし、クラスタへの接続を確立した後、データに対する操作を実行できます。データ操作の具体的な例については、データ操作の例をご参照ください。