Oracle NoSQL Database Analytics Integratorの実行

Oracle NoSQL Database Analytics Integratorを実行するステップ。

インテグレータ用の構成ファイルの作成

Oracle NoSQL Database Analytics Integratorを実行する前に、まず構成ファイルを作成する必要があります。この構成ファイルは、ユーティリティの起動時に使用されます。次の例に示すように、構成ファイルにはJSON形式のエントリが必要です。次に、2つのサンプル構成ファイルを示します。次で使用されるすべてのパラメータが必須ではありません。次の表では、この例で使用されているすべてのパラメータについて説明し、オプションまたは必須の場合は強調表示します。

例1: Oracle Cloud Computeインスタンスからユーティリティを実行し、Instance Principalを使用して認証します。

{
    "nosqlstore": {
        "type" : "nosqldb_cloud",
        "endpoint" : "us-ashburn-1",
        "useInstancePrincipal" : true,
        "compartment" : <ocid.of.compartment.containing.nosql.tables>,
        "table" : <tableName1,tableName2,tableName3>,
        "readUnitsPercent" : "90,90,90",
        "requestTimeoutMs" : "5000"
    },
    "objectstore" : {
        "type" : "object_storage_oci",
        "endpoint" : "us-ashburn-1",
        "useInstancePrincipal" : true,
        "compartment" : <ocid.of.compartment.containing.bucket>,
        "bucket" : <bucket-name-objectstorage>,
        "compression" : "snappy"
    },
    "database": {
        "type" : "database_cloud",
        "endpoint" : "us-ashburn-1",
        "credentials" : "/home/opc/.oci/config",
        "credentialsProfile" : <profile-for-adw-auth>,
        "databaseName" : <database-name>,
        "databaseUser" : "ADMIN",
        "databaseWallet"” : <path-where-wallet-unzipped>

    }
}

例2:独自のユーザー資格証明を使用して認証するか、Oracle Cloudの外部から実行しているため、Instance Principal認証は使用できません。

{
    "nosqlstore": {
        "type" : "nosqldb_cloud",
        "endpoint" : "us-ashburn-1",
        "credentials" : "/home/opc/.oci/config",
        "credentialsProfile" : <nosqldb-user-credentials>,
        "table" : <tableName1,tableName2,tableName3>,
        "readUnitsPercent" : "90,90,90",
        "requestTimeoutMs" : "5000"
    },
    "objectstore" : {
        "type" : "object_storage_oci",
        "endpoint" : "us-ashburn-1",
        "credentials" : "/home/opc/.oci/config",
        "credentialsProfile" : <objectstorage-user-credentials>,
        "bucket" : <bucket-name-objectstorage>,
        "compression" : "snappy"
    },
    "database": {
        "type" : "database_cloud",
        "endpoint" : "us-ashburn-1",
        "credentials" : "/home/opc/.oci/config",
        "credentialsProfile" : <adw-user-credentials>,
        "databaseName" : <database-name>,
        "databaseUser" : "ADMIN",
        "databaseWallet" : <path-where-wallet-unzipped>
    } 
   "abortOnError" : false
}

構成は、nosqlstore、objectstoreおよびdatabaseの3つのセクションに分かれており、そのエントリは、ユーティリティが各クラウド・サービスとどのように相互作用するかを指定するために使用されます(NoSQL Cloud Service、Oracle ObjectStorageおよびOracle Autonomous Data Warehouse)。

3つのセクションすべてに共通のパラメータがあります。

表- すべてのセクションの共通パラメータ

パラメータ名パラメータの詳細

タイプ現在、このパラメータには、nosqldb_cloud (nosqlstoreセクションの場合)、object_storage_oci (オブジェクトストア・セクションの場合)およびdatabase_cloud (データベース・セクションの場合)の3つの値のいずれかを指定できます。

endpoint このエントリの値は、関連付けられたリソースが配置されているリージョンに設定する必要があります。このエントリに指定する値は、リージョンのAPIエンドポイントまたはリソースのリージョン識別子のいずれかです。たとえば、各リソースが米国東部(アッシュバーン)リージョンにある場合、各セクションのエンドポイント・エントリは、リージョンの識別子(US-ashburn-1)または目的のサービスのリージョンのAPIエンドポイントを使用して指定できます。

