NoSQLハンドルの取得

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

非セキュア・データ・ストア

アプリケーションで、Oracle NoSQL Databaseプロキシへの接続となるNoSQLHandleを作成します。このNoSQLHandleを使用して、Oracle NoSQL Database表にアクセスし、Oracle NoSQL Database操作を実行できます。

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

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

非セキュア・プロキシに接続するNoSQLHandleを作成する例を次に示します。

// Service URL of the proxy
String endpoint = "http://<proxy_host>:<proxy_http_port>";

// 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);

説明

• proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したホストと一致している必要があります。
• proxy_http_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に構成したhttpポートと一致する必要があります。

ハンドルは、最初にborneo.NoSQLHandleConfigインスタンスを作成して、通信エンドポイント、認可情報、およびハンドル構成のデフォルト値を構成することで作成されます。

非セキュアなOracle NoSQL DatabaseのNoSQLHandleを取得する例:

from borneo import NoSQLHandle, NoSQLHandleConfig
from borneo.kv import StoreAccessTokenProvider
endpoint = 'http://<proxy_host>:<proxy_http_port>'
# 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)

説明

• proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したホストと一致している必要があります。
• proxy_http_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に構成したhttpポートと一致する必要があります。

goアプリケーションをデータ・ストアに接続する最初のステップは、サービスへのリクエストの送信に使用するnosqldb.Clientハンドルを作成することです。この場合、Endpoint構成パラメータが、NoSQLプロキシ・ホストおよびポートの場所を指す必要があります。

cfg:= nosqldb.Config{
    Mode:     "onprem",
    Endpoint: "http://<proxy_host>:<proxy_http_port>",
}
client, err:=nosqldb.NewClient(cfg)
...

説明

• proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したホストと一致している必要があります。
• proxy_http_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に構成したhttpポートと一致する必要があります。

NoSQLClientクラスは、サービスへのメイン・アクセス・ポイントを表します。NoSQLClientのインスタンスを作成するには、適切な構成情報を指定する必要があります。

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

次のコードを使用してプロキシに接続します。

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

説明

• proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したホストと一致している必要があります。
• proxy_http_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に構成したhttpポートと一致する必要があります。

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

{
    "serviceType": "KVSTORE",
    "endpoint": "<proxy_host>:<proxy_http_port>",
}

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

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

ノート:

ファイル・パスが指定されている場合、パスは、アプリケーションの現在の作業ディレクトリに対する絶対パスまたは相対パスにすることができます。

クラスNoSQLClientは、サービスへのメイン・アクセス・ポイントを表します。NoSQLClientのインスタンスを作成するには、適切な構成情報を指定する必要があります。

非セキュアなモードでは、ドライバはHTTPプロトコル経由でプロキシと通信します。必要な情報は通信エンドポイントのみです。オンプレミスNoSQLデータベースの場合、エンドポイントはプロキシのURLをhttp://proxy_host:proxy_http_portの形式で指定します。

NoSQLConfigのインスタンスは、直接またはJSON構成ファイルで指定できます。

var client = new NoSQLClient(
    new NoSQLConfig
    {
        ServiceType = ServiceType.KVStore,
        Endpoint = "<proxy_host>:<proxy_http_port>"
    });

説明

• proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したホストと一致している必要があります。
• proxy_http_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に構成したhttpポートと一致する必要があります。

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

{
    "ServiceType": "KVStore",
    "Endpoint": "<proxy_host>:<proxy_http_port>"
}

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

varclient = new NoSQLClient("</path/to/config.json>");

ノート:

ファイル・パスが指定されている場合、パスは、アプリケーションの現在の作業ディレクトリに対する絶対パスまたは相対パスにすることができます。

セキュア・データ・ストア

