Exécution de l'intégrateur d'analyses d'Oracle NoSQL Database

Etapes d'exécution de l'intégrateur d'analyses d'Oracle NoSQL Database.

Créer un fichier de configuration pour l'intégrateur

Avant de pouvoir exécuter l'intégrateur d'analyses d'Oracle NoSQL Database, vous devez 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 illustré dans les exemples ci-dessous. Ce qui suit ne sont que deux exemples de fichiers de configuration. Les paramètres utilisés ci-dessous ne sont pas tous requis. Le tableau ci-dessous explique chaque paramètre utilisé dans l'exemple et met en évidence s'il est facultatif ou obligatoire.

Exemple 1 : Vous exécutez l'utilitaire à partir d'une instance du service 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 données d'identification d'utilisateur ou vous exécutez à partir de l'extérieur d'Oracle Cloud et 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, objectstore et database - dont les entrées sont utilisées pour spécifier comment l'utilitaire interagit avec chaque service en nuage respectif : NoSQL Cloud Service, Oracle ObjectStorage et Oracle Autonomous Data Warehouse.

Certains paramètres sont communs dans les trois sections.

Table - 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 database).
point d'extrémité La valeur de cette entrée doit être réglée à la région dans laquelle se trouve la ressource associée. La valeur spécifiée pour cette entrée peut être le point d'extrémité 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 États-Unis (Ashburn), l'entrée de point d'extrémité de chaque section peut être spécifiée à l'aide de l'identificateur de la région ("US-ashburn-1") ou du point d'extrémité d'API de la région pour le service souhaité.

Table - Paramètres du fichier de configuration

Nom de paramètre Section spécifiée Détails de la section
useInstancePrincipal

nosqlstore(Facultatif)

magasin d'objets (facultatif)
L'entrée useInstancePrincipal peut être spécifiée en tant que valeur booléenne Vrai si les conditions suivantes sont remplies :
  • L'utilitaire sera exécuté à partir d'une instance Oracle Cloud Compute.
  • 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 de données d'identification n'est pas spécifiée
Si Vrai est spécifié pour l'entrée useInstancePrincipal et que l'entrée de données d'identification est également spécifiée, l'entrée de données d'identification a préséance et les données d'identification d'utilisateur référencées dans la valeur de cette entrée seront utilisées pour interagir avec la ressource associée.

Note :

Les données d'identification d'utilisateur doivent être spécifiées dans la section de base de données, car Autonomous Database hébergé dans ADW l'exige.
compartiment

nosqlstore(Facultatif)

magasin d'objets (facultatif)
  • Si Vrai est spécifié pour l'entrée useInstancePrincipal, l'OCID du compartiment contenant cette ressource doit également être spécifié.
  • Si la valeur Faux est spécifiée pour l'entrée useInstancePrincipal ou si l'entrée de données d'identification est spécifiée, l'entrée de compartiment est facultative; bien qu'elle doive être spécifiée dans le fichier référencé par l'entrée de données d'identification.
credentials

nosqlstore(Facultatif)

magasin d'objets (facultatif)

base de données(Obligatoire)
L'entrée des données d'identification est requise dans la section de base de données en toutes circonstances. Elle est requise dans les sections nosqlstore et objectstore dans une ou plusieurs des circonstances suivantes :
  • Soit l'utilitaire sera exécuté de l'extérieur d'Oracle Cloud, soit il sera exécuté à 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 réglée à Faux.

La valeur spécifiée pour cette entrée doit référencer un fichier dans le système de fichiers local qui spécifie les données d'identification de l'utilisateur pouvant être utilisées pour interagir en toute sécurité avec la ressource associée.

credentialsProfile

nosqlstore(Facultatif)

magasin d'objets (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 de données 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, où 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 la base de données Autonomous Data Warehouse.
readUnitsPercent nosqlstore(Facultatif)

