Melakukan Deployment Konektor CSV

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

Panduan ini mencakup petunjuk untuk melakukan tugas utama yang terkait dengan deployment konektor CSV:

  • Mendownload software konektor CSV Google Cloud Search
  • Mengonfigurasi konektor untuk digunakan dengan sumber data CSV tertentu
  • Menerapkan dan menjalankan konektor

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

Ringkasan konektor CSV Google Cloud Search

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

Konektor CSV Google Cloud Search mengekstrak setiap baris file CSV dan mengindeksnya ke dalam Cloud Search melalui Indexing API Cloud Search. Setelah berhasil diindeks, setiap baris file CSV dapat ditelusuri melalui klien Cloud Search atau Query API Cloud Search. Konektor CSV juga mendukung pengontrolan akses pengguna ke konten dalam hasil penelusuran menggunakan ACL.

Konektor CSV Google Cloud Search dapat diinstal di Linux atau Windows. Sebelum melakukan deployment konektor CSV Google Cloud Search, pastikan Anda memiliki komponen berikut:

  • Java JRE 1.8 yang diinstal di komputer yang menjalankan konektor CSV Google Cloud Search

  • Informasi Google Workspace yang diperlukan untuk menghubungkan Google Cloud Search dan sumber data:

    Biasanya, administrator Google Workspace untuk domain dapat menyediakan kredensial ini untuk Anda.

Langkah-langkah penerapan

Untuk melakukan deployment konektor CSV Google Cloud Search, ikuti langkah-langkah berikut:

  1. Menginstal software konektor CSV Google Cloud Search
  2. Menentukan konfigurasi konektor CSV
  3. Mengonfigurasi akses ke sumber data Google Cloud Search
  4. Mengonfigurasi akses file CSV
  5. Menentukan nama kolom yang akan diindeks, kolom kunci unik, dan kolom tanggal dan waktu
  6. Menentukan kolom yang akan digunakan di URL hasil penelusuran yang dapat diklik
  7. Menentukan informasi metadata, format kolom
  8. Menjadwalkan traversal data
  9. Menentukan opsi Daftar Kontrol Akses (ACL)

1. Instal SDK

Instal SDK ke repositori Maven lokal Anda.

  1. Lakukan clone repositori SDK dari GitHub.

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

  2. Periksa versi SDK yang diinginkan:

    $ git checkout tags/v1-0.0.3

  3. Buat konektor:

    $ mvn package

  4. Salin file zip konektor ke direktori penginstalan lokal Anda:

    $ 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

Sebagai administrator konektor, Anda dapat mengontrol perilaku dan atribut konektor CSV yang menentukan parameter dalam file konfigurasi konektor. Parameter yang dapat dikonfigurasi meliputi:

  • Akses ke sumber data
  • Lokasi file CSV
  • Definisi kolom CSV
  • Kolom yang menentukan ID unik
  • Opsi traversal
  • Opsi ACL untuk membatasi akses data

Agar konektor dapat mengakses file CSV dan mengindeks konten yang relevan dengan tepat, Anda harus membuat file konfigurasinya terlebih dahulu.

Untuk membuat file konfigurasi:

  1. Buka editor teks pilihan Anda dan beri nama file konfigurasi.
    Tambahkan pasangan key=value ke konten file seperti yang dijelaskan di bagian berikut.
  2. Simpan dan beri nama file konfigurasi.
    Google merekomendasikan untuk memberi nama file konfigurasi connector-config.properties sehingga Anda tidak perlu menambahkan parameter command line lain untuk menjalankan konektor.

Karena Anda dapat menentukan lokasi file konfigurasi pada command line, lokasi file standar tidak diperlukan. Namun, simpan file konfigurasi dalam direktori yang sama dengan konektor agar konektor mudah dilacak dan dijalankan.

Untuk memastikan agar konektor mengenali file konfigurasi Anda, tentukan lokasinya di command line. Jika tidak, konektor akan menggunakan connector-config.properties di direktori lokal Anda sebagai nama file default. Untuk mengetahui informasi tentang cara menentukan lokasi konfigurasi pada command line, lihat Menjalankan konektor CSV Cloud Search.

