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">
|
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:
- Clé privée Google Workspace, qui contient également l'ID du compte de service. Pour savoir comment obtenir une clé privée, accédez à Configurer l'accès à Google Cloud Recherche dans l'API REST
- ID de la source de données Google Workspace. Pour savoir comment obtenir un ID de source de données, consultez Ajoutez une source de données pour la recherche.
Étape 1 : Télécharger et créer le logiciel du connecteur de base de données
- Clonez le dépôt du connecteur depuis GitHub.
$ git clone https://github.com/google-cloudsearch/database-connector.git $ cd database-connector
- Vérifiez la version souhaitée du connecteur:
$ git checkout tags/v1-0.0.3
- Créez le connecteur.
Pour ignorer les tests lors de la création du connecteur, utilisez$ mvn package
mvn package -DskipTests
. - 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
- 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. - 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. 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éesmysql-connector-java-5.1.41-bin.jar
est le pilote JDBC utilisé. pour accéder à la base de donnéesmysql.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 utiliseconnector-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 |
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 :
|
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
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 |
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. |