Wdrażanie oprogramowania sprzęgającego bazy danych

Ostrzeżenie: oprogramowanie sprzęgające Cloud Search jest udostępniane w stanie, w jakim się znajduje, jako przykładowy kod do wykorzystania podczas tworzenia własnego działającego oprogramowania sprzęgającego. Ten przykładowy kod wymaga dużych dostosowań i testów przed użyciem w środowiskach produkcyjnych lub modeli koncepcyjnych. W przypadku zastosowań produkcyjnych zdecydowanie zalecamy uzyskanie pomocy od jednego z naszych partnerów Cloud Search. Aby znaleźć odpowiedniego partnera Cloud Search, skontaktuj się ze swoim opiekunem klienta w Google.

Możesz skonfigurować Google Cloud Search pod kątem wykrywania i indeksowania danych z baz danych organizacji, korzystając z oprogramowania sprzęgającego bazy danych Google Cloud Search.

Ważne informacje

Oprogramowanie sprzęgające bazy danych Cloud Search możesz zainstalować i uruchomić w prawie każdym środowisku, w którym mogą działać aplikacje Java, o ile oprogramowanie sprzęgające ma dostęp zarówno do internetu, jak i do bazy danych.

Wymagania systemowe

Wymagania systemowe
System operacyjny Windows lub Linux
Baza danych SQL Dowolna baza danych SQL ze sterownikiem zgodnym z JDBC 4.0 lub nowszym, w tym:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Oprogramowanie Sterownik JDBC używany przez oprogramowanie sprzęgające do uzyskiwania dostępu do bazy danych (pobierany i instalowany oddzielnie)

Wdrażanie oprogramowania sprzęgającego

Poniżej znajdziesz instrukcje instalacji oprogramowania sprzęgającego i konfigurowania go pod kątem indeksowania określonych baz danych i zwracania wyników użytkownikom Cloud Search.

Wymagania wstępne

Przed wdrożeniem oprogramowania sprzęgającego bazy danych Cloud Search zbierz te informacje:

Krok 1. Pobierz i utwórz oprogramowanie sprzęgające bazy danych

  1. Sklonuj repozytorium oprogramowania sprzęgającego z GitHuba. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. Sprawdź odpowiednią wersję oprogramowania sprzęgającego:
    $ git checkout tags/v1-0.0.3
  3. Utwórz oprogramowanie sprzęgające. 
    $ mvn package
    Aby pominąć testy podczas tworzenia oprogramowania sprzęgającego, użyj mvn package -DskipTests.
  4. Skopiuj plik ZIP oprogramowania sprzęgającego do lokalnego katalogu instalacji i rozpakuj go: 
    $ 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

Krok 2. Skonfiguruj oprogramowanie sprzęgające bazy danych

  1. Utwórz plik tekstowy i nadaj mu nazwę connector-config.properties (domyślną) lub podobną. Google zaleca nadawanie plików konfiguracji z rozszerzeniem .properties lub .config oraz przechowywanie ich w tym samym katalogu co oprogramowanie sprzęgające. Jeśli użyjesz innej nazwy lub ścieżki, podczas uruchamiania oprogramowania sprzęgającego musisz określić ścieżkę.
  2. Dodaj parametry w postaci par klucz/wartość do zawartości pliku. Plik konfiguracji musi określać parametry dostępu do źródła danych, dostępu do bazy danych, instrukcji SQL pełnego przemierzania bazy danych, tytułu pola treści oraz definicji kolumn. Możesz też skonfigurować inne działanie oprogramowania sprzęgającego z opcjonalnymi parametrami. Na przykład: 
    # 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

    Szczegółowe opisy parametrów związanych z bazą danych znajdziesz w artykule z informacjami o parametrach konfiguracji na końcu tego artykułu.

    Aby poznać parametry wspólne dla wszystkich programów sprzęgających Cloud Search, takie jak konfiguracja metadanych, formaty daty i godziny czy opcje listy kontroli dostępu, otwórz parametry oprogramowania sprzęgającego dostarczone przez Google.

    W razie potrzeby określ właściwości obiektu schematu w parametrach zapytania SQL przemierzania. Zwykle można dodać aliasy do instrukcji SQL. Jeśli np. masz bazę danych filmu, a schemat źródła danych zawiera definicję właściwości o nazwie „ActorName”, instrukcja SQL może mieć postać: SELECT …, last_name AS ActorName, … FROM … .