アプリケーションで、プロキシを介してセキュアなデータ・ストアに接続するためのNoSQLHandleを作成します。NoSQLHandleを使用して、Oracle NoSQL Database表にアクセスし、Oracle NoSQL Database操作を実行できます。プロキシを起動する前に、プロキシがセキュリティ接続をブートストラップできるように、セキュア・データ・ストアにブートストラップ・ユーザー(proxy_user)を作成する必要があります。詳細は、セキュア・データ・ストアのユーザーの作成およびプロキシの起動を参照してください。

セキュア・データ・ストアにアクセスするには、アプリケーションのアプリケーション・ユーザーを作成する必要もあります。アプリケーション・ユーザーはデータ・ストアに接続し、様々なデータベース操作を実行します。

sql-> CREATE USER <appln_user> IDENTIFIED BY "<applnuser_password>"

アプリケーション・ユーザーには、アプリケーションのニーズとセキュリティ上の問題とのバランスを慎重にとりながら、最小権限アクセスに基づいたロールを付与する必要があります。詳細は、権限およびロールの構成を参照してください。

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

Javaアプリケーションの最初のステップは、セキュア・データ・ストアにリクエストを送信するために使用されるNoSQLHandleを作成することです。このハンドルは、資格証明およびその他の認証情報を使用して構成されます。

次のステップを使用して、セキュア・データ・ストアに接続できます。

1. 前述のように、セキュア・プロキシを介してデータ・ストアにアクセスするアプリケーション・ユーザー(appln_user)を作成します。
2. Oracle NoSQL Database Javaドライバをアプリケーションのクラスパスにインストールします。
3. セキュア・アクセスの場合は、パラメータ化されたコンストラクタを使用してStoreAccessTokenProviderクラスのインスタンスを作成し、それを使用するようにNoSQLハンドルを構成します。次のコードを使用してプロキシに接続します。

   String endpoint = "https://<proxy_host>:<proxy_https_port>";
   StoreAccessTokenProvider atProvider = 
       new StoreAccessTokenProvider("<appln_user>","<applnuser_password>".toCharArray());
   NoSQLHandleConfig config = new NoSQLHandleConfig(endpoint);
   config.setAuthorizationProvider(atProvider);
   NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);

   説明
   • proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したプロキシ・ホストと一致する必要があります。
   • proxy_https_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に設定したプロキシhttpsポートと一致する必要があります。
   • appln_userは、セキュア・ストアに接続するために作成されたユーザーです。これは、前述の項で作成したユーザーと一致する必要があります。
   • applnuser_passwordは、appln_userのパスワードです。
4. プロキシのSSL証明書を含むトラスト・ストアの詳細は、次の2つの方法のいずれかで指定できます。
   次に示すように、Javaコードの一部として設定できます。

   /* the trust store containing SSL cert for the proxy */ 
   System.setProperty("javax.net.ssl.trustStore", trustStore);
   if (trustStorePassword != null) {     
      System.setProperty("javax.net.ssl.trustStorePassword",trustStorePassword); 
   } 

   または、次のコマンドを使用して、アプリケーション・プログラムを起動し、driver.trustファイルのパスをJavaトラスト・ストアに設定できます。これは、プロキシがcertificate.pemファイルおよびkey-pkcs8.pemファイルを使用してすでに設定されているため必要となります。

   java -Djavax.net.ssl.trustStore=<fullpath_driver.trust> \
   -Djavax.net.ssl.trustStorePassword=<password of driver.trust> \
   -cp .:lib/nosqldriver.jar application_program

   driver.trustには、certificate.pemまたはrootCA.crt証明書が含まれます。証明書certificate.pemが、JAVA_HOME/jre/lib/security/cacertsにリストされている信頼できるCAによって署名されたチェーンに含まれている場合は、JavaコマンドでJava環境パラメータ-Djavax.net.ssl.trustStoreを追加する必要はありません。

ハンドルは、最初にborneo.NoSQLHandleConfigインスタンスを作成して、通信エンドポイント、認可情報、およびハンドル構成のデフォルト値を構成することで作成されます。