3. Konfigurasikan akses ke sumber data Google Cloud Search

Parameter pertama yang harus ditentukan oleh setiap file konfigurasi adalah paramenter yang diperlukan untuk mengakses sumber data Cloud Search, seperti yang ditunjukkan pada tabel berikut. Biasanya, Anda memerlukan ID Sumber data, ID akun layanan, dan lokasi ke file kunci pribadi akun layanan untuk mengonfigurasi akses konektor ke Cloud Search. Langkah-langkah yang diperlukan untuk menyiapkan sumber data dijelaskan dalam Mengelola sumber data pihak ketiga

Setelan Parameter
ID sumber data api.sourceId=1234567890abcdef

Wajib. ID sumber data Google Cloud Search disiapkan oleh administrator Google Workspace, seperti yang dijelaskan dalam Mengelola sumber data pihak ketiga.
Lokasi ke file kunci pribadi akun layanan api.serviceAccountPrivateKeyFile=./PrivateKey.json

Wajib ada. File kunci akun layanan Google Cloud Search untuk aksesibilitas konektor CSV Google Cloud Search.
ID sumber identitas api.identitySourceId=x0987654321

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

4. Mengonfigurasi parameter file CSV

Sebelum konektor dapat melintasi file CSV dan mengekstrak data dari file tersebut untuk pengindeksan, Anda harus mengidentifikasi lokasi ke file. Anda juga dapat menentukan format file dan jenis encoding file. Tambahkan parameter berikut untuk menentukan properti file CSV dalam file konfigurasi.

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

Wajib ada. Lokasi ke file CSV yang akan diakses serta konten yang diekstrak untuk pengindeksan.
Format file csv.format=DEFAULT

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

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 pada cara Cloud Search menangani file. Metode yang memungkinkan berasal dari class CSVFormat Apache Commons CSV dan menyertakan 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

Set karakter Java yang akan digunakan saat Cloud Search membaca file. Jika tidak ditentukan, Cloud Search akan menggunakan kumpulan karakter default platform.

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

Agar konektor dapat mengakses dan mengindeks file CSV, Anda harus memberikan informasi tentang definisi kolom dalam file konfigurasi. Jika file konfigurasi tidak berisi parameter yang menentukan nama kolom yang akan diindeks dan kolom kunci unik, nilai default akan digunakan.

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

Nama kolom yang akan diindeks dari file CSV. Jika csv.csvColumns tidak ditetapkan, baris pertama file CSV akan digunakan sebagai header. Jika csv.csvColumns ditetapkan, parameter tersebut akan diprioritaskan daripada baris pertama CSV. Jika Anda telah menetapkan csv.csvColumns dan baris pertama file CSV adalah daftar nama kolom, Anda perlu menetapkan csv.skipHeaderRecord=true agar baris pertama tidak diindeks sebagai data. Nilai defaultnya adalah kolom pada baris header dalam file.
Kolom kunci unik csv.uniqueKeyColumns=movieId

Kolom CSV yang nilainya akan digunakan untuk membuat ID unik dari setiap record. Jika tidak ditentukan, hash data CSV harus digunakan sebagai kunci uniknya. Nilai defaultnya adalah kode hash record.

6. Tentukan kolom yang akan digunakan di URL hasil penelusuran yang dapat diklik

Saat pengguna melakukan penelusuran menggunakan Google Cloud Search, Google Cloud Search akan merespons dengan menampilkan halaman hasil yang menyertakan URL yang dapat diklik untuk setiap hasil. Untuk mengaktifkan fitur ini, Anda harus menambahkan parameter yang ditampilkan dalam tabel berikut ke file konfigurasi.

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

Wajib ada. Format untuk membuat URL tampilan dari konten CSV.
Parameter URL hasil penelusuran. url.columns=movieId

Wajib ada. 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 informasi metadata, format kolom, dan kualitas penelusuran

