Triển khai trình kết nối CSV

Hướng dẫn này dành cho quản trị viên của trình kết nối Google Cloud Search CSV (giá trị được phân tách bằng dấu phẩy), tức là bất kỳ ai 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 thực hiện các nhiệm vụ chính liên quan đến việc triển khai trình kết nối CSV:

• Tải phần mềm trình kết nối CSV của Google Cloud Search xuống
• Định cấu hình trình kết nối để sử dụng với 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 phải nắm rõ các khái niệm cơ bản về 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 Google 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 chứa cá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 và mỗi dòng của tệp là một bản ghi dữ liệu.

Trình kết nối CSV của Google Cloud Search trích xuất từng hàng riêng lẻ từ tệp CSV và lập chỉ mục các hàng đó vào Cloud Search thông qua API Lập chỉ mục của Cloud Search. Sau khi được lập chỉ mục thành công, bạn có thể tìm kiếm từng hàng trong tệp CSV thông qua ứng dụng của Cloud Search hoặc API Truy vấn của Cloud Search. Trình kết nối CSV cũng hỗ trợ việc kiểm soát quyền truy cập của người dùng vào nội dung trong kết quả tìm kiếm bằng cách sử dụng ACL.

Bạn có thể cài đặt trình kết nối CSV của Google Cloud Search trên Linux hoặc Windows. Trước khi triển khai trình kết nối CSV của Google Cloud Search, hãy đảm bảo rằng bạn có các thành phần bắt buộc sau:

• Java JRE 1.8 được cài đặt trên máy tính chạy trình kết nối CSV của Google Cloud Search

• Thông tin cần thiết về Google Workspace để thiết lập mối quan hệ giữa Google Cloud Search và nguồn dữ liệu:

  • Khoá riêng của Google Workspace (chứa mã tài khoản dịch vụ)
  • Mã nguồn dữ liệu Google Workspace

  Thông thường, quản trị viên Google Workspace của miền có thể cung cấp các thông tin xác thực này cho bạn.

Các bước triển khai

Để triển khai trình kết nối CSV của Google Cloud Search, hãy làm theo các bước sau:

1. Cài đặt phần mềm trình kết nối CSV của Google Cloud Search
2. Chỉ định cấu hình trình kết nối CSV
3. Định cấu hình quyền truy cập vào nguồn dữ liệu Google Cloud Search
4. Định cấu hình quyền truy cập vào tệp CSV
5. Chỉ định tên cột để lập chỉ mục, cột khoá duy nhất và cột ngày giờ
6. Chỉ định các cột để sử dụng trong URL kết quả tìm kiếm có thể nhấp
7. Chỉ định thông tin siêu dữ liệu, định dạng cột
8. Lịch biểu truyền tải dữ liệu
9. Chỉ định các tuỳ chọn Danh sách kiểm soát quyền truy cập (ACL)

1. Cài đặt SDK

Cài đặt SDK vào kho lưu trữ Maven cục bộ.

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

2. Xem phiên bản SDK mong muốn:

   $ git checkout tags/v1-0.0.3

3. Tạo trình kết nối:

   $ mvn package

4. Sao chép tệp zip của trình kết nối vào thư mục cài đặt cục bộ:

   $ 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

Là quản trị viên của trình kết nối, bạn kiểm soát hành vi và các thuộc tính của trình kết nối CSV xác định các tham số trong tệp cấu hình của trình kết nối. Các tham 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í của tệp CSV
• Định nghĩa cột CSV
• (Các) cột xác định mã nhận dạng duy nhất
• Tuỳ chọn truyền tải
• Các tuỳ chọn ACL để hạn chế quyền truy cập dữ liệu

Để trình kết nối truy cập đúng cách vào tệp CSV và lập chỉ mục nội dung có liên quan, trước tiên, bạn phải tạo tệp cấu hình của trình kết nối.

Cách tạo tệp cấu hình:

1. Mở một trình chỉnh sửa văn bản mà bạn chọn rồi đặt tên cho tệp cấu hình.
   Thêm các cặp khoá=giá trị vào nội dung tệp như mô tả trong các phần sau.
