Melakukan Deployment Konektor CSV

Panduan ini ditujukan untuk administrator konektor CSV (nilai yang dipisahkan koma) Google Cloud Search yang bertanggung jawab untuk mendownload, mengonfigurasi, menjalankan, dan memantau konektor.

Panduan ini mencakup petunjuk untuk tugas-tugas utama berikut:

  • Download software konektor CSV Cloud Search.
  • Mengonfigurasi konektor untuk sumber data CSV tertentu.
  • Deploy dan jalankan konektor.

Untuk memahami konsep dalam dokumen ini, Anda harus memahami Google Workspace, file CSV, dan Daftar Kontrol Akses (ACL).

Ringkasan konektor CSV Cloud Search

Konektor CSV Cloud Search berfungsi dengan file teks nilai yang dipisahkan koma (CSV). File CSV menyimpan data dalam bentuk tabel, dengan setiap baris merupakan record data.

Konektor mengekstrak baris dari file CSV dan mengindeksnya ke Cloud Search menggunakan Indexing API. Setelah diindeks, baris dapat ditelusuri melalui klien Cloud Search atau Query API. Konektor juga mendukung ACL untuk mengontrol akses pengguna ke konten.

Anda dapat menginstal konektor di Linux atau Windows. Sebelum deployment, pastikan Anda memiliki komponen berikut:

Biasanya, administrator Google Workspace untuk domain menyediakan kredensial ini.

Langkah-langkah penerapan

Ikuti langkah-langkah berikut untuk men-deploy konektor CSV Cloud Search:

  1. Instal software konektor
  2. Tentukan konfigurasi konektor
  3. Mengonfigurasi akses ke sumber data Cloud Search
  4. Mengonfigurasi akses file CSV
  5. Tentukan nama kolom, kunci unik, dan kolom tanggal dan waktu
  6. Menentukan kolom untuk URL hasil penelusuran yang dapat diklik
  7. Menentukan metadata dan format kolom
  8. Menjadwalkan traversal data
  9. Menentukan opsi ACL

1. Instal SDK

Instal SDK ke repositori Maven lokal Anda.

  1. Buat clone repositori SDK dari GitHub. 

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

  2. Lihat versi yang Anda pilih: 

    $ git checkout tags/v1-0.0.3

  3. Buat konektor: 

    $ mvn package

  4. Ekstrak dan instal konektor: 

    $ 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. Tentukan konfigurasi konektor CSV

Anda dapat mengontrol perilaku konektor melalui parameter dalam file konfigurasinya. Parameter yang dapat dikonfigurasi meliputi:

  • Akses sumber data.
  • Lokasi dan definisi file CSV.
  • Kolom ID unik.
  • Opsi traversal dan ACL.

Untuk membuat file konfigurasi:

  1. Buka editor teks dan beri nama file connector-config.properties.
  2. Tambahkan parameter konfigurasi sebagai pasangan key=value, dengan setiap pasangan berada di baris baru. Untuk contoh file konfigurasi, lihat Contoh file konfigurasi.

Simpan file konfigurasi di direktori yang sama dengan konektor agar pelacakan lebih mudah. Untuk memastikan konektor mengenali file Anda, tentukan lokasinya di command line. Jika tidak, konektor akan menggunakan connector-config.properties di direktori lokal Anda. Lihat Menjalankan konektor.

3. Mengonfigurasi akses ke sumber data Cloud Search

File konfigurasi harus menentukan parameter untuk mengakses sumber data Cloud Search. Anda memerlukan ID Sumber data, ID akun layanan, dan lokasi ke file kunci pribadi akun layanan.

Setelan Parameter
ID sumber data api.sourceId=1234567890abcdef

Wajib. ID sumber Cloud Search yang disiapkan oleh administrator Google Workspace.
Jalur ke kunci pribadi akun layanan api.serviceAccountPrivateKeyFile=./PrivateKey.json

Wajib. File kunci akun layanan untuk aksesibilitas konektor.
ID sumber identitas api.identitySourceId=x0987654321

Diperlukan jika menggunakan pengguna dan grup eksternal. ID sumber identitas yang disiapkan oleh administrator Google Workspace.

4. Mengonfigurasi parameter file CSV

Identifikasi jalur, format, dan encoding file.

Setelan Parameter
Jalur ke file CSV csv.filePath=./movie_content.csv

Wajib. Jalur ke file untuk pengindeksan.
Format file csv.format=DEFAULT

Format file. Nilai yang mungkin berasal dari class CSVFormat Apache Commons CSV.

Nilai format mencakup: DEFAULT, EXCEL, INFORMIX_UNLOAD, INFORMIX_UNLOAD_CSV, MYSQL, RFC4180, ORACLE, POSTGRESQL_CSV, POSTGRESQL_TEXT, dan TDF. Jika tidak ditentukan, Cloud Search akan menggunakan DEFAULT.
Pengubah format file csv.format.withMethod=value

