运行 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 端点或资源的 Region identifier 。例如，如果每个资源位于美国东部（阿什本）区域，则可以使用区域的标识符 ("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 或者指定了身份证明条目，则区间条目是可选的；尽管必须在身份证明条目引用的文件中指定该条目。
Credential (身份证明)	nosqlstore（可选） objectstore（可选）数据库（必需）	在所有情况下，数据库部分都需要输入身份证明。在以下一种或多种情况下，nosqlstore 和 objectstore 部分需要该命令：该实用程序将从 Oracle Cloud 外部执行，或者将从不是实例主用户的 Oracle Cloud 计算实例执行未指定 useInstancePrincipal 条目或将其设置为 false。为此条目指定的值必须引用本地文件系统上的文件，该文件指定可用于安全地与关联资源交互的用户凭证。
身份证明概要文件	nosqlstore（可选） objectstore（可选）数据库（可选）	credentialProfile 条目在每个部分中是可选的，即使指定了此选项，也仅在指定相应的身份证明条目时适用。
table (表)	nosqlstore（必需）	表条目是必需的，必须在 nosqlstore 部分中指定。此条目的值是一个字符串，由逗号分隔的名称列表组成；其中每个名称引用 NoSQL Database Cloud Service 中应检索其内容并将其复制到 Oracle Autonomous AI Lakehouse 的表的名称。
readUnits 百分比	nosqlstore（可选）	readUnitsPercent 条目是可选的，仅适用于 nosqlstore 部分。此条目的值是一个字符串，由逗号分隔的整数列表组成；介于 1 和 100 之间，表示从相应表中检索数据时可以使用的读取单位百分比。此条目允许您为表条目中引用的每个表指定不同的读取单位百分比；其中列表中的第一个百分比与表列表中的第一个表相对应，第二个百分比与第二个表相对应，依此类推。此列表中的百分比数不一定等于表列表中的表数。默认值为 90%，将分配给此列表中没有相应百分比的表。例如，假设在表条目中指定了四个表名，但 readUnitsPercent 条目设置为值 "50,80"。在这种情况下，将使用可用读取单位的 50% 检索第一个表中的数据，而从第二个表中检索数据时将使用 80% 的读取单位。最后，对于其余两个表，90% 的读取单位（默认值）将在从每个表检索数据时使用。
请求超时	nosqlstore（可选）	requestTimeoutMs 条目是可选的，仅适用于 nosqlstore 部分。此条目的值是一个字符串，由逗号分隔的 positive 整数列表组成；其中，每个整数表示为对应表完成的每个数据检索请求所允许的毫秒数。此条目允许您为表条目中引用的每个表指定不同的超时值。如果未指定此条目，或者如果此条目仅为表的某个子集指定超时，则会将默认值 5000 分配给其余表。
存储桶	objectstore（必需）	存储桶条目是必需的，必须在对象存储部分中指定。此条目的值是一个字符串，表示 OCI 对象存储存储桶的名称，实用程序会将从 NoSQL 表中检索到的数据复制到该存储桶中。
压缩	objectstore（可选）	压缩条目是可选的，仅适用于对象存储部分。为此条目指定的值是一个字符串，表示如何从 nosqlstore 中指定的表检索数据。如果设置了此项，则在复制到对象存储时会压缩表数据。为此条目指定的值必须是以下值之一： snappy - 用于 snappy 压缩 gzip - 用于 gzip 压缩 none - 不压缩复制到 ObjectStorage 的表数据注意：如果未指定压缩条目，则将执行 snappy 压缩。
databaseName	数据库（必需）	dabaseName 条目是必需的，必须在数据库部分中指定。此条目是一个字符串，其值是在 Oracle Autonomous AI Lakehouse Cloud Service 中创建的数据库的名称。
数据库用户	数据库（可选）	databaseUser 条目是可选的，应当在数据库部分中指定。此条目是一个字符串，其值是 dabaseName 条目中指定的自治 AI 数据库中用户帐户的名称。如果未指定此条目，则会在命令行中提示您提供该值。
数据库 Wallet	数据库（必需）	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
数据库 OCID	自治 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 NoSQL Database Analytics Integrator

为集成器创建配置文件

运行该工具

日志记录

相关主题