2. Lưu và đặt tên cho tệp cấu hình.
   Bạn nên đặt tên tệp cấu hình là connector-config.properties để không cần thêm thông số dòng lệnh nào khác để chạy trình kết nối.

Vì bạn có thể chỉ định đường dẫn tệp cấu hình trên dòng lệnh, nên không cần vị trí tệp chuẩn. Tuy nhiên, hãy 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 và chạy trình kết nối.

Để đảm bảo trình kết nối nhận ra tệp cấu hình 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ẽ sử dụng connector-config.properties trong thư mục cục bộ của bạn làm tên tệp mặc định. Để biết thông tin về cách chỉ định đường dẫn cấu hình trên dòng lệnh, hãy xem phần Chạy trình kết nối CSV của Cloud Search.

3. Định cấu hình quyền truy cập vào nguồn dữ liệu Google Cloud Search

Các tham số đầu tiên mà mọi tệp cấu hình phải chỉ định là các tham số cần thiết để truy cập vào nguồn dữ liệu Tìm kiếm trên đám mây, như trong bảng sau. Thông thường, bạn sẽ cần Mã nguồn dữ liệu, mã 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ụ để định cấu hình quyền truy cập của trình kết nối vào Cloud Search. Các bước cần thiết để thiết lập nguồn dữ liệu được mô tả trong phần Quản lý nguồn dữ liệu của bên thứ ba

4. Định cấu hình các tham số tệp CSV

Trước khi trình kết nối có thể duyệt qua tệp CSV và trích xuất dữ liệu từ tệp đó để lập chỉ mục, bạn phải xác định đường dẫn đến tệp. Bạn cũng có thể chỉ định định dạng tệp và loại mã hoá tệp. Thêm các tham số sau để chỉ định các thuộc tính tệp CSV trong tệp cấu hình.

5. Chỉ định tên cột để lập chỉ mục và cột khoá duy nhất

Để trình kết nối truy cập và lập chỉ mục tệp CSV, bạn phải cung cấp thông tin về định nghĩa cột trong tệp cấu hình. Nếu tệp cấu hình không chứa các thông số chỉ định tên cột để lập chỉ mục và cột khoá duy nhất, thì các giá trị mặc định sẽ được sử dụng.

6. Chỉ định các cột để sử dụng trong URL kết quả tìm kiếm có thể nhấp

Khi người dùng tìm kiếm bằng Google Cloud Search, dịch vụ này sẽ phản hồi bằng cách hiển thị một trang kết quả bao gồm các URL có thể nhấp vào cho mỗi kết quả. Để bật tính năng này, bạn phải thêm tham số hiển thị trong bảng sau vào tệp cấu hình.

7. Chỉ định thông tin siêu dữ liệu, định dạng cột, 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:

• Thông số cấu hình siêu dữ liệu
• Định dạng cột
• Chất lượng tìm kiếm

Tham số cấu hình siêu dữ liệu

Tham số cấu hình siêu dữ liệu mô tả các cột CSV dùng để điền siêu dữ liệu của mặt hàng. Nếu tệp cấu hình không chứa các thông số này, thì hệ thống sẽ sử dụng các giá trị mặc định. Bảng sau đây cho thấy các tham số này.

Định dạng ngày giờ

Định dạng ngày giờ chỉ định định dạng dự kiến trong các thuộc tính siêu dữ liệu. Nếu tệp cấu hình không chứa tham số này, thì các giá trị mặc định sẽ được sử dụng. Bảng sau đây cho thấy thông số này.

Định dạng cột

Định dạng cột chỉ định thông tin về(các) cột sẽ thuộc nội dung có thể tìm kiếm. Nếu tệp cấu hình không chứa các thông số này, thì hệ thống sẽ sử dụng các giá trị mặc định. Bảng sau đây cho thấy các tham số này.

Chất lượng tìm kiếm

Trình kết nối CSV của Cloud Search cho phép định dạng HTML tự động cho các trường dữ liệu. Trình kết nối xác định các trường dữ liệu ở đầu quá trình thực thi trình kết nối, sau đó sử dụng mẫu nội dung để định dạng từng bản ghi dữ liệu trước khi tải lên Cloud Search.

