Ten przewodnik jest przeznaczony dla administratorów łącznika Google Cloud Search CSV (wartości rozdzielone przecinkami), którzy odpowiadają za pobieranie, konfigurowanie, uruchamianie i monitorowanie łącznika.
Ten przewodnik zawiera instrukcje dotyczące tych kluczowych zadań:
- Pobierz oprogramowanie sprzęgające Cloud Search CSV.
- Skonfiguruj łącznik dla konkretnego źródła danych CSV.
- wdrożyć i uruchomić oprogramowanie sprzęgające,
Aby zrozumieć koncepcje przedstawione w tym dokumencie, musisz znać Google Workspace, pliki CSV i listy kontroli dostępu (ACL).
Omówienie oprogramowania sprzęgającego Cloud Search CSV
Oprogramowanie sprzęgające CSV Cloud Search działa z dowolnym plikiem tekstowym z wartościami rozdzielonymi przecinkami (CSV). Plik CSV przechowuje dane w formie tabeli, w której każdy wiersz jest rekordem danych.
Oprogramowanie sprzęgające wyodrębnia wiersze z pliku CSV i indeksuje je w Cloud Search za pomocą interfejsu Indexing API. Po zindeksowaniu wiersze można wyszukiwać za pomocą klientów Cloud Search lub interfejsu Query API. Łącznik obsługuje też listy kontroli dostępu, które umożliwiają kontrolowanie dostępu użytkowników do treści.
Oprogramowanie sprzęgające możesz zainstalować w systemie Linux lub Windows. Przed wdrożeniem upewnij się, że masz te komponenty:
- Na komputerze, na którym działa oprogramowanie sprzęgające, musi być zainstalowane środowisko Java JRE 1.8.
- Informacje o Google Workspace potrzebne do nawiązania połączeń:
- Klucz prywatny Google Workspace (zawierający identyfikator konta usługi).
- Identyfikator źródła danych Google Workspace.
Zazwyczaj dane logowania podaje administrator Google Workspace w domenie.
Etapy wdrażania
Aby wdrożyć oprogramowanie sprzęgające CSV Cloud Search, wykonaj te czynności:
- Instalowanie oprogramowania sprzęgającego
- Określanie konfiguracji oprogramowania sprzęgającego
- Konfigurowanie dostępu do źródła danych Cloud Search
- Konfigurowanie dostępu do pliku CSV
- Określ nazwy kolumn, klucze unikalne i kolumny daty i godziny
- Określanie kolumn dla adresów URL wyników wyszukiwania, które można kliknąć
- Określanie metadanych i formatów kolumn
- Planowanie przechodzenia po danych
- Określanie opcji listy kontroli dostępu
1. Instalowanie pakietu SDK
Zainstaluj pakiet SDK w lokalnym repozytorium Maven.
Sklonuj repozytorium SDK z GitHub.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Sprawdź wybraną wersję:
$ git checkout tags/v1-0.0.3
Utwórz oprogramowanie sprzęgające:
$ mvn package
Wyodrębnij i zainstaluj oprogramowanie sprzęgające:
$ 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 oprogramowania sprzęgającego CSV
Działaniem oprogramowania sprzęgającego sterujesz za pomocą parametrów w pliku konfiguracyjnym. Parametry, które można konfigurować:
- Dostęp do źródła danych.
- Lokalizacja i definicje pliku CSV.
- Kolumny unikalnych identyfikatorów.
- Opcje przechodzenia i listy kontroli dostępu.
Aby utworzyć plik konfiguracji:
- Otwórz edytor tekstu i nadaj plikowi nazwę
connector-config.properties. - Dodaj parametry konfiguracji jako pary
key=value, z których każda znajduje się w nowym wierszu. Przykładowy plik konfiguracji znajdziesz w artykule Przykładowy plik konfiguracji.
Aby ułatwić śledzenie, zachowaj plik konfiguracyjny w tym samym katalogu co oprogramowanie sprzęgające. Aby mieć pewność, że łącznik rozpozna plik, określ jego ścieżkę w wierszu poleceń. W przeciwnym razie łącznik domyślnie przyjmuje wartość connector-config.properties w katalogu lokalnym. Zobacz Uruchamianie oprogramowania sprzęgającego.
3. Konfigurowanie dostępu do źródła danych Cloud Search
Plik konfiguracyjny musi zawierać parametry dostępu do źródła danych Cloud Search. Potrzebujesz identyfikatora źródła danych, identyfikatora konta usługi i ścieżki do pliku klucza prywatnego konta usługi.
| Ustawienie | Parametr |
| Identyfikator źródła danych | api.sourceId=1234567890abcdef
Wymagane. Identyfikator źródła Cloud Search skonfigurowany przez administratora Google Workspace. |
| Ścieżka do klucza prywatnego konta usługi | api.serviceAccountPrivateKeyFile=./PrivateKey.json
Wymagane. Plik klucza konta usługi na potrzeby dostępności łącznika. |
| 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 skonfigurowany przez administratora Google Workspace. |
4. Konfigurowanie parametrów pliku CSV
Określ ścieżkę, format i kodowanie pliku.
| Ustawienie | Parametr |
| Ścieżka do pliku CSV | csv.filePath=./movie_content.csv
Wymagane. Ścieżka do pliku do indeksowania. |
| Format pliku | csv.format=DEFAULT
Format pliku. Możliwe wartości pochodzą z klasy CSVFormat Apache Commons CSV. 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 Apache Commons CSV i obejmują te, które przyjmują pojedynczy znak, ciąg znaków lub wartość logiczną. Aby na przykład określić średnik jako separator, użyj |
| Typ kodowania pliku | csv.fileEncoding=UTF-8
Zestaw znaków Java, który ma być używany. Domyślnie jest to zestaw znaków platformy. |
5. Określanie nazw kolumn do indeksowania i kolumn kluczy unikalnych
Podaj informacje o kolumnach w pliku konfiguracyjnym.
| Ustawienie | Parametr |
| Kolumny do zindeksowania | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
Nazwy kolumn, które mają być indeksowane z pliku CSV. Domyślnie pierwszy wiersz pliku CSV jest używany jako nagłówek. Jeśli określono wartość |
| Kolumny z unikalnym kluczem | csv.uniqueKeyColumns=movieId
Kolumny używane do generowania unikalnego identyfikatora. Domyślnie jest to kod skrótu rekordu. |
6. Określanie kolumn klikalnych adresów URL wyników wyszukiwania
Włączanie klikalnych adresów URL w wynikach wyszukiwania.
| Ustawienie | Parametr |
| Format adresu URL wyniku wyszukiwania | url.format=https://mymoviesite.com/movies/{0}
Wymagane. Format używany do tworzenia adresu URL widoku. |
| Parametry adresu URL | url.columns=movieId
Wymagane. Nazwy kolumn w pliku CSV, których wartości będą używane do generowania adresu URL widoku rekordu. |
| Parametry adresu URL wyników wyszukiwania, których znaczenie należy zmienić | url.columnsToEscape=movieId
Opcjonalnie. Nazwy kolumn w pliku CSV, których wartości zostaną zmienione w taki sposób, aby wygenerować prawidłowy URL wyświetlenia. |
7. Określanie metadanych, formatów kolumn i jakości wyszukiwania
Do pliku konfiguracji możesz dodać parametry, które określają:
Parametry konfiguracji metadanych
Te parametry opisują kolumny do wypełniania metadanych produktów.
| Ustawienie | Parametr |
| Tytuł | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
Atrybut metadanych dla tytułu dokumentu. Domyślnie jest to pusty ciąg znaków. |
| URL | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
Atrybut metadanych adresu URL dokumentu w wynikach wyszukiwania. |
| Sygnatura czasowa utworzenia | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
Atrybut metadanych sygnatury czasowej utworzenia dokumentu. |
| Czas ostatniej modyfikacji | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
Atrybut metadanych sygnatury czasowej ostatniej modyfikacji dokumentu. |
| Język dokumentu | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
Język treści indeksowanych dokumentów. |
| Typ obiektu schematu | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
Typ obiektu używany przez łącznik, zdefiniowany w schemacie. Jeśli ta właściwość nie zostanie określona, łącznik nie będzie indeksować żadnych danych strukturalnych. |
Formaty daty i godziny
Ten parametr określa dodatkowe formaty daty i godziny do analizowania wartości ciągów znaków w polach daty lub daty i godziny.
| Ustawienie | Parametr |
| Dodatkowe formaty daty i godziny | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Lista dodatkowych java.time.format.DateTimeFormatter wzorców rozdzielonych średnikami. Wzorce są używane podczas analizowania wartości ciągów w przypadku pól daty lub daty i godziny w metadanych lub schemacie. Wartością domyślną jest pusta lista, ale formaty RFC 3339 i RFC 1123 są zawsze obsługiwane.
|
Formaty kolumn
Te parametry określają sposób analizowania kolumn w pliku CSV.
| Ustawienie | Parametr |
| Pomiń nagłówek | csv.skipHeaderRecord=true
Zignoruj pierwszy wiersz. Domyślną wartością jest false (fałsz). |
| Kolumny z wieloma wartościami | csv.multiValueColumns=genre,actors
Nazwy kolumn z wieloma wartościami. |
| Separator kolumn wielowartościowych | csv.multiValue.genre=;
Ogranicznik kolumn wielowartościowych. Domyślnym separatorem jest przecinek. |
Jakość wyszukiwania
Oprogramowanie sprzęgające używa szablonu treści do formatowania rekordów. Pole tytułu ma najwyższy priorytet. Możesz przypisać poziomy priorytetu (wysoki, średni, niski) do innych pól.
| Ustawienie | Parametr |
| Tytuł treści |
contentTemplate.csv.title=movieTitle
Tytuł treści jest polem o najwyższej jakości wyszukiwania. |
| Wysoka jakość wyszukiwania w polach treści |
contentTemplate.csv.quality.high=actors
Pola treści, którym przypisano wysoką wartość 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, którym przypisano niską wartość 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, którym przypisano średnią wartość jakości wyszukiwania. Domyślnie jest to pusty ciąg znaków. |
| Nieokreślone pola treści |
contentTemplate.csv.unmappedColumnsMode=IGNORE
Jak łącznik obsługuje nieokreślone pola treści. Prawidłowe wartości to:
Wartością domyślną jest APPEND. |
8. Planowanie przechodzenia po danych
Przeszukiwanie to proces odkrywania treści. Oprogramowanie sprzęgające przetwarza wiersze pliku CSV i indeksuje je za pomocą interfejsu Indexing API. Oprogramowanie sprzęgające CSV wykonuje tylko pełne przeszukiwania.
| Ustawienie | Parametr |
| Interwał przechodzenia | schedule.traversalIntervalSecs=7200
Odstęp między pełnymi przejściami w sekundach. Wartość domyślna to 86400 (1 dzień). |
| Przeszukiwanie przy uruchamianiu | schedule.performTraversalOnStart=false
Oprogramowanie sprzęgające wykonuje przejście przy uruchamianiu, zamiast czekać na upłynięcie pierwszego interwału. Wartość domyślna to |
9. Określanie opcji listy kontroli dostępu
Łącznik używa list ACL do kontrolowania dostępu. Jeśli repozytorium udostępnia listy ACL, prześlij je. W przeciwnym razie skonfiguruj domyślne listy ACL. Ustaw wartość defaultAcl.mode inną niż none.
| Ustawienie | Parametr |
| Tryb listy ACL | defaultAcl.mode=fallback
Wymagane. Oprogramowanie sprzęgające obsługuje tylko tryb rezerwowy. |
| Domyślna nazwa listy ACL | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
Opcjonalnie. Zastępuje nazwę kontenera wirtualnego używaną przez oprogramowanie sprzęgające w przypadku domyślnych list ACL. Wartością domyślną jest |
| Domyślna publiczna lista ACL | defaultAcl.public=true
Ustawia całe repozytorium jako dostępne w domenie publicznej. Wartość domyślna to false. |
| Odczytujący wspólne grupy ACL | defaultAcl.readers.groups=google:group1, group2
|
| Popularne czytniki ACL | defaultAcl.readers.users=user1, user2, google:user3
|
| Odmowa dostępu do wspólnej listy ACL dla czytelników z grupy | defaultAcl.denied.groups=group3
|
| Common Acl denied readers | defaultAcl.denied.users=user4, user5
|
| Dostęp do całej domeny | Aby określić, że każdy indeksowany rekord ma być publicznie dostępny dla każdego użytkownika w domenie, ustaw obie te opcje na odpowiednie wartości:
|
| Wspólna zdefiniowana lista ACL | Aby zdefiniować wspólną listę ACL dla każdego rekordu, ustaw te parametry:
Zakłada się, że użytkownicy i grupy są zdefiniowani w domenie lokalnej, chyba że przed nimi znajduje się prefiks „ Domyślny użytkownik lub grupa to pusty ciąg znaków. Opcje użytkownika i grupy podawaj tylko wtedy, gdy Jeśli |
Definicja schematu
Aby obsługiwać zapytania dotyczące danych strukturalnych, skonfiguruj schemat źródła danych.
Rozważmy na przykład plik CSV z tymi informacjami o filmach:
- movieId
- movieTitle
- opis
- rok
- releaseDate
- aktorzy (wiele wartości rozdzielonych przecinkami (,)),
- gatunek (wiele wartości)
- oceny
Na podstawie tej struktury możesz zdefiniować ten schemat źródła danych:
{
"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
W przykładowym pliku konfiguracyjnym poniżej pokazujemy pary parametrów key=value, które określają zachowanie 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
Uruchamianie oprogramowania sprzęgającego
Aby uruchomić łącznik z wiersza poleceń:
$ 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 rejestrować dane w plikach, podając logging.properties.