Datenbankconnector bereitstellen

Warnung: Die Cloud Search-Referenz-Connectors werden „wie besehen“ als Beispielcode für die Erstellung Ihrer eigenen funktionierenden Connectors bereitgestellt. Dieser Beispielcode muss umfassend angepasst und getestet werden, bevor er in Proof of Concept- oder Produktionsumgebungen verwendet werden kann. Für den Einsatz in der Produktion empfehlen wir dringend, sich an einen unserer Cloud Search-Partner zu wenden. Weitere Unterstützung bei der Suche nach einem geeigneten Cloud Search-Partner erhalten Sie von Ihrem Google Account Manager.

Sie können Google Cloud Search so einrichten, dass Daten in den Datenbanken Ihrer Organisation mit dem Datenbank-Connector von Google Cloud Search erkannt und indexiert werden.

Wichtige Aspekte

Sie können den Cloud Search-Datenbankconnector in fast jeder Umgebung installieren und ausführen, in der Java-Anwendungen ausgeführt werden können. Voraussetzung ist, dass der Connector Zugriff sowohl auf das Internet als auch auf die Datenbank hat.

Systemanforderungen

Systemanforderungen
Betriebssystem Windows oder Linux
SQL-Datenbank Jede SQL-Datenbank mit einem mit JDBC 4.0 oder höher kompatiblen Treiber, einschließlich:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Software JDBC-Treiber für den Connector zum Zugriff auf die Datenbank (separat heruntergeladen und installiert)

Connector bereitstellen

In den folgenden Schritten wird beschrieben, wie Sie den Connector installieren und so konfigurieren, dass er die angegebenen Datenbanken indexiert und die Ergebnisse an Cloud Search-Nutzer zurückgibt.

Voraussetzungen

Halten Sie die folgenden Informationen bereit, bevor Sie den Cloud Search-Datenbankconnector bereitstellen:

Schritt 1: Software für den Datenbankconnector herunterladen und erstellen

  1. Klonen Sie das Connector-Repository von GitHub. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. Prüfen Sie die gewünschte Version des Connectors:
    $ git checkout tags/v1-0.0.3
  3. Erstellen Sie den Connector. 
    $ mvn package
    Wenn Sie die Tests beim Erstellen des Connectors überspringen möchten, verwenden Sie mvn package -DskipTests.
  4. Kopieren Sie die ZIP-Datei des Connectors in das lokale Installationsverzeichnis und entpacken Sie sie: 
    $ 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

Schritt 2: Datenbankconnector konfigurieren

  1. Erstellen Sie eine Textdatei und nennen Sie sie connector-config.properties (Standardeinstellung) oder ähnlich. Google empfiehlt, Konfigurationsdateien mit der Endung .properties oder .config zu benennen und im selben Verzeichnis wie der Connector zu belassen. Wenn Sie einen anderen Namen oder Pfad verwenden, müssen Sie den Pfad beim Ausführen des Connectors angeben.
  2. Fügen Sie dem Dateiinhalt Parameter als Schlüssel/Wert-Paare hinzu. Die Konfigurationsdatei muss die Parameter für den Zugriff auf die Datenquelle und den Datenbankzugriff, eine SQL-Anweisung für den vollständigen Durchlauf der Datenbank, einen Titel für das Inhaltsfeld und Spaltendefinitionen enthalten. Mit optionalen Parametern können Sie auch ein anderes Connectorverhalten konfigurieren. Beispiel: 
    # 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

    Eine ausführliche Beschreibung der datenbankspezifischen Parameter finden Sie in der Referenz zu Konfigurationsparametern am Ende dieses Artikels.

    Weitere Informationen zu den gemeinsamen Parametern aller Cloud Search-Connectors, z. B. Metadatenkonfiguration, Datum/Uhrzeit-Formate und ACL-Optionen, finden Sie unter Von Google bereitgestellte Connector-Parameter.

    Geben Sie gegebenenfalls Attribute des Schemaobjekts in den Parametern der SQL-Abfrage für den Durchlauf an. Normalerweise können Sie der SQL-Anweisung Aliasse hinzufügen. Wenn Sie beispielsweise eine Filmdatenbank haben und das Datenquellenschema eine Attributdefinition mit dem Namen „ActorName“ enthält, könnte eine SQL-Anweisung das folgende Format haben: SELECT …, last_name AS ActorName, … FROM … .

