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:
|
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:
- Klucz prywatny Google Workspace, który zawiera też identyfikator konta usługi. Informacje o tym, jak uzyskać klucz prywatny, znajdziesz w sekcji Konfigurowanie dostępu do interfejsu Google Cloud Search API typu REST.
- Identyfikator źródła danych Google Workspace. O tym, jak uzyskać identyfikator źródła danych, dowiesz się z sekcji Dodawanie źródła danych do wyszukiwania.
Krok 1. Pobierz i utwórz oprogramowanie sprzęgające bazy danych
- Sklonuj repozytorium oprogramowania sprzęgającego z GitHuba.
$ git clone https://github.com/google-cloudsearch/database-connector.git $ cd database-connector
- Sprawdź odpowiednią wersję oprogramowania sprzęgającego:
$ git checkout tags/v1-0.0.3
- Utwórz oprogramowanie sprzęgające.
$ mvn package
Aby pominąć testy podczas tworzenia oprogramowania sprzęgającego, użyjmvn package -DskipTests
. - 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
- 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ę. - 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 danychmysql-connector-java-5.1.41-bin.jar
to sterownik JDBC używany do uzyskiwania dostępu do bazy danychmysql.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 nazwyconnector-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. |
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:
|
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 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 |
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. |