Wdrażanie oprogramowania sprzęgającego bazy danych

Ostrzeżenie: oprogramowanie sprzęgające Cloud Search do plików referencyjnych jest dostarczane w stanie „takim, jaki jest” jako przykładowy kod do wykorzystania przy tworzeniu własnego działającego oprogramowania sprzęgającego. Ten przykładowy kod wymaga należy wprowadzić znaczne modyfikacje i testy przed użyciem w modelu koncepcyjnym lub środowiska produkcyjne. W przypadku zastosowań produkcyjnych zdecydowanie zalecamy uzyskanie pomocy od jednego z naszych partnerów Cloud Search. Jeśli potrzebujesz dalszej pomocy w znalezieniu odpowiedniej chmury Partner wyszukiwania, skontaktuj się ze swoim opiekunem klienta w Google.

Możesz skonfigurować usługę Google Cloud Search tak, aby wykrywała i indeksowała dane z z baz danych za pomocą oprogramowania sprzęgającego 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 w Javie, o ile oprogramowanie sprzęgające ma dostęp do obu funkcji między internetem a bazą danych.

Wymagania systemowe

Wymagania systemowe
System operacyjny Windows lub Linux
Baza danych SQL Każda baza danych SQL ze sterownikiem zgodnym z JDBC 4.0 lub nowszym, w tym:
  • Serwer MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Oprogramowanie Sterownik JDBC dla oprogramowania sprzęgającego służącego do uzyskiwania dostępu do bazy danych (pobierane i instalowane oddzielnie)

Wdrażanie oprogramowania sprzęgającego

Poniższe kroki opisują sposób instalowania i konfigurowania oprogramowania sprzęgającego do indeksowania określonych baz danych i zwrócenia wyników użytkownikom Cloud Search.

Wymagania wstępne

Zanim wdrożysz oprogramowanie sprzęgające 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ź wybraną 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. Konfigurowanie oprogramowania sprzęgającego bazy danych

  1. Utwórz plik tekstowy i nadaj mu nazwę connector-config.properties (domyślnie) lub podobną. Zalecenia Google nadawania nazw plikom konfiguracji za pomocą funkcji .properties lub .config i zachowaj plik w tym samym katalogu co oprogramowanie sprzęgające. Jeśli użyjesz innej nazwy lub ścieżki, musisz ją podać podczas uruchamiania oprogramowania sprzęgającego.
  2. Dodaj parametry jako pary klucz/wartość do zawartości pliku. Plik konfiguracji musi określić parametry dostępu do źródła danych, dostęp do bazy danych, instrukcja SQL przemierzania całej bazy danych tytuł pola treści i definicje 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 Dokumentacja parametrów konfiguracji na końcu tego artykułu.

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

    W razie potrzeby określ właściwości obiektu schematu w kodzie SQL przemierzania parametrów zapytania. Zwykle można dodać aliasy do SQL. . Na przykład, jeśli masz film baza danych, a schemat źródła danych zawiera definicję właściwości o nazwie „Użytkownik, który wykonał czynność”, instrukcja SQL może mieć postać: SELECT …, last_name AS ActorName, … FROM … .

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

W tym przykładzie założono, że wymagane komponenty znajdują się w regionie w systemie Linux.

Aby uruchomić oprogramowanie sprzęgające z 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 używany sterownik JDBC aby uzyskać dostęp do bazy danych
  • mysql.config to plik konfiguracji o niestandardowej nazwie. Aby oprogramowanie sprzęgające rozpoznawało i określ jego ścieżkę w wierszu poleceń. W przeciwnym razie oprogramowanie sprzęgające korzysta z funkcji connector-config.properties w Twojej okolicy jako domyślną nazwę pliku.

Oprogramowanie sprzęgające zgłasza błędy konfiguracji, gdy je wykryje. Niektóre błędy są zgłaszane, gdy inicjuje oprogramowanie sprzęgające, na przykład gdy kolumna bazy danych jest zdefiniowana jako część treści rekordu. (w db.allColumns), ale kolumna nie jest używana w zapytaniu SQL przemierzającym w bazie danych (w db.allRecordsSql). Inne błędy są wykrywane i raportowane tylko wtedy, oprogramowanie sprzęgające próbuje uzyskać dostęp do bazy danych podczas pierwszego przemierzania, np. do nieprawidłowej składni instrukcji SQL.