Krok 3. Uruchamianie oprogramowania sprzęgającego bazy danych

W poniższym przykładzie założono, że wymagane komponenty znajdują się w katalogu lokalnym w systemie Linux.

Aby uruchomić oprogramowanie sprzęgające z poziomu wiersza poleceń, wpisz następujące polecenie: 

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]

Gdzie:

  • google-cloud-search-database-connector-v1-0.0.3.jar to plik .jar oprogramowania sprzęgającego bazy danych
  • mysql-connector-java-5.1.41-bin.jar to sterownik JDBC używany do uzyskiwania dostępu do bazy danych
  • mysql.config to plik konfiguracji o niestandardowej nazwie. Aby mieć pewność, że oprogramowanie sprzęgające rozpozna plik konfiguracji, podaj jego ścieżkę w wierszu poleceń. W przeciwnym razie oprogramowanie sprzęgające będzie używać jako domyślnej nazwy pliku nazwy connector-config.properties z katalogu lokalnego.

Oprogramowanie sprzęgające zgłasza błędy konfiguracji w miarę ich wykrycia. Niektóre błędy są zgłaszane podczas inicjowania oprogramowania sprzęgającego, na przykład gdy kolumna bazy danych jest zdefiniowana jako część treści rekordu (w db.allColumns), ale ta kolumna nie jest używana w zapytaniu SQL przemierzania bazy danych (w db.allRecordsSql). Inne błędy są wykrywane i zgłaszane tylko wtedy, gdy oprogramowanie sprzęgające próbuje uzyskać dostęp do bazy danych podczas pierwszego przemierzania (np. nieprawidłowa składnia SQL).

Informacje o parametrach konfiguracji

Parametry dostępu do źródła danych

lokalizacji, Parametr
Identyfikator źródła danych api.sourceId = source-ID

To pole jest wymagane. Identyfikator źródła Cloud Search skonfigurowany przez administratora Google Workspace.
Identyfikator źródła tożsamości api.identitySourceId = identity-source-ID

Wymagane do używania zewnętrznych użytkowników i grup na potrzeby list kontroli dostępu. Identyfikator źródła tożsamości Cloud Search skonfigurowany przez administratora Google Workspace.
Konto usługi api.serviceAccountPrivateKeyFile = path-to-private-key

To pole jest wymagane. Ścieżka do pliku klucza konta usługi Cloud Search utworzonego przez administratora Google Workspace.

Parametry dostępu do bazy danych

lokalizacji, Parametr
Adres URL bazy danych db.url = database-URL

To pole jest wymagane. Pełna ścieżka bazy danych, do której chcesz uzyskać dostęp, np. jdbc:mysql://127.0.0.1/dbname.
Nazwa użytkownika i hasło do bazy danych db.user = username
db.password = password

To pole jest wymagane. Prawidłowa nazwa użytkownika i hasło, za pomocą których oprogramowanie sprzęgające uzyskuje dostęp do bazy danych. Ten użytkownik bazy danych musi mieć uprawnienia do odczytu odpowiednich rekordów odczytywanej bazy danych.
Sterownik JDBC db.driverClass = oracle.jdbc.OracleDriver

Wymagane tylko wtedy, gdy sterownik JDBC 4.0 nie został jeszcze określony w ścieżce klasy.

Parametry zapytania SQL przemierzania

Oprogramowanie sprzęgające przeszukuje rekordy bazy danych za pomocą zapytań SQL SELECT w pliku konfiguracji. Musisz skonfigurować zapytanie obejmujące pełne przemierzanie. Zapytania dotyczące przemierzania przyrostowego są opcjonalne.

Pełne przemierzanie odczytuje każdy rekord bazy danych skonfigurowany na potrzeby indeksowania. Pełne przemierzanie jest wymagane w celu indeksowania nowych rekordów w Cloud Search, a także ponownego zindeksowania wszystkich istniejących rekordów.

Przyrostowe przemierzanie odczytuje i ponownie indeksuje tylko nowo zmodyfikowane rekordy bazy danych oraz ostatnie wpisy w bazie danych. Przemierzenia przyrostowe mogą być skuteczniejsze niż pełne. Aby można było korzystać z przyrostowego przemierzania, baza danych musi zawierać pola sygnatur czasowych wskazujące zmodyfikowane rekordy.

