Hướng dẫn này dành cho quản trị viên trình kết nối CSV (giá trị được phân tách bằng dấu phẩy) của Google Cloud Search, chịu trách nhiệm tải xuống, định cấu hình, chạy và giám sát trình kết nối.
Hướng dẫn này bao gồm hướng dẫn cho các nhiệm vụ chính sau:
- Tải phần mềm trình kết nối CSV của Cloud Search xuống.
- Định cấu hình trình kết nối cho một nguồn dữ liệu CSV cụ thể.
- Triển khai và chạy trình kết nối.
Để hiểu các khái niệm trong tài liệu này, bạn cần nắm rõ Google Workspace, tệp CSV và Danh sách kiểm soát truy cập (ACL).
Tổng quan về trình kết nối CSV của Cloud Search
Trình kết nối CSV của Cloud Search hoạt động với mọi tệp văn bản có giá trị được phân tách bằng dấu phẩy (CSV). Tệp CSV lưu trữ dữ liệu dạng bảng, trong đó mỗi dòng là một bản ghi dữ liệu.
Trình kết nối trích xuất các hàng từ một tệp CSV và lập chỉ mục các hàng đó vào Cloud Search bằng API Lập chỉ mục. Sau khi được lập chỉ mục, các hàng có thể tìm kiếm được thông qua các ứng dụng Cloud Search hoặc Query API. Trình kết nối này cũng hỗ trợ ACL để kiểm soát quyền truy cập của người dùng vào nội dung.
Bạn có thể cài đặt trình kết nối trên Linux hoặc Windows. Trước khi triển khai, hãy đảm bảo bạn có các thành phần sau:
- Java JRE 1.8 được cài đặt trên máy tính chạy trình kết nối.
- Thông tin về Google Workspace để thiết lập các mối kết nối:
- Khoá riêng tư của Google Workspace (chứa mã nhận dạng tài khoản dịch vụ).
- Mã nhận dạng nguồn dữ liệu Google Workspace.
Thông thường, quản trị viên Google Workspace của miền sẽ cung cấp thông tin đăng nhập này.
Các bước triển khai
Làm theo các bước sau để triển khai trình kết nối CSV của Cloud Search:
- Cài đặt phần mềm trình kết nối
- Chỉ định cấu hình trình kết nối
- Định cấu hình quyền truy cập vào nguồn dữ liệu Cloud Search
- Định cấu hình quyền truy cập vào tệp CSV
- Chỉ định tên cột, khoá riêng biệt và cột ngày giờ
- Chỉ định các cột cho URL của kết quả tìm kiếm có thể nhấp
- Chỉ định siêu dữ liệu và định dạng cột
- Lập lịch truyền tải dữ liệu
- Chỉ định các lựa chọn ACL
1. Cài đặt SDK
Cài đặt SDK vào kho lưu trữ Maven cục bộ.
Sao chép kho lưu trữ SDK trên GitHub.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Kiểm tra phiên bản bạn chọn:
$ git checkout tags/v1-0.0.3
Tạo trình kết nối:
$ mvn package
Giải nén và cài đặt trình kết nối:
$ 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. Chỉ định cấu hình trình kết nối CSV
Bạn kiểm soát hành vi của trình kết nối thông qua các tham số trong tệp cấu hình của trình kết nối. Các thông số có thể định cấu hình bao gồm:
- Quyền truy cập vào nguồn dữ liệu.
- Vị trí và định nghĩa của tệp CSV.
- Các cột mã nhận dạng duy nhất.
- Các lựa chọn về việc duyệt qua và ACL.
Cách tạo tệp cấu hình:
- Mở một trình chỉnh sửa văn bản và đặt tên cho tệp là
connector-config.properties. - Thêm các thông số cấu hình dưới dạng các cặp
key=value, với mỗi cặp trên một dòng mới. Để biết ví dụ về tệp cấu hình, hãy xem phần Ví dụ về tệp cấu hình.
Giữ tệp cấu hình trong cùng thư mục với trình kết nối để đơn giản hoá việc theo dõi. Để đảm bảo trình kết nối nhận dạng tệp của bạn, hãy chỉ định đường dẫn của tệp đó trên dòng lệnh. Nếu không, trình kết nối sẽ mặc định là connector-config.properties trong thư mục cục bộ của bạn. Xem phần Chạy trình kết nối.
3. Định cấu hình quyền truy cập vào nguồn dữ liệu Cloud Search
Tệp cấu hình phải chỉ định các tham số để truy cập vào nguồn dữ liệu Cloud Search. Bạn cần có mã nhận dạng Nguồn dữ liệu, mã nhận dạng tài khoản dịch vụ và đường dẫn đến tệp khoá riêng tư của tài khoản dịch vụ.
| Cài đặt | Tham số |
| Mã nguồn dữ liệu | api.sourceId=1234567890abcdef
Bắt buộc. Mã nguồn Cloud Search do quản trị viên Google Workspace thiết lập. |
| Đường dẫn đến khoá riêng tư của tài khoản dịch vụ | api.serviceAccountPrivateKeyFile=./PrivateKey.json
Bắt buộc. Tệp khoá tài khoản dịch vụ để hỗ trợ tiếp cận trình kết nối. |
| Mã nguồn nhận dạng | api.identitySourceId=x0987654321
Bắt buộc nếu sử dụng người dùng và nhóm bên ngoài. Mã nhận dạng nguồn danh tính do quản trị viên Google Workspace thiết lập. |
4. Định cấu hình các tham số của tệp CSV
Xác định đường dẫn, định dạng và phương thức mã hoá của tệp.
| Cài đặt | Tham số |
| Đường dẫn đến tệp CSV | csv.filePath=./movie_content.csv
Bắt buộc. Đường dẫn đến tệp cần lập chỉ mục. |
| Định dạng tệp | csv.format=DEFAULT
Định dạng của tệp. Các giá trị có thể là của lớp CSVFormat trong Apache Commons CSV. Các giá trị định dạng bao gồm: |
| Giá trị bổ sung định dạng tệp | csv.format.withMethod=value
Một thay đổi về cách Cloud Search xử lý tệp. Các phương thức có thể có là từ lớp CSVFormat của Apache Commons CSV và bao gồm những phương thức lấy một ký tự, chuỗi hoặc giá trị boolean. Ví dụ: để chỉ định dấu chấm phẩy làm dấu phân cách, hãy sử dụng |
| Loại mã hoá tệp | csv.fileEncoding=UTF-8
Bộ ký tự Java sẽ sử dụng. Giá trị mặc định là bộ ký tự nền tảng. |
5. Chỉ định tên cột để lập chỉ mục và các cột khoá duy nhất
Cung cấp thông tin về cột trong tệp cấu hình.
| Cài đặt | Tham số |
| Các cột cần lập chỉ mục | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
Tên cột cần được lập chỉ mục trong tệp CSV. Theo mặc định, hàng đầu tiên của tệp CSV được dùng làm tiêu đề. Nếu bạn chỉ định |
| Cột khoá riêng biệt | csv.uniqueKeyColumns=movieId
Các cột được dùng để tạo mã nhận dạng duy nhất. Giá trị mặc định là mã băm của bản ghi. |
6. Chỉ định các cột cho URL kết quả tìm kiếm có thể nhấp
Bật URL có thể nhấp cho kết quả tìm kiếm.
| Cài đặt | Tham số |
| Định dạng URL của kết quả tìm kiếm | url.format=https://mymoviesite.com/movies/{0}
Bắt buộc. Định dạng dùng để tạo URL chế độ xem. |
| Thông số URL | url.columns=movieId
Bắt buộc. Tên cột CSV có giá trị sẽ được dùng để tạo URL xem của bản ghi. |
| Tham số URL của kết quả tìm kiếm cần thoát | url.columnsToEscape=movieId
Không bắt buộc. Tên cột CSV có giá trị sẽ được thoát URL để tạo URL hợp lệ cho chế độ xem. |
7. Chỉ định siêu dữ liệu, định dạng cột và chất lượng tìm kiếm
Bạn có thể thêm các tham số vào tệp cấu hình để chỉ định:
Tham số cấu hình siêu dữ liệu
Các tham số này mô tả các cột để điền sẵn siêu dữ liệu của mặt hàng.
| Chế độ cài đặt | Tham số |
| Tiêu đề | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
Thuộc tính siêu dữ liệu cho tiêu đề tài liệu. Giá trị mặc định là một chuỗi trống. |
| URL | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
Thuộc tính siêu dữ liệu cho URL của tài liệu trong kết quả tìm kiếm. |
| Dấu thời gian tạo | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
Thuộc tính siêu dữ liệu cho dấu thời gian tạo tài liệu. |
| Lần sửa cuối | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
Thuộc tính siêu dữ liệu cho dấu thời gian sửa đổi gần đây nhất của tài liệu. |
| Ngôn ngữ của giấy tờ | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
Ngôn ngữ nội dung của tài liệu đang được lập chỉ mục. |
| Loại đối tượng giản đồ | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
Loại đối tượng mà trình kết nối sử dụng, như được xác định trong schema. Trình kết nối sẽ không lập chỉ mục bất kỳ dữ liệu có cấu trúc nào nếu bạn không chỉ định tài sản này. |
Định dạng ngày giờ
Tham số này chỉ định các định dạng ngày giờ bổ sung để phân tích cú pháp các giá trị chuỗi thành trường ngày hoặc trường ngày giờ.
| Chế độ cài đặt | Tham số |
| Các định dạng ngày giờ khác | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Danh sách các mẫu java.time.format.DateTimeFormatter bổ sung được phân tách bằng dấu chấm phẩy. Các mẫu này được dùng khi phân tích cú pháp các giá trị chuỗi cho mọi trường ngày hoặc ngày giờ trong siêu dữ liệu hoặc giản đồ. Giá trị mặc định là một danh sách trống, nhưng các định dạng RFC 3339 và RFC 1123 luôn được hỗ trợ.
|
Định dạng cột
Các tham số này chỉ định cách phân tích cú pháp các cột trong tệp CSV.
| Cài đặt | Tham số |
| Bỏ qua tiêu đề | csv.skipHeaderRecord=true
Bỏ qua dòng đầu tiên. Mặc định là sai. |
| Cột có nhiều giá trị | csv.multiValueColumns=genre,actors
Tên cột có nhiều giá trị. |
| Dấu phân cách cho cột có nhiều giá trị | csv.multiValue.genre=;
Dấu phân cách cho các cột có nhiều giá trị. Dấu phân cách mặc định là dấu phẩy. |
Chất lượng tìm kiếm
Trình kết nối sử dụng một mẫu nội dung để định dạng các bản ghi. Trường tiêu đề có mức độ ưu tiên cao nhất. Bạn có thể chỉ định mức độ ưu tiên (cao, trung bình, thấp) cho các trường khác.
| Cài đặt | Tham số |
| Tiêu đề nội dung |
contentTemplate.csv.title=movieTitle
Tiêu đề nội dung là trường có chất lượng tìm kiếm cao nhất. |
| Chất lượng tìm kiếm cao cho các trường nội dung |
contentTemplate.csv.quality.high=actors
Các trường nội dung được chỉ định giá trị chất lượng tìm kiếm cao. Giá trị mặc định là một chuỗi trống. |
| Chất lượng tìm kiếm thấp cho các trường nội dung |
contentTemplate.csv.quality.low=genre
Các trường nội dung được chỉ định giá trị chất lượng tìm kiếm thấp. Giá trị mặc định là một chuỗi trống. |
| Chất lượng tìm kiếm trung bình cho các trường nội dung |
contentTemplate.csv.quality.medium=description
Các trường nội dung được chỉ định giá trị chất lượng tìm kiếm ở mức trung bình. Giá trị mặc định là một chuỗi trống. |
| Các trường nội dung không được chỉ định |
contentTemplate.csv.unmappedColumnsMode=IGNORE
Cách trình kết nối xử lý các trường nội dung không xác định. Các giá trị hợp lệ là:
Giá trị mặc định là APPEND. |
8. Lập lịch duyệt qua dữ liệu
Truy cập là quá trình khám phá nội dung. Trình kết nối này duyệt qua các hàng CSV và lập chỉ mục bằng API Lập chỉ mục. Trình kết nối CSV chỉ thực hiện các lượt duyệt qua đầy đủ.
| Cài đặt | Tham số |
| Khoảng thời gian truyền tải | schedule.traversalIntervalSecs=7200
Khoảng thời gian giữa các lần duyệt qua toàn bộ (tính bằng giây). Giá trị mặc định là 86400 (một ngày). |
| Truy cập khi khởi động | schedule.performTraversalOnStart=false
Trình kết nối thực hiện một lần truyền tải khi khởi động trình kết nối, thay vì chờ hết khoảng thời gian đầu tiên. Giá trị mặc định là |
9. Chỉ định các lựa chọn về ACL
Trình kết nối sử dụng ACL để kiểm soát quyền truy cập. Nếu kho lưu trữ của bạn cung cấp ACL, hãy tải chúng lên. Nếu không, hãy định cấu hình các ACL mặc định. Đặt defaultAcl.mode thành một giá trị khác none.
| Cài đặt | Tham số |
| Chế độ ACL | defaultAcl.mode=fallback
Bắt buộc. Trình kết nối này chỉ hỗ trợ chế độ dự phòng. |
| Tên ACL mặc định | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
Không bắt buộc. Ghi đè tên vùng chứa ảo mà trình kết nối dùng cho ACL mặc định. Giá trị mặc định là |
| ACL công khai mặc định | defaultAcl.public=true
Đặt toàn bộ kho lưu trữ ở chế độ truy cập công khai. Mặc định là false. |
| Nhóm người đọc ACL phổ biến | defaultAcl.readers.groups=google:group1, group2
|
| Các trình đọc ACL phổ biến | defaultAcl.readers.users=user1, user2, google:user3
|
| Nhóm người đọc thường bị ACL từ chối | defaultAcl.denied.groups=group3
|
| Common Acl denied readers | defaultAcl.denied.users=user4, user5
|
| Quyền truy cập vào toàn bộ miền | Để chỉ định rằng mọi người dùng trong miền đều có thể truy cập công khai vào mọi bản ghi được lập chỉ mục, hãy đặt cả hai lựa chọn sau đây bằng các giá trị:
|
| ACL được xác định chung | Để xác định một ACL chung cho từng bản ghi, hãy đặt các tham số sau:
Người dùng và nhóm được giả định là do miền cục bộ xác định, trừ phi có tiền tố " Người dùng hoặc nhóm mặc định là một chuỗi trống. Chỉ cung cấp các lựa chọn về người dùng và nhóm nếu Nếu |
Định nghĩa giản đồ
Để hỗ trợ các truy vấn dữ liệu có cấu trúc, hãy thiết lập một lược đồ cho nguồn dữ liệu của bạn.
Ví dụ: hãy xem xét một tệp CSV có thông tin sau về các bộ phim:
- movieId
- movieTitle
- mô tả
- năm
- releaseDate
- diễn viên (nhiều giá trị được phân tách bằng dấu phẩy (,))
- thể loại (nhiều giá trị)
- xếp hạng
Dựa trên cấu trúc này, bạn có thể xác định giản đồ sau cho nguồn dữ liệu của mình:
{
"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"
}
}
}
]
}
]
}
Tệp cấu hình mẫu
Tệp cấu hình ví dụ sau đây cho thấy các cặp tham số key=value xác định hành vi của một trình kết nối mẫu.
# 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
Chạy trình kết nối
Cách chạy trình kết nối qua dòng lệnh:
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
Theo mặc định, nhật ký của trình kết nối có trên đầu ra chuẩn. Bạn có thể ghi nhật ký vào tệp bằng cách chỉ định logging.properties.