1. 管理者ガイド
  2. Oracle NoSQL Databaseプロキシおよびドライバ
  3. Oracle NoSQL Databaseドライバ
  4. NoSQLハンドルの取得

NoSQLハンドルの取得

Oracle NoSQL Databaseドライバを使用して表にアクセスする方法について学習します。NoSQLハンドルを作成することにより、アプリケーションの開発を開始します。NoSQLHandleを使用して表にアクセスし、すべての操作を実行します。

アプリケーションで、Oracle NoSQL Databaseプロキシへの接続となるNoSQLHandleを作成します。このNoSQLHandleを使用して、Oracle NoSQL Database表にアクセスし、Oracle NoSQL Database操作を実行できます。NoSQLHandleをインスタンス化するには、NoSQLHandleConfigクラスの参照をNoSQLHandleFactory.CreateNoSQLHandleメソッドに渡します。NoSQLHandleConfigクラスをインスタンス化するために、Oracle NoSQL DatabaseプロキシURLをパラメータ化されたコンストラクタとして指定します。

Oracle NoSQL Databaseサーバーで、非セキュア・モードまたはセキュア・モードでプロキシを構成できます。アプリケーションではNoSQLHandleConfigクラスを使用して、ハンドルが使用するセキュリティ構成情報を指定できます。非セキュア・アクセスの場合は、引数なしのコンストラクタを使用してStoreAccessTokenProviderクラスのインスタンスを作成します。セキュア・アクセスの場合は、パラメータ化されたコンストラクタを使用して、StoreAccessTokenProviderクラスのインスタンスを作成します。StoreAccessTokenProviderクラスの参照をNoSQLHandleConfigクラスに提供して、適切な接続を確立します。

非セキュア・プロキシに接続するNoSQLHandleを作成する例を次に示します。 
// Service URL of the proxy
String endpoint = "http://localhost:5000";

// Create a default StoreAccessTokenProvider for accessing the proxy
StoreAccessTokenProvider provider = new StoreAccessTokenProvider();

// Create a NoSQLHandleConfig
NoSQLHandleConfig config = new NoSQLHandleConfig(endpoint);

// Setup authorization provider using StoreAccessTokenProvider
config.setAuthorizationProvider(provider);

// Create NoSQLHandle using the information provided in the config
NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);
セキュア・プロキシに接続するNoSQLHandleを作成する例を次に示します。 
// Service URL of the secure proxy
String endpoint = "https://localhost:5000";

// Username of kvstore
String userName = "driver_user";

// Password of the driver user
String password = "DriverPass@@123";

//Construct StoreAccessTokenProvider with username and password
StoreAccessTokenProvider provider = 
    new StoreAccessTokenProvider(userName, password.toCharArray());

// Create a NoSQLHandleConfig
NoSQLHandleConfig config = new NoSQLHandleConfig(endpoint);

// Setup authorization provider using StoreAccessTokenProvider
config.setAuthorizationProvider(provider);

// Create NoSQLHandle using the information provided in the config
NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);
セキュア・アクセスの場合、StoreAccessTokenProviderのパラメータ化されたコンストラクタは次の引数を使用します。
  • usernameは、kvstoreのユーザー名です。
  • passwordは、kvstoreユーザーのパスワードです。

ノート:

クライアント・ドライバ・プログラムでは、JVM環境パラメータjavax.net.ssl.trustStoreにdriver.trustファイルのパスを含めて、セキュアな接続が動作するようにする必要があります。driver.trustは、プロキシが構成され、起動されたときに配布する必要があります。このファイルは、クライアント・ドライバがプロキシ・サーバーのIDを認証して、安全な接続を確立できるようにします。

ユーザーは、セキュアなプロキシにアクセスするために、javaドライバのdriver.trustファイルを生成する必要があります。セキュリティ・ガイドのOracle NoSQL Databaseプロキシの証明書と秘密キーの生成を参照してください。

クライアント・プログラムにdriver.trustファイルを追加する例を次に示します。 

java -Djavax.net.ssl.trustStore=driver.trust -cp .:/lib/nosqldriver.jar Example

ハンドルには、メモリーとネットワーク・リソースが関連付けられています。このため、アプリケーションがハンドルの使用を終了したら、NoSQLHandle.closeメソッドを起動してリソースを解放します。

ネットワーク・アクティビティ、リソース割当ておよび割当て解除のオーバーヘッドを最小限に抑えるには、ハンドルの作成と終了を繰り返さないようにすることをお薦めします。たとえば、操作ごとにハンドルを作成して終了すると、大量のリソース割当てのオーバーヘッドが発生し、アプリケーションのパフォーマンスが低下します。1つのハンドルで同時操作が可能なため、マルチスレッド・アプリケーションの表にアクセスするには単一のハンドルで十分です。複数のハンドルを作成してもパフォーマンス上の利点はなく、追加のリソース・オーバーヘッドが発生します。

