Avviso: i connettori di riferimento di Cloud Search vengono forniti "così come sono" come codice di esempio da utilizzare per la creazione di connettori funzionanti. Questo codice campione richiede una personalizzazione e test significativi prima di essere utilizzato in ambienti di produzione o proof of concept. Per l'uso in produzione, ti consigliamo di chiedere assistenza a uno dei nostri partner Cloud Search. Per ulteriori informazioni su come trovare un partner Cloud Search adatto, contatta il tuo account manager Google. |
Puoi configurare Google Cloud Search per rilevare e indicizzare i dati dei database della tua organizzazione utilizzando il connettore di database Google Cloud Search.
Considerazioni importanti
Puoi installare ed eseguire il connettore per database Cloud Search in quasi tutti gli ambienti in cui possono essere eseguite app Java, a condizione che il connettore abbia accesso sia a internet sia al database.
Requisiti di sistema
Requisiti di sistema | |
---|---|
Sistema operativo | Windows o Linux |
Database SQL | Qualsiasi database SQL con un driver compatibile con JDBC 4.0 o versioni successive, incluso quanto segue:
|
streaming | Driver JDBC del connettore da utilizzare per accedere al database (scaricato e installato separatamente) |
Eseguire il deployment del connettore
I passaggi seguenti descrivono come installare il connettore e configurarlo in modo da indicizzare i database specificati e restituire i risultati agli utenti di Cloud Search.
Prerequisiti
Prima di eseguire il deployment del connettore di database Cloud Search, raccogli le seguenti informazioni:
- Chiave privata di Google Workspace, che contiene anche l'ID account di servizio. Per scoprire come ottenere una chiave privata, consulta Configurare l'accesso all'API REST di Google Cloud Search.
- ID origine dati Google Workspace. Per scoprire come ottenere un ID origine dati, vai a Aggiungere un'origine dati alla ricerca.
Passaggio 1: Scarica e crea il software del connettore di database
- Clona il repository del connettore da GitHub.
$ git clone https://github.com/google-cloudsearch/database-connector.git $ cd database-connector
- Verifica la versione desiderata del connettore:
$ git checkout tags/v1-0.0.3
- Crea il connettore.
$ mvn package
Per saltare i test durante la creazione del connettore, utilizzamvn package -DskipTests
. - Copia il file ZIP del connettore nella directory di installazione locale e decomprimilo:
$ 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
Passaggio 2: Configura il connettore di database
- Crea un file di testo e assegnagli il nome
connector-config.properties
(valore predefinito) o un nome simile. Google consiglia di denominare i file di configurazione con l'estensione.properties
o.config
e di mantenere il file nella stessa directory del connettore. Se utilizzi un nome o un percorso diverso, devi specificare il percorso quando esegui il connettore. - Aggiungi i parametri sotto forma di coppie chiave/valore ai contenuti del file. Il file di configurazione deve specificare i parametri per l'accesso all'origine dati, l'accesso al database, un'istruzione SQL Full Traversal del database, un titolo per il campo dei contenuti e le definizioni delle colonne. Puoi anche configurare altri comportamenti del connettore
con parametri facoltativi. Ad esempio:
# 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
Per descrizioni dettagliate dei parametri specifici del database, consulta il riferimento sui parametri di configurazione alla fine di questo articolo.
Per informazioni sui parametri comuni a tutti i connettori Cloud Search, come configurazione dei metadati, formati data/ora e opzioni ACL, vai a Parametri del connettore forniti da Google.
Se applicabile, specifica le proprietà dell'oggetto schema nei parametri di query SQL trasversale. In genere puoi aggiungere alias all'istruzione SQL. Ad esempio, se hai un database di filmati e lo schema dell'origine dati contiene una definizione di proprietà denominata "ActorName", un'istruzione SQL potrebbe avere il seguente formato:
SELECT …, last_name AS ActorName, … FROM …
.
Passaggio 3: Esegui il connettore di database
L'esempio seguente presuppone che i componenti richiesti si trovino nella directory locale su un sistema Linux.
Per eseguire il connettore dalla riga di comando, inserisci il seguente comando:
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]
Dove:
google-cloud-search-database-connector-v1-0.0.3.jar
è il file .jar del connettore del databasemysql-connector-java-5.1.41-bin.jar
è il driver JDBC utilizzato per accedere al databasemysql.config
è un file di configurazione con nomi personalizzati. Per assicurarti che il connettore riconosca il file di configurazione, specifica il percorso nella riga di comando. In caso contrario, il connettore utilizzaconnector-config.properties
nella directory locale come nome file predefinito.
Il connettore segnala gli errori di configurazione non appena li rileva. Alcuni errori vengono segnalati al momento dell'inizializzazione del connettore, ad esempio quando una colonna di database viene definita come parte del contenuto del record (in db.allColumns
), ma la colonna non viene utilizzata nella query SQL di attraversamento del database (in db.allRecordsSql
). Altri errori vengono rilevati e segnalati solo quando il connettore tenta di accedere al database per il primo attraversamento, ad esempio una sintassi SQL non valida.
Riferimento per i parametri di configurazione
Parametri di accesso all'origine dati
Impostazione | Parametro |
---|---|
ID origine dati | api.sourceId = source-ID
Obbligatorio. L'ID origine di Cloud Search configurato dall'amministratore di Google Workspace. |
ID origine identità | api.identitySourceId = identity-source-ID
Necessario per utilizzare utenti e gruppi esterni per gli ACL. L'ID origine identità di Cloud Search configurato dall'amministratore di Google Workspace. |
Account di servizio | api.serviceAccountPrivateKeyFile = path-to-private-key
Obbligatorio. Il percorso del file della chiave dell'account di servizio Cloud Search creato dall'amministratore di Google Workspace. |
Parametri di accesso al database
Impostazione | Parametro |
---|---|
URL database | db.url = database-URL
Obbligatorio. Il
percorso completo del database a cui accedere, ad esempio |
Nome utente e password del database | db.user = username db.password = password
Obbligatorio. Un nome utente e una password validi utilizzati dal connettore per accedere al database. Questo utente del database deve avere accesso in lettura ai record pertinenti del database letto. |
Driver JDBC | db.driverClass = oracle.jdbc.OracleDriver
Obbligatorio solo se il driver JDBC 4.0 non è già specificato nel percorso della classe. |
Parametri di query SQL per il trasferimento
Il connettore attraversa i record del database con query SQL SELECT nel file di configurazione. Devi configurare una query Full Trasversale. Le query per gli attraversamenti incrementali sono facoltative.
Un trasversale completo legge ogni record di database configurato per l'indicizzazione. È necessario un attraversamento completo per indicizzare i nuovi record per Cloud Search e anche per reindicizzare tutti i record esistenti.
Un attraversamento incrementale legge e reindicizza solo i record di database appena modificati e le voci recenti nel database. Gli attraversamenti incrementali possono essere più efficienti di quelli completi. Per utilizzare attraversamenti incrementali, il database deve contenere campi timestamp per indicare i record modificati.
Il connettore esegue questi attraversamenti in base alle pianificazioni definite nei parametri di pianificazione degli attraversamenti.
Impostazione | Parametro |
---|---|
Query attraversamento completo | db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name
Obbligatorio. La query viene eseguita per ogni attraversamento completo. Ogni nome di colonna che il connettore utilizzerà a qualsiasi capacità (contenuti, ID univoco, ACL) deve essere presente in questa query. Il connettore esegue alcune verifiche preliminari all'avvio per rilevare errori e omissioni. Per questo motivo, non utilizzare una query generica "SELECT * FROM ...". |
Impaginazione full traversal | db.allRecordsSql.pagination = {none | offset}
Il valore può essere:
|
Query trasversale incrementale | db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?
Obbligatorio se pianifichi gli attraversamenti incrementali. Il carattere "?" nella query è un segnaposto obbligatorio per un valore di timestamp. Il connettore utilizza il timestamp per monitorare le modifiche tra query SQL trasversali incrementali. Per monitorare la colonna del timestamp del database per l'ora dell'ultimo aggiornamento, aggiungi l'alias Per il primo attraversamento incrementale, il connettore utilizza l'ora di inizio del connettore stesso. Dopo il primo attraversamento incrementale, Cloud Search archivia il timestamp in modo che i riavvii del connettore possano accedere al timestamp di attraversamento incrementale precedente. |
Fuso orario database | db.timestamp.timezone = America/Los_Angeles
Specifica il fuso orario da utilizzare per i timestamp del database. Il timestamp del database utilizzato per identificare l'aggiunta di nuovi record o i record di database appena modificati. Il valore predefinito è il fuso orario locale dell'esecuzione del connettore. |
Esempi di query SQL per il trasferimento
- Query full traversal di base che legge ogni record di interesse in un database dei dipendenti per l'indicizzazione:
db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \ FROM employee
- Specifica l'impaginazione in base all'offset e suddividi un attraversamento completo in più query.
Per SQL Server 2012 o Oracle 12c (sintassi standard di SQL 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
oppure, per MySQL o 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
- Query attraversamento completo che applica singoli ACL con 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
- Query attraversamento incrementale di base:
db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \ FROM employee \ WHERE last_update_time > ?
- Query trasversale incrementale che applica singoli ACL con 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 > ?
- Query di attraversamento incrementale che utilizza il timestamp del database anziché l'ora attuale:
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 > ?
Parametri di definizione delle colonne
I seguenti parametri specificano le colonne da utilizzare nelle istruzioni di attraversamento e per identificare in modo univoco ciascun record.
Impostazione | Parametro |
---|---|
Tutte le colonne | db.allColumns = column-1, column-2, ...column-N
Obbligatorio. Identifica tutte le colonne necessarie in una query SQL per accedere al database. Nelle query si deve fare riferimento alle colonne definite con questo parametro. Ogni altro parametro di definizione della colonna viene confrontato con questo insieme di colonne. Esempio: db.allColumns = customer_id, first_name, last_name, phone, change_timestamp |
Colonne chiave univoche | db.uniqueKeyColumns = column-1[, column-2]
Obbligatorio. Elenca una singola colonna di database contenente valori univoci o in base a una combinazione di colonne i cui valori insieme definiscono un ID univoco. Cloud Search richiede che ogni documento disponibile per la ricerca abbia un identificatore univoco all'interno di un'origine dati. Devi essere in grado di definire un ID univoco per ogni record di database dai valori della colonna. Se esegui più connettori su database separati, ma esegui l'indicizzazione in un set di dati comune, assicurati di specificare un ID univoco in tutti i documenti. Esempi: db.uniqueKeyColumns = customer_id # or db.uniqueKeyColumns = last_name, first_name |
Colonna Link URL | url.columns = column-1[, column-2]
Obbligatorio. Specifica uno o più nomi validi e definiti delle colonne utilizzate per l'URL utilizzato per un risultato di ricerca cliccabile. Per i database che non hanno un URL pertinente associato a ciascun record di database, è possibile utilizzare un link statico per ogni record. Tuttavia, se i valori della colonna definiscono un link valido per ogni record, è necessario specificare le colonne dell'URL di visualizzazione e i valori di configurazione del formato. |
Formato URL | url.format = https://www.example.com/{0}
Definisce il formato dell'URL di visualizzazione. I parametri numerati si riferiscono alle colonne specificate in db.columns in ordine, partendo da zero. Se non specificato, il valore predefinito è "{0}.". Di seguito sono riportati alcuni esempi. |
Colonne con codifica percentuale per URL | url.columnsToEscape = column-1[, column-2]
Specifica le colonne di db.columns i cui valori saranno codificati in percentuale prima di essere inclusi nella stringa dell'URL formattata. |
Esempi di colonne URL
Per specificare le colonne utilizzate nelle query trasversali e il formato dell'URL di visualizzazione:
- Per utilizzare un URL statico che non utilizza valori di record di database:
url.format = https://www.example.com
- Per utilizzare un singolo valore di colonna che corrisponda all'URL di visualizzazione:
url.format = {0} url.columns = customer_id
- Per utilizzare un singolo valore di colonna da sostituire nell'URL di visualizzazione nella posizione {0}:
url.format = https://www.example.com/customer/id={0} url.columns = customer_id url.columnsToEscape = customer_id
- Per utilizzare più valori di colonna per creare l'URL di visualizzazione (le colonne dipendono dall'ordine):
url.format = {1}/customer={0} url.columns = customer_id, linked_url url.columnsToEscape = customer_id
Campi dei contenuti
Utilizza le opzioni di contenuto per definire i valori dei record da includere nei contenuti disponibili per la ricerca.
Impostazione | Parametro |
---|---|
Colonna di ricerca di massima qualità | contentTemplate.db.title = column-name
Obbligatorio. La colonna con la qualità più alta per l'indicizzazione della ricerca e l'assegnazione della priorità ai risultati. |
Assegnazione delle priorità alle colonne per la ricerca | contentTemplate.db.quality.high = column-1[, column-2...] contentTemplate.db.quality.medium = column-1[, column-2...] contentTemplate.db.quality.low = column-1[, column-2...]
Specifica le colonne di contenuti (tranne quelle impostate per |
Colonne di dati sui contenuti | db.contentColumns = column-1[, column-2...]
Specifica le colonne di contenuti nel database. Questi vengono formattati e caricati in Cloud Search come contenuti dei documenti disponibili per la ricerca. Se non specifichi alcun valore, il valore predefinito è "*", che indica che devono essere utilizzate tutte le colonne per i contenuti. |
Colonna blob | db.blobColumn = column-name
Specifica il nome di una singola colonna blob da utilizzare per i contenuti dei documenti anziché una combinazione di colonne di contenuti. Se viene specificata una colonna blob, questa viene considerata un errore se sono definite anche colonne di contenuti. Tuttavia, le definizioni delle colonne di metadati e dati strutturati sono ancora consentite insieme alle colonne blob. |