Schritt 3: Datenbankconnector ausführen

Im folgenden Beispiel wird davon ausgegangen, dass sich die erforderlichen Komponenten im lokalen Verzeichnis eines Linux-Systems befinden.

Geben Sie den folgenden Befehl ein, um den Connector über die Befehlszeile auszuführen: 

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]

Wobei:

  • google-cloud-search-database-connector-v1-0.0.3.jar ist die JAR-Datei des Datenbankconnectors.
  • mysql-connector-java-5.1.41-bin.jar ist der JDBC-Treiber, der für den Zugriff auf die Datenbank verwendet wird.
  • mysql.config ist eine benutzerdefinierte Konfigurationsdatei. Damit der Connector die Konfigurationsdatei erkennt, geben Sie ihren Pfad in der Befehlszeile an. Andernfalls verwendet der Connector connector-config.properties in Ihrem lokalen Verzeichnis als Standarddateinamen.

Der Connector meldet Konfigurationsfehler, sobald er sie erkennt. Einige Fehler werden beim Initialisieren des Connectors gemeldet, z. B. wenn eine Datenbankspalte als Teil des Eintragsinhalts definiert ist (in db.allColumns), die Spalte aber nicht in der SQL-Abfrage der Datenbank (in db.allRecordsSql) verwendet wird. Andere Fehler werden nur erkannt und gemeldet, wenn der Connector versucht, beim ersten Durchlauf auf die Datenbank zuzugreifen, z. B. ungültige Syntax von SQL-Anweisungen.

Konfigurationsparameter

Parameter für den Zugriff auf Datenquellen

Einstellung Parameter
ID der Datenquelle api.sourceId = source-ID

Erforderlich. Die ID der Cloud Search-Quelle, die der Google Workspace-Administrator eingerichtet hat.
ID der Identitätsquelle api.identitySourceId = identity-source-ID

Erforderlich, um externe Nutzer und Gruppen für ACLs zu verwenden. Die ID der Cloud Search-Identitätsquelle, die der Google Workspace-Administrator eingerichtet hat.
Dienstkonto api.serviceAccountPrivateKeyFile = path-to-private-key

Erforderlich. Der Pfad zur Schlüsseldatei des Cloud Search-Dienstkontos, die der Google Workspace-Administrator erstellt hat.

Parameter für den Datenbankzugriff

Einstellung Parameter
Datenbank-URL db.url = database-URL

Erforderlich. Der vollständige Pfad der Datenbank, auf die zugegriffen werden soll, z. B. jdbc:mysql://127.0.0.1/dbname.
Nutzername und Passwort der Datenbank db.user = username
db.password = password

Erforderlich. Ein gültiger Nutzername und ein gültiges Passwort, mit denen der Connector auf die Datenbank zugreift. Dieser Datenbanknutzer muss Lesezugriff auf die relevanten Datensätze der gelesenen Datenbank haben.
JDBC-Treiber db.driverClass = oracle.jdbc.OracleDriver

Nur erforderlich, wenn der JDBC 4.0-Treiber noch nicht im Klassenpfad angegeben ist.

SQL-Abfrageparameter für Durchlauf

Der Connector durchsucht Datenbankeinträge mit SQL-SELECT-Abfragen in der Konfigurationsdatei. Sie müssen eine Abfrage für einen vollständigen Durchlauf konfigurieren. Abfragen für inkrementelle Durchläufe sind optional.

Bei einem vollständigen Durchlauf werden alle Datensätze gelesen, die für die Indexierung konfiguriert sind. Es ist ein vollständiger Durchlauf erforderlich, um neue Datensätze für Cloud Search sowie alle vorhandenen Datensätze noch einmal zu indexieren.

Bei einem inkrementellen Durchlauf werden nur neu geänderte Datenbankeinträge und aktuelle Einträge in der Datenbank gelesen und neu indexiert. Inkrementelle Durchläufe können effizienter sein als vollständige. Wenn Sie inkrementelle Durchläufe verwenden möchten, muss Ihre Datenbank Zeitstempelfelder enthalten, um geänderte Datensätze anzugeben.

