Executando o Oracle NoSQL Database Analytics Integrator
Etapas para executar o Oracle NoSQL Database Analytics Integrator.
Criar um arquivo de configuração para o integrador
Para poder executar o Oracle NoSQL Database Analytics Integrator, primeiro crie um arquivo de configuração. Este arquivo de configuração será usado ao chamar o utilitário. O arquivo de configuração deve ter as entradas em um formato JSON, conforme mostrado nos exemplos abaixo. A seguir estão apenas dois exemplos de arquivos de configuração. Nem todos os parâmetros usados abaixo são obrigatórios. A tabela abaixo explica cada parâmetro que está sendo usado no exemplo e destaca se é opcional ou obrigatório.
Exemplo 1:Você executa o utilitário de uma Instância do Oracle Cloud Compute e deseja autenticar usando um Controlador de Instâncias.
{
"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>
}
}Exemplo 2: Você prefere se autenticar usando suas próprias credenciais de usuário ou está executando de fora do Oracle Cloud e, portanto, a autenticação do Controlador de Instâncias não está disponível.
{
"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
}A configuração é dividida em três seções - nosqlstore, objectstore e database - cujas entradas são usadas para especificar como o utilitário interage com cada respectivo serviço de nuvem: o NoSQL Cloud Service, o Oracle Object Storage e o Oracle Autonomous AI Lakehouse.
Existem alguns parâmetros que são comuns em todas as três seções.
Tabela - Parâmetros Comuns para todas as seções
| Nome do parâmetro | Detalhes do parâmetro |
|---|---|
| tipo | No momento, esse parâmetro pode ter um dos três valores: nosqldb_cloud (para a seção nosqlstore), object_storage_oci (para a seção objectstore) e database_cloud (para a seção do banco de dados). |
| ponto final | O valor desta entrada deve ser definido para a região na qual o recurso associado está localizado. O valor especificado para essa entrada pode ser o ponto final da API da região ou o Identificador da região do recurso. Por exemplo, se cada recurso estiver localizado na região Leste dos EUA (Ashburn), a entrada de ponto final em cada seção poderá ser especificada usando o identificador da região ("us-ashburn-1") ou o ponto final da API da região para o serviço desejado. |
Tabela - Parâmetros no arquivo de configuração
| Nome do parâmetro | Seção Especificada | Detalhes da seção |
|---|---|---|
| usarInstânciaPrincipal | nosqlstore(Opcional) objectstore(Opcional) |
A entrada useInstancePrincipal pode ser especificada como o valor booliano verdadeiro se as seguintes condições forem satisfeitas:
Se true for especificado para a entrada useInstancePrincipal e a entrada de credenciais também for especificada, a entrada de credenciais terá precedência, e as credenciais do usuário referenciadas no valor dessa entrada serão usadas para interagir com o recurso associado. Observação: As credenciais do usuário devem ser especificadas na seção do banco de dados porque o Autonomous AI Database hospedado no Oracle Autonomous AI Lakehouse exige isso. |
| compartimento | nosqlstore(Opcional) objectstore(Opcional) |
|
| credentials | nosqlstore(Opcional) objectstore(Opcional) banco de dados (Obrigatório) |
A entrada de credenciais é obrigatória na seção do banco de dados em todas as circunstâncias. É necessário nas seções nosqlstore e objectstore em uma ou mais das seguintes circunstâncias:
O valor especificado para esta entrada deve fazer referência a um arquivo no sistema de arquivos local que especifica as credenciais do usuário que podem ser usadas para interagir com segurança com o recurso associado. |
| credenciaisPerfil | nosqlstore(Opcional) objectstore(Opcional) banco de dados (Opcional) |
A entrada credentialProfile é opcional em cada seção e, mesmo se especificada, se aplica somente quando uma entrada de credenciais correspondente também é especificada. |
| tabela | nosqlstore(Obrigatório) | A entrada da tabela é obrigatória e deve ser especificada na seção nosqlstore. O valor dessa entrada é uma string que consiste em uma lista de nomes separada por vírgulas; em que cada nome faz referência ao nome de uma tabela no NoSQL Database Cloud Service cujo conteúdo deve ser recuperado e copiado para o Oracle Autonomous AI Lakehouse. |
| percentagem de readUnits | nosqlstore(Opcional) | A entrada readUnitsPercent é opcional e só é aplicável na seção nosqlstore. O valor desta entrada é uma string que consiste em uma lista de inteiros separados por vírgulas; entre 1 e 100, representando a porcentagem de unidades de leitura que podem ser consumidas ao recuperar dados da tabela correspondente. Esta entrada permite especificar diferentes porcentagens de unidade de leitura para cada uma das tabelas referenciadas na entrada da tabela; onde a primeira porcentagem da lista corresponde à primeira tabela da lista de tabelas, a segunda porcentagem corresponde à segunda tabela e assim por diante. Não é necessário que o número de porcentagens nesta lista seja igual ao número de tabelas na lista de tabelas. Um valor padrão de 90% será atribuído a qualquer tabela na lista de tabelas que não tenha um percentual correspondente nessa lista. Por exemplo, suponha que quatro nomes de tabela sejam especificados na entrada de tabela, mas a entrada readUnitsPercent esteja definida com o valor "50,80". Para este caso, os dados da primeira tabela serão recuperados usando 50% das unidades de leitura disponíveis, enquanto 80% das unidades de leitura serão usadas ao recuperar dados da segunda tabela. E, finalmente, para as duas tabelas restantes, 90% das unidades de leitura (o padrão) serão usadas ao recuperar os dados de cada uma dessas tabelas. |
| requestTimeoutMs | nosqlstore(Opcional) | A entrada requestTimeoutMs é opcional e só é aplicável na seção nosqlstore. O valor desta entrada é uma string que consiste em uma lista separada por vírgulas de números inteiros positivos; onde cada número inteiro representa o número de milissegundos permitidos para cada solicitação de recuperação de dados a ser concluída para a tabela correspondente. Esta entrada permite especificar valores de timeout diferentes para cada uma das tabelas referenciadas na entrada da tabela. Se esta entrada não for especificada, ou se esta entrada especificar um timeout para apenas um subconjunto das tabelas, o valor padrão de 5000 será atribuído às tabelas restantes. |
| bucket | objectstore(Obrigatório) | A entrada do bucket é obrigatória e deve ser especificada na seção de armazenamento de objetos. O valor dessa entrada é uma string que representa o nome do bucket do OCI Object Storage, no qual o utilitário copia os dados recuperados das tabelas NoSQL. |
| compactação | objectstore(Opcional) | A entrada de compactação é opcional e só se aplica à seção de armazenamento de objetos. O valor especificado para esta entrada é uma string que representa como os dados são recuperados da(s) tabela(s) especificada(s) no nosqlstore. Se isso for definido, os dados da tabela serão compactados durante a cópia para o armazenamento de objetos. O valor especificado para esta entrada deve ser um dos seguintes:
Observação: Se a entrada de compactação não for especificada, a compactação rápida será executada. |
| databaseName | banco de dados (Obrigatório) | A entrada dabaseName é obrigatória e deve ser especificada na seção do banco de dados. Esta entrada é uma string cujo valor é o nome do banco de dados criado no Oracle Autonomous AI Lakehouse Cloud Service. |
| usuáriobanco | banco de dados (Opcional) | A entrada databaseUser é opcional e deve ser especificada na seção banco de dados. Esta entrada é uma string cujo valor é o nome da conta do usuário no Autonomous AI Database especificado na entrada dabaseName. Se essa entrada não for especificada, você será solicitado na linha de comando a fornecer o valor. |
| carteira de banco de dados | banco de dados (Obrigatório) | A entrada databaseWallet é obrigatória e deve ser especificada na seção do banco de dados. Esta entrada é uma string cujo valor é o caminho do sistema de arquivos para o diretório que contém o conteúdo do Oracle Wallet submetido a download da conta de usuário do Autonomous AI Database especificada na entrada databaseUser no arquivo de configuração. |
| abortOnError | Opcional | Especifica a ação a ser tomada ao enfrentar um erro. O valor padrão é verdadeiro. |
Observação: cada entrada no arquivo de configuração pode ser substituída na linha de comando, definindo uma propriedade do sistema com o nome do formulário, section.entry, por exemplo, -Dnosqlstore.table=tableName1,tableName3. Se uma entrada não estiver localizada dentro de uma seção, o nome a ser usado para tal propriedade será simplesmente o nome da própria entrada; por exemplo, -DabortOnError=false. Esse recurso pode ser útil ao testar ou gravar scripts que executam o utilitário em intervalos regulares.
Especificando informações de configuração no arquivo de credenciais:
O Oracle Cloud Infrastructure requer informações básicas de configuração, como credenciais do usuário, OCID da tenancy etc., que podem ser especificadas no arquivo de configuração. O local padrão para este arquivo de configuração é ~/.oci. Você pode especificar vários conjuntos de credenciais de usuário neste arquivo de configuração.
Um exemplo de arquivo de credenciais é mostrado abaixo.
[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>Observação: no arquivo de configuração acima, há três entradas separadas para nosql-db-user, objectstorage-user e adw-user. Isso não é obrigatório e um arquivo de configuração só pode existir com um perfil DEFAULT. No entanto, ter perfis separados é uma boa prática, em vez de combinar todos os parâmetros no perfil DEFAULT.
| Nome do Parâmetro | Detalhes do parâmetro |
|---|---|
| user | O OCID do usuário |
| impressão digital | Uma sequência curta de bytes usada para identificar uma chave pública mais longa para o usuário padrão |
| arquivo de chaves | O caminho/nome do arquivo que contém a chave privada do usuário padrão |
| tenancy | O OCID da tenancy |
| regiões | O ponto final da região |
| compartimento | nome do compartimento ou OCID do compartimento do usuário padrão |
| dbmsOcid | OCID do Autonomous AI Database |
| dbmsNomeCredencial | Este é o nome da credencial que o banco de dados do Oracle Autonomous AI Lakehouse usará para autenticação com o Object Storage; que é o nome OCI$RESOURCE_PRINCIPAL (se você optar por empregar a autenticação do Controlador de Recursos) ou o nome da credencial AUTH_TOKEN que é criada quando o procedimento DBMS_CLOUD.CREATE_CREDENTIAL é executado pelo usuário ou pelo administrador do sistema (por exemplo,NOSQLADWDB_OBJ_STORE_CREDENTIAL ). |
Executando a ferramenta
Depois que todos os requisitos para usar os serviços necessários do Oracle Cloud (NoSQL Database, Object Storage e Oracle Autonomous AI Lakehouse) tiverem sido concluídos e um arquivo de configuração válido tiver sido criado, o Oracle NoSQL Database Analytics Integrator poderá ser executado simplesmente digitando um comando na linha de comando.
-
Navegue até o diretório nosqlanalytics no diretório de instalação
(/home/opc/nosqlanalytics-<version>).cd /home/opc/nosqlanalytics-1.0.1/nosqlanalytics -
Chame o utilitário usando o comando a seguir. O arquivo de configuração
oci-nosqlanalytics-config.jsonestá presente no diretório.ocidentro do diretório home.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
Observação: as propriedades do sistema que configuram os loggers usados durante a execução são opcionais. Se essas propriedades do sistema não forem especificadas, o utilitário não produzirá nenhuma saída de log.
Log
O Oracle NoSQL Database Analytics Integrator executa software de várias bibliotecas de terceiros, em que cada biblioteca define seu próprio conjunto de loggers com diferentes namespaces. Por conveniência, o Oracle NoSQL Database Analytics Integrator fornece dois arquivos de configuração de log como parte da release; um para configurar mecanismos de log com base no java.util.logging e outro para loggers com base no Log4j2.
Observação: Por padrão, os arquivos de configuração do logger fornecidos com o utilitário são projetados para produzir uma saída mínima à medida que o utilitário é executado. Mas se você quiser ver a saída detalhada dos vários componentes que são empregados pelo utilitário, então você deve aumentar os níveis de log dos loggers específicos cujo comportamento você deseja analisar.