Esegui il deployment di un connettore di database

Avviso: i connettori di riferimento di Cloud Search vengono forniti "così come sono" come codice campione per creare i tuoi connettori funzionanti. Questo codice campione richiede personalizzazione e test sostanziali prima di essere utilizzati come proof-of-concept o ambienti di produzione. Per uso in produzione, consigliamo vivamente di richiedere assistenza di uno dei nostri partner Cloud Search. Per ulteriore assistenza nella ricerca di un cloud adatto Partner di ricerca, contatta il tuo account manager Google.

Puoi configurare Google Cloud Search per rilevare e indicizzare i dati del database utilizzando il connettore di database di Google Cloud Search.

Considerazioni importanti

Puoi installare ed eseguire il connettore di database Cloud Search in quasi tutti gli ambienti in cui possono essere eseguite le app Java, purché il connettore abbia accesso a entrambi internet e il database.

Requisiti di sistema

Requisiti di sistema
Sistema operativo Windows o Linux
Database SQL Qualsiasi database SQL con 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
Software Driver JDBC che il connettore utilizza per accedere al database (scaricato e installato separatamente)

Esegui il deployment del connettore

I passaggi seguenti spiegano come installare il connettore e configurarlo per 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. Controlla la versione del connettore che ti interessa:
    $ 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 (predefinito) o un nome simile. Google consiglia assegnare ai file di configurazione i nomi .properties o .config e mantieni 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 parametri come 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 database full traversal, un titolo per il campo di 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, vai al Riferimento ai parametri di configurazione alla fine di questo articolo.

    Per conoscere i parametri comuni a tutti i servizi Cloud Search come la configurazione dei metadati, i formati data/ora e le opzioni ACL, vai a Parametri del connettore forniti da Google.

    Se applicabile, specifica le proprietà dell'oggetto schema nell'SQL di attraversamento parametri di ricerca. Di solito puoi aggiungere alias al prompt l'Informativa. Ad esempio, se hai un film e lo schema dell'origine dati contiene una definizione della proprietà denominata "ActorName", un'istruzione SQL potrebbe avere il formato: SELECT …, last_name AS ActorName, … FROM … .

Passaggio 3: Esegui il connettore di database

L'esempio seguente presuppone che i componenti richiesti si trovino nell'ambiente su un sistema Linux.

Per eseguire il connettore dalla riga di comando, inserisci questo 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 di database
  • mysql-connector-java-5.1.41-bin.jar è il driver JDBC che viene utilizzato per accedere al database
  • mysql.config è un file di configurazione con nome personalizzato. Per assicurarti che il connettore riconosca di configurazione del deployment, specifica il relativo percorso nella riga di comando. In caso contrario, il connettore utilizza connector-config.properties nella tua località come nome file predefinito.

