Déployer un connecteur de base de données

Avertissement: Les connecteurs de référence Cloud Search sont fournis "en l'état" sous forme d'exemple de code afin de vous permettre de créer vos propres connecteurs de travail. Cet exemple de code nécessite une personnalisation et des tests importants avant d'être utilisé dans des environnements de démonstration de faisabilité ou de production. Pour une utilisation en production, nous vous recommandons vivement d'obtenir l'aide de l'un de nos partenaires Cloud Search. Si vous avez besoin d'aide pour trouver un partenaire Cloud Search adapté, contactez votre responsable de compte Google.

Vous pouvez configurer Google Cloud Search de sorte qu'il découvre et indexe les données des bases de données de votre organisation à l'aide du connecteur de base de données Google Cloud Search.

Remarques importantes

Vous pouvez installer et exécuter le connecteur de base de données Cloud Search dans presque tous les environnements permettant l'exécution d'applications Java, à condition que le connecteur ait accès à Internet et à la base de données.

Configuration système requise

Configuration système requise
Système d'exploitation Windows ou Linux
Base de données SQL Toute base de données SQL avec un pilote compatible avec JDBC 4.0 ou version ultérieure, y compris les suivantes:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Logiciels Pilote JDBC permettant au connecteur d'accéder à la base de données (téléchargé et installé séparément)

Déployer le connecteur

Les étapes suivantes décrivent comment installer le connecteur et le configurer pour indexer les bases de données spécifiées et renvoyer les résultats aux utilisateurs de Cloud Search.

Conditions préalables

Avant de déployer le connecteur de base de données Cloud Search, rassemblez les informations suivantes:

Étape 1 : Télécharger et créer le logiciel du connecteur de base de données

  1. Clonez le dépôt du connecteur depuis GitHub. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. Vérifiez la version souhaitée du connecteur:
    $ git checkout tags/v1-0.0.3
  3. Créez le connecteur. 
    $ mvn package
    Pour ignorer les tests lors de la création du connecteur, utilisez mvn package -DskipTests.
  4. Copiez le fichier ZIP du connecteur dans votre répertoire d'installation local et décompressez-le : 
    $ cp target/google-cloudsearch-database-connector-v1-0.0.3.zip installation-dir
$ cd installation-dir
$ unzip google-cloudsearch-database-connector-v1-0.0.3.zip
$ cd google-cloudsearch-database-connector-v1-0.0.3

Étape 2 : Configurer le connecteur de base de données

  1. Créez un fichier texte et nommez-le connector-config.properties (par défaut) ou un nom similaire. Google vous recommande de nommer les fichiers de configuration avec l'extension .properties ou .config et de les conserver dans le même répertoire que le connecteur. Si vous utilisez un nom ou un chemin d'accès différents, vous devez spécifier le chemin d'accès lorsque vous exécutez le connecteur.
  2. Ajoutez des paramètres sous forme de paires clé/valeur aux contenus des fichiers. Le fichier de configuration doit spécifier les paramètres d'accès à la source de données et à la base de données, une instruction SQL de balayage complet à la base de données, un titre de champ de contenu et des définitions de colonne. Vous pouvez également configurer d'autres comportements de connecteur avec des paramètres facultatifs. Exemple : 
    # Required parameters for data source access
api.sourceId=1234567890abcdef
api.identitySourceId=0987654321lmnopq
api.serviceAccountPrivateKeyFile=./PrivateKey.json
#
# Required parameters for database access
db.url=jdbc:mysql://localhost:3306/mysql_test
db.user=root
db.password=passw0rd
#
# Required full traversal SQL statement parameter
db.allRecordsSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book
#
# Required parameters for column definitions and URL format
db.allColumns=customer_id, first_name, last_name, phone, change_timestamp
db.uniqueKeyColumns=customer_id
url.columns=customer_id
#
# Required content field parameter
contentTemplate.db.title=customer_id
#
# Optional parameters to set ACLs to "entire domain" access
defaultAcl.mode=fallback
defaultAcl.public=true
#
# Optional parameters for schedule traversals
schedule.traversalIntervalSecs=36000
schedule.performTraversalOnStart=true
schedule.incrementalTraversalIntervalSecs=3600

    Pour obtenir une description détaillée des paramètres spécifiques à la base de données, consultez la documentation de référence sur les paramètres de configuration à la fin de cet article.

    Pour en savoir plus sur les paramètres communs à tous les connecteurs Cloud Search, tels que la configuration des métadonnées, les formats de date et d'heure et les options de LCA, consultez la page Paramètres de connecteur fournis par Google.

    Le cas échéant, spécifiez les propriétés de l'objet de schéma dans les paramètres de requête SQL de balayage. En règle générale, vous pouvez ajouter des alias à l'instruction SQL. Par exemple, si vous disposez d'une base de données de films et que le schéma de source de données contient une définition de propriété nommée "ActorName", une instruction SQL peut prendre la forme suivante: SELECT …, last_name AS ActorName, … FROM … .