パラメータ名	パラメータの詳細
タイプ	現在、このパラメータには、`nosqldb_cloud` (nosqlstoreセクションの場合)、`object_storage_oci` (オブジェクトストア・セクションの場合)および`database_cloud` (データベース・セクションの場合)の3つの値のいずれかを指定できます。
endpoint	このエントリの値は、関連付けられたリソースが配置されているリージョンに設定する必要があります。このエントリに指定する値は、リージョンのAPIエンドポイントまたはリソースのリージョン識別子のいずれかです。たとえば、各リソースが米国東部(アッシュバーン)リージョンにある場合、各セクションのエンドポイント・エントリは、リージョンの識別子(US-ashburn-1)または目的のサービスのリージョンのAPIエンドポイントを使用して指定できます。

表- 構成ファイルのパラメータ

パラメータ名	指定されたセクション	セクションの詳細
useInstancePrincipal	nosqlstore(オプション) objectstore(オプション)	次の条件を満たす場合は、useInstancePrincipalエントリをブール値trueとして指定できます。ユーティリティは、Oracle Cloud Computeインスタンスから実行されます。構成されるセクションは、データベース・セクションではありませんコンピュート・インスタンスは、Instance Principalとして、構成中のセクションで参照されているリソースに対してアクションを実行する権限があります The credentials entry is not specified useInstancePrincipalエントリにtrueが指定され、資格証明エントリも指定されている場合、資格証明エントリが優先され、そのエントリの値で参照されるユーザー資格証明が関連リソースとの対話に使用されます。ノート: ADWでホストされるAutonomous Databaseではユーザー資格証明が必要なため、データベース・セクションでユーザー資格証明を指定する必要があります。
コンパートメント	nosqlstore(オプション) objectstore(オプション)	useInstancePrincipalエントリにtrueが指定されている場合は、そのリソースを含むコンパートメントのOCIDも指定する必要があります。 useInstancePrincipalエントリにfalseが指定されている場合、または資格証明エントリが指定されている場合、コンパートメント・エントリはオプションです。ただし、資格証明エントリによって参照されるファイルに指定する必要があります。
credentials	nosqlstore(オプション) objectstore(オプション) データベース(必須)	資格証明エントリは、すべての状況でデータベース・セクションに必要です。これは、次の1つ以上の状況でnosqlstoreおよびobjectstoreセクションに必要です。ユーティリティはOracle Cloudの外部から実行されるか、Instance PrincipalではないOracle Cloud Computeインスタンスから実行されます。 useInstancePrincipalエントリが指定されていないか、falseに設定されています。このエントリに指定する値は、関連付けられたリソースとの安全な対話に使用できるユーザー資格証明を指定するローカル・ファイル・システム上のファイルを参照する必要があります。
credentialsProfile	nosqlstore(オプション) objectstore(オプション) データベース(オプション)	credentialsProfileエントリは各セクションでオプションであり、指定されている場合でも、対応する資格証明エントリも指定されている場合にのみ適用されます。
表	nosqlstore(必須)	表エントリは必須であり、nosqlstoreセクションで指定する必要があります。このエントリの値は、名前のカンマ区切りリストで構成される文字列です。各名前は、コンテンツを取得してAutonomous Data Warehouseにコピーする必要があるNoSQL Database Cloud Serviceの表の名前を参照します。
readUnitsPercent	nosqlstore(オプション)	readUnitsPercentエントリはオプションで、nosqlstoreセクションでのみ適用可能です。このエントリの値は、1から100までの整数のカンマ区切りリストで構成される文字列で、対応する表からデータを取得するときに消費できる読取りユニットの割合を表します。このエントリを使用すると、テーブルエントリで参照されるテーブルごとに異なる読み取り単位の割合を指定できます。リスト内の最初の割合はテーブルリスト内の最初のテーブルに対応し、2番目の割合は2番目のテーブルに対応します。このリストの割合が表リスト内の表の数と等しい必要はありません。デフォルト値の90%は、このリストに対応するパーセンテージがない表のリスト内の表に割り当てられます。たとえば、表エントリに4つの表名が指定されているが、readUnitsPercentエントリが値50,80に設定されているとします。この場合、最初の表のデータは使用可能な読取りユニットの50%を使用して取得されますが、2番目の表からデータを取得する場合は読取りユニットの80%が使用されます。最後に、残りの2つの表では、各表からデータを取得する際に、読取りユニットの90%(デフォルト)が使用されます。
requestTimeoutMs	nosqlstore(オプション)	requestTimeoutMsエントリはオプションで、nosqlstoreセクションでのみ適用可能です。このエントリの値は、正整数のカンマ区切りリストで構成される文字列です。各整数は、対応する表のデータ取得リクエストが完了するまでのミリ秒数を表します。このエントリを使用すると、テーブルエントリで参照されるテーブルごとに異なるタイムアウト値を指定できます。このエントリが指定されていない場合、またはこのエントリが表のサブセットのタイムアウトのみを指定する場合、デフォルト値の5000が残りの表に割り当てられます。
bucket	オブジェクトストア(必須)	バケット・エントリは必須であり、オブジェクトストア・セクションで指定する必要があります。このエントリの値は、OCIオブジェクト・ストレージ・バケットの名前を表す文字列で、ユーティリティはNoSQL表から取得したデータをコピーします。
圧縮	objectstore(オプション)	圧縮エントリはオプションであり、オブジェクトストア・セクションにのみ適用されます。このエントリに指定された値は、nosqlstoreで指定された表からデータを取得する方法を表す文字列です。これを設定すると、オブジェクト・ストレージにコピーされるときに表データが圧縮されます。このエントリには、次のいずれかの値を指定します。 snappy - snappy圧縮の場合 gzip - gzip圧縮用 none - ObjectStorageにコピーされた表データを圧縮しません。ノート: 圧縮エントリが指定されていない場合は、snappy圧縮が実行されます。
databaseName	データベース(必須)	dabaseNameエントリは必須であり、データベース・セクションで指定する必要があります。このエントリは、値がOracle Autonomous Data Warehouse Cloud Serviceで作成されたデータベースの名前である文字列です。
databaseUser	データベース(オプション)	databaseUserエントリはオプションであり、データベース・セクションで指定する必要があります。このエントリは、値がdabaseNameエントリで指定されたAutonomous Databaseのユーザー・アカウントの名前である文字列です。このエントリを指定しない場合、コマンドラインで値を指定するように要求されます。
databaseWallet	データベース(必須)	databaseWalletエントリは必須であり、データベース・セクションで指定する必要があります。このエントリは、値が、構成ファイルの`databaseUser`エントリで指定されたAutonomous Databaseユーザー・アカウントからダウンロードされたOracle Walletの内容を含むディレクトリへのファイルシステム・パスである文字列です。
abortOnError	任意	エラー発生時に実行するアクションを指定します。デフォルト値はTRUEです。

