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. Veja a seguir 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 ele é 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 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 banco de dados - 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 ObjectStorage e o Oracle Autonomous Data Warehouse.

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 do 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.

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 do 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 secção
useInstancePrincipal	nosqlstore(Opcional) objectstore (Opcional)	A entrada useInstancePrincipal poderá ser especificada como o valor booliano verdadeiro se as seguintes condições forem atendidas: O utilitário será executado de uma Instância do Oracle Cloud Compute. A seção que está sendo configurada não é a seção do banco de dados A instância de computação está autorizada, como um Controlador de Instâncias, a executar ações no recurso referenciado na seção que está sendo configurada A entrada de credenciais não está especificada 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 Database hospedado no ADW exige isso.
compartimento	nosqlstore(Opcional) objectstore (Opcional)	Se true for especificado para a entrada useInstancePrincipal, o OCID do compartimento que contém esse recurso também deverá ser especificado. Se falso for especificado para a entrada useInstancePrincipal ou a entrada de credenciais for especificada, a entrada do compartimento será opcional; embora deva ser especificada no arquivo referenciado pela entrada de credenciais.
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. Ele é necessário nas seções nosqlstore e objectstore em uma ou mais das seguintes circunstâncias: O utilitário será executado de fora do Oracle Cloud ou será executado de uma Instância do Oracle Cloud Compute que não seja um Controlador de Instâncias A entrada useInstancePrincipal não foi especificada ou está definida como falsa. O valor especificado para essa entrada deve fazer referência a um arquivo no sistema de arquivos local que especifique credenciais de usuário que podem ser usadas para interagir com segurança com o recurso associado.
credentialsProfile	nosqlstore(Opcional) objectstore (Opcional) banco de dados (Opcional)	A entrada credentialsProfile é opcional em cada seção e, mesmo que especificada, só se aplica 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 Autonomous Data Warehouse.
readUnitsPercent	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 o primeiro percentual na lista corresponde à primeira tabela na lista de tabelas, o segundo percentual corresponde à segunda tabela e assim por diante. Não é necessário que o número de porcentagens nessa 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 da tabela, mas a entrada readUnitsPercent seja definida com o valor "50,80". Nesse 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 dessa entrada é uma string que consiste em uma lista separada por vírgulas de números inteiros positivos; em que cada número inteiro representa o número de milissegundos permitidos para que cada solicitação de recuperação de dados seja concluída para a tabela correspondente. Essa 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 é aplicável somente na seção objectstore. O valor especificado para essa 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 ao serem copiados para o armazenamento de objetos. O valor especificado para esta entrada deve ser um dos seguintes: snappy - para compactação instantânea gzip - para compactação gzip none - não compacte os dados da tabela copiados para ObjectStorage Observação: Se a entrada de compactação não for especificada, a compactação instantânea 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 Data Warehouse Cloud Service.
databaseUser	banco de dados (Opcional)	A entrada databaseUser é opcional e deve ser especificada na seção do banco de dados. Essa entrada é uma string cujo valor é o nome da conta de usuário no Autonomous Database especificado na entrada dabaseName. Se essa entrada não for especificada, você será solicitado na linha de comandos a fornecer o valor.
databaseWallet	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 baixado da conta de usuário do Autonomous Database especificada na entrada `databaseUser` no arquivo de configuração.
abortOnError	Opcional	Especifica a ação a ser tomada diante de 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 essa 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 deste arquivo de configuração é ~/.oci. Você pode especificar vários conjuntos de credenciais de usuário neste arquivo de configuração.

Um arquivo de credenciais de amostra é 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 pode existir com apenas um perfil DEFAULT. No entanto, ter perfis separados é uma boa prática, em vez de combinar todos os parâmetros no perfil DEFAULT.

Tabela - Parâmetros no arquivo de credenciais

Nome do Parâmetro	Detalhes do parâmetro
user	O OCID do usuário
impressão digital	Uma sequência curta de bytes usados para identificar uma chave pública mais longa para o usuário padrão
arquivo de chave	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 Database
dbmsCredentialName	Este é o nome da credencial que o banco de dados do ADW 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 Autonomous Data Warehouse) 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.json está presente no diretório .oci dentro 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á saída de log.

Tópicos Relacionados

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 em java.util.logging e outro para loggers com base em 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ê deseja ver saída detalhada dos vários componentes que são empregados pelo utilitário, então você deve aumentar os níveis de registro dos loggers específicos cujo comportamento você deseja analisar.

Título e Informações de Copyright

Executando o Oracle NoSQL Database Analytics Integrator

Oracle e/ou suas empresas afiliadas.