Oracle NoSQL Database Analytics Integratorの実行

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

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

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

例1: Oracle Cloudコンピュート・インスタンスからユーティリティを実行し、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 Object StorageおよびOracle Autonomous AI Lakehouse)を指定します。

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

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

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

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

パラメータ名	指定したセクション	セクションの詳細
インスタンス・プリンシパルを使用	nosqlstore(オプション) objectstore(オプション)	次の条件が満たされた場合、useInstancePrincipalエントリをブール値trueとして指定できます。 ユーティリティは、Oracle Cloud Computeインスタンスから実行されます。 構成中のセクションはデータベース・セクションではありません コンピュート・インスタンスは、Instance Principalとして、構成中のセクションで参照されているリソースに対してアクションを実行する権限が付与されます 資格証明エントリが指定されていない useInstancePrincipalエントリにtrueが指定され、資格証明エントリも指定されている場合、資格証明エントリが優先され、そのエントリの値で参照されるユーザー資格証明が、関連付けられたリソースと対話するために使用されます。 ノート: Oracle Autonomous AI LakehouseでホストされるAutonomous AI Databaseにはユーザー資格証明が必要であるため、データベース・セクションでユーザー資格証明を指定する必要があります。
コンパートメント	nosqlstore(オプション) objectstore(オプション)	useInstancePrincipalエントリにtrueが指定されている場合は、そのリソースを含むコンパートメントのOCIDも指定する必要があります。 useInstancePrincipalエントリにfalseが指定されているか、資格証明エントリが指定されている場合、コンパートメント・エントリはオプションです。ただし、資格証明エントリによって参照されるファイルで指定する必要があります。
credentials	nosqlstore(オプション) objectstore(オプション) データベース(必須)	資格証明エントリは、すべての状況でデータベース・セクションに必要です。次の1つ以上の状況では、nosqlstoreおよびobjectstoreセクションで必須です。 Either the utility will be executed from outside the Oracle Cloud, or it will be executed from an Oracle Cloud Compute Instance that is not an Instance Principal useInstancePrincipalエントリが指定されていないか、falseに設定されています。 このエントリに指定する値は、関連付けられたリソースと安全に対話するために使用できるユーザー資格証明を指定するローカル・ファイル・システム上のファイルを参照する必要があります。
資格証明プロファイル	nosqlstore(オプション) objectstore(オプション) データベース(オプション)	credentialsProfileエントリは各セクションでオプションであり、指定されている場合でも、対応する資格証明エントリも指定されている場合にのみ適用されます。
表	nosqlstore(必須)	テーブル・エントリは必須であり、nosqlstoreセクションで指定する必要があります。このエントリの値は、名前のカンマ区切りリストで構成される文字列です。各名前は、Oracle Autonomous AI Lakehouseにコンテンツを取得してコピーする必要があるNoSQL Database Cloud Service内の表の名前を参照します。
読取りユニット率	nosqlstore(オプション)	readUnitsPercentエントリはオプションであり、nosqlstoreセクションでのみ適用可能です。このエントリの値は、コンマで区切られた整数のリストで構成される文字列です。1から100の間は、対応する表からデータを取得するときに消費できる読取りユニットの割合を表します。 このエントリを使用すると、表エントリで参照される各表に異なる読取りユニット・パーセンテージを指定できます。リストの最初のパーセンテージは表リストの最初の表に対応し、2番目のパーセンテージは2番目の表に対応し、同様に続きます。このリストのパーセント数が、テーブルのリスト内のテーブルの数と等しくなる必要はありません。デフォルト値の90%は、このリストに対応するパーセンテージを持たない表のリスト内の表に割り当てられます。 たとえば、テーブルエントリに4つのテーブル名が指定されているが、readUnitsPercentエントリが値「50,80」に設定されているとします。この場合、最初の表のデータは、使用可能な読取りユニットの50%を使用して取得されますが、2番目の表からデータを取得する際には、読取りユニットの80%が使用されます。最後に、残りの2つの表について、これらの各表からデータを取得するときに読取りユニットの90パーセント(デフォルト)が使用されます。
リクエストタイムアウト	nosqlstore(オプション)	requestTimeoutMsエントリはオプションで、nosqlstoreセクションでのみ適用できます。このエントリの値は、正の整数のカンマ区切りリストで構成される文字列です。各整数は、対応する表に対してデータ取得リクエストが完了するまでのミリ秒数を表します。 このエントリを使用すると、表エントリで参照される各表に異なるタイムアウト値を指定できます。このエントリが指定されていない場合、またはこのエントリが表のサブセットのみのタイムアウトを指定した場合、デフォルト値の5000が残りの表に割り当てられます。
bucket	objectstore(必須)	バケット・エントリは必須であり、オブジェクト・ストア・セクションで指定する必要があります。このエントリの値は、OCIオブジェクト・ストレージ・バケットの名前を表す文字列で、このバケットには、NoSQL表から取得したデータがユーティリティによってコピーされます。
圧縮	objectstore(オプション)	圧縮エントリはオプションで、objectstoreセクションにのみ適用できます。このエントリに指定された値は、nosqlstoreで指定された表からのデータの取得方法を表す文字列です。これが設定されている場合、表データはオブジェクト・ストレージにコピーされるときに圧縮されます。このエントリに指定する値は、次のいずれかである必要があります。 snappy - Snappy圧縮の場合 gzip - gzip圧縮用 none - ObjectStorageにコピーされた表データを圧縮しません。 ノート: 圧縮エントリが指定されていない場合は、snappy圧縮が実行されます。
databaseName	データベース(必須)	dabaseNameエントリは必須であり、データベース・セクションで指定する必要があります。このエントリは、値がOracle Autonomous AI Lakehouse Cloud Serviceで作成されたデータベースの名前である文字列です。
データベース・ユーザー	データベース(オプション)	databaseUserエントリはオプションであり、データベース・セクションで指定する必要があります。このエントリは、値がdabaseNameエントリで指定されたAutonomous AI Databaseのユーザー・アカウントの名前である文字列です。このエントリを指定しない場合は、コマンドラインで値を指定するよう求められます。
データベースウォレット	データベース(必須)	databaseWalletエントリは必須であり、データベース・セクションで指定する必要があります。このエントリは、値が、構成ファイルのdatabaseUserエントリで指定されたAutonomous AI 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 AI DatabaseのOCID
dbms資格証明名	これは、Oracle Autonomous AI Lakehouseデータベースがオブジェクト・ストレージでの認証に使用する資格証明の名前です。これは、OCI$RESOURCE_PRINCIPALという名前(リソース・プリンシパル認証を使用する場合)か、またはDBMS_CLOUD.CREATE_CREDENTIALプロシージャがユーザーまたはシステム管理者によって実行されたときに作成されるAUTH_TOKEN資格証明の名前(たとえば、NOSQLADWDB_OBJ_STORE_CREDENTIAL)です。

ツールの実行

必要なOracle Cloudサービス(NoSQL Database、Object StorageおよびOracle Autonomous AI Lakehouse)を使用するためのすべての要件が完了し、有効な構成ファイルが作成された後、コマンドラインでコマンドを入力するだけで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 Autonomous Databaseでのデータの確認
• Oracle Analyticsでのデータの確認
• Oracle NoSQL Database Analytics Integratorの既知の問題