執行 Oracle NoSQL Database Analytics Integrator

執行 Oracle NoSQL Database Analytics Integrator 的步驟。

建立整合器的組態檔

您必須先建立組態檔，才能執行 Oracle NoSQL Database Analytics Integrator。呼叫公用程式時將會使用此組態檔。組態檔應具有 JSON 格式的項目，如以下範例所示。以下只是兩個範例組態檔。並非所有以下使用的參數都是必要的。下表說明範例中所使用的每個參數，並在其為選擇性或必要時標示。

範例 1：您可以從 Oracle Cloud Compute 執行處理執行公用程式，而且想要使用執行處理主體進行認證。

{
    "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 外部執行，因此無法使用「執行處理主體」認證。

{
    "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、物件存放區和資料庫 - 其項目是用來指定公用程式與每個個別雲端服務互動的方式：NoSQL Cloud Service、Oracle ObjectStorage 和 Oracle Autonomous Data Warehouse。

這三個區段都有一些共同的參數。

表格 - 所有區段的通用參數

參數名稱	參數的詳細資訊
類型	目前，此參數可採用下列三個值之一：`nosqldb_cloud` (適用於 nosqlstore 區段)、`object_storage_oci` (適用於物件存放區區段) 及 `database_cloud` (適用於資料庫區段)。
endpoint	此項目的值必須設為關聯資源所在的區域。指定給此項目的值可以是區域的 API 端點或資源的區域 ID 。例如，如果每個資源都位於美國東部 (阿什本) 區域，則可以使用區域的 ID (US-ashburn-1) 或想要之服務的區域 API 端點來指定每個區段中的端點項目。

表格 - 組態檔中的參數

參數名稱	指定的區段	區段的詳細資料
useInstancePrincipal	nosqlstore (選擇性) objectstore (選擇性)	如果滿足下列條件，可以將 useInstancePrincipal 項目指定為布林值 true：公用程式將從 Oracle Cloud Compute 執行處理執行。目前設定的區段不是資料庫區段運算執行處理已被授權為執行處理主體，可對目前設定之區段中所參照的資源執行動作未指定證明資料項目如果為 useInstancePrincipal 項目指定 true，同時指定證明資料項目，則會優先使用證明資料項目，並使用該項目值中參照的使用者證明資料與關聯的資源互動。附註：必須在資料庫區段中指定使用者證明資料，因為 ADW 中代管的 Autonomous Database 需要它。
區間	nosqlstore (選擇性) objectstore (選擇性)	如果為 useInstancePrincipal 項目指定 true，則也必須指定包含該資源之區間的 OCID。如果為 useInstancePrincipal 項目指定 false 或指定證明資料項目，則區間項目是選擇性的；雖然必須在證明資料項目參照的檔案中指定。
credentials - 證明資料	nosqlstore (選擇性) objectstore (選擇性) 資料庫 (必要)	在所有情況下，資料庫區段中都需要證明資料項目。在下列一或多個情況中，nosqlstore 和 objectstore 區段是必要的：公用程式將會從 Oracle Cloud 外部執行，或是從不是執行處理主體的 Oracle Cloud Compute 執行處理執行未指定 useInstancePrincipal 項目或設為 false。指定給此項目的值必須參照本機檔案系統上的檔案，該檔案指定可用來安全地與關聯資源互動的使用者證明資料。
credentialsProfile	nosqlstore (選擇性) objectstore (選擇性) 資料庫 (選擇性)	每個區段中的 credentialsProfile 項目都是選擇性的，即使已指定，也只會在同時指定對應的證明資料項目時套用。
表格	nosqlstore (必要)	必須輸入表格項目，而且必須在 nosqlstore 區段中指定。此項目的值是由以逗號區隔的名稱清單所組成的字串，其中每個名稱都參照 NoSQL Database Cloud Service 中應擷取內容並複製到 Autonomous Data Warehouse 的表格名稱。
readUnitsPercent	nosqlstore (選擇性)	readUnitsPercent 項目是選擇性的，僅適用於 nosqlstore 區段。此項目的值是由逗號分隔整數清單所組成的字串；介於 1 與 100 之間，代表從對應表格擷取資料時可使用的讀取單位百分比。此項目可讓您為表格項目中參照的每個表格指定不同的讀取單位百分比；其中清單中的第一個百分比對應至表格清單中的第一個表格，第二個百分比對應第二個表格等等。此清單中的百分比數目不一定等於表格清單中的表格數目。系統會將 90% 的預設值指派給表格清單中沒有此清單中對應百分比的任何表格。例如，假設表格項目中指定了四個表格名稱，但 readUnitsPercent 項目設為值 "50,80"。在此情況下，會使用可用讀取單位的 50% 來擷取第一個表格的資料，而從第二個表格擷取資料時，將會使用 80% 的讀取單位。最後，對於其餘兩個表格，從這些表格擷取資料時，會使用 90% 的讀取單位 (預設值)。
requestTimeoutMs	nosqlstore (選擇性)	requestTimeoutMs 項目是選擇性的，僅適用於 nosqlstore 區段。此項目的值是由逗號區隔的正整數清單所組成的字串；其中每個整數代表對應表格之每個資料擷取要求所允許的毫秒數。此項目可讓您為表格項目中參照的每個表格指定不同的逾時值。如果未指定此項目，或如果此項目只指定表格子集的逾時，則預設值 5000 會指派給其餘的表格。
儲存桶	objectstore (必要)	必須輸入儲存桶項目，而且必須在物件存放區區段中指定。此項目的值是代表 OCI 物件儲存之儲存桶名稱的字串，公用程式會將擷取自 NoSQL 表格的資料複製到其中。
壓縮	objectstore (選擇性)	壓縮項目是選擇性的，僅適用於物件存放區區段。指定給此項目的值是一個字串，代表如何從 nosqlstore 中指定的表格擷取資料。如果設定此選項，則會將表格資料複製到物件儲存體時進行壓縮。指定給此項目的值必須是下列之一： snappy - 適用於 snappy 壓縮 gzip - 用於 gzip 壓縮無 - 不壓縮複製到 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 有三個不同的項目。這不是必要項目，而且組態檔只能有一個 DEFAULT 設定檔。但是，擁有個別設定檔是一個良好的實行範例，而不是合併 DEFAULT 設定檔中的所有參數。

表格 - 證明資料檔案中的參數

參數名稱	參數的詳細資訊
使用者	使用者的 OCID
指紋	用於識別較長預設使用者公開金鑰的簡短位元組順序
索引鍵檔案	包含預設使用者私密金鑰的檔案路徑 / 檔案名稱
租用戶	租用戶的 OCID
區域	區域的端點
區間	預設使用者區間的區間名稱或 OCID
dbmsOcid	Autonomous Database 的 OCID
dbmsCredentialName	這是 ADW 資料庫將用來向物件儲存進行認證的證明資料名稱，也就是名稱 `OCI$RESOURCE_PRINCIPAL` (如果您選擇使用「資源主體」認證)，或是使用者或系統管理員執行 `DBMS_CLOUD.CREATE_CREDENTIAL` 程序時所建立的 AUTH_TOKEN 證明資料名稱 (例如，`NOSQLADWDB_OBJ_STORE_CREDENTIAL`)。

執行工具

完成使用必要 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 提供兩個日誌記錄組態檔作為版本的一部分；一個用來設定以 java.util.logging 為基礎的日誌記錄機制，一個用於以 Log4j2 為基礎的日誌記錄器。

附註：

公用程式提供的日誌記錄器組態檔預設會設計成在公用程式執行時產生最小輸出。但如果您希望看到公用程式所使用之各種元件的詳細輸出，則應該增加想要分析其行為之特定日誌記錄器的記錄日誌層次。

標題與著作權資訊

執行 Oracle NoSQL Database Analytics Integrator

Oracle 和 (或) 其關係企業。