ハンドルは、最初にborneo.NoSQLHandleConfigインスタンスを作成して、通信エンドポイント、認可情報、およびハンドル構成のデフォルト値を構成することで作成されます。borneo.NoSQLHandleConfigは、サービスへの接続を表します。作成後は、リソースをクリーンアップするために、メソッドborneo.NoSQLHandle.close()を使用してクローズする必要があります。ハンドルはスレッドセーフで、共有するためのものです。

セキュア・ストアを実行する場合は、REQUESTS_CA_BUNDLE環境変数を使用して証明書パスを指定する必要があります。
$ export
    REQUESTS_CA_BUNDLE=<path-to-certificate>/certificate.pem:$REQUESTS_CA_BUNDLE

さらに、アプリケーションの必要な操作(表やデータの操作など)を実行する権限を持つユーザー・アイデンティティをストアに(別々に)作成する必要があります。アイデンティティはborneo.kv.StoreAccessTokenProviderで使用されます。ストアがセキュアでない場合は、borneo.kv.StoreAccessTokenProviderの空のインスタンスが使用されます。

Oracle NoSQL DatabaseのNoSQLハンドルを取得する例:
from borneo import NoSQLHandle, NoSQLHandleConfig
from borneo.kv import StoreAccessTokenProvider
#
# Assume the proxy is running on localhost:8080
#
endpoint = 'http://localhost:8080'
#
# Assume the proxy is secure and running on localhost:443
#
endpoint = 'https://localhost:443'
#
# Create the AuthorizationProvider for a secure store:
#
ap = StoreAccessTokenProvider(user_name, password)
#
# Create the AuthorizationProvider for a not secure store:
#
ap = StoreAccessTokenProvider()
#
# create a configuration object
#
config = NoSQLHandleConfig(endpoint).set_authorization_provider(ap)

#
# set the certificate path if running a secure store
#
config.set_ssl_ca_certs(<ca_certs>)

#
# create a handle from the configuration object
#
handle = NoSQLHandle(config)

非セキュアなオンプレミスOracle NoSQL Database用の構成

アプリケーションを非セキュアなNoSQLデータベースに接続するには、プロキシ・サーバーが実行されているエンドポイントを指定し、構成モードとしてonpremを指定します。
cfg:= nosqldb.Config{
    Mode:     "onprem",
    Endpoint: "http://exampleHostServer:8080",
}
client, err:=nosqldb.NewClient(cfg)
...

セキュアなオンプレミスOracle NoSQL Database用の構成

アプリケーションをセキュアなNoSQLデータベースに接続するには、サーバーでの認証に使用されるユーザー資格証明を指定する必要があります。プロキシ・サーバーが自己署名付き証明書またはデフォルトのシステムCAによって信頼されない証明書で構成されている場合は、サーバーの証明書の検証に使用される証明書パスとサーバー名にもCertPathおよびServerNameを指定する必要があります。
cfg:= nosqldb.Config{
    Mode:     "onprem",
    Endpoint: "https://exampleHostServer",
    Username: "driverUser",
    Password: []byte("ExamplePassword__123"),
    HTTPConfig: httputil.HTTPConfig{
        CertPath: "/path/to/server-certificate",
        ServerName: "exampleHostServer", // should match the CN subject value from the certificate
    },
}
client, err:=nosqldb.NewClient(cfg)

クラスNoSQLClientは、サービスへのメイン・アクセス・ポイントを表します。NoSQLClientのインスタンスを作成するには、適切な構成情報を指定する必要があります。この情報は、プレーンJavaScriptオブジェクトで表され、オブジェクト・リテラルとしてNoSQLClientのコンストラクタに提供できます。または、この情報をJSON構成ファイルに格納し、NoSQLClientのコンストラクタをそのファイルへのパス(絶対パスまたはアプリケーションの現在のディレクトリに対する相対パス)とともに格納することもできます。

非セキュアなストアへの接続

非セキュア・モードでプロキシに接続するには、通信エンドポイントを指定する必要があります。

たとえば、構成JavaScriptオブジェクトを使用する場合:
const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const ServiceType = require('oracle-nosqldb').ServiceType;

const client = new NoSQLClient({
    serviceType: ServiceType.KVSTORE,
    endpoint: 'myhost:8080'
});
同じ構成をファイルに格納することもできます。次の内容を含むファイルconfig.jsonを作成します。
{
    "serviceType": "KVSTORE",
    "endpoint": "myhost:8080",
}
その後、このファイルを使用してNoSQLClientインスタンスを作成できます。
const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const client = new NoSQLClient('/path/to/config.json');

