NoSQLハンドルの取得

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

• Java
• Python
• Go
• Node.js
• C#

アプリケーションで、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クラスに提供して、適切な接続を確立します。

様々なクラスおよびメソッドの詳細は、Oracle NoSQL Java SDK APIリファレンスを参照してください。

非セキュア・プロキシに接続する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ユーザーのパスワードです。

ユーザーは、セキュアなプロキシにアクセスするために、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()を使用してクローズする必要があります。ハンドルはスレッドセーフで、共有するためのものです。

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

非セキュアなストアを実行している場合は、httpリクエストを使用し、localhost:8080を使用します。

非セキュアな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'
# Create the AuthorizationProvider for a not secure store:
#
ap = StoreAccessTokenProvider()
#
# create a configuration object
#
config = NoSQLHandleConfig(endpoint).set_authorization_provider(ap)
#
# create a handle from the configuration object
#
handle = NoSQLHandle(config)

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

セキュア・ストアを実行する場合は、REQUESTS_CA_BUNDLE環境変数を使用して証明書パスを指定する必要があります。

$ export
    REQUESTS_CA_BUNDLE=<path-to-certificate>/certificate.pem:$REQUESTS_CA_BUNDLE

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

様々なクラスおよびメソッドの詳細は、Oracle NoSQL Python SDK APIリファレンスを参照してください。

セキュアなOracle NoSQL DatabaseのNoSQLハンドルを取得する例:

from borneo import NoSQLHandle, NoSQLHandleConfig
from borneo.kv import StoreAccessTokenProvider
#
# 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 goアプリケーションでの最初のステップは、サービスへのリクエストの送信に使用されるnosqldb.Clientハンドルを作成することです。そのクライアント・ハンドルのインスタンスは、複数のゴールーチンによる同時使用でも安全であり、マルチゴールーチン・アプリケーションで共有されることを目的としています。このハンドルは、資格証明およびその他の認証情報を使用して構成されます。

非セキュアなオンプレミス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)

様々なクラスおよびメソッドの詳細は、Oracle NoSQL Go SDK APIリファレンスを参照してください。

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

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

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

たとえば、構成JavaScriptオブジェクトを使用する場合:

import { NoSQLClient, ServiceType } from 'oracle-nosqldb';
const client = new NoSQLClient({
    serviceType: ServiceType.KVSTORE,
    endpoint: '<myhost>:8080'
});

ノート:

すべてのコード・サンプルにおいて、myhost:8080を、エンドポイントの実際のシステム/ポートに置き換えます。

同じ構成をファイルに格納することもできます。次の内容を含むファイルconfig.jsonを作成します。

{
    "serviceType": "KVSTORE",
    "endpoint": "myhost:8080",
}

その後、このサンプル・ファイルを使用してNoSQLClientインスタンスを作成できます:

import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient('/path/to/config.json');

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

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

• ユーザー名とパスワードを直接渡す ユーザー名とパスワードを直接指定できます。パスワードはメモリーにプレーン・テキストで格納されるため、このオプションは安全性が低下します。

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

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

  ファイル・システムの権限で保護されている別のファイルに資格証明を格納することを選択できます。資格証明ファイルは、次の形式である必要があります:

  {
      "user":     "<Driver user name>",
      "password": "<Driver user password>"
  }

  その後、このサンプル資格証明ファイルを次のように参照できます:

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

• 独自のKVStoreCredentialsProviderの作成:

  KVStoreCredentialsProviderインタフェースのインスタンスとして、ドライバ資格証明をセキュアに格納し取得するための独自の資格証明プロバイダを実装できます。loadCredentials関数は、Promiseを返すため、非同期関数として実装できます。

  import { NoSQLClient } from 'oracle-nosqldb';
  
  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);
           })
    });

すべてのクラスおよびメソッドの詳細は、Oracle NoSQL Dotnet SDK APIリファレンスを参照してください。