Étape 3. Exécuter le connecteur de base de données

L'exemple suivant suppose que les composants requis se trouvent dans le répertoire local d'un système Linux.

Pour exécuter le connecteur à partir de la ligne de commande, saisissez la commande suivante: 

java \
   -cp "google-cloudsearch-database-connector-v1-0.0.3.jar:mysql-connector-java-5.1.41-bin.jar" \
   com.google.enterprise.cloudsearch.database.DatabaseFullTraversalConnector \
   [-Dconfig=mysql.config]

Où :

  • google-cloud-search-database-connector-v1-0.0.3.jar est le fichier .jar du connecteur de base de données.
  • mysql-connector-java-5.1.41-bin.jar est le pilote JDBC utilisé pour accéder à la base de données.
  • mysql.config est un fichier de configuration portant un nom personnalisé. Pour vous assurer que le connecteur reconnaît votre fichier de configuration, indiquez son chemin d'accès dans la ligne de commande. Sinon, le connecteur utilisera le nom de fichier par défaut connector-config.properties stocké dans votre répertoire local.

Le connecteur signale les erreurs de configuration dès qu'il les détecte. Certaines erreurs sont signalées lors de l'initialisation du connecteur, par exemple lorsqu'une colonne de base de données est définie dans le contenu de l'enregistrement (dans db.allColumns), mais que la colonne n'est pas utilisée dans la requête SQL de balayage de la base de données (dans db.allRecordsSql). D'autres erreurs ne sont détectées et signalées que lorsque le connecteur tente d'accéder à la base de données pour le premier balayage, comme des instructions SQL incorrectes.

Documentation de référence sur les paramètres de configuration

Paramètres d'accès à la source de données

Paramètre Paramètres
ID de la source de données api.sourceId = source-ID

Obligatoire. ID de la source Cloud Search configuré par l'administrateur Google Workspace.
ID de la source d'identité api.identitySourceId = identity-source-ID

Requis pour l'utilisation d'utilisateurs et de groupes externes pour les LCA. ID de la source d'identité Cloud Search configuré par l'administrateur Google Workspace.
Compte de service api.serviceAccountPrivateKeyFile = path-to-private-key

Obligatoire. Chemin d'accès au fichier de clé du compte de service Cloud Search créé par l'administrateur Google Workspace.

Paramètres d'accès à la base de données

Paramètre Paramètres
URL de la base de données db.url = database-URL

Obligatoire. Chemin d'accès complet de la base de données concernée, par exemple jdbc:mysql://127.0.0.1/dbname.
Nom d'utilisateur et mot de passe de la base de données db.user = username
db.password = password

Obligatoire. Nom d'utilisateur et mot de passe valides permettant au connecteur d'accéder à la base de données. Cet utilisateur de base de données doit disposer d'un accès en lecture aux enregistrements pertinents de la base de données en cours de lecture.
Pilote JDBC db.driverClass = oracle.jdbc.OracleDriver

Obligatoire uniquement si le pilote JDBC 4.0 n'est pas déjà spécifié dans le chemin d'accès de la classe.

Paramètres de requête SQL de balayage

Le connecteur balaie les enregistrements de base de données à l'aide de requêtes SQL SELECT dans le fichier de configuration. Vous devez configurer une requête de balayage complet, mais les requêtes de balayage incrémentiel sont facultatives.

Le balayage complet permet de lire tous les enregistrements de base de données configurés pour l'indexation. Un balayage complet est nécessaire pour indexer les nouveaux enregistrements pour Cloud Search, ainsi que pour réindexer tous les enregistrements existants.

