Esecuzione di Oracle NoSQL Database Analytics Integrator

Passi per eseguire Oracle NoSQL Database Analytics Integrator.

Creare un file di 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 illustrato 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 seguente vengono illustrati tutti i parametri utilizzati nell'esempio e viene evidenziato se è facoltativo o obbligatorio.

Esempio 1: la utility viene eseguita 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 dall'esterno di Oracle Cloud, pertanto l'autenticazione del 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, objectstore e database, le cui voci vengono utilizzate per specificare la modalità di interazione della utility con ciascun rispettivo servizio cloud: NoSQL Cloud Service, Oracle ObjectStorage e Oracle Autonomous Data Warehouse.

Esistono 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 seguenti: nosqldb_cloud (per la sezione nosqlstore), object_storage_oci (per la sezione dell'area di memorizzazione degli oggetti) e database_cloud (per la sezione del 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), la voce dell'endpoint in ogni sezione può essere specificata 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
useInstancePrincipal

nosqlstore (facoltativo)

objectstore (facoltativo)
La voce useInstancePrincipal può essere specificata come valore booleano vero se vengono soddisfatte le seguenti condizioni:
  • La utility verrà eseguita da un'istanza di computazione Oracle Cloud.
  • La sezione in fase di configurazione non è la sezione del database
  • L'istanza di computazione è autorizzata, in qualità di principal dell'istanza, a eseguire azioni sulla risorsa a cui viene fatto riferimento nella sezione in fase di configurazione
  • La voce delle credenziali non è stata specificata
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

È necessario specificare le credenziali utente nella sezione del database perché l'Autonomous Database ospitato in ADW lo richiede.
compartimento

nosqlstore (facoltativo)

objectstore (facoltativo)
  • Se si specifica true per la voce useInstancePrincipal, è necessario specificare anche l'OCID del compartimento che contiene tale risorsa.
  • Se per la voce useInstancePrincipal è specificato false o la voce delle credenziali, la voce del compartimento è facoltativa, anche se deve essere specificata nel file a cui fa riferimento la voce delle credenziali.
credenziali

nosqlstore (facoltativo)

objectstore (facoltativo)

database (obbligatorio)
La voce delle credenziali è obbligatoria nella sezione del database in tutte le circostanze. È obbligatorio nelle sezioni nosqlstore e objectstore in una o più delle seguenti circostanze:
  • La utility verrà eseguita dall'esterno di Oracle Cloud oppure verrà eseguita da un'istanza di computazione Oracle Cloud non un principal dell'istanza
  • La voce useInstancePrincipal non è specificata o è impostata su false.

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.

credentialsProfile

nosqlstore (facoltativo)

objectstore (facoltativo)

database (facoltativo)

La voce credentialsProfile è 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 nel servizio NoSQL Database Cloud il cui contenuto deve essere recuperato e copiato in Autonomous Data Warehouse.
readUnitsPercent nosqlstore (facoltativo)

La voce readUnitsPercent è facoltativa ed è applicabile solo nella sezione nosqlstore. Il valore di questa voce è una stringa costituita da un elenco di numeri interi separati da virgole; compreso tra 1 e 100, che rappresenta la percentuale di unità di lettura che è possibile utilizzare 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; dove 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. Un valore predefinito del 90% verrà assegnato a qualsiasi tabella dell'elenco di tabelle che non ha una percentuale corrispondente in questo 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 durante il recupero dei dati dalla seconda tabella. Infine, per le rimanenti due tabelle, verrà utilizzato il 90% delle unità di lettura (impostazione predefinita) durante il recupero dei 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 si fa 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 di 5000 verrà assegnato alle tabelle rimanenti.
bucket objectstore (obbligatorio) La voce del bucket è obbligatoria e deve essere specificata nella sezione dell'area di memorizzazione degli oggetti. 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 objectstore (facoltativo)
La voce di compressione è facoltativa ed è applicabile solo nella sezione dell'area di memorizzazione degli oggetti. Il valore specificato per questa voce è una stringa che rappresenta la modalità di recupero dei dati dalle tabelle specificate nel 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:
  • snappy per una compressione scattante
  • gzip per la compressione gzip
  • none: non comprimere i dati della tabella copiati in ObjectStorage

Nota

Se la voce di compressione non viene specificata, verrà eseguita la compressione scattante.
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 Data Warehouse Cloud Service.
databaseUser database (facoltativo)

La voce databaseUser è facoltativa e deve essere specificata nella sezione del database. Questa voce è una stringa il cui valore è il nome dell'account utente nell'Autonomous Database specificato nella voce dabaseName. Se questa voce non viene specificata, verrà richiesto nella riga di comando di fornire il valore.
databaseWallet database (obbligatorio) La voce databaseWallet è obbligatoria e deve essere specificata nella sezione del database. Questa voce è una stringa il cui valore è il percorso del file system della directory contenente il contenuto di Oracle Wallet scaricato dall'account utente di Autonomous Database specificato nella voce databaseUser nel file di configurazione.
abortOnError Facoltativo Specifica l'azione da eseguire per affrontare un errore. Il valore predefinito è true.

Nota

È possibile eseguire l'override di ogni voce del file di configurazione 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 credenziali utente, 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. Questo non è obbligatorio e può esistere un file di configurazione con un solo profilo DEFAULT. Tuttavia, avere profili separati è una buona prassi piuttosto che combinare tutti i parametri nel profilo DEFAULT.

Tabella - Parametri nel file delle credenziali

Nome parametro Dettagli del parametro
utente OCID dell'utente
impronta Breve sequenza di byte utilizzata per identificare una chiave pubblica più lunga per l'utente predefinito
file di chiave 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 o OCID del compartimento dell'utente predefinito
dbmsOcid OCID di Autonomous Database
dbmsCredentialName

Nome della credenziale che il database ADW utilizzerà per l'autenticazione con lo storage degli oggetti, ovvero il nome OCI$RESOURCE_PRINCIPAL (se si sceglie di utilizzare l'autenticazione del principal risorsa) o il nome della credenziale AUTH_TOKEN creata quando la procedura DBMS_CLOUD.CREATE_CREDENTIAL viene eseguita dall'utente o dall'amministratore del sistema (ad esempio,NOSQLADWDB_OBJ_STORE_CREDENTIAL).

Esecuzione dello strumento

Dopo aver completato tutti i requisiti per l'uso dei servizi Oracle Cloud necessari (database NoSQL, storage degli oggetti e Autonomous Data Warehouse) 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 nella directory di installazione (/home/opc/nosqlanalytics-<version>).
    cd /home/opc/nosqlanalytics-1.0.1/nosqlanalytics
  • Richiamare la utility utilizzando il comando seguente. Il file di configurazione oci-nosqlanalytics-config.json è presente nella directory .oci all'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, l'utility non produrrà alcun output di log.

Argomenti correlati

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 del 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 l'utilità sono progettati per produrre output minimo durante l'esecuzione dell'utilità. Ma se si desidera visualizzare un output dettagliato dai vari componenti utilizzati dall'utilità, è necessario aumentare i livelli di log dei logger specifici di cui si desidera analizzare il comportamento.