Esecuzione di Oracle NoSQL Database Analytics Integrator
Passi per eseguire Oracle NoSQL Database Analytics Integrator.
Creare un file della configurazione per l'integratore
Prima di poter eseguire Oracle NoSQL Database Analytics Integrator, è necessario creare un file di configurazione. Questo file di configurazione verrà utilizzato quando si richiama la utility. Il file di configurazione deve avere le voci in formato JSON come mostrato negli esempi riportati di seguito. Di seguito sono riportati solo due file di configurazione di esempio. Non tutti i parametri utilizzati di seguito sono obbligatori. Nella tabella riportata di seguito vengono illustrati tutti i parametri utilizzati nell'esempio ed evidenziati se sono facoltativi o obbligatori.
Esempio 1: si esegue la utility da un'istanza di computazione Oracle Cloud e si desidera eseguire l'autenticazione utilizzando un principal dell'istanza.
{
"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>
}
}Esempio 2: si preferisce eseguire l'autenticazione utilizzando le proprie credenziali utente oppure si sta eseguendo dall'esterno di Oracle Cloud e pertanto l'autenticazione Principal dell'istanza non è disponibile.
{
"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
}La configurazione è suddivisa in tre sezioni: nosqlstore, objecttore e database, le cui voci vengono utilizzate per specificare in che modo la utility interagisce con ogni rispettivo servizio cloud: NoSQL Cloud Service, Oracle Object Storage e Oracle Autonomous AI Lakehouse.
Ci sono alcuni parametri comuni in tutte e tre le sezioni.
Tabella - Parametri comuni per tutte le sezioni
| Nome parametro | Dettagli del parametro |
|---|---|
| type | Attualmente, questo parametro può assumere uno dei tre valori: nosqldb_cloud (per la sezione nosqlstore), object_storage_oci (per la sezione objecttore) e database_cloud (per la sezione database). |
| endpoint | Il valore di questa voce deve essere impostato sull'area in cui si trova la risorsa associata. Il valore specificato per questa voce può essere l'endpoint API dell'area o l'identificativo area per la risorsa. Ad esempio, se ogni risorsa si trova nell'area orientale degli Stati Uniti (Ashburn), è possibile specificare la voce dell'endpoint in ogni sezione utilizzando l'identificativo dell'area ("us-ashburn-1") o l'endpoint API dell'area per il servizio desiderato. |
Tabella - Parametri nel file di configurazione
| Il nome del parametro | Sezione specificata | Dettagli della sezione corrente |
|---|---|---|
| useInstancePrincipal | nosqlstore(facoltativo) objecttore(facoltativo) |
La voce useInstancePrincipal può essere specificata come valore booleano true se vengono soddisfatte le seguenti condizioni:
Se si specifica true per la voce useInstancePrincipal e si specifica anche la voce delle credenziali, la voce delle credenziali ha la precedenza e le credenziali utente a cui viene fatto riferimento nel valore della voce verranno utilizzate per interagire con la risorsa associata. Nota Le credenziali utente devono essere specificate nella sezione del database perché Autonomous AI Database ospitato in Oracle Autonomous AI Lakehouse lo richiede. |
| compartimento | nosqlstore(facoltativo) objecttore(facoltativo) |
|
| credenziali | nosqlstore(facoltativo) objecttore(facoltativo) database (obbligatorio) |
La voce delle credenziali è obbligatoria nella sezione del database in tutte le circostanze. È richiesto nelle sezioni nosqlstore e objecttore in una o più delle seguenti circostanze:
Il valore specificato per questa voce deve fare riferimento a un file nel file system locale che specifica le credenziali utente che possono essere utilizzate per interagire in modo sicuro con la risorsa associata. |
| profilo credenziali | nosqlstore(facoltativo) objecttore(facoltativo) database (facoltativo) |
La voce credentialProfile è facoltativa in ogni sezione e, anche se specificata, si applica solo quando viene specificata anche una voce di credenziali corrispondente. |
| Tabella | nosqlstore(Obbligatorio) | La voce della tabella è obbligatoria e deve essere specificata nella sezione nosqlstore. Il valore di questa voce è una stringa costituita da una lista di nomi separata da virgole, in cui ogni nome fa riferimento al nome di una tabella in NoSQL Database Cloud Service il cui contenuto deve essere recuperato e copiato in Oracle Autonomous AI Lakehouse. |
| readUnitsPercentuale | nosqlstore(facoltativo) | La voce readUnitsPercent è facoltativa ed è applicabile solo nella sezione nosqlstore. Il valore di questa voce è una stringa costituita da una lista separata da virgole di numeri interi; tra 1 e 100, che rappresenta la percentuale di unità di lettura che possono essere consumate durante il recupero dei dati dalla tabella corrispondente. Questa voce consente di specificare percentuali di unità di lettura diverse per ciascuna delle tabelle a cui si fa riferimento nella voce della tabella; se la prima percentuale nell'elenco corrisponde alla prima tabella nell'elenco delle tabelle, la seconda percentuale corrisponde alla seconda tabella e così via. Non è necessario che il numero di percentuali in questo elenco sia uguale al numero di tabelle nell'elenco di tabelle. Verrà assegnato un valore predefinito del 90% a qualsiasi tabella dell'elenco di tabelle che non dispone di una percentuale corrispondente nell'elenco. Si supponga, ad esempio, che nella voce della tabella siano specificati quattro nomi di tabella, ma che la voce readUnitsPercent sia impostata sul valore "50,80". In questo caso, i dati della prima tabella verranno recuperati utilizzando il 50% delle unità di lettura disponibili, mentre l'80% delle unità di lettura verrà utilizzato quando si recuperano i dati dalla seconda tabella. Infine, per le due tabelle rimanenti, il 90% delle unità di lettura (impostazione predefinita) verrà utilizzato quando si recuperano i dati da ciascuna di tali tabelle. |
| RequestTimeoutMs | nosqlstore(facoltativo) | La voce requestTimeoutMs è facoltativa ed è applicabile solo nella sezione nosqlstore. Il valore di questa voce è una stringa costituita da una lista separata da virgole di numeri interi positivi, in cui ogni numero intero rappresenta il numero di millisecondi consentiti per il completamento di ogni richiesta di recupero dati per la tabella corrispondente. Questa voce consente di specificare valori di timeout diversi per ciascuna delle tabelle a cui viene fatto riferimento nella voce della tabella. Se questa voce non viene specificata o se questa voce specifica un timeout solo per un subset delle tabelle, il valore predefinito 5000 verrà assegnato alle tabelle rimanenti. |
| secchio | objecttore(Obbligatorio) | La voce del bucket è obbligatoria e deve essere specificata nella sezione dell'objecttore. Il valore di questa voce è una stringa che rappresenta il nome del bucket di OCI Object Storage, in cui la utility copia i dati recuperati dalle tabelle NoSQL. |
| compressione | objecttore(facoltativo) | La voce di compressione è facoltativa ed è applicabile solo nella sezione dell'oggetto. Il valore specificato per questa voce è una stringa che rappresenta la modalità di recupero dei dati dalle tabelle specificate in nosqlstore. Se questa opzione è impostata, i dati della tabella vengono compressi durante la copia nello storage degli oggetti. Il valore specificato per questa voce deve essere uno dei seguenti:
Nota Se la voce di compressione non è specificata, verrà eseguita la compressione del serpente. |
| databaseName | database (obbligatorio) | La voce dabaseName è obbligatoria e deve essere specificata nella sezione del database. Questa voce è una stringa il cui valore è il nome del database creato in Oracle Autonomous AI Lakehouse Cloud Service. |
| utente database | database (facoltativo) | La voce databaseUser è facoltativa e deve essere specificata nella sezione database. Questa voce è una stringa il cui valore è il nome dell'account utente nell'Autonomous AI Database specificato nella voce dabaseName. Se questa voce non viene specificata, nella riga di comando verrà richiesto di fornire il valore. |
| Wallet database | database (obbligatorio) | La voce databaseWallet è obbligatoria e deve essere specificata nella sezione database. Questa voce è una stringa il cui valore è il percorso del file system alla directory contenente il contenuto di Oracle Wallet scaricato dall'account utente di Autonomous AI Database specificato nella voce databaseUser nel file di configurazione. |
| abortOnError | Facoltativo | Specifica l'azione da eseguire per risolvere un errore. Il valore predefinito è true. |
Nota: ogni voce nel file di configurazione può essere sostituita dalla riga di comando impostando una proprietà di sistema con il nome del modulo, section.entry, ad esempio -Dnosqlstore.table=tableName1,tableName3. Se una voce non si trova all'interno di una sezione, il nome da utilizzare per tale proprietà è semplicemente il nome della voce stessa; ad esempio, -DabortOnError=false. Questa funzione può essere utile durante il test o la scrittura di script che eseguono l'utility a intervalli regolari.
Specifica delle informazioni di configurazione nel file delle credenziali:
Oracle Cloud Infrastructure richiede informazioni di configurazione di base, come le credenziali utente, l'OCID tenancy e così via, che possono essere specificate nel file di configurazione. La posizione predefinita per questo file di configurazione è ~/.oci. In questo file di configurazione è possibile specificare più set di credenziali utente.
Di seguito è riportato un file di credenziali di esempio.
[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>Nota: nel file di configurazione sopra riportato, sono disponibili tre voci separate per nosql-db-user, objectstorage-user e adw-user. Non è obbligatorio e può esistere un file di configurazione con un solo profilo DEFAULT. Tuttavia, avere profili separati è una buona pratica piuttosto che combinare tutti i parametri nel profilo DEFAULT.
| Nome parametro | Dettagli del parametro |
|---|---|
| utente | OCID dell'utente |
| impronta | Sequenza breve di byte utilizzata per identificare una chiave pubblica più lunga per l'utente predefinito |
| file di chiavi | Percorso/nome file del file che contiene la chiave privata per l'utente predefinito |
| tenancy | OCID della tenancy |
| aree | L'endpoint della regione |
| compartimento | nome compartimento o OCID del compartimento dell'utente predefinito |
| Id database | OCID di Autonomous AI Database |
| dbmsNomeCredenziale | Nome della credenziale che il database Oracle Autonomous AI Lakehouse utilizzerà per eseguire l'autenticazione con lo storage degli oggetti, ovvero il nome OCI$RESOURCE_PRINCIPAL (se si sceglie di utilizzare l'autenticazione principal risorsa) o il nome della credenziale AUTH_TOKEN creata quando la procedura DBMS_CLOUD.CREATE_CREDENTIAL viene eseguita dall'utente o dall'amministratore di sistema (ad esempio,NOSQLADWDB_OBJ_STORE_CREDENTIAL ). |
Esecuzione dello strumento
Dopo aver completato tutti i requisiti per l'uso dei servizi Oracle Cloud necessari (NoSQL Database, Object Storage e Oracle Autonomous AI Lakehouse) e aver creato un file di configurazione valido, Oracle NoSQL Database Analytics Integrator può essere eseguito semplicemente digitando un comando sulla riga di comando.
-
Passare alla directory nosqlanalytics sotto la directory di installazione
(/home/opc/nosqlanalytics-<version>).cd /home/opc/nosqlanalytics-1.0.1/nosqlanalytics -
Richiamare l'utility utilizzando il comando seguente. Il file di configurazione
oci-nosqlanalytics-config.jsonè presente nella directory.ociall'interno della directory 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
Nota: le proprietà di sistema che configurano i logger utilizzati durante l'esecuzione sono facoltative. Se tali proprietà di sistema non vengono specificate, la utility non produrrà alcun output di log.
Log
Oracle NoSQL Database Analytics Integrator esegue il software da più librerie di terze parti, in cui ogni libreria definisce il proprio set di logger con spazi di nomi diversi. Per comodità, Oracle NoSQL Database Analytics Integrator fornisce due file di configurazione di log nell'ambito della release, uno per configurare i meccanismi di log basati su java.util.logging e uno per i logger basati su Log4j2.
Nota: per impostazione predefinita, i file di configurazione del logger forniti con la utility sono progettati per produrre un output minimo durante l'esecuzione della utility. Ma se si desidera vedere l'output verboso dai vari componenti che vengono utilizzati dall'utilità, allora si dovrebbe aumentare i livelli di registrazione dei logger specifici di cui si desidera analizzare il comportamento.