Ten przewodnik jest przeznaczony dla administratorów łącznika Google Cloud Search CSV (wartości rozdzielane przecinkami), czyli osób odpowiedzialnych za pobieranie, konfigurowanie, uruchamianie i monitorowanie tego łącznika.
Ten przewodnik zawiera instrukcje wykonywania kluczowych zadań związanych z wdrażaniem łącznika CSV:
- Pobieranie oprogramowania łącznika CSV do Google Cloud Search
- Skonfiguruj złącze do użycia z określonym źródłem danych CSV
- Wdrażanie i uruchamianie łącznika
Aby zrozumieć pojęcia zawarte w tym dokumencie, musisz znać podstawy Google Workspace, plików CSV i list kontroli dostępu (ACL).
Omówienie programu CSV do przesyłania danych do Google Cloud Search
Złącze CSV Cloud Search działa z dowolnym plikiem tekstowym CSV. Plik CSV przechowuje dane tabelaryczne, a każdy wiersz pliku jest rekordem danych.
Sprzęgające oprogramowanie CSV w usłudze Google Cloud Search wyodrębnia poszczególne wiersze z pliku CSV i indeksuje je w Cloud Search za pomocą interfejsu Cloud Search Indexing API. Po zindeksowaniu poszczególnych wierszy plików CSV można je wyszukiwać za pomocą klientów Cloud Search lub interfejsu Query API Cloud Search. Złącze CSV umożliwia też kontrolowanie dostępu użytkowników do treści w wynikach wyszukiwania za pomocą list ACL.
Oprogramowanie sprzęgające CSV usługi Google Cloud Search można zainstalować w systemie Linux lub Windows. Zanim wdrożysz łącznik CSV Google Cloud Search, upewnij się, że masz te wymagane komponenty:
- Java JRE 1.8 zainstalowana na komputerze, na którym działa łącznik CSV do Google Cloud Search
Informacje Google Workspace wymagane do ustanowienia relacji między Google Cloud Search a źródłem danych:
- klucz prywatny Google Workspace (zawierający identyfikator konta usługi);
- Identyfikator źródła danych Google Workspace
Zwykle administrator Google Workspace w domenie może udostępnić te dane logowania.
Etapy wdrażania
Aby wdrożyć konwerter CSV do Google Cloud Search:
- Instalowanie oprogramowania łącznika CSV Google Cloud Search
- Konfigurowanie połączenia CSV
- Konfigurowanie dostępu do źródła danych Google Cloud Search
- Konfigurowanie dostępu do pliku CSV
- Określ nazwy kolumn do indeksowania, kolumny z unikalnym kluczem i kolumny z datą i godziną
- Określanie kolumn do użycia w klikalnych adresach URL wyników wyszukiwania
- Określanie informacji metadanych i formatów kolumn
- Planowanie przechodzenia przez dane
- Określanie opcji listy kontroli dostępu (ACL)
1. Instalowanie pakietu SDK
Zainstaluj pakiet SDK w lokalnym repozytorium Maven.
Sklonuj repozytorium SDK z GitHuba.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Pobierz odpowiednią wersję pakietu SDK:
$ git checkout tags/v1-0.0.3Utwórz oprogramowanie sprzęgające:
$ mvn packageSkopiuj plik ZIP z oprogramowaniem sprzęgającym do lokalnego katalogu instalacji:
$ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir $ cd installation-dir $ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip $ cd google-cloudsearch-csv-connector-v1-0.0.3
2. Określanie konfiguracji łącznika CSV
Jako administrator łącznika możesz kontrolować zachowanie i atrybuty łącznika CSV, definiując parametry w pliku konfiguracyjnym łącznika. Parametry, które można konfigurować:
- Dostęp do źródła danych
- Lokalizacja pliku CSV
- Definicje kolumn w pliku CSV
- Kolumny, które definiują niepowtarzalny identyfikator
- Opcje przeszukiwania
- Opcje ACL do ograniczania dostępu do danych
Aby usługa konwertera miała prawidłowy dostęp do pliku CSV i mogła zindeksować odpowiednie treści, musisz najpierw utworzyć plik konfiguracji.
Aby utworzyć plik konfiguracji:
- Otwórz dowolny edytor tekstu i nadaj nazwę plikowi konfiguracji.
Dodaj do treści pliku pary klucz=wartość zgodnie z opisem w następnych sekcjach. - Zapisz plik konfiguracji i nadaj mu nazwę.
Google zaleca, aby nazwa pliku konfiguracji była taka jakconnector-config.properties, aby nie trzeba było podawać dodatkowych parametrów wiersza poleceń podczas uruchamiania oprogramowania sprzęgającego.
Ponieważ ścieżkę do pliku konfiguracyjnego można podać w wierszu poleceń, standardowa lokalizacja pliku nie jest wymagana. Plik konfiguracji powinien jednak znajdować się w tym samym katalogu co łącznik, aby ułatwić śledzenie i uruchamianie tego łącznika.
Aby mieć pewność, że oprogramowanie sprzęgające rozpozna Twój plik konfiguracji, określ jego ścieżkę na linii poleceń. W przeciwnym razie łącznik używa nazwy connector-config.properties w katalogu lokalnym jako nazwy pliku domyślnego. Informacje o określaniu ścieżki konfiguracji w wierszu poleceń znajdziesz w artykule Uruchamianie programu sprzęgającego CSV Cloud Search.
3. Konfigurowanie dostępu do źródła danych Google Cloud Search
Pierwszymi parametrami, które musi zawierać każdy plik konfiguracji, są te, które są potrzebne do uzyskania dostępu do źródła danych Cloud Search, jak pokazano w tabeli poniżej. Aby skonfigurować dostęp łącznika do Cloud Search, zazwyczaj potrzebujesz identyfikatora źródła danych, identyfikatora konta usługi i ścieżki do pliku klucza prywatnego konta usługi. Instrukcje konfigurowania źródła danych znajdziesz w artykule Zarządzanie zewnętrznymi źródłami danych.
| Ustawienie | Parametr |
| Identyfikator źródła danych | api.sourceId=1234567890abcdef
Wymagane. Identyfikator źródła Google Cloud Search skonfigurowany przez administratora Google Workspace zgodnie z opisem w artykule Zarządzanie zewnętrznymi źródłami danych. |
| Ścieżka do pliku klucza prywatnego konta usługi | api.serviceAccountPrivateKeyFile=./PrivateKey.json
Wymagane. Plik klucza konta usługi Google Cloud Search do obsługi złącza CSV Google Cloud Search. |
| Identyfikator źródła tożsamości | api.identitySourceId=x0987654321
Wymagane, jeśli używasz użytkowników i grup zewnętrznych. Identyfikator źródła tożsamości Google Cloud Search skonfigurowany przez administratora Google Workspace. |
4. Konfigurowanie parametrów pliku CSV
Zanim oprogramowanie sprzęgające przejdzie przez plik CSV i wyodrębni z niego dane na potrzeby indeksowania, musisz określić ścieżkę do tego pliku. Możesz też określić format pliku i typ kodowania. Aby określić właściwości pliku CSV w pliku konfiguracji, dodaj te parametry.
| Ustawienie | Parametr |
| Ścieżka do pliku CSV | csv.filePath=./movie_content.csv
Wymagane. Ścieżka do pliku CSV, do którego chcesz uzyskać dostęp i z którego chcesz wyodrębnić treści na potrzeby indeksowania. |
| Format pliku | csv.format=DEFAULT
Format pliku. Możliwe wartości to wartości klasy Apache Commons CSV CSVFormat. Wartości formatu to: |
| Modyfikator formatu pliku | csv.format.withMethod=value
Zmiana sposobu obsługi pliku przez Cloud Search. Możliwe metody pochodzą z klasy CSVFormat pakietu Apache Commons CSV i obejmują te, które przyjmują pojedynczy znak, ciąg znaków lub wartość logiczną. Aby na przykład użyć średnika jako separatora, użyj |
| Typ kodowania pliku | csv.fileEncoding=UTF-8
Zestaw znaków Java, który ma być używany, gdy Cloud Search odczytuje plik. Jeśli nie zostanie określony, Cloud Search użyje domyślnego zestawu znaków na platformie. |
5. Określ nazwy kolumn do indeksowania i kolumn kluczy unikalnych
Aby umożliwić mu dostęp do plików CSV i ich indeksowanie, musisz podać informacje o definicjach kolumn w pliku konfiguracyjnym. Jeśli plik konfiguracji nie zawiera parametrów określających nazwy kolumn indeksu i kolumn kluczy unikalnych, używane są wartości domyślne.
| Ustawienie | Parametr |
| Kolumny do zindeksowania | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
nazwy kolumn, które mają zostać zindeksowane z pliku CSV; Jeśli parametr |
| Kolumny z unikalnymi kluczami | csv.uniqueKeyColumns=movieId
Kolumny CSV, których wartości będą używane do generowania unikalnego identyfikatora każdej pozycji. Jeśli nie zostanie podany, jako unikalny klucz należy użyć hasha rekordu CSV. Wartością domyślną jest kod szyfrowania rekordu. |
6. Określanie kolumn do użycia w klikalnych adresach URL wyników wyszukiwania
Gdy użytkownik wyszukuje informacje za pomocą Google Cloud Search, usługa wyświetla stronę wyników z możliwością kliknięcia adresów URL każdego wyniku. Aby włączyć tę funkcję, dodaj do pliku konfiguracji parametr pokazany w tabeli poniżej.
| Ustawienie | Parametr |
| Format adresu URL wyniku wyszukiwania | url.format=https://mymoviesite.com/movies/{0}
Wymagane. Format, w którym należy utworzyć adres URL widoku dla treści CSV. |
| Parametry adresu URL wyników wyszukiwania. | url.columns=movieId
Wymagane. Nazwy kolumn pliku CSV, których wartości będą używane do generowania adresu URL widoku rekordu. |
| Parametry adresu URL wyników wyszukiwania, które należy zamienić na znaki ucieczki | url.columnsToEscape=movieId
Opcjonalnie: Nazwy kolumn CSV, których wartości zostaną ujęte w znakach ucieczkowych w celu wygenerowania prawidłowego adresu URL widoku. |
7. Określ informacje o metadanych, formaty kolumn i jakość wyszukiwania
Do pliku konfiguracji możesz dodać parametry, które określają:
Parametry konfiguracji metadanych
Parametry konfiguracji metadanych opisują kolumny CSV używane do wypełniania metadanych produktu. Jeśli plik konfiguracji nie zawiera tych parametrów, używane są wartości domyślne. Parametry te są podane w tabeli poniżej.
| Ustawienie | Parametr |
| Tytuł | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
Atrybut metadanych zawierający wartość odpowiadającą tyłowi dokumentu. Wartością domyślną jest pusty ciąg znaków. |
| URL | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
Atrybut metadanych zawierający wartość adresu URL dokumentu w wynikach wyszukiwania. |
| Sygnatura czasowa utworzenia | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
Atrybut metadanych zawierający wartość sygnatury czasowej utworzenia dokumentu. |
| Czas ostatniej modyfikacji | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
Atrybut metadanych zawierający wartość sygnatury czasowej ostatniej modyfikacji dokumentu. |
| Język dokumentu | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
Język treści dokumentów indeksowanych. |
| Typ obiektu schematu | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
Typ obiektu używany przez łącznik, zdefiniowany w schemacie. Jeśli ta usługa nie jest określona, usługa sprzęgająca nie będzie indeksować żadnych danych uporządkowanych. |
Formaty daty i godziny
Formaty daty i godziny określają formaty oczekiwane w atrybutach metadanych. Jeśli plik konfiguracji nie zawiera tego parametru, używane są wartości domyślne. Parametr ten jest widoczny w tabeli poniżej.
| Ustawienie | Parametr |
| Dodatkowe formaty daty i godziny | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Lista dodatkowych wzorów java.time.format.DateTimeFormatter rozdzielona średnikiem. Te wzorce są używane podczas analizowania wartości ciągu znaków w polach daty lub daty i godziny w metadanych lub schemacie. Wartość domyślna to pusta lista, ale formaty RFC 3339 i RFC 1123 są zawsze obsługiwane. |
Formaty kolumn
Formaty kolumn określają informacje o kolumnach, które powinny być częścią treści możliwych do wyszukiwania. Jeśli plik konfiguracji nie zawiera tych parametrów, używane są wartości domyślne. Parametry te są podane w tabeli poniżej.
| Ustawienie | Parametr |
| Pomiń nagłówek | csv.skipHeaderRecord=true
Wartość logiczna. Zignoruj rekord nagłówka (pierwszy wiersz) w pliku CSV. Jeśli ustawisz parametr |
| Kolumny z wieloma wartościami | csv.multiValueColumns=genre,actors
nazwy kolumn w pliku CSV, które mają wiele wartości; Wartością domyślną jest pusty ciąg znaków. |
| Separator kolumn wielowartościowych | csv.multiValue.genre=;
Separator kolumn wielowartościowych. Domyślnym separatorem jest przecinek. |
Jakość wyszukiwania
Oprogramowanie sprzęgające Cloud Search CSV umożliwia automatyczne formatowanie w formacie HTML pól danych. Łącznik definiuje pola danych na początku jego wykonywania, a potem używa szablonu treści do formatowania każdego rekordu danych przed przesłaniem go do Cloud Search.
Szablon treści określa znaczenie każdej wartości pola w wyszukiwaniu. Pole tytułu jest wymagane i ma najwyższy priorytet. Możesz wyznaczyć poziomy ważności jakości wyszukiwania dla wszystkich innych pól treści: wysoki, średni lub niski. Wszelkie pola treści niezdefiniowane w konkretnej kategorii mają domyślnie niski priorytet. Parametry te są podane w tabeli poniżej.
| Ustawienie | Parametr |
| Tytuł treści | contentTemplate.csv.title=movieTitle
Tytuł treści to pole o najwyższej jakości w wyszukiwarce. |
| Wysoka jakość wyszukiwania w przypadku pól treści | contentTemplate.csv.quality.high=actors
Pola treści o wysokiej wartości jakości wyszukiwania. Domyślnie jest to pusty ciąg znaków. |
| Niska jakość wyszukiwania w przypadku pól treści | contentTemplate.csv.quality.low=genre
Pola treści o niskiej wartości jakości wyszukiwania. Domyślnie jest to pusty ciąg znaków. |
| Średnia jakość wyszukiwania w przypadku pól treści | contentTemplate.csv.quality.medium=description
Pola treści z średnią wartością jakości wyszukiwania. Domyślnie jest to pusty ciąg znaków. |
| Nieokreślone pola treści | contentTemplate.csv.unmappedColumnsMode=IGNORE
Sposób obsługi przez konwerter nieokreślonych pól treści. Prawidłowe wartości to:
|
8. Planowanie przeszukiwania danych
Przeszukiwanie to proces polegający na znajdowaniu treści w źródle danych, w tym przypadku w pliku CSV. Podczas działania łącznik CSV przejdzie przez wiersze pliku CSV i za pomocą interfejsu API indeksowania zindeksuje każdy wiersz w Cloud Search.
Pełne przeszukiwanie indeksuje wszystkie kolumny w pliku. Incremental traversal indeksuje tylko kolumny, które zostały dodane lub zmodyfikowane od czasu poprzedniego przejścia. Oprogramowanie sprzęgające CSV wykonuje tylko pełne przejścia. Nie wykonuje ona dodatkowych przejść.
Parametry harmonogramu określają, jak często łącznik czeka między przekształceniami. Jeśli plik konfiguracji nie zawiera parametrów harmonogramu, używane są wartości domyślne. Parametry te są podane w tabeli poniżej.
| Ustawienie | Parametr |
| Pełne przejście po interwale | schedule.traversalIntervalSecs=7200
Po upływie określonego czasu łącznik wykonuje pełne przejście. Określ odstęp między przejściami w sekundach. Wartość domyślna to 86 400 (liczba sekund w dodaniu do 1 dnia). |
| Pełne przeszukiwanie podczas uruchamiania łącznika | schedule.performTraversalOnStart=false
Zamiast czekać na zakończenie pierwszego przedziału, usługa sprzęgająca wykonuje pełne przejście podczas uruchamiania. Wartością domyślną jest true (prawda). |
9. Określ opcje listy kontroli dostępu (ACL)
Oprogramowanie sprzęgające Google Cloud Search CSV obsługuje uprawnienia za pomocą list kontrolnych dostępu, aby kontrolować dostęp do zawartości pliku CSV w wynikach wyszukiwania. Dostępnych jest kilka opcji listy ACL, które umożliwiają ochronę dostępu użytkowników do zindeksowanych rekordów.
Jeśli repozytorium zawiera informacje o indywidualnych listach kontroli dostępu powiązanych z każdym dokumentem, prześlij wszystkie informacje o liście kontroli dostępu, aby kontrolować dostęp do dokumentów w Cloud Search. Jeśli repozytorium zawiera tylko częściowe informacje ACL lub nie zawiera ich wcale, możesz podać domyślne informacje ACL w poniższych parametrach, które pakiet SDK przekazuje do złącza.
Oprogramowanie sprzęgające korzysta z domyślnych list ACL włączonych w pliku konfiguracyjnym. Aby włączyć domyślne listy ACL, ustaw defaultAcl.mode na dowolny tryb inny niż none i skonfiguruj go za pomocą defaultAcl.*.
| Ustawienie | Parametr |
| Tryb ACL | defaultAcl.mode=fallback
Wymagane. Oprogramowanie sprzęgające CSV korzysta z domyślnej funkcji ACL. Oprogramowanie sprzęgające obsługuje tylko tryb awaryjny. |
| Domyślna nazwa listy ACL | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
Opcjonalnie: Umożliwia zastąpienie nazwy wirtualnego kontenera używanej przez oprogramowanie sprzęgające do konfigurowania domyślnych list ACL. Wartość domyślna to „DEFAULT_ACL_VIRTUAL_CONTAINER”. Możesz zmienić tę wartość, jeśli kilka złączy indeksuje treści w tej samej źródle danych. |
| Domyślna publiczna lista ACL | defaultAcl.public=true
Domyślny dostęp kontrolowany przez listę ACL używany w całym repozytorium jest ustawiony na dostęp publiczny. Wartość domyślna to false. |
| Wspólni czytelnicy grupy ACL | defaultAcl.readers.groups=google:group1, group2 |
| Czytelnicy z dostępem do list ACL | defaultAcl.readers.users=user1, user2, google:user3 |
| Czytelnicy grup z dostępem odmowa na liście ACL | defaultAcl.denied.groups=group3 |
| Czytelnicy z dostępem do zwykłych zasobów | defaultAcl.denied.users=user4, user5 |
| Dostęp do całej domeny | Aby określić, że każdy zindeksowany rekord ma być publicznie dostępny dla każdego użytkownika w domenie, ustaw obie te opcje, podając wartości:
|
| Zdefiniowana lista ACL | Aby określić jeden zestaw zasad dostępu do każdego rekordu w repozytorium danych, ustaw wszystkie te wartości parametrów:
|
Definicja schematu
Cloud Search umożliwia indeksowanie i wyświetlanie treści uporządkowanych i nieuporządkowanych. Aby obsługiwać zapytania dotyczące danych strukturalnych, musisz skonfigurować schemat dla źródła danych.
Po zdefiniowaniu oprogramowanie sprzęgające CSV może używać zdefiniowanego schematu do tworzenia żądań indeksowania. Na potrzeby przykładu rozważmy plik CSV zawierający informacje o filmach.
Załóżmy, że wejściowy plik CSV zawiera następujące dane.
- movieId
- movieTitle
- opis
- rok
- releaseDate
- aktorzy (wiele wartości rozdzielonych przecinkami (,))
- gatunek (wiele wartości)
- oceny
Na podstawie tej struktury danych możesz zdefiniować schemat źródła danych, w którym chcesz indeksować dane z pliku CSV.
{
"objectDefinitions": [
{
"name": "movie",
"propertyDefinitions": [
{
"name": "actors",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"textPropertyOptions": {
"operatorOptions": {
"operatorName": "actor"
}
}
},
{
"name": "releaseDate",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"datePropertyOptions": {
"operatorOptions": {
"operatorName": "released",
"lessThanOperatorName": "releasedbefore",
"greaterThanOperatorName": "releasedafter"
}
}
},
{
"name": "movieTitle",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"textPropertyOptions": {
"retrievalImportance": {
"importance": "HIGHEST"
},
"operatorOptions": {
"operatorName": "title"
}
}
},
{
"name": "genre",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"enumPropertyOptions": {
"operatorOptions": {
"operatorName": "genre"
},
"possibleValues": [
{
"stringValue": "Action"
},
{
"stringValue": "Documentary"
},
{
"stringValue": "Drama"
},
{
"stringValue": "Crime"
},
{
"stringValue": "Sci-fi"
}
]
}
},
{
"name": "userRating",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": true,
"integerPropertyOptions": {
"orderedRanking": "ASCENDING",
"maximumValue": "10",
"operatorOptions": {
"operatorName": "score",
"lessThanOperatorName": "scorebelow",
"greaterThanOperatorName": "scoreabove"
}
}
}
]
}
]
}
Przykładowy plik konfiguracji
Poniżej przykładowy plik konfiguracji zawiera pary parametrów key=value, które definiują działanie przykładowego łącznika.
# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json
# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle
# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE
#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true
Szczegółowe opisy poszczególnych parametrów znajdziesz w dokumentacji dotyczącej parametrów konfiguracji.
Uruchamianie oprogramowania sprzęgającego Cloud Search CSV
Aby uruchomić łącznik z wiersza poleceń, wpisz to polecenie:
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
Domyślnie dzienniki oprogramowania sprzęgającego są dostępne w standardowym wyjściu. Możesz zapisywać logi w plikach, podając logging.properties.