ノート:

構成ファイルの各エントリは、section.entryという形式の名前でシステム・プロパティ(-Dnosqlstore.table=tableName1,tableName3など)を設定することで、コマンドラインでオーバーライドできます。エントリがセクション内にない場合、このようなプロパティに使用する名前は、単にエントリ自体の名前になります。たとえば、-DabortOnError=false.この機能は、ユーティリティを定期的に実行するスクリプトをテストまたは記述する場合に便利です。

資格証明ファイルでの構成情報の指定:

Oracle Cloud Infrastructureには、構成ファイルで指定できるユーザー資格証明、テナンシOCIDなどの基本的な構成情報が必要です。この構成ファイルのデフォルトの場所は~/.ociです。この構成ファイルには、ユーザー資格証明の複数のセットを指定できます。

サンプル資格証明ファイルを次に示します。

[DEFAULT]
user=<ocid.of.default.user>
fingerprint=<fingerprint.of.default.user>
key_file=<path.to.default.user.oci.api.private.key.file.pem>
tenancy=<ocid.of.default.user.tenancy>
region=us-ashburn-1
compartment=<ocid.of.default.compartment>

[nosqldb-user-credentials]
user=<ocid.of.nosqldb.user>
fingerprint=<fingerprint.of.nosqldb.user>
key_file=<path.to.nosqldb.user.oci.api.private.key.file.pem>
tenancy=<ocid.of.nosqldb.user.tenancy>
region=us-ashburn-1
compartment=<ocid.of.nosqldb.compartment>

[objectstorage-user-credentials]
user=<ocid.of.objectstorage.user>
fingerprint=<fingerprint.of.objectstorage.user>
key_file=<path.to.objectstorage.user.oci.api.private.key.file.pem>
tenancy=<ocid.of.objectstorage.user.tenancy>
region=us-ashburn-1
compartment=<ocid.of.objectstorage.compartment>