次のステップを使用して、セキュア・データ・ストアに接続できます。

1. 前述のように、セキュア・プロキシを介してデータ・ストアにアクセスするアプリケーション・ユーザー(appln_user)を作成します。
2. セキュア・ストアを実行する場合は、REQUESTS_CA_BUNDLE環境変数を使用して証明書パスを指定する必要があります。

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

   またはborneo.NoSQLHandleConfig.set_ssl_ca_certs()。
3. 次のコードを使用してプロキシに接続します。

   from borneo import NoSQLHandle, NoSQLHandleConfig
   from borneo.kv import StoreAccessTokenProvider
   endpoint = 'https://<proxy_host>:<proxy_https_port>'
   # Create the AuthorizationProvider for a secure store:
   ap = StoreAccessTokenProvider(<appln_user>, <applnuser_password>)
   # 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)

   説明
   • proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したプロキシ・ホストと一致する必要があります。
   • proxy_https_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に設定したプロキシhttpsポートと一致する必要があります。
   • appln_userは、セキュア・ストアに接続するために作成されたユーザーです。これは、前述の項で作成したユーザーと一致する必要があります。
   • applnuser_passwordは、appln_userのパスワードです。

Oracle NoSQL Database goアプリケーションでの最初のステップは、サービスへのリクエストの送信に使用されるnosqldb.Clientハンドルを作成することです。このハンドルは、資格証明およびその他の認証情報を使用して構成されます。

次のステップを使用して、セキュア・データ・ストアに接続できます。

1. 前述のように、セキュア・プロキシを介してデータ・ストアにアクセスするアプリケーション・ユーザー(appln_user)を作成します。
2. 次のコードを使用してプロキシに接続します。

   import (
       "fmt"     
       "github.com/oracle/nosql-go-sdk/nosqldb"
       "github.com/oracle/nosql-go-sdk/nosqldb/httputil"
   )
   ...cfg:= nosqldb.Config{
       Endpoint: "https://<proxy_host>:<proxy_https_port>",
       Mode:     "onprem",
       Username: "<appln_user>",
       Password: "<applnuser_password>",
      },
       // Specify the CertPath and ServerName
       // ServerName is used to verify the hostname for self-signed certificates.
       // This field is set to the "CN" subject value from the certificate specified by CertPath.
       HTTPConfig: httputil.HTTPConfig{
          CertPath: "<fully_qualified_path_to_cert>",
          ServerName: "<server_name>", 
       },
   }
   client, err:=nosqldb.NewClient(cfg)
   iferr!=nil {
       fmt.Printf("failed to create a NoSQL client: %v\n", err)
       return
   }
   deferclient.Close()
   // Perform database operations using client APIs.
   // ...

   説明
   • proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したプロキシ・ホストと一致する必要があります。
   • proxy_https_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に設定したプロキシhttpsポートと一致する必要があります。
   • appln_userは、セキュア・ストアに接続するために作成されたユーザーです。これは、前述の項で作成したユーザーと一致する必要があります。
   • applnuser_passwordは、appln_userのパスワードです。

NoSQLClientのインスタンスを作成するには、適切な構成情報を指定する必要があります。次のステップを使用して、セキュア・データ・ストアに接続できます。

