Exécution d'Oracle NoSQL Database Analytics Integrator
Etapes d'exécution d'Oracle NoSQL Database Analytics Integrator.
Création d'un fichier de configuration pour l'intégrateur
Avant de pouvoir exécuter Oracle NoSQL Database Analytics Integrator, vous devez créer un fichier de configuration. Ce fichier de configuration sera utilisé lors de l'appel de l'utilitaire. Les entrées du fichier de configuration doivent être au format JSON, comme indiqué dans les exemples ci-dessous. Voici quelques exemples de fichiers de configuration. Les paramètres utilisés ci-dessous ne sont pas tous obligatoires. Le tableau ci-dessous explique chaque paramètre utilisé dans l'exemple et indique s'il est facultatif ou obligatoire.
Exemple 1 : exécutez l'utilitaire à partir d'une instance Oracle Cloud Compute et vous souhaitez vous authentifier à l'aide d'un principal d'instance.
{
"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>
}
}Exemple 2 : vous préférez vous authentifier à l'aide de vos propres informations d'identification utilisateur ou vous exécutez à partir de l'extérieur d'Oracle Cloud. L'authentification du principal d'instance n'est donc pas disponible.
{
"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 configuration est divisée en trois sections : nosqlstore, objecttore et base de données, dont les entrées sont utilisées pour indiquer comment l'utilitaire interagit avec chaque service cloud respectif : NoSQL Cloud Service, Oracle Object Storage et Oracle Autonomous AI Lakehouse.
Certains paramètres sont communs aux trois sections.
Table - Paramètres communs à toutes les sections
| Nom du paramètre | Détails du paramètre |
|---|---|
| type | Actuellement, ce paramètre peut prendre l'une des trois valeurs suivantes : nosqldb_cloud (pour la section nosqlstore), object_storage_oci (pour la section objectstore) et database_cloud (pour la section database). |
| endpoint | La valeur de cette entrée doit être définie sur la région dans laquelle se trouve la ressource associée. La valeur indiquée pour cette entrée peut être l'adresse d'API de la région ou l'identificateur de région de la ressource. Par exemple, si chaque ressource est située dans la région Est des Etats-Unis (Ashburn), l'entrée d'adresse de chaque section peut être indiquée à l'aide de l'identificateur de la région ("us-ashburn-1") ou de l'adresse d'API de la région pour le service souhaité. |
Table - Paramètres dans le fichier de configuration
| Nom de paramètre | Section spécifiée | Détails de la section |
|---|---|---|
| useInstancePrincipal | nosqlstore(Facultatif) objecttore (facultatif) |
L'entrée useInstancePrincipal peut être indiquée comme valeur booléenne True si les conditions suivantes sont remplies :
Si true est indiqué pour l'entrée useInstancePrincipal et que l'entrée d'informations d'identification est également indiquée, l'entrée d'informations d'identification est prioritaire et les informations d'identification utilisateur référencées dans la valeur de cette entrée sont utilisées pour interagir avec la ressource associée. Remarques : Les informations d'identification utilisateur doivent être indiquées dans la section de base de données car la base de données Autonomous AI hébergée dans Oracle Autonomous AI Lakehouse l'exige. |
| compartiment | nosqlstore(Facultatif) objecttore (facultatif) |
|
| credentials | nosqlstore(Facultatif) objecttore (facultatif) base de données (obligatoire) |
L'entrée d'informations d'identification est requise dans la section de base de données en toutes circonstances. Elle est requise dans les sections nosqlstore et objecttore dans une ou plusieurs des circonstances suivantes :
La valeur indiquée pour cette entrée doit référencer un fichier sur le système de fichiers local qui spécifie les informations d'identification utilisateur pouvant être utilisées pour interagir en toute sécurité avec la ressource associée. |
| Informations d'identificationProfil | nosqlstore(Facultatif) objecttore (facultatif) base de données (facultatif) |
L'entrée credentialsProfile est facultative dans chaque section et, même si elle est spécifiée, ne s'applique que lorsqu'une entrée d'informations d'identification correspondante est également spécifiée. |
| table | nosqlstore(Obligatoire) | L'entrée de table est obligatoire et doit être spécifiée dans la section nosqlstore. La valeur de cette entrée est une chaîne composée d'une liste de noms séparés par des virgules. Chaque nom référence le nom d'une table dans le service NoSQL Database Cloud dont le contenu doit être extrait et copié dans Oracle Autonomous AI Lakehouse. |
| readUnitsPercent | nosqlstore(Facultatif) | L'entrée readUnitsPercent est facultative et s'applique uniquement dans la section nosqlstore. La valeur de cette entrée est une chaîne composée d'une liste d'entiers séparés par des virgules, comprise entre 1 et 100, représentant le pourcentage d'unités de lecture pouvant être consommées lors de l'extraction de données de la table correspondante. Cette entrée vous permet d'indiquer des pourcentages d'unités de lecture différents pour chacune des tables référencées dans l'entrée de table. Lorsque le premier pourcentage de la liste correspond à la première table de la liste des tables, le deuxième pourcentage correspond à la deuxième table, etc. Il n'est pas nécessaire que le nombre de pourcentages de cette liste soit égal au nombre de tables de la liste. Une valeur par défaut de 90 % est affectée à toute table de la liste des tables qui n'a pas de pourcentage correspondant dans cette liste. Par exemple, supposons que quatre noms de table soient spécifiés dans l'entrée de table, mais que l'entrée readUnitsPercent soit définie sur la valeur "50,80". Dans ce cas, les données de la première table seront extraites à l'aide de 50 % des unités de lecture disponibles, tandis que 80 % des unités de lecture seront utilisées lors de l'extraction des données de la deuxième table. Enfin, pour les deux tables restantes, 90 % des unités de lecture (valeur par défaut) seront utilisées lors de l'extraction des données de chacune de ces tables. |
| RequestTimeoutMs | nosqlstore(Facultatif) | L'entrée requestTimeoutMs est facultative et s'applique uniquement dans la section nosqlstore. La valeur de cette entrée est une chaîne composée d'une liste d'entiers positifs séparés par des virgules. Chaque entier représente le nombre de millisecondes autorisé pour chaque demande d'extraction de données à terminer pour la table correspondante. Cette entrée vous permet de spécifier différentes valeurs de délai d'expiration pour chacune des tables référencées dans l'entrée de table. Si cette entrée n'est pas spécifiée, ou si elle spécifie un délai d'expiration pour un seul sous-ensemble des tables, la valeur par défaut 5000 sera affectée aux tables restantes. |
| bucket | objecttore(Obligatoire) | L'entrée de bucket est obligatoire et doit être indiquée dans la section objectstore. La valeur de cette entrée est une chaîne représentant le nom du bucket OCI Object Storage, dans lequel l'utilitaire copie les données extraites des tables NoSQL. |
| compression | objecttore (facultatif) | L'entrée de compression est facultative et s'applique uniquement à la section de banque d'objets. La valeur indiquée pour cette entrée est une chaîne représentant la manière dont les données sont extraites des tables indiquées dans nosqlstore. Si cette option est définie, les données de la table sont compressées lors de la copie vers le stockage d'objets. La valeur spécifiée pour cette entrée doit être l'une des suivantes :
Remarques : Si l'entrée de compression n'est pas spécifiée, une compression rapide est effectuée. |
| databaseName | base de données (obligatoire) | L'entrée dabaseName est obligatoire et doit être spécifiée dans la section de base de données. Cette entrée est une chaîne dont la valeur est le nom de la base de données créée dans Oracle Autonomous AI Lakehouse Cloud Service. |
| utilisateur de base de données | base de données (facultatif) | L'entrée databaseUser est facultative et doit être spécifiée dans la section database. Cette entrée est une chaîne dont la valeur est le nom du compte utilisateur dans la base de données Autonomous AI indiquée dans l'entrée dabaseName. Si cette entrée n'est pas spécifiée, vous êtes invité à fournir la valeur dans la ligne de commande. |
| Portefeuille de base de données | base de données (obligatoire) | L'entrée databaseWallet est obligatoire et doit être indiquée dans la section de base de données. Cette entrée est une chaîne dont la valeur est le chemin du système de fichiers vers le répertoire contenant le contenu d'Oracle Wallet téléchargé à partir du compte utilisateur de base de données Autonomous AI indiqué dans l'entrée databaseUser du fichier de configuration. |
| AbortOnError | Facultatif | Indique l'action à effectuer face à une erreur. La valeur par défaut est True. |
Remarque : chaque entrée du fichier de configuration peut être remplacée sur la ligne de commande en définissant une propriété système avec le nom du formulaire, section.entry par exemple, -Dnosqlstore.table=tableName1,tableName3. Si une entrée n'est pas située dans une section, le nom à utiliser pour une telle propriété est simplement le nom de l'entrée elle-même ; par exemple, -DabortOnError=false. Cette fonctionnalité peut être utile lors du test ou de l'écriture de scripts qui exécutent l'utilitaire à intervalles réguliers.
Spécification des informations de configuration dans le fichier d'informations d'identification :
Oracle Cloud Infrastructure requiert des informations de configuration de base, telles que les informations d'identification utilisateur, l'OCID de location, etc., qui peuvent être indiquées dans le fichier de configuration. L'emplacement par défaut de ce fichier de configuration est ~/.oci. Vous pouvez spécifier plusieurs ensembles d'informations d'identification utilisateur dans ce fichier de configuration.
Un exemple de fichier d'informations d'identification est présenté ci-dessous.
[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>Remarque : dans le fichier de configuration ci-dessus, il existe trois entrées distinctes pour nosql-db-user, objectstorage-user et adw-user. Ce n'est pas obligatoire et un fichier de configuration ne peut exister qu'avec un seul profil DEFAULT. Toutefois, il est recommandé de disposer de profils distincts plutôt que de combiner tous les paramètres du profil DEFAULT.
| Nom de paramètre | Détails du paramètre |
|---|---|
| user | OCID de l'utilisateur |
| empreinte | Séquence courte d'octets utilisée pour identifier une clé publique plus longue pour l'utilisateur par défaut |
| fichier de clés | Chemin/nom de fichier du fichier contenant la clé privée de l'utilisateur par défaut |
| location | OCID de la location |
| régions | Adresse de la région |
| compartiment | nom de compartiment ou OCID du compartiment de l'utilisateur par défaut |
| dbmsOcid | OCID de la base de données Autonomous AI |
| dbmsCredentialName | Nom des informations d'identification que la base de données Oracle Autonomous AI Lakehouse utilisera pour l'authentification auprès d'Object Storage. Il s'agit du nom OCI$RESOURCE_PRINCIPAL (si vous choisissez d'utiliser l'authentification de principal de ressource) ou du nom des informations d'identification AUTH_TOKEN créées lorsque la procédure DBMS_CLOUD.CREATE_CREDENTIAL est exécutée par l'utilisateur ou l'administrateur système (par exemple, NOSQLADWDB_OBJ_STORE_CREDENTIAL ). |
Exécution de l'outil
Une fois toutes les exigences d'utilisation des services Oracle Cloud nécessaires (NoSQL Database, Object Storage et Oracle Autonomous AI Lakehouse) terminées et qu'un fichier de configuration valide a été créé, Oracle NoSQL Database Analytics Integrator peut être exécuté en saisissant simplement une commande sur la ligne de commande.
-
Accédez au répertoire nosqlanalytics sous le répertoire d'installation
(/home/opc/nosqlanalytics-<version>).cd /home/opc/nosqlanalytics-1.0.1/nosqlanalytics -
Appelez l'utilitaire à l'aide de la commande suivante. Le fichier de configuration
oci-nosqlanalytics-config.jsonse trouve dans le répertoire.ocidu répertoire de base.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
Remarque : les propriétés système qui configurent les journaliseurs utilisés lors de l'exécution sont facultatives. Si ces propriétés système ne sont pas spécifiées, l'utilitaire ne génère aucune sortie de journalisation.
Logging
Oracle NoSQL Database Analytics Integrator exécute le logiciel à partir de plusieurs bibliothèques tierces, où chaque bibliothèque définit son propre ensemble de journaliseurs avec différents espaces de noms. Pour plus de commodité, Oracle NoSQL Database Analytics Integrator fournit deux fichiers de configuration de journalisation dans la version, l'un pour configurer les mécanismes de journalisation basés sur java.util.logging et l'autre pour les journaliseurs basés sur Log4j2.
Remarque : Par défaut, les fichiers de configuration du journaliseur fournis avec l'utilitaire sont conçus pour produire une sortie minimale lors de l'exécution de l'utilitaire. Mais si vous souhaitez voir la sortie détaillée des différents composants utilisés par l'utilitaire, vous devez augmenter les niveaux de journalisation des journaliseurs spécifiques dont vous souhaitez analyser le comportement.