Der Connector führt diese Durchläufe gemäß den Zeitplänen aus, die Sie in den Parametern für die Planung von Durchläufen definiert haben.

Einstellung Parameter
Abfrage für vollständigen Durchlauf db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

Erforderlich. Die Abfrage, die für jeden vollständigen Durchlauf ausgeführt wird.

Jeder Spaltenname, den der Connector verwendet, muss für jede Funktion (Inhalt, eindeutige ID, ACLs) in dieser Abfrage vorhanden sein. Der Connector führt beim Start einige vorläufige Überprüfungen durch, um Fehler und Auslassungen zu erkennen. Verwenden Sie daher keine allgemeine Abfrage des Typs SELECT * FROM ....
Paginierung für vollständigen Durchlauf db.allRecordsSql.pagination = {none | offset}

Mögliche Werte sind:

  • none: keine Paginierung
  • offset: Paginierung nach Zeilenversatz

    Wenn Sie die Paginierung nach Offset verwenden möchten, muss die SQL-Abfrage ein Platzhalterfragezeichen (?) für einen Zeilenversatz enthalten, der mit null beginnt. Bei jedem vollständigen Durchlauf wird die Abfrage wiederholt ausgeführt, bis keine Ergebnisse mehr zurückgegeben werden.
Abfrage für inkrementellen Durchlauf db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

Erforderlich, wenn Sie Durchläufe mit Teilindexierung planen.

Das „?“ in der Abfrage ist ein obligatorischer Platzhalter für einen Zeitstempelwert. Der Connector verwendet den Zeitstempel, um Änderungen zwischen SQL-Abfragen für inkrementelle Durchläufe zu verfolgen.

Wenn Sie die Datenbankzeitstempelspalte für den letzten Aktualisierungszeitpunkt verfolgen möchten, fügen Sie der SQL-Anweisung den Alias timestamp_column hinzu. Verwenden Sie andernfalls den aktuellen Zeitstempel des Connectordurchlaufs.

Beim ersten inkrementellen Durchlauf verwendet der Connector die Startzeit des Connectors. Nach dem ersten Durchlauf mit Teilindexierung wird der Zeitstempel in Cloud Search gespeichert, damit bei Connector-Neustarts auf den Zeitstempel des vorherigen Durchlaufs zugegriffen werden kann.
Zeitzone der Datenbank db.timestamp.timezone = America/Los_Angeles

Gibt die Zeitzone an, die für Datenbankzeitstempel verwendet werden soll. Der Datenbankzeitstempel, der zum Identifizieren neuer oder kürzlich geänderter Datenbankeinträge verwendet wird. Die Standardeinstellung ist die lokale Zeitzone, in der der Connector ausgeführt wird.