L'entrée readUnitsPercent est facultative et s'applique uniquement à 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 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 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 % sera 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 réglée à 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 autres tables, 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 à 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ées 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 temporisation pour chacune des tables référencées dans l'entrée de table. Si cette entrée n'est pas précisée ou si elle précise une temporisation pour un sous-ensemble seulement des tables, la valeur par défaut de 5000 sera affectée aux tables restantes.
bucket magasin d'objets (obligatoire) L'entrée de seau est obligatoire et doit être spécifiée dans la section du magasin d'objets. La valeur de cette entrée est une chaîne représentant le nom du seau de stockage d'objets OCI, dans laquelle l'utilitaire copie les données extraites des tables NoSQL.
compression magasin d'objets (facultatif)
L'entrée de compression est facultative et s'applique uniquement à la section Objectstore. La valeur spécifiée pour cette entrée est une chaîne représentant la façon dont les données sont extraites des tables spécifié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
  • aucun - Ne compressez pas les données de table copiées dans ObjectStorage

Note :

Si l'entrée de compression n'est pas spécifiée, la compression snappy est effectuée.
databaseName base de données(Obligatoire) L'entrée dabaseName est requise 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 le service Oracle Autonomous Data Warehouse Cloud.
databaseUser base de données (Facultatif)

L'entrée databaseUser est facultative 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 du compte d'utilisateur dans Autonomous Database spécifié dans l'entrée dabaseName. Si cette entrée n'est pas spécifiée, vous serez invité dans la ligne de commande à fournir la valeur.
databaseWallet base de données(Obligatoire) L'entrée databaseWallet est requise 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 chemin du système de fichiers vers le répertoire contenant le contenu du portefeuille Oracle Wallet téléchargé à partir du compte d'utilisateur Autonomous Database spécifié dans l'entrée databaseUser du fichier de configuration.
abortOnError Facultatif Indique l'action à entreprendre pour faire face à une erreur. La valeur par défaut est true.

Note :

Chaque entrée du fichier de configuration peut être remplacée sur la ligne de commande en définissant une propriété de 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 fonction 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 de données d'identification :

Oracle Cloud Infrastructure nécessite des informations de configuration de base, telles que les données d'identification d'utilisateur, l'OCID de la location, etc., qui peuvent être spécifiées dans le fichier de configuration. L'emplacement par défaut de ce fichier de configuration est ~/.oci. Vous pouvez spécifier plusieurs jeux de données d'identification d'utilisateur dans ce fichier de configuration.

Un exemple de fichier de données 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>

Note :

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. Cependant, avoir des profils distincts est une bonne pratique plutôt que de combiner tous les paramètres du profil DEFAULT.

Table - Paramètres du fichier de données d'identification

Nom du paramètre Détails du paramètre
user OCID de l'utilisateur
Empreinte numérique 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 Point d'extrémité de la région
compartiment nom ou OCID du compartiment de l'utilisateur par défaut
dbmsOcid OCID de la base de données Autonomous Database
dbmsCredentialName

Il s'agit du nom des données d'identification que la base de données ADW utilisera pour s'authentifier auprès du stockage d'objets. Il s'agit du nom OCI$RESOURCE_PRINCIPAL (si vous choisissez d'utiliser l'authentification de principal de ressource) ou du nom des données d'identification AUTH_TOKEN créées lorsque la procédure DBMS_CLOUD.CREATE_CREDENTIAL est exécutée par l'utilisateur ou l'administrateur de système (par exemple, NOSQLADWDB_OBJ_STORE_CREDENTIAL ).

Exécution de l'outil

Une fois toutes les exigences requises pour utiliser les services Oracle Cloud (NoSQL Database, Object Storage et Autonomous Data Warehouse) terminées et un fichier de configuration valide créé, l'intégrateur d'analyses d'Oracle NoSQL Database peut être exécuté en entrant simplement une commande sur la ligne de commande.
  • Naviguez jusqu'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

Note :

Les propriétés système qui configurent les enregistreurs de journal 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 produira aucune sortie de journalisation.

Rubriques connexes

Journalisation

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

Note :

Par défaut, les fichiers de configuration de l'enregistreur automatique 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 verbose des différents composants utilisés par l'utilitaire, vous devez augmenter les niveaux de journalisation des enregistreurs spécifiques dont vous souhaitez analyser le comportement.