セキュア・ストアへの接続

セキュア・モードでプロキシに接続するには、通信エンドポイントに加えて、ドライバ・ユーザーのユーザー名とパスワードを指定する必要があります。この情報はkvstoreプロパティのConfig#authオブジェクトに渡され、次に示す3つの方法のいずれかで指定できます。
  • ユーザー名とパスワードを直接渡す ユーザー名とパスワードを直接指定できます。パスワードはメモリーにプレーン・テキストで格納されるため、このオプションは安全性が低下します。
    const NoSQLClient = require('oracle-nosqldb').NoSQLClient;

const client = new NoSQLClient({
    endpoint: 'https://myhost:8081',
    auth: {
        kvstore: {
            user: 'John',
            password: johnsPassword
        }
    }
});

  • ファイルへの資格証明の格納:

    ファイル・システムの権限で保護されている別のファイルに資格証明を格納することを選択できます。資格証明ファイルの形式は次のとおりです。
    {
    "user":     "<Driver user name>",
    "password": "<Driver user password>"
}
    その後、この資格証明ファイルを次のように参照できます。
    const NoSQLClient = require('oracle-nosqldb').NoSQLClient;

const client = new NoSQLClient({
    endpoint: 'https://myhost:8081',
    auth: {
        kvstore: {
            credentials: 'path/to/credentials.json'
        }
    }
});

  • 独自のKVStoreCredentialsProviderの作成:

    KVStoreCredentialsProviderインタフェースのインスタンスとして、ドライバ資格証明をセキュアに格納および取得するための独自の資格証明プロバイダを実装できます。loadCredentialsはPromiseを返すため、非同期関数として実装できます。
    const NoSQLClient = require('oracle-nosqldb').NoSQLClient;

class MyKVStoreCredentialsProvider {
    constructor() {
        // Initialize required state information if needed
    }

    async loadCredentials() {
        // Obtain client id, client secret, user name and user password somehow
        return { // Return credentials object as a result
            user: driverUserName,
            password: driverPassword
        };
    }
}
let client = new NoSQLClient({
    endpoint: 'https://myhost:8081',
    auth: {
        kvstore: {
            credentials: new MyKVStoreCredentialsProvider(myArgs...)
        }
    }
});

クラスNoSQLClientは、サービスへのメイン・アクセス・ポイントを表します。NoSQLClientのインスタンスを作成するには、適切な構成情報を指定する必要があります。この情報は、NoSQLClientのコンストラクタにインスタンスを提供できるNoSQLConfigクラスで表されます。または、構成情報をJSON構成ファイルに格納し、そのファイルへのパス(絶対パスまたは現在のディレクトリに対する相対パス)を取得するNoSQLClientのコンストラクタを使用することもできます。

非セキュアなストアへの接続

非セキュアなモードでは、ドライバはHTTPプロトコル経由でプロキシと通信します。必要な情報は通信エンドポイントのみです。オンプレミスNoSQLデータベースの場合、エンドポイントはプロキシのURLをhttp://proxy_host:proxy_http_portの形式で指定します。非セキュア・モードでプロキシに接続するには、通信エンドポイントおよびサービス・タイプをServiceType.KVStoreとして指定する必要があります。

NoSQLConfigのインスタンスは、直接またはJSON構成ファイルで指定できます。
var client = new NoSQLClient(
    new NoSQLConfig
    {
        ServiceType = ServiceType.KVStore,
        Endpoint = "myhost:8080"
    });
JSON構成ファイルで同じ構成を指定することもできます。次の内容を含むファイルconfig.jsonを作成します。
{
    "ServiceType": "KVStore",
    "Endpoint": "myhost:8080"
}
その後、このファイルを使用してNoSQLClientインスタンスを作成できます。
varclient = new NoSQLClient("/path/to/config.json");

セキュア・ストアへの接続 :

セキュア・モードでプロキシに接続するには、通信エンドポイントに加えて、ドライバ・ユーザーのユーザー名とパスワードを指定する必要があります。この情報はKVStoreAuthorizationProviderのインスタンスで渡され、次に示す3つの方法のいずれかで指定できます。

ユーザー名とパスワードを直接渡す

ユーザー名とパスワードを直接指定することもできます。パスワードはNoSQLClientインスタンスの存続期間中、メモリーにプレーン・テキストで格納されるため、このオプションは安全性が低下します。パスワードはchar[]として指定されているため、NoSQLClientの使用終了後に消去できます。

