运行 Oracle NoSQL Database Analytics Integrator

运行 Oracle NoSQL Database Analytics Integrator 的步骤。

为集成器创建配置文件

必须先创建配置文件，然后才能执行 Oracle NoSQL Database Analytics Integrator。调用实用程序时将使用此配置文件。配置文件应具有 JSON 格式的条目，如下例所示。以下是两个示例配置文件。并非下面使用的所有参数都是必需的。下表说明示例中使用的每个参数，并突出显示它是可选的还是必需的。

示例 1：您从 Oracle Cloud 计算实例执行实用程序，并且希望使用实例主用户进行验证。

{
    "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、objectstore 和 database - 其条目用于指定实用程序如何与每个相应的云服务进行交互：NoSQL Cloud Service、Oracle Object Storage 和 Oracle Autonomous AI Lakehouse。

有一些参数在所有三个部分中都很常见。

表 - 所有部分的公用参数

参数名称	参数的详细信息
类型	当前，此参数可以采用以下三个值之一：`nosqldb_cloud`（用于 nosqlstore 部分）、`object_storage_oci`（用于对象存储部分）和 `database_cloud`（用于数据库部分）。
endpoint	此条目的值必须设置为关联资源所在的区域。为此条目指定的值可以是区域的 API 端点或资源的区域标识符。例如，如果每个资源位于美国东部 (Ashburn) 区域，则可以使用区域的标识符 ("US-ashburn-1") 或区域的 API 端点为所需服务指定每个部分中的端点条目。

表 - 配置文件中的参数

参数名称	指定的部分	本节的详细信息
useInstancePrincipal	nosqlstore（可选）对象存储（可选）	如果满足以下条件，则可以将 useInstancePrincipal 条目指定为布尔值 true：将从 Oracle Cloud 计算实例执行该实用程序。要配置的部分不是数据库部分计算实例有权作为实例主用户对所配置部分中引用的资源执行操作凭证条目未指定如果为 useInstancePrincipal 条目指定了 true，并且还指定了凭证条目，则凭证条目优先，该条目值中引用的用户凭证将用于与关联的资源交互。注意：必须在数据库部分中指定用户身份证明，因为在 Oracle Autonomous AI Lakehouse 中托管的自治 AI 数据库需要它。
区间	nosqlstore（可选）对象存储（可选）	如果为 useInstancePrincipal 条目指定了 true，则还必须指定包含该资源的区间的 OCID。如果为 useInstancePrincipal 条目指定了 false 或者指定了凭证条目，则区间条目是可选的；尽管必须在凭证条目引用的文件中指定该条目。
Credential (身份证明)	nosqlstore（可选）对象存储（可选）数据库（必需）	在所有情况下，数据库部分都需要身份证明条目。在以下一种或多种情况下，nosqlstore 和 objectstore 部分中需要它：该实用程序将从 Oracle Cloud 外部执行，或者将从不是实例主用户的 Oracle Cloud 计算实例执行 useInstancePrincipal 条目未指定或设置为 false。为此条目指定的值必须引用本地文件系统上的文件，该文件指定可用于与关联资源安全交互的用户凭证。
credentialsProfile	nosqlstore（可选）对象存储（可选）数据库（可选）	credentialsProfile 条目在每个部分中是可选的，即使已指定，也仅在指定了相应的凭证条目时适用。
table (表)	nosqlstore（必需）	表条目是必需的，必须在 nosqlstore 部分中指定。此条目的值是一个字符串，由逗号分隔的名称列表组成；其中每个名称引用 NoSQL Database Cloud Service 中应检索其内容并将其复制到 Oracle Autonomous AI Lakehouse 的表的名称。
readUnitsPercent	nosqlstore（可选）	readUnitsPercent 条目是可选的，仅适用于 nosqlstore 部分。此项的值是由逗号分隔的整数列表组成的字符串；介于 1 和 100 之间，表示从相应表中检索数据时可以使用的读取单位百分比。使用此条目可以为表条目中引用的每个表指定不同的读取单位百分比；其中，列表中的第一个百分比对应于表列表中的第一个表，第二个百分比对应于第二个表，依此类推。不要求此列表中的百分比数等于表列表中的表数。默认值 90% 将分配给此列表中没有相应百分比的表列表中的任何表。例如，假设在表条目中指定了四个表名，但 readUnitsPercent 条目设置为值 "50,80"。在这种情况下，将使用 50% 的可用读取单位检索第一个表中的数据，而从第二个表中检索数据时将使用 80% 的读取单位。最后，对于其余两个表，从每个表中检索数据时将使用 90% 的读取单位（默认值）。
requestTimeoutMs	nosqlstore（可选）	requestTimeoutMs 条目是可选的，仅适用于 nosqlstore 部分。此项的值是由逗号分隔的 positive 整数列表组成的字符串；其中每个整数表示允许每个数据检索请求为相应表完成的毫秒数。使用此条目可以为表条目中引用的每个表指定不同的超时值。如果未指定此条目，或者如果此条目仅为表子集指定超时，则会将默认值 5000 分配给其余表。
存储桶	objectstore（必需）	存储桶条目是必需的，必须在对象存储部分中指定。此项的值是表示 OCI 对象存储存储桶名称的字符串，实用程序会将从 NoSQL 表中检索的数据复制到该存储桶中。
压缩	对象存储（可选）	压缩条目是可选的，仅适用于对象存储部分。为此条目指定的值是一个字符串，表示如何从 nosqlstore 中指定的表中检索数据。如果设置了此项，则在复制到对象存储时会压缩表数据。为此条目指定的值必须是下列值之一： snappy - 用于 snappy 压缩 gzip - 用于 gzip 压缩 none - 不压缩复制到 ObjectStorage 的表数据注意：如果未指定压缩条目，则将执行 snappy 压缩。
databaseName	数据库（必需）	dabaseName 条目是必需的，必须在数据库部分中指定。此条目是一个字符串，其值是在 Oracle Autonomous AI Lakehouse Cloud Service 中创建的数据库的名称。
databaseUser	数据库（可选）	databaseUser 条目是可选的，应在数据库部分中指定。此条目是一个字符串，其值是 dabaseName 条目中指定的自治 AI 数据库中用户帐户的名称。如果未指定此条目，则会在命令行中提示您提供该值。
databaseWallet	数据库（必需）	databaseWallet 条目是必需的，必须在数据库部分中指定。此条目是一个字符串，其值是目录的文件系统路径，该目录包含从配置文件的 `databaseUser` 条目中指定的自治 AI 数据库用户帐户下载的 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	自治 AI 数据库的 OCID
dbmsCredentialName	这是 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 和/或其关联公司。