Esegui il deployment di un connettore di database

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:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
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:

Passaggio 1: Scarica e crea il software del connettore di database

  1. Clona il repository del connettore da GitHub. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. Verifica la versione desiderata del connettore:
    $ git checkout tags/v1-0.0.3
  3. Crea il connettore. 
    $ mvn package
    Per saltare i test durante la creazione del connettore, utilizza mvn package -DskipTests.
  4. 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

  1. 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.
  2. 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 database
  • mysql-connector-java-5.1.41-bin.jar è il driver JDBC utilizzato per accedere al database
  • mysql.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 utilizza connector-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 jdbc:mysql://127.0.0.1/dbname.
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:

  • none: non utilizzare l'impaginazione
  • offset: utilizza l'impaginazione in base all'offset di riga

    Per utilizzare l'impaginazione in base all'offset, la query SQL deve avere un punto interrogativo segnaposto (?) per un offset di riga, che inizia con zero. In ogni attraversamento completo, la query viene eseguita ripetutamente finché non viene restituito alcun risultato.
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 timestamp_column all'istruzione SQL. In caso contrario, utilizza il timestamp attuale dell'attraversamento del connettore.

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 contentTemplate.db.title) come campi con qualità di ricerca alta, media o bassa. Per impostazione predefinita, le colonne non specificate sono basse.
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.