Le balayage incrémentiel permet de lire et de réindexer uniquement les enregistrements de base de données récemment modifiés et les entrées récentes dans la base de données. Les balayages incrémentiels peuvent s'avérer plus efficaces que les balayages complets. Pour utiliser les balayages incrémentiels, votre base de données doit contenir des champs d'horodatage indiquant les enregistrements modifiés.

Le connecteur exécute ces balayages selon le planning que vous avez défini dans les paramètres de planification des balayages.

Paramètre Paramètres
Requête de balayage complet db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

Obligatoire. Requête exécutée pour chaque balayage complet.

Chaque nom de colonne que le connecteur utilisera, quel que soit son degré de capacité (contenu, identifiant unique, LCA) doit être présent dans cette requête. Le connecteur effectue quelques vérifications préliminaires au démarrage pour détecter les erreurs et les omissions. Pour cette raison, n'utilisez pas une requête générale "SELECT * FROM ...".
Pagination de balayage complet db.allRecordsSql.pagination = {none | offset}

La valeur peut être :

  • none: aucune pagination
  • offset: utiliser la pagination par décalage de ligne

    Si vous souhaitez utiliser la pagination par décalage, la requête SQL doit comporter un point d'interrogation dans l'espace réservé (?) correspondant à un décalage de ligne, commençant par zéro. Lors de chaque balayage complet, la requête est exécutée plusieurs fois jusqu'à ce qu'aucun résultat ne soit renvoyé.
Requête de balayage incrémentiel db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

Obligatoire si vous planifiez des balayages incrémentiels.

Le "?" de la requête est un espace réservé obligatoire pour une valeur d'horodatage. Le connecteur utilise l'horodatage pour suivre les modifications entre les requêtes SQL de balayage incrémentiel.

Pour effectuer le suivi de la colonne d'horodatage de la dernière mise à jour, ajoutez l'alias timestamp_column à l'instruction SQL. Sinon, utilisez l'horodatage actuel du balayage effectué par le connecteur.

Pour le premier balayage incrémentiel, le connecteur utilise l'heure de début du connecteur. Après le premier balayage incrémentiel, Cloud Search stocke l'horodatage afin que les redémarrages du connecteur puissent accéder à l'horodatage précédent.
Fuseau horaire de la base de données db.timestamp.timezone = America/Los_Angeles

Spécifie le fuseau horaire à utiliser pour les codes temporels de la base de données. Horodatage de la base de données permettant d'identifier les nouveaux enregistrements ou les enregistrements modifiés dans la base de données. La valeur par défaut est le fuseau horaire local dans lequel le connecteur s'exécute.

Exemples de requêtes SQL de balayage

  • Requête de balayage complet de base qui lit tous les enregistrements intéressants dans une base de données d'employés à indexer : 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • Spécifiez la pagination par décalage et divisez un balayage complet en plusieurs requêtes.

    Pour SQL Server 2012 ou Oracle 12c (syntaxe SQL standard 2008):

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id OFFSET ? ROWS FETCH FIRST 1000 ROWS ONLY
db.allRecordsSql.pagination = offset

    Pour MySQL ou Google Cloud SQL:

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id LIMIT 1000 OFFSET ?
db.allRecordsSql.pagination = offset
  • Requête de balayage complet qui applique des LCA individuelles avec alias : 
    db.allRecordsSql = SELECT customer_id, first_name, last_name,  employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee
  • Requête de balayage incrémentiel de base : 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • Requête de balayage incrémentiel qui applique des LCA individuelles avec des alias : 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee \
     WHERE last_update_time > ?
  • Requête de balayage incrémentiel utilisant l'horodatage de la base de données plutôt que l'heure actuelle : 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, \
     last_update_time AS timestamp_column \
     FROM employee \
     WHERE last_update_time > ?

Paramètres de définition des colonnes

Les paramètres suivants spécifient les colonnes à utiliser dans les instructions de balayage pour identifier chaque enregistrement de manière unique.

Paramètre Paramètres
Toutes les colonnes db.allColumns = column-1, column-2, ...column-N