Beispiele für Durchlauf-SQL-Abfragen

  • Einfache Abfrage für vollständigen Durchlauf, die alle relevanten Datensätze in einer Mitarbeiterdatenbank zur Indexierung liest: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • Geben Sie die Paginierung mit Offset an und teilen Sie einen Durchlauf mit vollständiger Indexierung in mehrere Abfragen auf.

    Für SQL Server 2012 oder Oracle 12c (Standard-SQL 2008-Syntax):

    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

    oder (für MySQL oder 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
  • Abfrage für vollständigen Durchlauf, bei der einzelne ACLs mit Aliassen angewendet werden: 
    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
  • Einfache Abfrage für inkrementellen Durchlauf: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • Abfrage für inkrementellen Durchlauf, bei der einzelne ACLs mit Aliassen angewendet werden: 
    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 > ?
  • Abfrage für inkrementellen Durchlauf, bei der der Datenbankzeitstempel und nicht die aktuelle Zeit verwendet wird: 
    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 > ?

Parameter für die Spaltendefinition

Die folgenden Parameter geben die Spalten an, die Sie in den Durchlaufanweisungen und zur eindeutigen Identifizierung der einzelnen Datensätze verwenden.

Einstellung Parameter
Alle Spalten db.allColumns = column-1, column-2, ...column-N

Erforderlich. Gibt alle Spalten an, die in einer SQL-Abfrage beim Zugriff auf die Datenbank erforderlich sind. Auf die mit diesem Parameter definierten Spalten muss in den Abfragen explizit verwiesen werden. Jeder andere Parameter für Spaltendefinitionen wird mit diesem Spaltensatz verglichen.

Beispiel:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
Spalten mit eindeutigem Schlüssel db.uniqueKeyColumns = column-1[, column-2]

Erforderlich. Listet entweder eine einzelne Datenbankspalte auf, die eindeutige Werte enthält, oder eine Kombination von Spalten, deren Werte zusammen eine eindeutige ID definieren.

Für Cloud Search muss jedes durchsuchbare Dokument eine eindeutige ID innerhalb einer Datenquelle haben. Sie müssen in der Lage sein, für jeden Datenbankeintrag eine eindeutige ID aus Spaltenwerten zu definieren. Wenn Sie mehrere Connectors für separate Datenbanken ausführen, aber in einem gemeinsamen Dataset indexieren, müssen Sie für alle Dokumente eine eindeutige ID angeben.

Beispiele:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
Spalte „URL-Link“ url.columns = column-1[, column-2]

Erforderlich. Gibt einen oder mehrere gültige, definierte Namen der Spalten an, die für die URL eines anklickbaren Suchergebnisses verwendet werden. Bei Datenbanken, bei denen jedem Datenbankeintrag keine relevante URL zugeordnet ist, kann für jeden Datensatz ein statischer Link verwendet werden.

Wenn die Spaltenwerte jedoch einen gültigen Link für jeden Eintrag definieren, sollten die Spalten für die Ansichts-URL und die Formatkonfigurationswerte angegeben werden.
URL-Format url.format = https://www.example.com/{0}

Definiert das Format der Ansichts-URL. Nummerierte Parameter beziehen sich auf die in db.columns angegebenen Spalten, beginnend mit null.

Wenn Sie nichts angeben, wird der Standardwert {0} verwendet.

Beispiele folgen dieser Tabelle.
In Prozent codierte Spalten für URL url.columnsToEscape = column-1[, column-2]

Gibt Spalten aus db.columns an, deren Werte in Prozent codiert werden, bevor sie in den formatierten URL-String eingefügt werden.

Beispiele für die URL-Spalte

So legen Sie die in Durchlaufabfragen verwendeten Spalten und das Format der Ansichts-URL fest:

  • So verwenden Sie eine statische URL ohne Werte für Datenbankeinträge: 
    url.format = https://www.example.com
  • So verwenden Sie einen einzelnen Spaltenwert, der die Ansichts-URL ist: 
    url.format = {0}
url.columns = customer_id
  • So verwenden Sie einen einzelnen Spaltenwert, der in der Ansichts-URL an Position {0} ersetzt wird: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • So verwenden Sie mehrere Spaltenwerte zum Erstellen der Ansichts-URL (Spalten sind reihenfolgeabhängig): 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

Inhaltsfelder

Verwenden Sie die Inhaltsoptionen, um festzulegen, welche Datensatzwerte Teil des durchsuchbaren Inhalts sein sollen.

Einstellung Parameter
Spalte für die höchste Suchqualität contentTemplate.db.title = column-name

Erforderlich. Die Spalte mit der höchsten Qualität für die Suchindexierung und Ergebnispriorisierung.
Spaltenpriorisierung für die Suche contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

Legen Sie Inhaltsspalten (mit Ausnahme der Spaltengruppe für contentTemplate.db.title) als Felder mit hoher, mittlerer oder niedriger Suchqualität fest. Nicht angegebene Spalten sind standardmäßig niedrig.
Spalten für Inhaltsdaten db.contentColumns = column-1[, column-2...]

Geben Sie Inhaltsspalten in der Datenbank an. Diese werden formatiert und als durchsuchbarer Dokumentinhalt in Cloud Search hochgeladen.

Wenn Sie keinen Wert angeben, wird der Standardwert "*" verwendet. Das bedeutet, dass alle Spalten für Inhalte verwendet werden sollen.
Blob-Spalte db.blobColumn = column-name

Geben Sie den Namen einer einzelnen Blob-Spalte an, die anstelle einer Kombination von Inhaltsspalten für Dokumentinhalte verwendet werden soll.

Wenn eine Blob-Spalte angegeben ist, gilt dies als Fehler, wenn auch Inhaltsspalten definiert sind. Definitionen für Metadaten und strukturierte Datenspalten sind aber zusammen mit Blob-Spalten weiterhin zulässig.