Anda dapat menambahkan parameter ke file konfigurasi yang menentukan:

Parameter Konfigurasi Metadata

Parameter Konfigurasi Metadata menjelaskan kolom CSV yang digunakan untuk mengisi metadata item. Jika file konfigurasi tidak berisi parameter ini, nilai default akan digunakan. Tabel berikut menunjukkan parameter tersebut.

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

Atribut metadata yang berisi nilai yang sesuai dengan judul dokumen. Nilai defaultnya adalah string kosong.
URL itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
Atribut metadata yang berisi nilai untuk URL dokumen untuk hasil penelusuran.
Stempel waktu pembuatan itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17

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

Atribut metadata yang berisi nilai stempel waktu dokumen terakhir diubah.
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

Format datetime menentukan format yang diharapkan dalam atribut metadata. Jika file konfigurasi tidak berisi parameter ini, nilai default akan digunakan. Tabel berikut menunjukkan parameter ini.

Setelan Parameter
Format datetime tambahan structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Daftar yang dipisahkan titik koma dari daftar pola java.time.format.DateTimeFormatter tambahan. 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

Format kolom menentukan informasi tentang kolom yang harus menjadi bagian dari konten yang dapat ditelusuri. Jika file konfigurasi tidak berisi parameter ini, nilai default akan digunakan. Tabel berikut menunjukkan parameter tersebut.

Setelan Parameter
Lewati header csv.skipHeaderRecord=true

Boolean. Abaikan record header (baris pertama) dalam file CSV. Jika csv.csvColumns telah ditetapkan dan file CSV memiliki baris header, Anda harus menetapkan skipHeaderRecord=true. Tindakan ini akan mencegah pengindeksan baris pertama dalam file sebagai data. Jika file CSV tidak memiliki baris header, tetapkan skipHeaderRecord=false. Nilai defaultnya adalah false.
Kolom banyak nilai csv.multiValueColumns=genre,actors

Nama kolom dalam file CSV yang memiliki beberapa nilai. Nilai defaultnya adalah string kosong.
Pemisah untuk kolom banyak nilai csv.multiValue.genre=;

Pemisah untuk kolom banyak nilai. Pemisah defaultnya adalah koma.

Kualitas penelusuran

Konektor CSV Cloud Search memungkinkan format HTML otomatis untuk kolom data. Konektor Anda menentukan kolom data pada awal konektor dijalankan, lalu menggunakan template konten untuk memformat setiap record data sebelum menguploadnya ke Cloud Search.

Template konten menentukan tingkat kepentingan dari setiap nilai kolom untuk penelusuran. Kolom judul diperlukan dan ditetapkan sebagai prioritas tertinggi. Anda dapat menentukan tingkat kepentingan kualitas penelusuran untuk semua kolom konten lainnya: tinggi, sedang, atau rendah. Kolom konten yang tidak ditentukan dalam kategori tertentu akan ditetapkan ke prioritas rendah secara default. Tabel berikut menunjukkan parameter tersebut.

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. Nilai defaultnya adalah string kosong.

Kualitas penelusuran rendah untuk kolom konten contentTemplate.csv.quality.low=genre

Kolom konten dengan nilai kualitas penelusuran rendah. Nilai defaultnya adalah string kosong.

Kualitas penelusuran sedang untuk kolom konten contentTemplate.csv.quality.medium=description

Kolom konten dengan nilai kualitas penelusuran sedang. Nilai 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 yang dilakukan konektor untuk menemukan konten dari sumber data, dalam hal ini, file CSV. Saat berjalan, konektor CSV akan melintasi baris file CSV, lalu mengindeks setiap baris ke Cloud Search melalui Indexing API.

Traversal penuh mengindeks semua kolom dalam file. Traversal inkremental hanya mengindeks kolom yang ditambahkan atau diubah sejak traversal sebelumnya. Konektor CSV hanya menjalankan traversal penuh. Konektor ini tidak menjalankan traversal inkremental.