ファイル・システムの権限で保護されている別のファイルに資格証明を格納することを選択できます。資格証明ファイルの形式は次のとおりです。
{
    "user":     "<Driver user name>",
    "password": "<Driver user password>"
}
その後、この資格証明ファイルを次のように使用できます。
var client = new NoSQLClient(
    new NoSQLConfig
    {
        Endpoint: 'https://myhost:8081',
        AuthorizationProvider=newKVStoreAuthorizationProvider(
            "path/to/credentials.json")
    });
ドライバ資格証明をセキュアに格納および取得するための独自の資格証明プロバイダを実装できます。ドライバによって資格証明が格納およびロードされる方法を制御するため、これは最も安全なオプションです。資格証明プロバイダは、Task<KVStoreCredentials>を返すデリゲート関数であるため、非同期に実装できます。
var client = new NoSQLClient(
    newNoSQLConfig
    {
        "Endpoint": "https://myhost:8081",
        AuthorizationProvider=newKVStoreAuthorizationProvider(
           async (CancellationToken) => {
                // Retrieve the credentials in a preferred manner.await..........
                returnnewKVStoreCredentials(myUserName, myPassword);
           })
    });

NoSQL接続の取得

Spring Dataアプリケーションでは、NosqlDbConfig Spring Beanを提供するAppConfigクラスを設定する必要があります。NosqlDbConfig Spring Beanは、Oracle NoSQL Databaseへの接続方法を示します。

AbstractNosqlConfigurationクラスを拡張するAppConfigクラスを作成します。これにより、Oracle NoSQL Database SDK for Spring Dataへの接続およびセキュリティ・パラメータが公開されます。

Oracle NoSQL Databaseプロキシへの接続の詳細を含むNosqlDbConfigインスタンス・オブジェクトを返します。このNosqlDbConfigクラスに、@Configurationと@EnableNoSQLRepositoriesの注釈を指定します。@Configuration注釈は、AppConfigクラスが、プログラムの実行前にロードする必要がある構成クラスであることをSpring Data Frameworkに通知します。@EnableNoSQLRepositories注釈は、プログラムをロードし、NosqlRepositoryインタフェースを拡張するリポジトリを検索する必要があることをSpring Data Frameworkに通知します。@Bean注釈は、リポジトリをインスタンス化するために必要です。

NosqlDBConfigクラスのインスタンスを返すnosqlDbConfig @Beanの注釈付きメソッドを作成します。NosqlDBConfigインスタンス・オブジェクトは、Oracle NoSQL Databaseを認証するためにSpring Data Frameworkで使用されます。

StoreAccessTokenProviderクラスを使用して、Oracle NoSQL Databaseに接続して認証するようにSpring Data Frameworkを構成できます。セキュアでないアクセス権のあるOracle NoSQL DatabaseプロキシのURLを指定する必要があります。StoreAccessTokenProviderクラスの詳細は、SDK for Spring Data APIリファレンスのStoreAccessTokenProviderに関する項を参照してください。
import com.oracle.nosql.spring.data.config.AbstractNosqlConfiguration;
import com.oracle.nosql.spring.data.config.NosqlDbConfig;
import com.oracle.nosql.spring.data.repository.config.EnableNosqlRepositories;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
import oracle.nosql.driver.kv.StoreAccessTokenProvider;
 
@Configuration
 
@EnableNosqlRepositories
 
public class AppConfig extends AbstractNosqlConfiguration {
    @Bean
    public NosqlDbConfig nosqlDbConfig() {
        AuthorizationProvider authorizationProvider;
        authorizationProvider = new StoreAccessTokenProvider();
 
        /* Provide the hostname and port number of the NoSQL cluster.*/
        return new NosqlDbConfig("http://<host:port>", authorizationProvider);
    }
}
次の例では、前述の例を変更してセキュアなOracle NoSQL Databaseストアに接続します。 
import com.oracle.nosql.spring.data.config.AbstractNosqlConfiguration;
import com.oracle.nosql.spring.data.config.NosqlDbConfig;
import com.oracle.nosql.spring.data.repository.config.EnableNosqlRepositories;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
import oracle.nosql.driver.kv.StoreAccessTokenProvider;
 
@Configuration
 
@EnableNosqlRepositories
public class AppConfig extends AbstractNosqlConfiguration {
 
    @Bean
    public NosqlDbConfig nosqlDbConfig() {
        AuthorizationProvider authorizationProvider;
        /* Provide the username and password of the NoSQL cluster.*/
        authorizationProvider = new StoreAccessTokenProvider(user, password);
 
        /* Provide the hostname and port number of the NoSQL cluster.*/
        return new NosqlDbConfig("http://<host:port>", authorizationProvider);
    }
}