Modifikasi cara Cloud Search menangani file. Kemungkinan metode berasal dari class CSVFormat Apache Commons CSV dan mencakup metode yang menggunakan satu karakter, string, atau nilai boolean.

Misalnya, untuk menentukan titik koma sebagai pembatas, gunakan csv.format.withDelimiter=;. Untuk mengabaikan baris kosong, gunakan csv.format.withIgnoreEmptyLines=true.
Jenis encoding file csv.fileEncoding=UTF-8

Himpunan karakter Java yang akan digunakan. Default-nya adalah set karakter platform.

5. Tentukan nama kolom yang akan diindeks dan kolom kunci unik

Berikan informasi kolom dalam file konfigurasi.

Setelan Parameter
Kolom yang akan diindeks csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...

Nama kolom yang akan diindeks dari file CSV. Secara default, baris pertama CSV digunakan sebagai header. Jika csv.csvColumns ditentukan, nilai tersebut akan diprioritaskan. Untuk menghindari pengindeksan baris pertama sebagai data saat csv.csvColumns disetel dan baris pertama berisi header, setel juga csv.skipHeaderRecord=true.
Kolom kunci unik csv.uniqueKeyColumns=movieId

Kolom yang digunakan untuk membuat ID unik. Setelan default-nya adalah kode hash record.

6. Menentukan kolom untuk URL hasil penelusuran yang dapat diklik

Aktifkan URL yang dapat diklik untuk hasil penelusuran.

Setelan Parameter
Format URL hasil penelusuran url.format=https://mymoviesite.com/movies/{0}

Wajib. Format yang digunakan untuk membuat URL tampilan.
Parameter URL url.columns=movieId

Wajib. Nama kolom CSV yang nilainya akan digunakan untuk membuat URL tampilan record.
Parameter URL hasil penelusuran yang akan dikecualikan url.columnsToEscape=movieId

Opsional. Nama kolom CSV yang nilainya akan menjadi URL, yang dikecualikan untuk membuat URL tampilan yang valid.

7. Tentukan metadata, format kolom, dan kualitas penelusuran

Anda dapat menambahkan parameter ke file konfigurasi yang menentukan:

Parameter konfigurasi metadata

Parameter ini menjelaskan kolom untuk mengisi metadata item.

Setelan Parameter
Judul itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind

Atribut metadata untuk judul dokumen. Defaultnya adalah string kosong.
URL itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
Atribut metadata untuk URL dokumen dalam hasil penelusuran.
Stempel waktu pembuatan itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17

Atribut metadata untuk stempel waktu pembuatan dokumen.
Waktu terakhir diubah itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17

Atribut metadata untuk stempel waktu modifikasi terakhir dokumen.
Bahasa dokumen itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US

Bahasa konten dokumen yang diindeks.
Jenis objek skema itemMetadata.objectType.field=type
itemMetadata.objectType.defaultValue=movie

Jenis objek yang digunakan oleh konektor, seperti yang dijelaskan dalam skema. Konektor tidak akan mengindeks data terstruktur apa pun jika properti ini tidak ditentukan.
Format tanggal dan waktu

Parameter ini menentukan format tanggal dan waktu tambahan untuk mengurai nilai string ke dalam kolom tanggal atau tanggal-waktu.

Setelan Parameter
Format datetime tambahan structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Daftar pola java.time.format.DateTimeFormatter tambahan yang dipisahkan titik koma. Pola digunakan saat mengurai nilai string untuk kolom tanggal atau tanggal-waktu pada metadata atau skema. Nilai defaultnya adalah daftar kosong, tetapi format RFC 3339 dan RFC 1123 selalu didukung.

Format kolom

Parameter ini menentukan cara mem-parsing kolom dalam file CSV.

Setelan Parameter
Lewati header csv.skipHeaderRecord=true

Abaikan baris pertama. Defaultnya adalah false.
Kolom banyak nilai csv.multiValueColumns=genre,actors

Nama kolom dengan beberapa nilai.
Pemisah untuk kolom banyak nilai csv.multiValue.genre=;

Pemisah untuk kolom banyak nilai. Pemisah defaultnya adalah koma.

Kualitas penelusuran

Konektor menggunakan template konten untuk memformat data. Kolom judul memiliki prioritas tertinggi. Anda dapat menetapkan tingkat prioritas (tinggi, sedang, rendah) ke kolom lainnya.

Setelan Parameter
Judul konten contentTemplate.csv.title=movieTitle

Judul konten adalah kolom dengan kualitas penelusuran tertinggi.
Kualitas penelusuran tinggi untuk kolom konten contentTemplate.csv.quality.high=actors

