Wdrażanie oprogramowania sprzęgającego CSV

Ten przewodnik jest przeznaczony dla administratorów łącznika Google Cloud Search CSV (wartości rozdzielone przecinkami), czyli osób odpowiedzialnych za pobieranie, konfigurowanie, uruchamianie i monitorowanie łącznika.

Ten przewodnik zawiera instrukcje wykonywania kluczowych zadań związanych z wdrażaniem konektora CSV:

• Pobierz oprogramowanie sprzęgające CSV Google Cloud Search
• Konfigurowanie oprogramowania sprzęgającego do używania z określonym źródłem danych CSV
• Wdrażanie i uruchamianie oprogramowania sprzęgającego

Aby zrozumieć pojęcia opisane w tym dokumencie, musisz znać podstawy Google Workspace, plików CSV i list kontroli dostępu (ACL).

Omówienie oprogramowania sprzęgającego CSV Google Cloud Search

Oprogramowanie sprzęgające CSV Cloud Search działa z dowolnym plikiem tekstowym CSV. Plik CSV przechowuje dane tabelaryczne, a każdy wiersz pliku jest rekordem danych.

Oprogramowanie sprzęgające CSV w 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 pomyślnym zindeksowaniu poszczególne wiersze z plików CSV można wyszukiwać za pomocą klientów Cloud Search lub interfejsu Cloud Search Query API. Łącznik 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 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 oprogramowanie sprzęgające Google Cloud Search CSV

• Informacje o Google Workspace wymagane do nawiązania 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

  Zazwyczaj dane logowania może Ci przekazać administrator Google Workspace w domenie.

Etapy wdrażania

Aby wdrożyć oprogramowanie sprzęgające CSV Google Cloud Search, wykonaj te czynności:

1. Instalowanie oprogramowania łącznika CSV Google Cloud Search
2. Określanie konfiguracji oprogramowania sprzęgającego CSV
3. Konfigurowanie dostępu do źródła danych Google Cloud Search
4. Konfigurowanie dostępu do pliku CSV
5. Określ nazwy kolumn do indeksowania, kolumny kluczy unikalnych i kolumny daty i godziny
6. Określanie kolumn do użycia w adresach URL wyników wyszukiwania, które można kliknąć
7. Określanie informacji o metadanych i formatów kolumn
8. Planowanie przechodzenia po danych
9. Określanie opcji listy kontroli dostępu (ACL)

1. Instalowanie pakietu SDK

Zainstaluj pakiet SDK w lokalnym repozytorium Maven.

1. Sklonuj repozytorium SDK z GitHub.

   $ git clone https://github.com/google-cloudsearch/connector-sdk.git
   $ cd connector-sdk/csv

2. Sprawdź wybraną wersję pakietu SDK:

   $ git checkout tags/v1-0.0.3

3. Utwórz oprogramowanie sprzęgające:

   $ mvn package

4. Skopiuj plik ZIP oprogramowania sprzęgającego do lokalnego katalogu instalacyjnego:

   $ 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 oprogramowania sprzęgającego możesz kontrolować jego działanie i atrybuty definiujące parametry w pliku konfiguracyjnym oprogramowania sprzęgającego. Parametry, które można konfigurować:

• Dostęp do źródła danych
• Lokalizacja pliku CSV
• Definicje kolumn CSV
• Kolumny, które definiują unikalny identyfikator
• Opcje przechodzenia
• Opcje list ACL ograniczające dostęp do danych

Aby łącznik miał prawidłowy dostęp do pliku CSV i indeksował odpowiednie treści, musisz najpierw utworzyć jego plik konfiguracyjny.

Aby utworzyć plik konfiguracji:

1. Otwórz wybrany edytor tekstu i nadaj nazwę plikowi konfiguracji.
   Dodaj do zawartości pliku pary klucz=wartość zgodnie z opisem w tych sekcjach.
2. Zapisz i nazwij plik konfiguracji.
   Google zaleca nadanie plikowi konfiguracji takiej nazwy,connector-config.properties aby do uruchomienia oprogramowania sprzęgającego nie były potrzebne żadne dodatkowe parametry wiersza poleceń.

Ścieżkę do pliku konfiguracyjnego możesz podać w wierszu poleceń, więc standardowa lokalizacja pliku nie jest konieczna. Plik konfiguracyjny należy jednak przechowywać w tym samym katalogu co łącznik, aby ułatwić śledzenie i uruchamianie łącznika.

Aby mieć pewność, że oprogramowanie sprzęgające rozpozna plik konfiguracji, określ jego ścieżkę w wierszu poleceń. W przeciwnym razie łącznik używa znaku connector-config.properties w katalogu lokalnym jako domyślnej nazwy pliku. Informacje o tym, jak określić ścieżkę 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

Pierwsze parametry, które musi określać każdy plik konfiguracyjny, to te, które są niezbędne do uzyskania dostępu do źródła danych Cloud Search. Zostały one przedstawione w tej tabeli. Aby skonfigurować dostęp łącznika do Cloud Search, zwykle potrzebujesz identyfikatora źródła danych, identyfikatora konta usługi i ścieżki do pliku klucza prywatnego konta usługi. Czynności wymagane do skonfigurowania źródła danych są opisane w artykule Zarządzanie zewnętrznymi źródłami danych.

4. Konfigurowanie parametrów pliku CSV

Zanim oprogramowanie sprzęgające będzie mogło przejść plik CSV i wyodrębnić z niego dane do indeksowania, musisz określić ścieżkę do pliku. Możesz też określić format pliku i typ kodowania. Aby określić właściwości pliku CSV w pliku konfiguracyjnym, dodaj te parametry:

5. Określanie nazw kolumn do indeksowania i kolumn kluczy unikalnych

Aby łącznik mógł uzyskiwać dostęp do plików CSV i je indeksować, w pliku konfiguracyjnym musisz podać informacje o definicjach kolumn. Jeśli plik konfiguracyjny nie zawiera parametrów określających nazwy kolumn do indeksowania i kolumn klucza unikalnego, używane są wartości domyślne.

6. Określanie kolumn do użycia w klikanych adresach URL wyników wyszukiwania

Gdy użytkownik wyszukuje informacje za pomocą Google Cloud Search, usługa wyświetla stronę wyników z adresami URL, które można kliknąć. Aby włączyć tę funkcję, musisz dodać do pliku konfiguracyjnego parametr podany w tabeli poniżej.

7. Określanie informacji o metadanych, formatów kolumn i jakości wyszukiwania

Do pliku konfiguracji możesz dodać parametry, które określają:

• Parametry konfiguracji metadanych
• Formaty kolumn
• Jakość wyszukiwania

Parametry konfiguracji metadanych

W sekcji Parametry konfiguracji metadanych opisano kolumny pliku CSV używane do wypełniania metadanych produktów. Jeśli plik konfiguracyjny nie zawiera tych parametrów, używane są wartości domyślne. W tabeli poniżej znajdziesz te parametry.

Formaty daty i godziny

Formaty daty i godziny określają formaty oczekiwane w atrybutach metadanych. Jeśli plik konfiguracyjny nie zawiera tego parametru, używane są wartości domyślne. W tabeli poniżej znajdziesz ten parametr.

Formaty kolumn

Formaty kolumn określają informacje o kolumnach, które powinny być częścią treści możliwych do wyszukiwania. Jeśli plik konfiguracyjny nie zawiera tych parametrów, używane są wartości domyślne. W tabeli poniżej znajdziesz te parametry.

Jakość wyszukiwania

Oprogramowanie sprzęgające Cloud Search CSV umożliwia automatyczne formatowanie HTML pól danych. Łącznik definiuje pola danych na początku wykonywania, a następnie używa szablonu treści do formatowania każdego rekordu danych przed przesłaniem go do Cloud Search.

Szablon treści określa znaczenie poszczególnych wartości pól w wyszukiwaniu. Pole tytułu jest wymagane i ma najwyższy priorytet. Możesz określić poziomy ważności jakości wyszukiwania dla wszystkich pozostałych pól treści: wysoki, średni lub niski. Każde pole treści, które nie jest zdefiniowane w określonej kategorii, ma domyślnie niski priorytet. W tabeli poniżej znajdziesz te parametry.

8. Planowanie przechodzenia po danych

Przeszukiwanie to proces, w którym łącznik wykrywa treści ze źródła danych, w tym przypadku z pliku CSV. Podczas działania oprogramowanie sprzęgające CSV będzie przechodzić przez wiersze pliku CSV i indeksować każdy wiersz w Cloud Search za pomocą interfejsu Indexing API.

Pełne przeszukiwanie indeksuje wszystkie kolumny w pliku. Indeksowanie przyrostowe indeksuje tylko kolumny, które zostały dodane lub zmodyfikowane od czasu poprzedniego indeksowania. Oprogramowanie sprzęgające CSV wykonuje tylko pełne przeszukiwania. Nie wykonuje przyrostowych przejść.

Parametry harmonogramu określają, jak często łącznik czeka między przejściami. Jeśli plik konfiguracyjny nie zawiera parametrów harmonogramu, używane są wartości domyślne. W tabeli poniżej znajdziesz te parametry.

9. Określanie opcji listy kontroli dostępu (ACL)

Oprogramowanie sprzęgające Google Cloud Search CSV obsługuje uprawnienia za pomocą list ACL, aby kontrolować dostęp do treści pliku CSV w wynikach wyszukiwania. Dostępnych jest kilka opcji list ACL, które umożliwiają ochronę dostępu użytkowników do indeksowanych rekordów.

Jeśli Twoje repozytorium zawiera informacje o poszczególnych listach kontroli dostępu powiązanych z każdym dokumentem, prześlij wszystkie informacje o listach kontroli dostępu, aby kontrolować dostęp do dokumentów w Cloud Search. Jeśli repozytorium zawiera niepełne informacje o listach ACL lub nie zawiera ich wcale, możesz podać domyślne informacje o listach ACL w tych parametrach, które pakiet SDK przekazuje do łącznika.

Oprogramowanie sprzęgające wymaga włączenia domyślnych list ACL 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.*

Definicja schematu

Cloud Search umożliwia indeksowanie i udostępnianie treści uporządkowanych i nieuporządkowanych. Aby obsługiwać zapytania dotyczące danych strukturalnych, musisz skonfigurować schemat źródła danych.

Po zdefiniowaniu schematu oprogramowanie sprzęgające CSV może się do niego odwoływać podczas tworzenia żądań indeksowania. Aby podać przykład, rozważmy plik CSV zawierający informacje o filmach.

Załóżmy, że wejściowy plik CSV ma następującą zawartość.

1. movieId
2. movieTitle
3. opis
4. rok
5. releaseDate
6. aktorzy (wiele wartości rozdzielonych przecinkami)
7. gatunek (wiele wartości)
8. oceny

Na podstawie powyższej 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

Przykładowy plik konfiguracji poniżej zawiera pary parametrów key=value, które określają 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 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 rejestrować dane w plikach, podając logging.properties.