Oprogramowanie sprzęgające uruchamia te przemierzanie zgodnie z harmonogramami określonymi przez Ciebie w parametrach harmonogramu przemierzania.

lokalizacji, Parametr
Zapytanie o pełne przemierzanie db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

To pole jest wymagane. Zapytanie jest wykonywane przy każdym pełnym przemierzeniu.

Każda nazwa kolumny, której oprogramowanie sprzęgające będzie używać w ramach dowolnej pojemności (treść, unikalny identyfikator, listy kontroli dostępu), musi być obecna w tym zapytaniu. Oprogramowanie sprzęgające przeprowadza wstępną weryfikację podczas uruchamiania, aby wykryć błędy i pominięcia. Z tego powodu nie używaj ogólnego zapytania „SELECT * FROM ...”.
Pełny podział na strony db.allRecordsSql.pagination = {none | offset}

Możliwe wartości:

  • none: nie używaj podziału na strony.
  • offset: użyj podziału na strony według przesunięcia wiersza

    Aby można było użyć podziału na strony według przesunięcia, zapytanie SQL musi zawierać zastępczy znak zapytania (?) dla przesunięcia wiersza zaczynający się od zera. W każdym pełnym przemierzeniu zapytanie jest wykonywane wielokrotnie, aż nie zostaną zwrócone żadne wyniki.
Zapytanie o przemierzanie przyrostowe db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

Wymagane, jeśli zaplanujesz dodatkowe przemierzanie.

Znak „?” w zapytaniu jest obowiązkowym obiektem zastępczym wartości sygnatury czasowej. Oprogramowanie sprzęgające korzysta z sygnatury czasowej do śledzenia modyfikacji między zapytaniami SQL przemierzania przyrostowego.

Aby śledzić kolumnę sygnatury czasowej bazy danych dla czasu ostatniej aktualizacji, dodaj alias timestamp_column do instrukcji SQL. W przeciwnym razie użyj bieżącej sygnatury czasowej przemierzania przez oprogramowanie sprzęgające.

W pierwszym przyrostowym przemierzeniu oprogramowanie sprzęgające używa czasu rozpoczęcia działania oprogramowania sprzęgającego. Po pierwszym przemierzeniu przyrostowym Cloud Search przechowuje sygnaturę czasową, aby ponowne uruchomienia oprogramowania sprzęgającego miały dostęp do poprzedniej sygnatury czasowej przyrostowego przemierzania.
Strefa czasowa bazy danych db.timestamp.timezone = America/Los_Angeles

Określa strefę czasową, która ma być używana na potrzeby sygnatur czasowych bazy danych. Sygnatura czasowa bazy danych służąca do identyfikowania nowo dodanych lub zmodyfikowanych rekordów bazy danych. Domyślną wartością jest lokalna strefa czasowa, w której działa oprogramowanie sprzęgające.

