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:

  • Kunci pribadi Google Workspace (yang berisi ID akun layanan)
  • ID sumber data Google Workspace

  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

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.

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.

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.

7. Tentukan informasi metadata, format kolom, dan kualitas penelusuran

Anda dapat menambahkan parameter ke file konfigurasi yang menentukan:

• Parameter Konfigurasi Metadata
• Format kolom
• Kualitas penelusuran

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.

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.

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.

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.

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.

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

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.