Dokumentacja parametrów konfiguracji

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

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

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

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

Wymagane. Ścieżka do Cloud Search utworzony przez administratora Google Workspace plik klucza konta usługi.

Parametry dostępu do bazy danych

Ustawienie Parametr
Adres URL bazy danych db.url = database-URL

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

Wymagane. Prawidłowa nazwa użytkownika oraz hasło używane przez oprogramowanie sprzęgające do uzyskiwania dostępu do bazy danych. Ten użytkownik bazy danych musi mieć dostęp w trybie odczytu do odpowiednich rekordów odczytywanej bazy danych.
Sterownik JDBC db.driverClass = oracle.jdbc.OracleDriver

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

Parametry zapytania SQL przemierzania

Oprogramowanie sprzęgające przemierza rekordy bazy danych za pomocą funkcji SQL SELECT i zapytania w pliku konfiguracji. Musisz skonfigurować zapytanie pełnego przemierzania; zapytań dla przemierzania przyrostowe są opcjonalne.

Funkcja pełnego przemierzania odczytuje każdy rekord bazy danych skonfigurowany na potrzeby indeksowania. Pełny przemierzanie jest wymagane do indeksowania nowych rekordów na potrzeby Cloud Search oraz do ponownego indeksowania wszystkich istniejących rekordów.

Przemierzanie przyrostowe odczytuje i ponownie indeksuje tylko nowo zmodyfikowaną bazę danych i najnowsze wpisy w bazie danych. Przemierzenia przyrostowe mogą być skuteczniejsze niż przez pełne przemierzenie. Aby można było używać przemierzania przyrostowego, baza danych musi zawierać pola sygnatury czasowej w celu wskazania zmodyfikowanych rekordów.

Oprogramowanie sprzęgające wykonuje te przemierzanie zgodnie z harmonogramami zdefiniowanymi w parametry harmonogramu przemierzania.

Ustawienie Parametr
Zapytanie pełnego przemierzania db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

Wymagane. Zapytanie jest wykonywane w przypadku każdego pełnego przemierzania.

Nazwa kolumny, której oprogramowanie sprzęgające będzie używać w to zapytanie musi zawierać pojemność (treść, unikalny identyfikator, listy kontroli dostępu). oprogramowanie sprzęgające przeprowadza wstępną weryfikację podczas uruchamiania, aby wykryć błędy i pominięć. Dlatego nie używaj ogólnego atrybutu „SELECT * FROM ...”. zapytania.
Podział na strony w ramach pełnego przemierzania db.allRecordsSql.pagination = {none | offset}

Możliwe wartości:

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

    Aby można było używać podziału na strony według przesunięcia, zapytanie SQL musi mieć zastępczy znak zapytania (?) dla przesunięcia wiersza, zaczynając od zera. Podczas każdego pełnego przemierzania zapytanie jest wykonywane wielokrotnie dopóki 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 przemierzanie przyrostowe.

Znak „?” to obowiązkowa zmienna dla 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 pod kątem czasu ostatniej aktualizacji, dodaj timestamp_column alias dla instrukcji SQL; W przeciwnym razie użyj bieżącej sygnatury czasowej aby uzyskać dostęp do wszystkich funkcji oprogramowania sprzęgającego.

W przypadku pierwszego przemierzania przyrostowego oprogramowanie sprzęgające używa czasu rozpoczęcia oprogramowania sprzęgającego. Po Cloud Search zapisuje sygnaturę czasową, ponowne uruchomienia oprogramowania sprzęgającego dają dostęp do poprzedniego przyrostowego przemierzania .
Strefa czasowa bazy danych db.timestamp.timezone = America/Los_Angeles

Określa strefę czasową używaną na potrzeby sygnatur czasowych bazy danych. Sygnatura czasowa bazy danych używana do identyfikowania nowo dodanych rekordów zmodyfikowanych rekordów bazy danych. Wartość domyślna to lokalna strefa czasowa, w której działa oprogramowanie sprzęgające.