Mẫu nội dung xác định tầm quan trọng của từng giá trị trường để tìm kiếm. Trường tiêu đề là trường bắt buộc và được xác định là trường có mức độ ưu tiên cao nhất. Bạn có thể chỉ định mức độ quan trọng của chất lượng tìm kiếm cho tất cả các trường nội dung khác: cao, trung bình hoặc thấp. Mọi trường nội dung không được xác định trong một danh mục cụ thể đều mặc định có mức độ ưu tiên thấp. Bảng sau đây cho thấy các tham số này.

8. Lên lịch duyệt dữ liệu

Truy cập là quy trình của trình kết nối để khám phá nội dung từ nguồn dữ liệu, trong trường hợp này là tệp CSV. Khi chạy, trình kết nối CSV sẽ duyệt qua các hàng của tệp CSV và lập chỉ mục từng hàng vào Cloud Search thông qua API Lập chỉ mục.

Phương thức duyệt qua đầy đủ sẽ lập chỉ mục tất cả các cột trong tệp. Phương thức duyệt tăng dần chỉ lập chỉ mục các cột được thêm hoặc sửa đổi kể từ lần duyệt trước. Trình kết nối CSV chỉ thực hiện các lượt truy cập đầy đủ. Phương thức này không thực hiện các lượt truy cập gia tăng.

Các tham số lên lịch xác định tần suất trình kết nối chờ giữa các lần truy cập. Nếu tệp cấu hình không chứa các thông số lên lịch, thì giá trị mặc định sẽ được sử dụng. Bảng sau đây cho thấy các tham số này.

9. Chỉ định các tuỳ chọn Danh sách kiểm soát quyền truy cập (ACL)

Trình kết nối CSV của Google Cloud Search hỗ trợ các quyền thông qua ACL để kiểm soát quyền truy cập vào nội dung của tệp CSV trong kết quả tìm kiếm. Có nhiều tuỳ chọn ACL để cho phép bạn bảo vệ quyền truy cập của người dùng vào các bản ghi được lập chỉ mục.

Nếu kho lưu trữ của bạn có thông tin ACL riêng lẻ liên kết với từng tài liệu, hãy tải tất cả thông tin ACL lên để kiểm soát quyền truy cập vào tài liệu trong Cloud Search. Nếu kho lưu trữ của bạn cung cấp một phần hoặc không có thông tin ACL, bạn có thể cung cấp thông tin ACL mặc định trong các thông số sau đây mà SDK cung cấp cho trình kết nối.

Trình kết nối này dựa vào việc ACL mặc định được bật trong tệp cấu hình. Để bật ACL mặc định, hãy đặt defaultAcl.mode thành bất kỳ chế độ nào khác ngoài none và định cấu hình chế độ đó bằng defaultAcl.*

Định nghĩa giản đồ

Cloud Search cho phép lập chỉ mục và phân phát nội dung có cấu trúc và không có cấu trúc. Để hỗ trợ các truy vấn dữ liệu có cấu trúc trên dữ liệu của mình, bạn cần thiết lập Lược đồ cho nguồn dữ liệu.

Sau khi được xác định, Trình kết nối CSV có thể tham chiếu giản đồ đã xác định để tạo các yêu cầu lập chỉ mục. Để minh hoạ, hãy xem xét một tệp CSV chứa thông tin về Phim.

Giả sử tệp CSV đầu vào có nội dung sau.

1. movieId
2. movieTitle
3. mô tả
4. năm
5. releaseDate
6. diễn viên (nhiều giá trị được phân tách bằng dấu phẩy (,))
7. thể loại (nhiều giá trị)
8. xếp hạng

Dựa trên cấu trúc dữ liệu ở trên, bạn có thể xác định giản đồ cho nguồn dữ liệu mà bạn muốn lập chỉ mục dữ liệu từ tệp 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"
            }
          }
        }
      ]
    }
  ]
}

Tệp cấu hình mẫu

Tệp cấu hình mẫu sau đây cho thấy các cặp tham số key=value xác định hành vi của 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

Để biết nội dung mô tả chi tiết về từng thông số, hãy xem tài liệu tham khảo về Thông số cấu hình.

Chạy trình kết nối CSV của Cloud Search

Để chạy trình kết nối từ dòng lệnh, hãy nhập lệnh sau:

$ 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ó sẵn 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.