Parameter penjadwalan menentukan frekuensi interval konektor antara traversal. Jika file konfigurasi tidak berisi parameter penjadwalan, nilai default akan digunakan. Tabel berikut menunjukkan parameter tersebut.

Setelan Parameter
Traversal penuh setelah interval schedule.traversalIntervalSecs=7200

Konektor menjalankan traversal penuh setelah interval yang ditentukan. Tentukan interval antara traversal dalam hitungan detik. Nilai default-nya adalah 86400 (jumlah detik dalam satu hari).

Traversal penuh pada startup konektor schedule.performTraversalOnStart=false

Konektor menjalankan traversal penuh pada awal konektor dijalankan, bukan menunggu interval pertama berakhir. Nilai defaultnya adalah true.

9. Tentukan opsi Daftar Kontrol Akses (ACL)

Konektor CSV Google Cloud Search mendukung izin melalui ACL untuk mengontrol akses ke konten file CSV dalam hasil penelusuran. Ada beberapa opsi ACL yang tersedia agar Anda dapat melindungi akses pengguna ke record yang diindeks.

Jika repositori Anda memiliki informasi ACL individual yang terkait dengan setiap dokumen, upload semua informasi ACL untuk mengontrol akses dokumen dalam Cloud Search. Jika repositori Anda memberikan sebagian atau tanpa informasi ACL, Anda dapat memberikan informasi ACL default dalam parameter berikut, yang diberikan SDK ke konektor.

Konektor mengandalkan ACL default yang diaktifkan di file konfigurasi. Untuk mengaktifkan ACL default, tetapkan defaultAcl.mode ke semua mode selain none, lalu konfigurasikan dengan defaultAcl.*

Setelan Parameter
Mode ACL defaultAcl.mode=fallback

Wajib ada. Konektor CSV mengandalkan fungsi ACL Default. Konektor hanya mendukung mode fallback.

Nama ACL default defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1

Opsional. Dapat mengganti nama container virtual yang digunakan oleh konektor untuk menyiapkan ACL default. Nilai defaultnya adalah "DEFAULT_ACL_VIRTUAL_CONTAINER". Anda dapat mengganti nilai ini jika beberapa konektor mengindeks konten dalam sumber data yang sama.

ACL publik default defaultAcl.public=true

ACL default yang digunakan untuk seluruh repositori ditetapkan ke akses domain publik. Nilai defaultnya 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 satu ACL untuk setiap data repositori, tetapkan semua nilai 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

    Setiap pengguna dan grup yang ditentukan dianggap sebagai pengguna/grup yang ditentukan domain lokal kecuali diawali dengan "google:" (konstanta literal).

    Pengguna atau grup defaultnya adalah string kosong. Berikan opsi kepada pengguna dan grup hanya jika defaultAcl.public ditetapkan menjadi false. Untuk membuat daftar beberapa grup dan pengguna, gunakan daftar yang dipisahkan koma.

    Jika defaultAcl.mode ditetapkan ke none, catatan tidak dapat ditelusuri tanpa ada ACL individual yang ditetapkan.

Definisi Skema

Cloud Search mengizinkan pengindeksan dan penayangan konten terstruktur dan tidak terstruktur. Untuk mendukung kueri data terstruktur pada data Anda, Anda perlu menyiapkan Skema untuk sumber data Anda.

Setelah ditentukan, Konektor CSV dapat merujuk skema yang ditentukan untuk membuat permintaan pengindeksan. Untuk memberikan contoh ilustrasi, coba pertimbangkan file CSV yang berisi informasi tentang Film.

Misalnya, file CSV input memiliki konten berikut.

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

Berdasarkan pada struktur data di atas, Anda dapat menentukan skema untuk sumber data yang ingin diindeks datanya dari file 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"
            }
          }
        }
      ]
    }
  ]
}

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

Untuk mengetahui deskripsi mendetail dari setiap parameter, lihat referensi Parameter konfigurasi.

Menjalankan konektor CSV Cloud Search

Untuk menjalankan konektor dari command line, ketikkan perintah berikut:

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