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

Pour pouvoir exécuter Oracle NoSQL Database Analytics Integrator, vous devez d'abord créer un fichier de configuration. Ce fichier de configuration sera utilisé lors de l'appel de l'utilitaire. Le fichier de configuration doit contenir les entrées au format JSON, comme indiqué dans les exemples ci-dessous. Vous trouverez ci-dessous deux exemples de fichiers de configuration. Tous les paramètres utilisés ci-dessous ne sont pas requis. Le tableau ci-dessous explique chaque paramètre utilisé dans l'exemple et met en évidence s'il est facultatif ou requis.

Exemple 1 : vous exécutez l'utilitaire à partir d'une instance de calcul Oracle Cloud 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 êtes en cours d'exécution en dehors d'Oracle Cloud. Par conséquent, l'authentification par principal d'instance n'est 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, objectstore 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 ObjectStorage et Oracle Autonomous Data Warehouse.

Certains paramètres sont communs aux trois sections.

Tableau - Paramètres communs pour 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 de base de données).
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)

objectstore (facultatif)
L'entrée useInstancePrincipal peut être spécifiée en tant que valeur booléenne True si les conditions suivantes sont remplies :
  • L'utilitaire sera exécuté à partir d'une instance de calcul Oracle Cloud.
  • La section en cours de configuration n'est pas la section de base de données
  • L'instance de calcul est autorisée, en tant que principal d'instance, à effectuer des actions sur la ressource référencée dans la section en cours de configuration
  • L'entrée d'informations d'identification n'est pas spécifiée
Si true est spécifié pour l'entrée useInstancePrincipal et que l'entrée d'informations d'identification est également spécifié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 l'instance Autonomous Database hébergée dans ADW l'exige.
compartiment

nosqlstore (facultatif)

objectstore (facultatif)
  • Si la valeur True est indiquée pour l'entrée useInstancePrincipal, l'OCID du compartiment contenant cette ressource doit également être indiqué.
  • Si la valeur False est indiquée pour l'entrée useInstancePrincipal ou si l'entrée d'informations d'identification est indiquée, l'entrée de compartiment est facultative, bien qu'elle doive être indiquée dans le fichier référencé par l'entrée d'informations d'identification.
credentials

nosqlstore (facultatif)

objectstore (facultatif)

Base de données (obligatoire)
L'entrée d'informations d'identification est requise dans la section Base de données en toutes circonstances. Elle est requise dans les sections nosqlstore et objectstore dans une ou plusieurs des circonstances suivantes :
  • L'utilitaire sera exécuté à partir de l'extérieur d'Oracle Cloud ou à partir d'une instance de calcul Oracle Cloud qui n'est pas un principal d'instance
  • L'entrée useInstancePrincipal n'est pas spécifiée ou est définie sur False.

La valeur spécifié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.

credentialsProfile

nosqlstore (facultatif)

objectstore (facultatif)

base de données (facultatif)

L'entrée credentialsProfile est facultative dans chaque section et, même si elle est spécifiée, s'applique uniquement 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 fait référence au nom d'une table du service NoSQL Database Cloud dont le contenu doit être extrait et copié vers Autonomous Data Warehouse.
readUnitsPercent nosqlstore (facultatif)

L'entrée readUnitsPercent est facultative et ne s'applique que 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 ; entre 1 et 100, représentant le pourcentage d'unités de lecture pouvant être consommées lors de l'extraction des données de la table correspondante.

Cette entrée vous permet de spécifier des pourcentages d'unités de lecture différents pour chacune des tables référencées dans l'entrée de table ; où le premier pourcentage de la liste correspond à la première table de la liste de tables, le deuxième pourcentage correspond à la deuxième table, etc. Il n'est pas obligatoire que le nombre de pourcentages de cette liste soit égal au nombre de tables de la liste. Une valeur par défaut de 90 % sera affectée à toute table de la liste 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 ne s'applique que 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, où 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 objectstore (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 objectstore (facultatif)
L'entrée de compression est facultative et s'applique uniquement à la section de la banque d'objets. La valeur indiquée pour cette entrée est une chaîne représentant la façon 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 dans le stockage d'objets. La valeur spécifiée pour cette entrée doit être l'une des suivantes :
  • snappy - pour une compression rapide
  • gzip - pour la compression gzip
  • none - ne pas compresser les données de table copiées dans ObjectStorage

Remarques :

Si l'entrée de compression n'est pas spécifiée, la compression snappy sera effectuée.
databaseName Base de données (obligatoire) L'entrée dabaseName est requise 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 nom de la base de données créée dans Oracle Autonomous Data Warehouse Cloud Service.
databaseUser base de données (facultatif)

L'entrée databaseUser est facultative 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 nom du compte utilisateur dans l'instance Autonomous Database indiquée dans l'entrée dabaseName. Si cette entrée n'est pas spécifiée, vous serez invité dans la ligne de commande à la fournir.
databaseWallet Base de données (obligatoire) L'entrée databaseWallet est requise 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 Autonomous Database indiqué dans l'entrée databaseUser du fichier de configuration.
abortOnError Facultatif Indique l'action à effectuer en cas d'erreur. La valeur par défaut est True.

Remarques :

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 de la forme, 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.

Voici un exemple de fichier d'informations d'identification.
[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>

Remarques :

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é d'utiliser des profils distincts plutôt que de combiner tous les paramètres du profil DEFAULT.

Table - Paramètres dans le fichier d'informations d'identification

Nom de paramètre Détails du paramètre
user OCID de l'utilisateur
empreinte Une courte séquence 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 l'instance Autonomous Database
dbmsCredentialName

Il s'agit du nom des informations d'identification que la base de données ADW utilisera pour l'authentification auprès d'Object Storage. Il s'agit soit du nom OCI$RESOURCE_PRINCIPAL (si vous choisissez d'utiliser l'authentification par principal de ressource), soit 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 que toutes les exigences relatives à l'utilisation des services Oracle Cloud nécessaires (NoSQL Database, Object Storage et Autonomous Data Warehouse) ont été remplies 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.json est présent sous le répertoire .oci dans le 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

Remarques :

Les propriétés système qui configurent les journaliseurs utilisés pendant 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.

Rubriques connexes

Logging

Oracle NoSQL Database Analytics Integrator exécute des logiciels à partir de plusieurs bibliothèques tierces, où chaque bibliothèque définit son propre ensemble de journaliseurs avec des espaces de noms différents. Pour plus de commodité, Oracle NoSQL Database Analytics Integrator fournit deux fichiers de configuration de journalisation dans la version : un pour configurer des mécanismes de journalisation basés sur java.util.logging et un pour les journaliseurs basés sur Log4j2.

Remarques :

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. Toutefois, si vous souhaitez afficher une 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.