Il connettore segnala gli errori di configurazione non appena li rileva. Alcuni errori vengono segnalati quando inizializza il connettore, ad esempio quando viene definita una colonna di database come parte del contenuto del record (in db.allColumns), ma la colonna non viene utilizzata nella query SQL di attraversamento del (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 dell'istruzione 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. Cloud Search ID origine configurato dall'amministratore di Google Workspace.

ID origine identità api.identitySourceId = identity-source-ID

Necessario per utilizzare utenti e gruppi esterni per gli ACL. Cloud Search ID origine identità configurato dall'amministratore di Google Workspace.

Account di servizio api.serviceAccountPrivateKeyFile = path-to-private-key

Obbligatorio. Percorso di Cloud Search il file della chiave dell'account di servizio creato dall'amministratore di Google Workspace.

Parametri di accesso al database

Impostazione Parametro
URL database db.url = database-URL

Obbligatorio. La 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 valido e password utilizzata dal connettore per accedere al database. Questo utente del database deve dispongono dell'accesso in lettura ai record pertinenti del database in fase di lettura.

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 di attraversamento

Il connettore attraversa i record del database con SQL SELECT query nel file di configurazione. Devi configurare una query di attraversamento completo. query per gli attraversamenti incrementali sono facoltativi.

Un attraversamento completo legge ogni record del database configurato per l'indicizzazione. Un il trasferimento è necessario per indicizzare i nuovi record per Cloud Search e anche per reindicizzare tutti i record esistenti.

Un attraversamento incrementale legge e reindicizza solo il database appena modificato record e voci recenti del database. Gli attraversamenti incrementali possono essere più efficienti attraversamenti 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 in parametri di pianificazione dell'attraversamento.

Impostazione Parametro
Query attraversamento completo db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

Obbligatorio. La query eseguita per ogni attraversamento completo.

Il nome di ogni colonna che il connettore utilizzerà in (contenuto, ID univoco, ACL) deve essere presente in questa query. La il connettore esegue alcune verifiche preliminari all'avvio per rilevare gli errori e omissioni. Per questo motivo, non utilizzare un'istruzione generica "SELECT * FROM ..." query.

Impaginazione full traversal db.allRecordsSql.pagination = {none | offset}

Il valore può essere:

  • nessuno: per 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, iniziando da zero. In ogni attraversamento completo, la query viene eseguita ripetutamente finché non viene restituito alcun risultato.

Query di attraversamento incrementale db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

Obbligatorio se piani attraversamenti incrementali.

Il "?" Nella query è presente un segnaposto obbligatorio per il valore del timestamp. La utilizza il timestamp per tenere traccia delle modifiche tra le query SQL di attraversamento incrementale.

Per monitorare la colonna del timestamp del database per l'ora dell'ultimo aggiornamento, aggiungi la colonna alias timestamp_column all'istruzione SQL; altrimenti usa il timestamp corrente l'attraversamento del connettore.

Per il primo attraversamento incrementale, il connettore utilizza l'ora di inizio del connettore. Dopo il primo attraversamento incrementale, Cloud Search memorizza il timestamp in modo che i riavvii del connettore siano in grado di accedere all'attraversamento incrementale precedente timestamp.

Fuso orario del 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 le aggiunte di nuovi record o le nuove e modificati del database. Il valore predefinito è il fuso orario locale in cui è in esecuzione il connettore.

Esempi di query SQL di attraversamento

  • Query di base full attraversal 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 SQL 2008 standard):

    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 di 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 di attraversamento 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 che utilizzi nelle istruzioni di attraversamento e a identificare in modo univoco ciascun record.

Impostazione Parametro
Tutte le colonne db.allColumns = column-1, column-2, ...column-N

Obbligatorio. Identifica tutte le colonne richiesti in una query SQL quando accedi al database. Le colonne definiti con questo parametro devono essere indicati in modo esplicito nelle query. Ogni evento 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 uno un'unica colonna di database che contiene valori univoci o in base a una combinazione di colonne i cui valori definiscono insieme 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 delle colonne. Se esegui più connettori su database separati, 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ù valori validi e definiti nomi delle colonne utilizzate per l'URL di un risultato di ricerca cliccabile. Per i database che non hanno un URL pertinente associato a ciascun record di database, viene un link statico può essere usato per ogni record.

Tuttavia, se i valori delle colonne definiscono un link valido per ogni record, la vista È necessario specificare le colonne dell'URL 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 specificato in db.columns in ordine, iniziando con zero.

Se non specificato, il valore predefinito è "{0}."

Ecco alcuni esempi.

Colonne con codifica percentuale per l'URL url.columnsToEscape = column-1[, column-2]

Specifica le colonne da db.columns i cui valori saranno codificati in percentuale prima di includerle nella stringa dell'URL formattata.

Esempi di colonne URL

Per specificare le colonne utilizzate nelle query di attraversamento 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 della colonna che sia l'URL di visualizzazione:
    url.format = {0}
    url.columns = customer_id
  • Per utilizzare un singolo valore della colonna che viene sostituito 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 dei contenuti per definire i valori dei record dovrebbero essere inserite nei contenuti disponibili per la ricerca.

Impostazione Parametro
Colonna di ricerca di massima qualità contentTemplate.db.title = column-name

Obbligatorio. La colonna di qualità più elevata per l'indicizzazione della ricerca e l'assegnazione della priorità ai risultati.

Assegnazione della 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 la colonna impostata per contentTemplate.db.title) ad alta, media o bassa qualità di ricerca. Il valore predefinito delle colonne non specificate è basso.

Colonne di dati sui contenuti db.contentColumns = column-1[, column-2...]

Specifica le colonne di contenuti nel database. Questi vengono formattati e in Cloud Search come contenuti dei documenti disponibili per la ricerca.

Se non specifichi un valore, il valore predefinito è "*" per indicare che tutti per i contenuti.

Colonna blob db.blobColumn = column-name

Specifica il nome di un singolo blob colonna da utilizzare per i contenuti del documento anziché per una combinazione di colonne di contenuti.

Se viene specificata una colonna blob, viene considerata un errore se le colonne dei contenuti . Tuttavia, le definizioni delle colonne di metadati e dati strutturati consentiti insieme alle colonne BLOB.