[adw-user-credentials]
user=<ocid.of.adw.user>
fingerprint=<fingerprint.of.adw.user>
key_file=<path.to.adw.user.oci.api.private.key.file.pem>
tenancy=<ocid.of.adw.user.tenancy>
region=us-ashburn-1
compartment=<ocid.of.adw.compartment>
dbmsOcid=<ocid.of.autonomous.database.in.adw>
dbmsCredentialName=<OCI$RESOURCE_PRINCIPAL or NOSQLADWDB_OBJ_STORE_CREDENTIAL>

ノート:

前述の構成ファイルには、nosql-db-user、objectstorage-userおよびadw-userの3つの個別のエントリがあります。これは必須ではなく、DEFAULTプロファイルが1つのみの構成ファイルが存在できます。ただし、DEFAULTプロファイルのすべてのパラメータを組み合せるのではなく、別々のプロファイルを使用することをお薦めします。

表- 資格証明ファイルのパラメータ

パラメータ名	パラメータの詳細
ユーザー	ユーザーのOCID
フィンガープリント	デフォルト・ユーザーのより長い公開キーを識別するために使用される短いバイト・シーケンス
キー・ファイル	デフォルト・ユーザーの秘密キーを含むファイルへのパス/ファイル名
テナンシ	テナンシのOCID
リージョン	リージョンのエンドポイント
コンパートメント	デフォルト・ユーザーのコンパートメント名またはOCID
dbmsOcid	Autonomous DatabaseのOCID
dbmsCredentialName	これは、ADWデータベースがオブジェクト・ストレージでの認証に使用する資格証明の名前で、`OCI$RESOURCE_PRINCIPAL`という名前(リソース・プリンシパル認証の使用を選択した場合)、または`DBMS_CLOUD.CREATE_CREDENTIAL`プロシージャがユーザーまたはシステム管理者(`NOSQLADWDB_OBJ_STORE_CREDENTIAL`など)によって実行されたときに作成されるAUTH_TOKEN資格証明の名前です。

ツールを実行する

必要なOracle Cloudサービス(NoSQL Database、Object StorageおよびAutonomous Data Warehouse)を使用するためのすべての要件が完了し、有効な構成ファイルが作成された後、コマンドラインでコマンドを入力するだけでOracle NoSQL Database Analytics Integratorを実行できます。

インストールディレクトリ (/home/opc/nosqlanalytics-<version>)の下のディレクトリ nosqlanalyticsに移動します。
```
cd /home/opc/nosqlanalytics-1.0.1/nosqlanalytics
```

次のコマンドを使用して、ユーティリティを起動します。構成ファイルoci-nosqlanalytics-config.jsonは、ホーム・ディレクトリ内の.oci ディレクトリの下にあります。

java -Djava.util.logging.config.file=./src/main/resources/logging/java-util-logging.properties
-Dlog4j.configurationFile=file:./src/main/resources/logging/log4j2-analytics.properties
-jar ./lib/nosqlanalytics-1.0.1.jar
-config ~/.oci/oci-nosqlanalytics-config.json

ノート:

実行時に使用されるロガーを構成するシステム・プロパティはオプションです。これらのシステム・プロパティが指定されていない場合、ユーティリティはロギング出力を生成しません。

関連項目

ロギング

Oracle NoSQL Database Analytics Integratorでは、複数のサード・パーティ・ライブラリからソフトウェアが実行され、各ライブラリでは異なるネームスペースを持つ独自のロガー・セットが定義されます。便宜上、Oracle NoSQL Database Analytics Integratorでは、リリースの一部として2つのロギング構成ファイルが提供されます。1つはjava.util.loggingに基づいてロギング・メカニズムを構成し、もう1つはLog4j2に基づいてロガーを構成します。

ノート:

デフォルトでは、ユーティリティで提供されるロガー構成ファイルは、ユーティリティの実行時に最小限の出力を生成するように設計されています。ただし、ユーティリティによって使用される様々なコンポーネントからの詳細な出力を表示する場合は、その動作を分析する特定のロガーのロギング・レベルを上げる必要があります。

タイトルおよび著作権情報

Oracle NoSQL Database Analytics Integratorの実行

Oracle and/or its affiliates.