執行 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 Object Storage 及 Oracle Autonomous AI Lakehouse。

在這三個部份中，有些參數是通用的。

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

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

表格 - 組態檔中的參數

參數名稱	指定的區段	區段的明細
使用例項主參與者	nosqlstore (選擇性) objectstore (選擇性)	如果滿足下列條件，則可將 useInstancePrincipal 項目指定為布林值 true：此公用程式將從 Oracle Cloud Compute 執行處理執行。要設定的區段不是資料庫區段運算執行處理已獲授權為執行處理主體，可對正在設定之區段中參照的資源執行動作未指定證明資料項目如果為 useInstancePrincipal 項目指定 true，同時指定證明資料項目，則會優先執行證明資料項目，並使用該項目值中參照的使用者證明資料與關聯的資源進行互動。附註：必須在資料庫區段中指定使用者證明資料，因為 Oracle Autonomous AI Lakehouse 中代管的自治式 AI 資料庫需有此資料庫。
區間	nosqlstore (選擇性) objectstore (選擇性)	如果針對 useInstancePrincipal 項目指定 true，則必須一併指定包含該資源之區間的 OCID。如果為 useInstancePrincipal 項目指定 false，或指定證明資料項目，則區間項目為選擇性項目；雖然必須在證明資料項目參照的檔案中指定此項目。
credentials - 證明資料	nosqlstore (選擇性) objectstore (選擇性) 資料庫 (必要)	在所有情況下，都需要在資料庫區段中輸入證明資料。在下列一或多個情況下，nosqlstore 與物件存放區區段中必須有此項目：公用程式將從 Oracle Cloud 外部執行，或是從不是執行處理主體的 Oracle Cloud Compute 執行處理執行未指定 useInstancePrincipal 項目或設為 false。指定給此項目的值必須參照本機檔案系統上的檔案，該檔案指定可用來安全地與相關資源互動的使用者證明資料。
憑證設定檔	nosqlstore (選擇性) objectstore (選擇性) 資料庫 (選擇性)	在每個區段中，credicProfile 項目是選擇性的，即使已指定，也只會在同時指定對應的證明資料項目時套用。
表格	nosqlstore (必要)	需有表格項目，且必須在 nosqlstore 區段中指定。此項目的值是由名稱清單 (以逗號區隔) 所組成的字串，其中每個名稱都參照 NoSQL Database Cloud Service 中應擷取內容並將其複製到 Oracle Autonomous AI Lakehouse 中的表格名稱。
讀取單位百分比	nosqlstore (選擇性)	readUnitsPercent 項目為選擇性項目，僅適用於 nosqlstore 區段。此項目的值是由以逗號分隔的整數清單所組成的字串；介於 1 與 100 之間，代表從對應表格擷取資料時可使用的讀取單位百分比。此項目可讓您為表格項目中參照的每個表格指定不同的讀取單位百分比；其中清單中的第一個百分比對應至表格清單中的第一個表格、第二個百分比對應至第二個表格等等。此清單中的百分比數不一定等於表格清單中的表格數。預設值 90% 會指定給表格清單中沒有此清單中對應百分比的任何表格。例如，假設表格項目中指定了四個表格名稱，但 readUnitsPercent 項目設為值 "50,80"。在此情況下，會使用可用讀取單位的 50% 來擷取第一個資料表的資料，而從第二個資料表擷取資料時，會使用 80% 的讀取單位。最後，在剩下的兩個表格中，從每個表格擷取資料時，會使用 90% 的讀取單位 (預設值)。
要求逾時訊息	nosqlstore (選擇性)	requestTimeoutMs 項目是選擇性的，僅適用於 nosqlstore 區段。此項目的值是由以逗號區隔的正整數清單所組成的字串；其中每個整數代表每個資料擷取要求可完成對應表格的毫秒數。此項目可讓您為表格項目中參照的每個表格指定不同的逾時值。若未指定此項目，或此項目僅指定表格子集的逾時，則預設值 5000 會指定給其餘表格。
儲存桶	物件存放區 (必要)	必須輸入儲存桶項目，而且必須在物件存放區區段中指定。此項目的值是代表 OCI 物件儲存的儲存桶名稱的字串，公用程式會在其中複製從 NoSQL 表格擷取的資料。
壓縮	objectstore (選擇性)	壓縮項目是選擇性的，僅適用於 objectstore 區段。指定給此項目的值是一個字串，代表如何從 nosqlstore 中指定的表格擷取資料。如果設定此選項，則表格資料會在複製到物件儲存時進行壓縮。為此項目指定的值必須為下列其中一項： snappy - 用於 snappy 壓縮 gzip - 用於 gzip 壓縮無 - 不壓縮複製到 ObjectStorage 的表格資料附註：如果未指定壓縮項目，則會執行 snappy 壓縮。
databaseName	資料庫 (必要)	必須輸入 dabaseName 項目，而且必須在資料庫區段中指定。此項目是一個字串，其值為在 Oracle Autonomous AI Lakehouse Cloud Service 中建立之資料庫的名稱。
資料庫使用者	資料庫 (選擇性)	databaseUser 項目是選擇性的，應在資料庫區段中指定。此項目是一個字串，其值為 dabaseName 項目中指定之自治式 AI 資料庫中的使用者帳戶名稱。如果未指定此項目，系統會在指令行中提示您提供值。
資料庫公事包	資料庫 (必要)	必須輸入 databaseWallet 項目，而且必須在資料庫區段中指定。此項目是一個字串，其值為目錄的檔案系統路徑，該目錄包含從組態檔中 `databaseUser` 項目中指定的「自治式 AI 資料庫」使用者帳戶下載的 Oracle Wallet 內容。
錯誤時中止	選擇性	指定發生錯誤時所要採取的動作。預設值為 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
dbms OCID	自治式 AI 資料庫的 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 提供兩個記錄日誌組態檔作為版本的一部份；一個用來設定以 java.util.logging 為基礎的記錄日誌機制，另一個用於以 Log4j2 為基礎的記錄日誌。

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

執行 Oracle NoSQL Database Analytics Integrator

建立整合器的組態檔

執行工具

日誌記錄

相關主題