Przykłady zapytań SQL przemierzania

  • Podstawowe zapytanie o pełnym przemierzeniu, które odczytuje każdy rekord w bazie danych pracowników na potrzeby indeksowania: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • Określ podział na strony według przesunięcia i podziel pełne przemierzanie na kilka zapytań.

    W przypadku SQL Server 2012 lub Oracle 12c (standardowa składnia 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

    albo dla MySQL lub 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
  • Zapytanie o pełne przemierzanie, które stosuje poszczególne listy kontroli dostępu z aliasami: 
    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
  • Podstawowe zapytanie przyrostowe przemierzania: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • Zapytanie o przemierzanie przyrostowe, które stosuje poszczególne listy kontroli dostępu z aliasami: 
    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 > ?
  • Zapytanie o przemierzanie przyrostowe, które korzysta z sygnatury czasowej bazy danych, a nie z bieżącego czasu: 
    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 > ?

Parametry definicji kolumn

Poniższe parametry określają kolumny używane w instrukcjach przemierzania oraz do jednoznacznej identyfikacji każdego rekordu.

lokalizacji, Parametr
Wszystkie kolumny db.allColumns = column-1, column-2, ...column-N

To pole jest wymagane. Identyfikuje wszystkie kolumny wymagane w zapytaniu SQL podczas uzyskiwania dostępu do bazy danych. Kolumny zdefiniowane za pomocą tego parametru muszą mieć wyraźne odwołania w zapytaniach. Wszystkie pozostałe parametry definicji kolumny są porównywane z tym zestawem kolumn.

Przykład:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
Unikalne kolumny kluczowe db.uniqueKeyColumns = column-1[, column-2]

To pole jest wymagane. Wyświetla jedną kolumnę bazy danych zawierającą unikalne wartości lub kombinację kolumn, których wartości razem definiują unikalny identyfikator.

Cloud Search wymaga, aby każdy dokument, który można przeszukiwać, miał unikalny identyfikator w obrębie źródła danych. Musisz mieć możliwość zdefiniowania unikalnego identyfikatora dla każdego rekordu bazy danych z wartości kolumny. Jeśli używasz wielu programów sprzęgających w oddzielnych bazach danych, ale indeksujesz je we wspólnym zbiorze danych, pamiętaj, by określić unikalny identyfikator we wszystkich dokumentach.

Przykłady:

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

To pole jest wymagane. Określa co najmniej jedną prawidłową, zdefiniowaną nazwę kolumn używanych w przypadku adresu URL używanego na potrzeby klikalnego wyniku wyszukiwania. W przypadku baz danych, które nie mają odpowiedniego adresu URL powiązanego z każdym rekordem bazy danych, dla każdego rekordu może być używany link statyczny.

Jeśli jednak wartości kolumn definiują prawidłowy link dla każdego rekordu, należy określić kolumny adresu URL widoku i wartości konfiguracji formatu.
Format adresu URL url.format = https://www.example.com/{0}

Określa format adresu URL widoku. Parametry numerowane odwołują się do kolumn określonych w db.columns, zaczynając od zera.

Jeśli nie podasz żadnej wartości, zostanie użyta wartość domyślna „{0}.”.

Przykłady poniżej.
Kolumny zakodowane za pomocą procentów w przypadku adresu URL url.columnsToEscape = column-1[, column-2]

Określa kolumny z db.columns, których wartości będą zakodowane za pomocą procentów, zanim zostaną uwzględnione w sformatowanym ciągu znaków adresu URL.

Przykłady kolumn z adresami URL

Aby określić kolumny używane w zapytaniach przemierzania oraz format adresu URL widoku:

  • Aby użyć statycznego adresu URL bez wartości rekordów bazy danych: 
    url.format = https://www.example.com
  • Aby użyć wartości pojedynczej kolumny, która jest adresem URL widoku: 
    url.format = {0}
url.columns = customer_id
  • Aby użyć wartości z jednej kolumny, która zostanie zastąpiona w adresie URL widoku danych w pozycji {0}: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • Aby użyć wielu wartości kolumn do utworzenia adresu URL widoku (kolumny są zależne od kolejności): 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

Pola treści

Użyj opcji treści, aby określić, które wartości rekordów mają być częścią treści dostępnej do przeszukiwania.

lokalizacji, Parametr
Kolumna wyszukiwania najwyższej jakości contentTemplate.db.title = column-name

To pole jest wymagane. Kolumna o najwyższej jakości na potrzeby indeksowania wyszukiwania i ustalania priorytetów wyników.
Priorytety kolumn w wyszukiwaniu contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

Kolumny z treścią (z wyjątkiem kolumn ustawionych dla kolumny contentTemplate.db.title) jako pola o wysokiej, średniej lub niskiej jakości wyszukiwania. Nieokreślone kolumny mają domyślnie wartość „niska”.
Kolumny danych o treści db.contentColumns = column-1[, column-2...]

Określ kolumny z treścią w bazie danych. Są one sformatowane i przesyłane do Cloud Search jako treści dokumentów, które można przeszukiwać.

Jeśli nie określisz wartości, zostanie użyta domyślna wartość „*”, co oznacza, że w przypadku treści powinny być używane wszystkie kolumny.
Kolumna obiektu blob db.blobColumn = column-name

Podaj nazwę pojedynczej kolumny bloba, która ma być używana na potrzeby treści dokumentu, a nie kombinacji kolumn treści.

Jeśli podasz kolumnę bloba, to gdy zdefiniowano też kolumny treści, zostanie uznany za błąd. Jednak metadane i definicje kolumn uporządkowanych danych są nadal dozwolone wraz z kolumnami blob.