Wdrażanie oprogramowania sprzęgającego CSV

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
• Konfigurowanie łącznika 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 tego 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 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 kontrolnych dostępu.

Oprogramowanie sprzęgające CSV do 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 z Google Workspace wymagane do ustanowienia relacji między Google Cloud Search a źródłem danych:

  • klucz prywatny Google Workspace (zawiera 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:

1. Instalowanie oprogramowania łącznika CSV Google Cloud Search
2. Konfigurowanie łącznika CSV
3. Konfigurowanie dostępu do źródła danych Google Cloud Search
4. Konfigurowanie dostępu do pliku CSV
5. Określanie nazw kolumn do indeksowania, kolumn kluczy unikalnych i kolumn daty i godziny
6. Określanie kolumn do użycia w klikalnych adresach URL wyników wyszukiwania
7. Określanie informacji metadanych i formatów kolumn
8. Planowanie przechodzenia przez dane
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 GitHuba.

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

2. Pobierz żądaną wersję pakietu SDK:

   $ git checkout tags/v1-0.0.3

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

   $ mvn package

4. Skopiuj 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 łącznika CSV i atrybuty definiujące 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:

1. 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.
2. Zapisz plik konfiguracji i nadaj mu nazwę.
   Google zaleca, aby nazwa pliku konfiguracji była taka jak connector-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.

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.

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.

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.

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
• Formaty kolumn
• Jakość wyszukiwania

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ą opisane w tabeli poniżej.

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.

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.

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 określa 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, które nie zostały zdefiniowane w konkretnej kategorii, mają domyślnie niski priorytet. Parametry te są podane w tabeli poniżej.

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ą opisane w tabeli poniżej.

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.*.

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. Aby zilustrować ten przykład, rozważmy plik CSV zawierający informacje o filmach.

Załóżmy, że wejściowy plik CSV zawiera następujące dane.

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 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 parametr logging.properties.