Déployer un connecteur de base de données

Avertissement: Les connecteurs de référence de Cloud Search sont fournis "en l'état" comme exemple de code pour créer vos propres connecteurs de travail. Cet exemple de code requiert une personnalisation et des tests importants avant d'être utilisés dans une démonstration de faisabilité ou environnements de production. Pour une utilisation en production, nous vous recommandons vivement d'obtenir de l'aide proposé par l'un de nos partenaires Cloud Search. Si vous avez besoin d'aide pour trouver un Cloud Partenaire du Réseau de Recherche : contactez votre responsable de compte Google.

Vous pouvez configurer Google Cloud Search pour découvrir et indexer des données à 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 compatibles avec l'exécution d'applications Java, à condition que le connecteur ait accès aux deux Internet et la base de données.

Configuration requise

Configuration requise
Système d'exploitation Windows ou Linux
Base de données SQL Toute base de données SQL dotée d'un pilote JDBC 4.0 ou version ultérieure, y compris les suivantes:
<ph type="x-smartling-placeholder">
    </ph>
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Logiciel Pilote JDBC que le connecteur doit utiliser pour 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 et configurer le connecteur pour indexer les bases de données spécifiées et renvoyer les résultats aux utilisateurs de Cloud Search.

Prérequis

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, puis 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. Ce que Google recommande que vous nommez les fichiers de configuration avec l'.properties ou .config et conservez le fichier dans le même répertoire que le connecteur. Si vous utilisez un autre nom ou chemin, 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, à l'accès à la base de données, à une instruction SQL de balayage complet de 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. Par 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 Référence des paramètres de configuration à la fin de cet article.

    Pour en savoir plus sur les paramètres communs à tous les environnements Cloud Search comme la configuration des métadonnées, les formats de date et d'heure ou les options de LCA, accédez à <ph type="x-smartling-placeholder"></ph> Paramètres de connecteur fournis par Google.

    Le cas échéant, spécifiez les propriétés de l'objet de schéma dans la requête SQL de balayage paramètres de requête. En général, vous pouvez ajouter des alias à la requête SQL . Par exemple, si vous avez un film base de données, tandis que le schéma de la 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 sur 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 correspond à 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 de configuration, spécifiez son chemin d'accès dans la ligne de commande. Sinon, le connecteur utilise connector-config.properties dans votre région comme nom de fichier par défaut.