1. 前述のように、セキュア・プロキシを介してデータ・ストアにアクセスするアプリケーション・ユーザー(appln_user)を作成します。
2. セキュア・モードでは、プロキシにSSL証明書と秘密キーが必要です。プロキシ証明書のルート認証局(CA)が信頼できるルートCAのいずれでもない場合、ドライバはプロキシに接続するために証明書チェーン・ファイル(certificates.pemなど)またはルートCA証明書ファイル(rootCA.crtなど)を必要とします。かわりに自己署名証明書を使用している場合、ドライバは接続するために自己署名証明書の証明書ファイル(certificate.pemなど)を必要とします。

   証明書または証明書チェーンをドライバに提供するには、コードで指定するか、環境変数として設定するかの2つのオプションがあります。

   NoSQLハンドルの作成時に、httpOptプロパティを使用して証明書を指定できます。httpOpt内では、次に示すように、caプロパティを使用してCAを指定できます。

   const client = new NoSQLClient({ .....,     
     httpOpt: {                     
       ca: fs.readFileSync(<caCertFile>)                                    
     },..... 
   });

   ノート:

   ファイル・パスが指定されている場合、パスは、アプリケーションの現在の作業ディレクトリに対する絶対パスまたは相対パスにすることができます。
   または、アプリケーションを実行する前に、次に示すように環境変数NODE_EXTRA_CA_CERTSを設定します。

   export NODE_EXTRA_CA_CERTS="<fully_qualified_path_to_driver.trust>"

   ここで、driver.trustは、CAの証明書チェーン・ファイル(certificates.pem)、ルートCAの証明書(rootCA.crt)または自己署名証明書(certificate.pem)のいずれかです。
3. セキュア・モードでプロキシに接続するには、通信エンドポイントに加えて、ドライバ・ユーザーのユーザー名とパスワードを指定する必要があります。この情報は、kvstoreプロパティのConfig#authオブジェクトに渡され、次に説明する3つの方法のいずれかで指定できます。
   ユーザー名とパスワードを直接指定することもできます。

   const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
   const client = new NoSQLClient({
       endpoint: 'https://<proxy_host>:<proxy_https_port>',
       auth: {
           kvstore: {
               user: '<appln_user>',
               password: '<applnuser_password>'
           }
       }
   });

   説明

   • proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したプロキシ・ホストと一致する必要があります。
   • proxy_https_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に設定したプロキシhttpsポートと一致する必要があります。
   • appln_userは、セキュア・ストアに接続するために作成されたユーザーです。これは、前述の項で作成したユーザーと一致する必要があります。
   • applnuser_passwordは、appln_userのパスワードです。

   パスワードはメモリーにプレーン・テキストで格納されるため、このオプションは安全性が低下します。
   資格証明は、ファイル・システム権限で保護されている別のファイルに格納することを選択できるため、資格証明はメモリーに格納されませんが、ログインが必要な場合にのみこのファイルからアクセスされるため、以前のオプションよりも安全です。資格証明ファイルの形式は次のとおりです。

   {
       "user":     "<appln_user>",
       "password": "<applnuser_password>"
   }

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

   const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
   const client = new NoSQLClient({
       endpoint: 'https://<proxy_host>:<proxy_https_port>',
       auth: {
           kvstore: {
               credentials: '<path/to/credentials.json>'
           }
       }
   });

   ノート:

   ファイル・パスが指定されている場合、パスは、アプリケーションの現在の作業ディレクトリに対する絶対パスまたは相対パスにすることができます。
   NoSQLClientインスタンスの作成に使用される構成ファイルでcredentials.jsonを参照することもできます。

   {
       "endpoint": "https://<proxy_host>:<proxy_https_port>",
       "auth": {
           "kvstore": {
               "credentials": "<path/to/credentials.json>"
           }
       }
   }

   const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
   const client = new NoSQLClient('</path/to/config.json>');

   ノート:

   ファイル・パスが指定されている場合、パスは、アプリケーションの現在の作業ディレクトリに対する絶対パスまたは相対パスにすることができます。

NoSQLClientのインスタンスを作成するには、適切な構成情報を指定する必要があります。次のステップを使用して、セキュア・データ・ストアに接続できます。