Kolom konten dengan nilai kualitas penelusuran tinggi. Defaultnya adalah string kosong.
Kualitas penelusuran rendah untuk kolom konten contentTemplate.csv.quality.low=genre

Kolom konten dengan nilai kualitas penelusuran rendah. Defaultnya adalah string kosong.
Kualitas penelusuran sedang untuk kolom konten contentTemplate.csv.quality.medium=description

Kolom konten dengan nilai kualitas penelusuran sedang. Defaultnya adalah string kosong.
Kolom konten yang tidak ditentukan contentTemplate.csv.unmappedColumnsMode=IGNORE

Cara konektor menangani kolom konten yang tidak ditentukan. Nilai yang valid adalah:

  • APPEND—menambahkan kolom konten yang tidak ditentukan ke template
  • IGNORE—mengabaikan kolom konten yang tidak ditentukan

Nilai defaultnya adalah APPEND.

8. Jadwalkan traversal data

Traversal adalah proses penemuan konten. Konektor melintasi baris CSV dan mengindeksnya menggunakan Indexing API. Konektor CSV hanya menjalankan traversal penuh.

Setelan Parameter
Interval traversal schedule.traversalIntervalSecs=7200

Interval antara traversal penuh dalam hitungan detik. Defaultnya adalah 86400 (satu hari).
Traversal saat startup schedule.performTraversalOnStart=false

Konektor menjalankan traversal saat konektor dimulai, bukan menunggu interval pertama berakhir. Default-nya adalah true.

9. Menentukan opsi ACL

Konektor menggunakan ACL untuk mengontrol akses. Jika repositori Anda menyediakan ACL, upload ACL tersebut. Jika tidak, konfigurasikan ACL default. Tetapkan defaultAcl.mode ke nilai selain none.

Setelan Parameter
Mode ACL defaultAcl.mode=fallback

Wajib. Konektor hanya mendukung mode penggantian.
Nama ACL default defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1

Opsional. Mengganti nama container virtual yang digunakan oleh konektor untuk ACL default. Nilai default-nya adalah DEFAULT_ACL_VIRTUAL_CONTAINER. Pertimbangkan untuk mengganti nilai ini jika beberapa konektor mengindeks konten dalam sumber data yang sama.
ACL publik default defaultAcl.public=true

Menetapkan seluruh repositori ke akses domain publik. Default-nya adalah false.
Pembaca grup ACL umum defaultAcl.readers.groups=google:group1, group2
Pembaca ACL umum defaultAcl.readers.users=user1, user2, google:user3
ACL umum menolak pembaca grup defaultAcl.denied.groups=group3
ACL umum menolak pembaca defaultAcl.denied.users=user4, user5
Seluruh akses domain Untuk menentukan apakah setiap record yang diindeks dapat diakses secara publik oleh setiap pengguna dalam domain, tetapkan kedua opsi berikut dengan nilai:
  • defaultAcl.mode=fallback
  • defaultAcl.public=true
ACL yang ditetapkan umum Untuk menentukan ACL umum untuk setiap record, tetapkan parameter berikut:
  • defaultAcl.mode=fallback
  • defaultAcl.public=false
  • defaultAcl.readers.groups=google:group1, group2
  • defaultAcl.readers.users=user1, user2, google:user3
  • defaultAcl.denied.groups=group3
  • defaultAcl.denied.users=user4, user5

Pengguna dan grup dianggap sebagai pengguna/grup yang ditentukan domain lokal, kecuali diawali dengan "google:".

Pengguna atau grup defaultnya adalah string kosong. Berikan opsi pengguna dan grup hanya jika defaultAcl.public adalah false. Gunakan daftar yang dipisahkan koma untuk beberapa grup dan pengguna.

Jika defaultAcl.mode adalah none, catatan tidak dapat ditelusuri tanpa ACL individual.

Definisi skema

Untuk mendukung kueri data terstruktur, siapkan skema untuk sumber data Anda.

Misalnya, pertimbangkan file CSV dengan informasi berikut tentang film:

  1. movieId
  2. movieTitle
  3. description
  4. year
  5. releaseDate
  6. actors (beberapa nilai yang dipisahkan koma (,))
  7. genre (beberapa nilai)
  8. peringkat

Berdasarkan struktur ini, Anda dapat menentukan skema berikut untuk sumber data:

{
  "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"
            }
          }
        }
      ]
    }
  ]
}

Contoh file konfigurasi

Contoh file konfigurasi berikut menunjukkan pasangan parameter key=value yang menentukan contoh perilaku konektor.

# 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

Menjalankan konektor

Untuk menjalankan konektor dari command line:

$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config

Secara default, log konektor tersedia pada output standar. Anda dapat membuat log ke file dengan menentukan logging.properties.