Obligatoire. Identifie toutes les colonnes requises dans une requête SQL lors de l'accès à la base de données. Les colonnes définies avec ce paramètre doivent être explicitement référencées dans les requêtes. Tous les autres paramètres de définition de colonne sont comparés à cet ensemble de colonnes.

Exemple :

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
Colonnes à clé unique db.uniqueKeyColumns = column-1[, column-2]

Obligatoire. Répertorie soit une seule colonne de base de données contenant des valeurs uniques, soit une combinaison de colonnes dont les valeurs ensemble définissent un identifiant unique.

Cloud Search exige que chaque document inclus dans l'index de recherche possède un identifiant unique au sein d'une source de données. Vous devez être en mesure de définir un ID unique pour chaque enregistrement de base de données à partir des valeurs des colonnes. Si vous exécutez plusieurs connecteurs sur des bases de données distinctes mais que vous les indexez dans un ensemble de données commun, veillez à spécifier un identifiant unique pour tous les documents.

Exemples :

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
Colonne "Lien de l'URL" url.columns = column-1[, column-2]

Obligatoire. Spécifie un ou plusieurs noms valides définis pour les colonnes utilisées pour l'URL associée à un résultat de recherche cliquable. Pour les bases de données dans lesquelles aucune URL pertinente n'est associée à chaque enregistrement, un lien statique peut être utilisé pour chaque enregistrement.

Toutefois, si les valeurs des colonnes définissent un lien valide pour chaque enregistrement, vous devez spécifier les colonnes de l'URL d'affichage et les valeurs de configuration du format.
Format d'URL url.format = https://www.example.com/{0}

Définit le format de l'URL d'affichage. Les paramètres numérotés font référence aux colonnes spécifiées dans db.columns, dans l'ordre, en commençant par la valeur zéro.

Si aucune valeur n'est spécifiée, la valeur par défaut est "{0}.".

Vous trouverez des exemples dans ce tableau.
Colonnes encodées en pourcentage pour l'URL url.columnsToEscape = column-1[, column-2]

Spécifie les colonnes de db.columns dont les valeurs seront encodées en pourcentage avant d'être incluses dans la chaîne d'URL mise en forme.

Exemples de colonnes d'URL

Pour spécifier les colonnes utilisées dans les requêtes de balayage et le format de l'URL d'affichage:

  • Pour utiliser une URL statique qui n'utilise aucune valeur d'enregistrement de base de données : 
    url.format = https://www.example.com
  • Pour utiliser une valeur de colonne unique correspondant à l'URL d'affichage : 
    url.format = {0}
url.columns = customer_id
  • Pour utiliser une valeur de colonne unique remplacée dans l'URL d'affichage à la position {0} : 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • Pour créer l'URL d'affichage à l'aide de plusieurs valeurs de colonnes (les colonnes dépendent de l'ordre) : 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

Champs de contenu

À l'aide des options de contenu, définissez les valeurs d'enregistrement à inclure dans le contenu interrogeable.

Paramètre Paramètres
Colonne de recherche de la plus haute qualité contentTemplate.db.title = column-name

Obligatoire. Colonne de qualité la plus élevée pour l'indexation de la recherche et la hiérarchisation des résultats.
Hiérarchisation des colonnes pour la recherche contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

Attribuez aux colonnes de contenu (à l'exception de celles définies pour contentTemplate.db.title) une qualité de recherche élevée, moyenne ou faible. La valeur par défaut des colonnes non spécifiées est faible.
Colonnes de données de contenu db.contentColumns = column-1[, column-2...]

Spécifiez les colonnes de contenu dans la base de données. Ces fichiers sont mis en forme et importés dans Cloud Search sous forme de contenu de document interrogeable.

Si vous ne spécifiez pas de valeur, la valeur par défaut est "*", indiquant que toutes les colonnes doivent être utilisées pour le contenu.
Colonne Blob db.blobColumn = column-name

Spécifiez le nom d'une colonne d'objet blob unique à utiliser pour le contenu du document au lieu d'une combinaison de colonnes de contenu.

Si une colonne d'objet blob est spécifiée, cela est considéré comme une erreur si des colonnes de contenu sont également définies. Toutefois, les définitions des colonnes de métadonnées et de données structurées sont toujours autorisées avec les colonnes d'objets blob.