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-konsep dalam dokumen ini, Anda harus sudah terbiasa dengan dasar-dasar Google Workspace, file CSV, dan Daftar Kontrol Akses (ACL).
Ringkasan konektor CSV Google Cloud Search
Konektor CSV Cloud Search berfungsi dengan teks nilai yang dipisahkan koma (CSV) . {i>File<i} CSV menyimpan data tabulasi, dan setiap baris file adalah data merekam.
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 membangun hubungan antara 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:
- Menginstal software konektor CSV Google Cloud Search
- Menentukan konfigurasi konektor CSV
- Mengonfigurasi akses ke sumber data Google Cloud Search
- Mengonfigurasi akses file CSV
- Menentukan nama kolom yang akan diindeks, kolom kunci unik, dan kolom tanggal dan waktu
- Menentukan kolom yang akan digunakan di URL hasil penelusuran yang dapat diklik
- Menentukan informasi metadata dan format kolom
- Menjadwalkan traversal data
- Menentukan opsi Daftar Kontrol Akses (ACL)
1. Instal SDK
Instal SDK ke repositori Maven lokal Anda.
Lakukan clone repositori SDK dari GitHub.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Periksa versi SDK yang diinginkan:
$ git checkout tags/v1-0.0.3Buat konektor:
$ mvn packageSalin 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:
- Buka editor teks pilihan Anda dan beri nama file konfigurasi.
Tambahkan key=value pair ke konten file seperti yang dijelaskan dalam bagian. - Simpan dan beri nama file konfigurasi.
Google merekomendasikan agar Anda memberi nama file konfigurasiconnector-config.propertiesjadi tidak ada parameter command line tambahan yang yang diperlukan 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 informasi tentang cara menentukan jalur konfigurasi di
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 Google Cloud Search yang 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 di 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 mungkin berasal dari class CSVFormat CSV Apache Commons. Nilai formatnya meliputi: |
| Pengubah format file | csv.format.withMethod=value
Modifikasi cara Cloud Search menangani file. Metode yang dapat digunakan berasal dari class CSVFormat Apache Commons dan menyertakan metode yang mengambil satu karakter, string, atau nilai boolean. Misalnya, untuk menentukan titik koma sebagai pembatas, gunakan |
| Jenis encoding file | csv.fileEncoding=UTF-8
Himpunan karakter Java yang akan digunakan saat Cloud Search membaca file. Jika tidak ditentukan, Cloud Search menggunakan himpunan 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 untuk mengindeks kolom kunci unik, nilai {i>default <i}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 |
| Kolom kunci unik | csv.uniqueKeyColumns=movieId
Kolom CSV yang nilainya akan digunakan untuk membuat ID unik setiap kumpulan data. 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=typeitemMetadata.objectType.defaultValue=movie
Jenis objek yang digunakan oleh konektor, seperti yang didefinisikan 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 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 Anda telah menetapkan |
| 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:
|
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 defaultnya 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. Kepada
mengaktifkan ACL default, setel defaultAcl.mode ke mode apa pun selain none dan
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 bahwa setiap data yang diindeks dapat diakses secara publik oleh setiap pengguna di domain, setel kedua opsi berikut dengan nilai:
|
| ACL yang ditetapkan umum | Untuk menentukan satu ACL untuk setiap kumpulan data repositori data, tetapkan semua nilai parameter berikut:
|
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.
- movieId
- movieTitle
- description
- year
- releaseDate
- actors (beberapa nilai yang dipisahkan koma (,))
- genre (beberapa nilai)
- 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 masuk ke file
dengan menentukan logging.properties.