Przykłady zapytań SQL przemierzania

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

    W przypadku serwera 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

    w przypadku 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 pełnego przemierzania, 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 dotyczące przemierzania przyrostowego: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • Zapytanie przemierzania przyrostowego, które stosuje poszczególne listy kontroli dostępu (ACL) 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 przemierzania przyrostowego, które używa sygnatury czasowej bazy danych zamiast 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 kolumny

Poniższe parametry określają kolumny używane w instrukcjach przemierzania oraz do: jednoznacznie identyfikować każdy rekord.

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

Wymagane. Identyfikuje wszystkie kolumny które są wymagane w zapytaniu SQL przy uzyskiwaniu dostępu do bazy danych. Kolumny zdefiniowane za pomocą tego parametru muszą być wyraźnie odwoływane w zapytaniach. Co inny parametr definicji kolumny zostanie porównany z tym zestawem kolumn.

Przykład:

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

Wymagane. Wyświetla listę: jedną kolumnę bazy danych, która zawiera unikalne wartości lub stanowi 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 źródle danych. Musisz mieć możliwość zdefiniowania unikalnego identyfikatora dla każdego rekordu bazy danych od wartości kolumn. Jeśli korzystasz z wielu programów sprzęgających w osobnych bazach danych, ale do wspólnego zbioru danych, pamiętaj, aby podać 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]

Wymagane. Wskazuje co najmniej jedną prawidłową, określoną nazwy kolumn użytych w adresie URL do klikalnego wyniku wyszukiwania. W przypadku baz danych, w których nie ma żadnego odpowiedniego adresu URL powiązanego z każdym rekordem bazy danych, statycznego linku można użyć dla każdego rekordu.

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

Określa format adresu URL widoku. Parametry numerowane odnoszą się do kolumn określone w db.columns w kolejności, zaczynając od zera.

Jeśli nie określisz tu żadnej wartości, zostanie użyte ustawienie domyślne „{0}.”

Przykłady podano w tabeli poniżej.
Zakodowane procentowo kolumny adresu URL url.columnsToEscape = column-1[, column-2]

Określa kolumny z kolumny db.columns, których wartości będą zakodowane procentowo. przed umieszczeniem ich w sformatowanym ciągu adresu URL.

Przykłady kolumn z adresami URL

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

  • Aby użyć statycznego adresu URL, który nie korzysta z żadnych wartości rekordów bazy danych: 
    url.format = https://www.example.com
  • Aby użyć wartości z jednej kolumny, która jest adresem URL wyświetlenia: 
    url.format = {0}
url.columns = customer_id
  • Aby użyć wartości z jednej kolumny zastępowanej adresem URL wyświetlenia w pozycji {0}: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • Aby utworzyć adres URL widoku danych za pomocą wielu wartości w kolumnach (kolumny zależą 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 powinny zostać uwzględnione w treści możliwej do wyszukania.

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

Wymagane. Kolumna o najwyższej jakości służącej do indeksowania wyszukiwań i określania priorytetów wyników.
Priorytety kolumn w sieci wyszukiwania contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

Wskazywanie kolumn z treścią (z wyjątkiem kolumn ustawionych dla kolumny contentTemplate.db.title) o wysokiej, średniej lub niskiej jakości. W nieokreślonych kolumnach domyślnie ustawiona jest niska wartość.
Kolumny danych o treści db.contentColumns = column-1[, column-2...]

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

Jeśli nie określisz wartości, zostanie przyjęta wartość domyślna „*”. co oznacza, że wszystkie kolumn dla treści.
Kolumna obiektu blob db.blobColumn = column-name

Podaj nazwę pojedynczego obiektu blob , która ma być używana do określania treści dokumentu, a nie jako kombinacji kolumn treści.

Określona kolumna blob jest uznawana za błąd, jeśli kolumna z treścią również są zdefiniowane. Definicje kolumn metadanych i uporządkowanych danych są jednak jest wciąż dozwolona wraz z kolumnami blob.