Le connecteur signale les erreurs de configuration dès qu'il les détecte. Certaines erreurs sont signalées le connecteur s'initialise, par exemple lorsqu'une colonne de base de données est définie dans le contenu de l'enregistrement. (dans db.allColumns), mais elle n'est pas utilisée dans la requête SQL de balayage (dans db.allRecordsSql). Les autres erreurs ne sont détectées et signalées le connecteur tente d'accéder à la base de données pour le premier balayage (en cas de syntaxe d'instruction SQL incorrecte, par exemple).

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

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

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

Obligatoire. Cloud Search ID de source configuré par l'administrateur Google Workspace.

ID de la source d'identité api.identitySourceId = identity-source-ID

Obligatoire pour l'utilisation d'utilisateurs et de groupes externes pour les LCA. Cloud Search l'ID de la source d'identité configurée par l'administrateur Google Workspace.

Compte de service api.serviceAccountPrivateKeyFile = path-to-private-key

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

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

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

Obligatoire. La 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. Un nom d'utilisateur valide et que le connecteur utilise pour accéder à la base de données. Cet utilisateur de la base de données doit avoir 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 de la classe.

Paramètres de requête SQL de balayage

Le connecteur balaie les enregistrements de la base de données à l'aide de la commande SQL SELECT. dans le fichier de configuration. Vous devez configurer une requête de balayage complet. requêtes pour les balayages incrémentiels sont facultatifs.

Le balayage complet lit tous les enregistrements de la base de données configurés pour l'indexation. Un le balayage est nécessaire pour indexer les nouveaux enregistrements destinés à Cloud Search et pour réindexer tous les enregistrements existants.

Le balayage incrémentiel permet de lire et de réindexer uniquement les bases de données récemment modifiées. des enregistrements et des entrées récentes de la base de données. Les balayages incrémentiels peuvent être plus efficaces lors des balayages complets. Pour utiliser les balayages incrémentiels, votre base de données doit contenir des champs de code temporel pour indiquer les enregistrements modifiés.

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

Paramètre Paramètre
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 utilisé par le connecteur dans (contenu, ID unique, LCA) doit être présente dans cette requête. La le connecteur effectue des vérifications préliminaires au démarrage pour détecter les erreurs et les omissions. Par conséquent, n'utilisez pas la formule "SELECT * FROM ..." requête.

Pagination de balayage complet db.allRecordsSql.pagination = {none | offset}

La valeur peut être :

  • none: n'utilisez pas la pagination.
  • offset: utilise la pagination par décalage de lignes

    Pour utiliser la pagination par décalage, la requête SQL doit comporter un espace réservé pour un point d'interrogation (?) pour un décalage de ligne, en 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 point d'interrogation (?) dans la requête est un espace réservé obligatoire pour une valeur de code temporel. La le connecteur utilise le code temporel pour suivre les modifications entre les requêtes SQL de balayage incrémentiel.

Pour effectuer le suivi de la colonne de code temporel de la base de données correspondant à l'heure de la dernière mise à jour, ajoutez le paramètre timestamp_column de l'instruction SQL Sinon, utilisez l'horodatage actuel lors du balayage du connecteur.

Pour le premier balayage incrémentiel, le connecteur utilise l'heure de début du connecteur. Après le lors du premier balayage incrémentiel, Cloud Search stocke l'horodatage le connecteur redémarré peut accéder au balayage incrémentiel précédent du code temporel.

Fuseau horaire de la base de données db.timestamp.timezone = America/Los_Angeles

Spécifie le fuseau horaire à utiliser pour les horodatages de base de données. Le code temporel de la base de données utilisé pour identifier les nouveaux enregistrements ou des enregistrements de base de données modifiés. La valeur par défaut est le fuseau horaire dans lequel le connecteur est exécuté.

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 des employés à des fins d'indexation:
    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
    

    ou, 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 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 le code temporel 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 et à d'identifier de manière unique chaque enregistrement.

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

Obligatoire. Identifie toutes les colonnes qui sont 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. Toutes les un autre paramètre de définition de colonne est comparé à 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. Liste une seule colonne de base de données contenant des valeurs uniques ou par 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 soit associé à un identifiant unique dans une source de données. Vous devez pouvoir définir un identifiant 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 dans un ensemble de données commun, veillez à spécifier un identifiant unique dans tous les documents.

Exemples :

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

Obligatoire. Spécifie une ou plusieurs valeurs valides, définies Noms des colonnes utilisées pour l'URL d'un résultat de recherche cliquable Pour les bases de données qui n'ont pas d'URL pertinente associée à chaque enregistrement, une vous pouvez utiliser un lien statique pour chaque enregistrement.

Toutefois, si les valeurs des colonnes définissent un lien valide pour chaque enregistrement, la vue Vous devez spécifier les colonnes d'URL 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é dans db.columns, dans l'ordre, en commençant par zéro.

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

Vous trouverez des exemples en dessous de 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 de les inclure dans la chaîne d'URL formatée.

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 sans 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 valeurs de colonnes multiples (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

Utiliser les options de contenu pour définir les valeurs d'enregistrement doit être intégré au contenu inclus dans l'index de recherche.

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

Obligatoire. Colonne de qualité optimale pour l'indexation des recherches 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...]

Désigner des colonnes de contenu (à l'exception de celle définie pour contentTemplate.db.title) que les champs de qualité de recherche élevée, moyenne ou faible. Pour les colonnes non spécifiées, la valeur par défaut est faible.

Colonnes de données de contenu db.contentColumns = column-1[, column-2...]

Spécifiez les colonnes de contenu de la base de données. Ceux-ci sont formatés et importé dans Cloud Search en tant que contenu de document inclus dans l'index de recherche.

Si vous ne spécifiez pas de valeur, la valeur par défaut est "*" indiquant que tous doivent être utilisées pour le contenu.

Colonne Blob db.blobColumn = column-name

Spécifier le nom d'un seul blob à 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, elle est considérée 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 ainsi que les colonnes blob.