1. 前述のように、セキュア・プロキシを介してデータ・ストアにアクセスするアプリケーション・ユーザー(appln_user)を作成します。
2. セキュア・モードでプロキシに接続するには、通信エンドポイントに加えて、ドライバ・ユーザーのユーザー名とパスワードを指定する必要があります。この情報はKVStoreAuthorizationProviderのインスタンスで渡され、次に説明するいずれかの方法で指定できます。
   ユーザー名とパスワードを直接指定することもできます。

   var client = new NoSQLClient(
       new NoSQLConfig
       {
           Endpoint = "https://<proxy_host>:<proxy_https_port>",
           AuthorizationProvider = new KVStoreAuthorizationProvider(
               <appln_user>, // user name as string
               <applnuser_password>) // password as char[]
       });

   説明

   • proxy_hostは、プロキシ・サービスを実行しているマシンのホスト名です。これは、以前に構成したプロキシ・ホストと一致する必要があります。
   • proxy_https_portは、プロキシがリクエストをリスニングしているポートです。これは、以前に設定したプロキシhttpsポートと一致する必要があります。
   • appln_userは、セキュア・ストアに接続するために作成されたユーザーです。これは、前述の項で作成したユーザーと一致する必要があります。
   • applnuser_passwordは、appln_userのパスワードです。

   パスワードはNoSQLClientインスタンスの存続期間中、メモリーにプレーン・テキストで格納されるため、このオプションは安全性が低下します。パスワードはchar[]として指定されているため、NoSQLClientの使用終了後に消去できます。
   資格証明は、ファイル・システム権限で保護されている別のファイルに格納することを選択できるため、資格証明はメモリーに格納されませんが、ストアへのログインが必要な場合にのみこのファイルからアクセスされるため、前のオプションよりも安全です。資格証明ファイルの形式は次のとおりです。

   {
       "UserName": "<appln_user>",
       "Password": "<applnuser_password>"
   }

   その後、この資格証明ファイルを次のように使用できます。

   var client = new NoSQLClient(
       new NoSQLConfig
       {
           Endpoint: 'https://<proxy_host>:<proxy_https_port>',
           AuthorizationProvider = new KVStoreAuthorizationProvider(
               "<path/to/credentials.json>")
       });

   ノート:

   ファイル・パスが指定されている場合、パスは、アプリケーションの現在の作業ディレクトリに対する絶対パスまたは相対パスにすることができます。
   NoSQLClientインスタンスの作成に使用されるJSON構成ファイルでcredentials.jsonを参照することもできます。

   {
       "Endpoint": "https://<proxy_host>:<proxy_https_port>",
       "AuthorizationProvider": {
           "AuthorizationType": "KVStore",
           "CredentialsFile": "<path/to/credentials.json>"
       }
   }

   var client = new NoSQLClient("</path/to/config.json>");

   config.jsonでは、認可プロバイダは、KVStoreAuthorizationProviderのプロパティと、認可プロバイダのタイプを示す追加のAuthorizationTypeプロパティ(セキュアなオンプレミス・ストアの場合はKVStore)を持つJSONオブジェクトとして表されることに注意してください。

プロキシ証明書の証明書チェーンが既知のCAの1つをルートとしていない場合は、ドライバに信頼できるルート証明書を提供する必要があります。提供された証明書は、カスタムCAまたは自己署名プロキシ証明書のいずれかです。これは、TrustedRootCertificateFileプロパティを使用して指定する必要があります。このプロパティは、1つ以上の信頼できるルート証明書を含むPEMファイルにファイル・パス(絶対パスまたは相対パス)を設定します(このファイルでは複数のルートが許可されます)。このプロパティは、NoSQLConfigのConnectionOptionsの一部として指定します。

var client = new NoSQLClient(
    new NoSQLConfig {
       Endpoint: 'https://<proxy_host>:<proxy_https_port>',
       AuthorizationProvider = new KVStoreAuthorizationProvider( "<path/to/credentials.json>"),
       ConnectionOptions: { "TrustedRootCertificateFile": "<path/to/certificates.pem>" }
});

ノート:

ファイル・パスが指定されている場合、パスは、アプリケーションの現在の作業ディレクトリに対する絶対パスまたは相対パスにすることができます。