Tạo trình kết nối nội dung

Trình kết nối nội dung là một chương trình phần mềm dùng để duyệt qua dữ liệu trong kho lưu trữ của một doanh nghiệp và điền sẵn nguồn dữ liệu. Google cung cấp các tuỳ chọn sau đây để phát triển trình kết nối nội dung:

• SDK Trình kết nối nội dung. Đây là một lựa chọn phù hợp nếu bạn đang lập trình bằng Java. SDK Trình kết nối nội dung là một trình bao bọc xung quanh API REST cho phép bạn nhanh chóng tạo trình kết nối. Để tạo trình kết nối nội dung bằng SDK, hãy tham khảo bài viết Tạo trình kết nối nội dung bằng SDK Trình kết nối nội dung.

• API REST cấp thấp hoặc thư viện API. Hãy sử dụng các tuỳ chọn này nếu bạn không lập trình bằng Java hoặc nếu cơ sở mã của bạn phù hợp hơn với API REST hoặc thư viện. Để tạo trình kết nối nội dung bằng API REST, hãy tham khảo phần Tạo trình kết nối nội dung bằng API REST.

Một trình kết nối nội dung thông thường thực hiện các nhiệm vụ sau:

1. Đọc và xử lý các thông số cấu hình.
2. Kéo các phần dữ liệu riêng biệt có thể lập chỉ mục, được gọi là "mục", từ kho lưu trữ nội dung của bên thứ ba.
3. Kết hợp ACL, siêu dữ liệu và dữ liệu nội dung thành các mục có thể lập chỉ mục.
4. Lập chỉ mục các mục vào nguồn dữ liệu Cloud Search.
5. (không bắt buộc) Theo dõi các thông báo thay đổi từ kho lưu trữ nội dung của bên thứ ba. Thông báo thay đổi được chuyển đổi thành yêu cầu lập chỉ mục để duy trì việc đồng bộ hoá nguồn dữ liệu Cloud Search với kho lưu trữ của bên thứ ba. Trình kết nối chỉ thực hiện nhiệm vụ này nếu kho lưu trữ hỗ trợ tính năng phát hiện thay đổi.

Tạo trình kết nối nội dung bằng SDK Trình kết nối nội dung

Các phần sau đây giải thích cách tạo trình kết nối nội dung bằng SDK Trình kết nối nội dung.

Thiết lập phần phụ thuộc

Bạn phải đưa một số phần phụ thuộc nhất định vào tệp bản dựng để sử dụng SDK. Nhấp vào một thẻ bên dưới để xem các phần phụ thuộc cho môi trường xây dựng của bạn:

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

compile group: 'com.google.enterprise.cloudsearch',
        name: 'google-cloudsearch-indexing-connector-sdk',
        version: 'v1-0.0.3'

Tạo cấu hình trình kết nối

Mỗi trình kết nối đều có một tệp cấu hình chứa các tham số mà trình kết nối sử dụng, chẳng hạn như mã nhận dạng cho kho lưu trữ của bạn. Các thông số được xác định là cặp khoá-giá trị, chẳng hạn như api.sourceId=1234567890abcdef.

SDK Google Cloud Search chứa một số tham số cấu hình do Google cung cấp mà tất cả trình kết nối đều sử dụng. Bạn phải khai báo các thông số do Google cung cấp sau đây trong tệp cấu hình:

• Đối với trình kết nối nội dung, bạn phải khai báo api.sourceId và api.serviceAccountPrivateKeyFile vì các tham số này xác định vị trí của kho lưu trữ và khoá riêng tư cần thiết để truy cập vào kho lưu trữ.

• Đối với trình kết nối danh tính, bạn phải khai báo api.identitySourceId vì tham số này xác định vị trí của nguồn danh tính bên ngoài. Nếu đang đồng bộ hoá người dùng, bạn cũng phải khai báo api.customerId làm mã nhận dạng duy nhất cho tài khoản Google Workspace của doanh nghiệp.

Trừ phi bạn muốn ghi đè các giá trị mặc định của các tham số khác do Google cung cấp, bạn không cần khai báo các tham số đó trong tệp cấu hình. Để biết thêm thông tin về các thông số cấu hình do Google cung cấp, chẳng hạn như cách tạo một số mã nhận dạng và khoá nhất định, hãy tham khảo phần Thông số cấu hình do Google cung cấp.

Bạn cũng có thể xác định các tham số dành riêng cho kho lưu trữ của riêng mình để sử dụng trong tệp cấu hình.

Truyền tệp cấu hình đến trình kết nối

Đặt thuộc tính hệ thống config để truyền tệp cấu hình đến trình kết nối. Bạn có thể đặt thuộc tính này bằng đối số -D khi khởi động trình kết nối. Ví dụ: lệnh sau đây khởi động trình kết nối bằng tệp cấu hình MyConfig.properties:

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

Nếu thiếu đối số này, SDK sẽ cố gắng truy cập vào tệp cấu hình mặc định có tên connector-config.properties.

Xác định chiến lược duyệt

Chức năng chính của trình kết nối nội dung là duyệt qua kho lưu trữ và lập chỉ mục dữ liệu của kho lưu trữ đó. Bạn phải triển khai chiến lược duyệt qua dựa trên kích thước và bố cục của dữ liệu trong kho lưu trữ. Bạn có thể thiết kế chiến lược của riêng mình hoặc chọn trong số các chiến lược sau được triển khai trong SDK:

Chiến lược truy cập toàn bộ

Chiến lược duyệt qua toàn bộ sẽ quét toàn bộ kho lưu trữ và lập chỉ mục mọi mục một cách mù quáng. Chiến lược này thường được dùng khi bạn có một kho lưu trữ nhỏ và có thể chi trả chi phí cho việc duyệt qua toàn bộ mỗi khi lập chỉ mục.

Chiến lược duyệt này phù hợp với các kho lưu trữ nhỏ chứa chủ yếu dữ liệu tĩnh, không phân cấp. Bạn cũng có thể sử dụng chiến lược duyệt này khi việc phát hiện thay đổi gặp khó khăn hoặc kho lưu trữ không hỗ trợ.

Chiến lược duyệt qua danh sách

Chiến lược duyệt qua danh sách sẽ quét toàn bộ kho lưu trữ, bao gồm cả tất cả các nút con, xác định trạng thái của từng mục. Sau đó, trình kết nối sẽ thực hiện một lượt truyền thứ hai và chỉ lập chỉ mục các mục mới hoặc đã được cập nhật kể từ lần lập chỉ mục gần đây nhất. Chiến lược này thường được dùng để thực hiện các lần cập nhật gia tăng cho một chỉ mục hiện có (thay vì phải thực hiện một lượt truy cập đầy đủ mỗi khi cập nhật chỉ mục).

Chiến lược duyệt này phù hợp khi việc phát hiện thay đổi gặp khó khăn hoặc kho lưu trữ không hỗ trợ, bạn có dữ liệu không phân cấp và bạn đang làm việc với các tập dữ liệu rất lớn.

Truy cập biểu đồ

Chiến lược duyệt qua biểu đồ sẽ quét toàn bộ nút mẹ để xác định trạng thái của từng mục. Sau đó, trình kết nối sẽ thực hiện một lượt thứ hai và chỉ lập chỉ mục các mục trong nút gốc là mới hoặc đã được cập nhật kể từ lần lập chỉ mục gần đây nhất. Cuối cùng, trình kết nối sẽ truyền mọi mã con rồi lập chỉ mục các mục trong các nút con mới hoặc đã được cập nhật. Trình kết nối tiếp tục đệ quy qua tất cả các nút con cho đến khi tất cả các mục được xử lý. Việc truy cập như vậy thường được dùng cho các kho lưu trữ phân cấp, trong đó việc liệt kê tất cả mã nhận dạng là không thực tế.

Chiến lược này phù hợp nếu bạn có dữ liệu phân cấp cần được thu thập dữ liệu, chẳng hạn như một loạt thư mục hoặc trang web.

Mỗi chiến lược duyệt này được triển khai bằng một lớp trình kết nối mẫu trong SDK. Mặc dù bạn có thể triển khai chiến lược duyệt của riêng mình, nhưng các mẫu này sẽ giúp đẩy nhanh quá trình phát triển trình kết nối. Để tạo một trình kết nối bằng mẫu, hãy chuyển đến phần tương ứng với chiến lược duyệt qua của bạn:

• Tạo trình kết nối xuyên suốt bằng lớp mẫu
• Tạo trình kết nối duyệt qua danh sách bằng cách sử dụng lớp mẫu
• Tạo trình kết nối duyệt qua biểu đồ bằng lớp mẫu

Tạo trình kết nối xuyên suốt bằng cách sử dụng lớp mẫu

Phần này của tài liệu đề cập đến các đoạn mã trong ví dụ FullTraversalSample.

Triển khai điểm truy cập của trình kết nối

Điểm truy cập vào một trình kết nối là phương thức main(). Nhiệm vụ chính của phương thức này là tạo một thực thể của lớp Application và gọi phương thức start() để chạy trình kết nối.

Trước khi gọi application.start(), hãy sử dụng lớp IndexingApplication.Builder để tạo bản sao mẫu FullTraversalConnector. FullTraversalConnector chấp nhận đối tượng Repository có các phương thức mà bạn triển khai. Đoạn mã sau đây cho thấy cách triển khai phương thức main():

/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Trong nền, SDK gọi phương thức initConfig() sau khi phương thức main() của trình kết nối gọi Application.build. Phương thức initConfig() thực hiện các nhiệm vụ sau:

1. Gọi phương thức Configuation.isInitialized() để đảm bảo rằng Configuration chưa được khởi chạy.
2. Khởi tạo đối tượng Configuration bằng các cặp khoá-giá trị do Google cung cấp. Mỗi cặp khoá-giá trị được lưu trữ trong một đối tượng ConfigValue trong đối tượng Configuration.

Triển khai giao diện Repository

Mục đích duy nhất của đối tượng Repository là thực hiện việc duyệt qua và lập chỉ mục các mục trong kho lưu trữ. Khi sử dụng mẫu, bạn chỉ cần ghi đè một số phương thức nhất định trong giao diện Repository để tạo trình kết nối nội dung. Các phương thức bạn ghi đè phụ thuộc vào mẫu và chiến lược duyệt qua mà bạn sử dụng. Đối với FullTraversalConnector, hãy ghi đè các phương thức sau:

• Phương thức init(). Để thực hiện bất kỳ hoạt động thiết lập và khởi chạy kho lưu trữ dữ liệu nào, hãy ghi đè phương thức init().

• Phương thức getAllDocs(). Để duyệt qua và lập chỉ mục tất cả các mục trong kho lưu trữ dữ liệu, hãy ghi đè phương thức getAllDocs(). Phương thức này được gọi một lần cho mỗi lần truy cập theo lịch (theo định nghĩa của cấu hình).

• (không bắt buộc) Phương thức getChanges(). Nếu kho lưu trữ của bạn hỗ trợ tính năng phát hiện thay đổi, hãy ghi đè phương thức getChanges(). Phương thức này được gọi một lần cho mỗi lần truy cập tăng dần theo lịch (do cấu hình của bạn xác định) để truy xuất các mục đã sửa đổi và lập chỉ mục các mục đó.

• (không bắt buộc) Phương thức close(). Nếu bạn cần dọn dẹp kho lưu trữ, hãy ghi đè phương thức close(). Phương thức này được gọi một lần trong quá trình tắt trình kết nối.

Mỗi phương thức của đối tượng Repository trả về một số loại đối tượng ApiOperation. Đối tượng ApiOperation thực hiện một hành động ở dạng một hoặc nhiều lệnh gọi IndexingService.indexItem() để thực hiện việc lập chỉ mục thực tế của kho lưu trữ.

Nhận tham số cấu hình tuỳ chỉnh

Trong quá trình xử lý cấu hình của trình kết nối, bạn sẽ cần lấy mọi tham số tuỳ chỉnh từ đối tượng Configuration. Tác vụ này thường được thực hiện trong phương thức init() của lớp Repository.

Lớp Configuration có một số phương thức để lấy các loại dữ liệu khác nhau từ một cấu hình. Mỗi phương thức trả về một đối tượng ConfigValue. Sau đó, bạn sẽ sử dụng phương thức get() của đối tượng ConfigValue để truy xuất giá trị thực tế. Đoạn mã sau đây, từ FullTraversalSample, cho biết cách truy xuất một giá trị số nguyên tuỳ chỉnh từ đối tượng Configuration:

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Để lấy và phân tích cú pháp một tham số chứa nhiều giá trị, hãy sử dụng một trong các trình phân tích cú pháp loại của lớp Configuration để phân tích cú pháp dữ liệu thành các phần riêng biệt. Đoạn mã sau đây, từ trình kết nối hướng dẫn sử dụng phương thức getMultiValue để lấy danh sách tên kho lưu trữ GitHub:

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Thực hiện một lượt truy cập đầy đủ

Ghi đè getAllDocs() để thực hiện một lượt truy cập đầy đủ và lập chỉ mục kho lưu trữ của bạn. Phương thức getAllDocs() chấp nhận một điểm kiểm tra. Điểm kiểm tra được dùng để tiếp tục lập chỉ mục tại một mục cụ thể nếu quy trình bị gián đoạn. Đối với mỗi mục trong kho lưu trữ, hãy thực hiện các bước sau trong phương thức getAllDocs():

1. Đặt quyền.
2. Đặt siêu dữ liệu cho mục mà bạn đang lập chỉ mục.
3. Kết hợp siêu dữ liệu và mục vào một RepositoryDoc có thể lập chỉ mục.
4. Đóng gói từng mục có thể lập chỉ mục vào một trình lặp do phương thức getAllDocs() trả về. Xin lưu ý rằng getAllDocs() thực sự trả về một CheckpointCloseableIterable, là một vòng lặp của các đối tượng ApiOperation, mỗi đối tượng đại diện cho một yêu cầu API được thực hiện trên RepositoryDoc, chẳng hạn như lập chỉ mục đối tượng đó.

Nếu tập hợp các mục quá lớn để xử lý trong một lệnh gọi, hãy thêm một điểm kiểm tra và đặt hasMore(true) để cho biết có nhiều mục hơn để lập chỉ mục.

Đặt quyền cho một mục

Kho lưu trữ của bạn sử dụng Danh sách kiểm soát quyền truy cập (ACL) để xác định những người dùng hoặc nhóm có quyền truy cập vào một mục. ACL là danh sách mã nhận dạng cho các nhóm hoặc người dùng có thể truy cập vào mục.

Bạn phải sao chép ACL mà kho lưu trữ của bạn sử dụng để đảm bảo rằng chỉ những người dùng có quyền truy cập vào một mục mới có thể xem mục đó trong kết quả tìm kiếm. Bạn phải thêm ACL cho một mục khi lập chỉ mục mục đó để Google Cloud Search có thông tin cần thiết nhằm cung cấp đúng cấp truy cập vào mục đó.

SDK Trình kết nối nội dung cung cấp một bộ các lớp và phương thức ACL phong phú để mô hình hoá ACL của hầu hết các kho lưu trữ. Bạn phải phân tích ACL cho từng mục trong kho lưu trữ và tạo ACL tương ứng cho Google Cloud Search khi bạn lập chỉ mục một mục. Nếu ACL của kho lưu trữ sử dụng các khái niệm như kế thừa ACL, thì việc lập mô hình ACL đó có thể sẽ gặp khó khăn. Để biết thêm thông tin về ACL của Google Cloud Search, hãy tham khảo bài viết ACL của Google Cloud Search.

Lưu ý: API Lập chỉ mục Cloud Search hỗ trợ các ACL một miền. API này không hỗ trợ các ACL trên nhiều miền. Sử dụng lớp Acl.Builder để đặt quyền truy cập vào từng mục bằng ACL. Đoạn mã sau đây, lấy từ mẫu duyệt qua đầy đủ, cho phép tất cả người dùng hoặc "chủ sở hữu" (getCustomerPrincipal()) trở thành "người đọc" của tất cả các mục (.setReaders()) khi thực hiện tìm kiếm.

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Bạn cần hiểu về ACL để mô hình hoá ACL cho kho lưu trữ đúng cách. Ví dụ: bạn có thể đang lập chỉ mục các tệp trong một hệ thống tệp sử dụng một số loại mô hình kế thừa, trong đó các thư mục con kế thừa quyền từ thư mục mẹ. Để lập mô hình tính năng kế thừa ACL, bạn cần có thêm thông tin được đề cập trong phần ACL của Google Cloud Search

Đặt siêu dữ liệu cho một mục

Siêu dữ liệu được lưu trữ trong đối tượng Item. Để tạo Item, bạn cần có tối thiểu một mã nhận dạng chuỗi duy nhất, loại mục, ACL, URL và phiên bản cho mục đó. Đoạn mã sau đây cho biết cách tạo Item bằng lớp trình trợ giúp IndexingItemBuilder.

// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Tạo mục có thể lập chỉ mục

Sau khi đặt siêu dữ liệu cho mục, bạn có thể tạo mục thực tế có thể lập chỉ mục bằng cách sử dụng lớp RepositoryDoc.Builder. Ví dụ sau đây cho thấy cách tạo một mục có thể lập chỉ mục.

// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc là một loại ApiOperation thực hiện yêu cầu IndexingService.indexItem() thực tế.

Bạn cũng có thể sử dụng phương thức setRequestMode() của lớp RepositoryDoc.Builder để xác định yêu cầu lập chỉ mục là ASYNCHRONOUS hoặc SYNCHRONOUS:

ASYNCHRONOUS

Chế độ không đồng bộ dẫn đến độ trễ từ việc lập chỉ mục đến phân phát lâu hơn và đáp ứng hạn mức thông lượng lớn cho các yêu cầu lập chỉ mục. Bạn nên sử dụng chế độ không đồng bộ để lập chỉ mục ban đầu (lấp đầy) toàn bộ kho lưu trữ.

SYNCHRONOUS

Chế độ đồng bộ giúp giảm độ trễ từ việc lập chỉ mục đến phân phát và đáp ứng hạn mức thông lượng bị giới hạn. Bạn nên sử dụng chế độ đồng bộ để lập chỉ mục nội dung cập nhật và thay đổi đối với kho lưu trữ. Nếu bạn không chỉ định, chế độ yêu cầu sẽ mặc định là SYNCHRONOUS.

Đóng gói từng mục có thể lập chỉ mục trong một trình lặp

Phương thức getAllDocs() trả về một Iterator, cụ thể là một CheckpointCloseableIterable của các đối tượng RepositoryDoc. Bạn có thể sử dụng lớp CheckpointClosableIterableImpl.Builder để tạo và trả về một trình lặp. Đoạn mã sau đây cho biết cách tạo và trả về một trình lặp.

CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

SDK thực thi từng lệnh gọi lập chỉ mục được bao bọc trong trình lặp.

Các bước tiếp theo

Sau đây là một số bước tiếp theo mà bạn có thể thực hiện:

• (không bắt buộc) Nếu tốc độ lập chỉ mục có vẻ chậm, hãy tham khảo phần Tăng tốc độ lập chỉ mục cho FullTraversalConnector.
• (không bắt buộc) Triển khai phương thức close() để giải phóng mọi tài nguyên trước khi tắt.
• (không bắt buộc) Tạo trình kết nối danh tính bằng SDK Trình kết nối nội dung.

Tạo trình kết nối duyệt qua danh sách bằng lớp mẫu

Hàng đợi lập chỉ mục Cloud Search được dùng để lưu trữ mã nhận dạng và giá trị băm không bắt buộc cho từng mục trong kho lưu trữ. Trình kết nối duyệt qua danh sách sẽ đẩy mã mục vào Hàng đợi lập chỉ mục của Google Cloud Search và truy xuất từng mã mục một để lập chỉ mục. Google Cloud Search duy trì hàng đợi và so sánh nội dung hàng đợi để xác định trạng thái của mục, chẳng hạn như liệu một mục có đã bị xoá khỏi kho lưu trữ hay không. Để biết thêm thông tin về Hàng đợi lập chỉ mục của Cloud Search, hãy tham khảo bài viết Hàng đợi lập chỉ mục của Cloud Search.

Phần này của tài liệu đề cập đến các đoạn mã trong ví dụ ListTraversalSample.

Triển khai điểm truy cập của trình kết nối

Điểm truy cập vào một trình kết nối là phương thức main(). Nhiệm vụ chính của phương thức này là tạo một thực thể của lớp Application và gọi phương thức start() để chạy trình kết nối.

Trước khi gọi application.start(), hãy sử dụng lớp IndexingApplication.Builder để tạo bản sao mẫu ListingConnector. ListingConnector chấp nhận đối tượng Repository có các phương thức mà bạn triển khai. Đoạn mã sau đây cho biết cách tạo bản sao của ListingConnector và Repository liên kết với ListingConnector:

/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Trong nền, SDK gọi phương thức initConfig() sau khi phương thức main() của trình kết nối gọi Application.build. Phương thức initConfig():

1. Gọi phương thức Configuation.isInitialized() để đảm bảo rằng Configuration chưa được khởi chạy.
2. Khởi tạo đối tượng Configuration bằng các cặp khoá-giá trị do Google cung cấp. Mỗi cặp khoá-giá trị được lưu trữ trong một đối tượng ConfigValue trong đối tượng Configuration.

Triển khai giao diện Repository

Mục đích duy nhất của đối tượng Repository là thực hiện việc duyệt qua và lập chỉ mục các mục trong kho lưu trữ. Khi sử dụng mẫu, bạn chỉ cần ghi đè một số phương thức nhất định trong giao diện Repository để tạo trình kết nối nội dung. Các phương thức bạn ghi đè phụ thuộc vào mẫu và chiến lược duyệt qua mà bạn sử dụng. Đối với ListingConnector, hãy ghi đè các phương thức sau:

• Phương thức init(). Để thực hiện bất kỳ hoạt động thiết lập và khởi chạy kho lưu trữ dữ liệu nào, hãy ghi đè phương thức init().

• Phương thức getIds(). Để truy xuất mã nhận dạng và giá trị băm cho tất cả bản ghi trong kho lưu trữ, hãy ghi đè phương thức getIds().

• Phương thức getDoc(). Để thêm, cập nhật, sửa đổi hoặc xoá các mục khỏi chỉ mục, hãy ghi đè phương thức getDoc().

• (không bắt buộc) Phương thức getChanges(). Nếu kho lưu trữ của bạn hỗ trợ tính năng phát hiện thay đổi, hãy ghi đè phương thức getChanges(). Phương thức này được gọi một lần cho mỗi lần truy cập tăng dần theo lịch (do cấu hình của bạn xác định) để truy xuất các mục đã sửa đổi và lập chỉ mục các mục đó.

• (không bắt buộc) Phương thức close(). Nếu bạn cần dọn dẹp kho lưu trữ, hãy ghi đè phương thức close(). Phương thức này được gọi một lần trong quá trình tắt trình kết nối.

Mỗi phương thức của đối tượng Repository trả về một số loại đối tượng ApiOperation. Đối tượng ApiOperation thực hiện một hành động ở dạng một hoặc nhiều lệnh gọi IndexingService.indexItem() để thực hiện việc lập chỉ mục thực tế của kho lưu trữ.

Nhận tham số cấu hình tuỳ chỉnh

Trong quá trình xử lý cấu hình của trình kết nối, bạn sẽ cần lấy mọi tham số tuỳ chỉnh từ đối tượng Configuration. Tác vụ này thường được thực hiện trong phương thức init() của lớp Repository.

Lớp Configuration có một số phương thức để lấy các loại dữ liệu khác nhau từ một cấu hình. Mỗi phương thức trả về một đối tượng ConfigValue. Sau đó, bạn sẽ sử dụng phương thức get() của đối tượng ConfigValue để truy xuất giá trị thực tế. Đoạn mã sau đây, từ FullTraversalSample, cho biết cách truy xuất một giá trị số nguyên tuỳ chỉnh từ đối tượng Configuration:

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Để lấy và phân tích cú pháp một tham số chứa nhiều giá trị, hãy sử dụng một trong các trình phân tích cú pháp loại của lớp Configuration để phân tích cú pháp dữ liệu thành các phần riêng biệt. Đoạn mã sau đây, từ trình kết nối hướng dẫn sử dụng phương thức getMultiValue để lấy danh sách tên kho lưu trữ GitHub:

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Thực hiện thao tác duyệt qua danh sách

Ghi đè phương thức getIds() để truy xuất mã nhận dạng và giá trị băm cho tất cả bản ghi trong kho lưu trữ. Phương thức getIds() chấp nhận một điểm kiểm tra. Điểm kiểm tra được dùng để tiếp tục lập chỉ mục tại một mục cụ thể nếu quá trình này bị gián đoạn.

Tiếp theo, ghi đè phương thức getDoc() để xử lý từng mục trong Hàng đợi lập chỉ mục của Cloud Search.

Đẩy mã mặt hàng và giá trị băm

Ghi đè getIds() để tìm nạp mã nhận dạng mặt hàng và giá trị băm nội dung liên quan của các mã nhận dạng đó từ kho lưu trữ. Sau đó, các cặp giá trị hàm băm và mã nhận dạng được đóng gói vào yêu cầu thao tác đẩy vào Hàng đợi lập chỉ mục của Cloud Search. Mã gốc hoặc mã mẹ thường được đẩy trước, theo sau là mã con cho đến khi toàn bộ hệ phân cấp của các mục được xử lý.

Phương thức getIds() chấp nhận một điểm kiểm tra đại diện cho mục cuối cùng cần được lập chỉ mục. Bạn có thể sử dụng điểm kiểm tra để tiếp tục lập chỉ mục tại một mục cụ thể nếu quy trình bị gián đoạn. Đối với mỗi mục trong kho lưu trữ, hãy thực hiện các bước sau trong phương thức getIds():

• Lấy từng mã mặt hàng và giá trị băm liên kết từ kho lưu trữ.
• Đóng gói từng cặp mã nhận dạng và giá trị băm vào một PushItems.
• Kết hợp từng PushItems vào một trình lặp do phương thức getIds() trả về. Xin lưu ý rằng getIds() thực sự trả về một CheckpointCloseableIterable, là một vòng lặp của các đối tượng ApiOperation, mỗi đối tượng đại diện cho một yêu cầu API được thực hiện trên RepositoryDoc, chẳng hạn như đẩy các mục vào hàng đợi.

Đoạn mã sau đây cho biết cách lấy từng mã mặt hàng và giá trị băm rồi chèn các mã đó vào PushItems. PushItems là một yêu cầu ApiOperation để đẩy một mục vào hàng đợi lập chỉ mục của Cloud Search.

PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

Đoạn mã sau đây cho biết cách sử dụng lớp PushItems.Builder để đóng gói mã nhận dạng và giá trị băm vào một ApiOperation đẩy duy nhất.

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;

Các mục sẽ được đẩy vào Hàng đợi lập chỉ mục của Cloud Search để xử lý thêm.

Truy xuất và xử lý từng mục

Ghi đè getDoc() để xử lý từng mục trong Hàng đợi lập chỉ mục Cloud Search. Một mục có thể là mới, đã sửa đổi, không thay đổi hoặc không còn tồn tại trong kho lưu trữ nguồn. Truy xuất và lập chỉ mục từng mục mới hoặc đã sửa đổi. Xoá các mục không còn tồn tại trong kho lưu trữ nguồn khỏi chỉ mục.

Phương thức getDoc() chấp nhận một Mục từ Hàng đợi lập chỉ mục của Google Cloud Search. Đối với mỗi mục trong hàng đợi, hãy thực hiện các bước sau trong phương thức getDoc():

1. Kiểm tra xem mã của mục trong hàng đợi lập chỉ mục của Cloud Search có tồn tại trong kho lưu trữ hay không. Nếu không, hãy xoá mục đó khỏi chỉ mục.

2. Điều tra chỉ mục để biết trạng thái của mục và nếu một mục không thay đổi (ACCEPTED), thì đừng làm gì cả.

3. Chỉ mục đã thay đổi hoặc mục mới:

   1. Thiết lập quyền.
   2. Đặt siêu dữ liệu cho mục mà bạn đang lập chỉ mục.
   3. Kết hợp siêu dữ liệu và mục vào một RepositoryDoc có thể lập chỉ mục.
   4. Trả về RepositoryDoc.

Lưu ý: Mẫu ListingConnector không hỗ trợ việc trả về null trên phương thức getDoc(). Trả về kết quả null trong NullPointerException.

Xử lý các mục đã xoá

Đoạn mã sau đây cho biết cách xác định xem một mục có tồn tại trong kho lưu trữ hay không và nếu không, hãy xoá mục đó.

String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}

Xin lưu ý rằng documents là một cấu trúc dữ liệu đại diện cho kho lưu trữ. Nếu không tìm thấy documentID trong documents, hãy trả về APIOperations.deleteItem(resourceName) để xoá mục đó khỏi chỉ mục.

Xử lý các mục không thay đổi

Đoạn mã sau đây cho biết cách thăm dò trạng thái mục trong Hàng đợi lập chỉ mục của Tìm kiếm trên đám mây và xử lý một mục không thay đổi.

String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

Để xác định xem mục đó có bị sửa đổi hay không, hãy kiểm tra trạng thái của mục đó cũng như siêu dữ liệu khác có thể cho biết có thay đổi hay không. Trong ví dụ này, hàm băm siêu dữ liệu được dùng để xác định xem mục đã được thay đổi hay chưa.

/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}

Đặt quyền cho một mục

Kho lưu trữ của bạn sử dụng Danh sách kiểm soát quyền truy cập (ACL) để xác định những người dùng hoặc nhóm có quyền truy cập vào một mục. ACL là danh sách mã nhận dạng cho các nhóm hoặc người dùng có thể truy cập vào mục.

Bạn phải sao chép ACL mà kho lưu trữ của bạn sử dụng để đảm bảo rằng chỉ những người dùng có quyền truy cập vào một mục mới có thể xem mục đó trong kết quả tìm kiếm. Bạn phải thêm ACL cho một mục khi lập chỉ mục mục đó để Google Cloud Search có thông tin cần thiết nhằm cung cấp đúng cấp truy cập vào mục đó.

SDK Trình kết nối nội dung cung cấp một bộ các lớp và phương thức ACL phong phú để mô hình hoá ACL của hầu hết các kho lưu trữ. Bạn phải phân tích ACL cho từng mục trong kho lưu trữ và tạo ACL tương ứng cho Google Cloud Search khi bạn lập chỉ mục một mục. Nếu ACL của kho lưu trữ sử dụng các khái niệm như kế thừa ACL, thì việc lập mô hình ACL đó có thể sẽ gặp khó khăn. Để biết thêm thông tin về ACL của Google Cloud Search, hãy tham khảo bài viết ACL của Google Cloud Search.

Lưu ý: API Lập chỉ mục Cloud Search hỗ trợ các ACL một miền. API này không hỗ trợ các ACL trên nhiều miền. Sử dụng lớp Acl.Builder để đặt quyền truy cập vào từng mục bằng ACL. Đoạn mã sau đây, lấy từ mẫu duyệt qua đầy đủ, cho phép tất cả người dùng hoặc "chủ sở hữu" (getCustomerPrincipal()) trở thành "người đọc" của tất cả các mục (.setReaders()) khi thực hiện tìm kiếm.

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Bạn cần hiểu về ACL để mô hình hoá ACL cho kho lưu trữ đúng cách. Ví dụ: bạn có thể đang lập chỉ mục các tệp trong một hệ thống tệp sử dụng một số loại mô hình kế thừa, trong đó các thư mục con kế thừa quyền từ thư mục mẹ. Để lập mô hình tính năng kế thừa ACL, bạn cần có thêm thông tin được đề cập trong phần ACL của Google Cloud Search

Đặt siêu dữ liệu cho một mục

Siêu dữ liệu được lưu trữ trong đối tượng Item. Để tạo Item, bạn cần có tối thiểu một mã nhận dạng chuỗi duy nhất, loại mục, ACL, URL và phiên bản cho mục đó. Đoạn mã sau đây cho biết cách tạo Item bằng lớp trình trợ giúp IndexingItemBuilder.

// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();

Tạo mục có thể lập chỉ mục

Sau khi đặt siêu dữ liệu cho mục, bạn có thể tạo mục có thể lập chỉ mục thực tế bằng cách sử dụng RepositoryDoc.Builder. Ví dụ sau đây cho thấy cách tạo một mục có thể lập chỉ mục.

// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc là một loại ApiOperation thực hiện yêu cầu IndexingService.indexItem() thực tế.

Bạn cũng có thể sử dụng phương thức setRequestMode() của lớp RepositoryDoc.Builder để xác định yêu cầu lập chỉ mục là ASYNCHRONOUS hoặc SYNCHRONOUS:

ASYNCHRONOUS

Chế độ không đồng bộ dẫn đến độ trễ từ việc lập chỉ mục đến phân phát lâu hơn và đáp ứng hạn mức thông lượng lớn cho các yêu cầu lập chỉ mục. Bạn nên sử dụng chế độ không đồng bộ để lập chỉ mục ban đầu (lấp đầy) toàn bộ kho lưu trữ.

SYNCHRONOUS

Chế độ đồng bộ giúp giảm độ trễ từ việc lập chỉ mục đến phân phát và đáp ứng hạn mức thông lượng bị giới hạn. Bạn nên sử dụng chế độ đồng bộ để lập chỉ mục nội dung cập nhật và thay đổi đối với kho lưu trữ. Nếu bạn không chỉ định, chế độ yêu cầu sẽ mặc định là SYNCHRONOUS.

Các bước tiếp theo

Sau đây là một số bước tiếp theo mà bạn có thể thực hiện:

• (không bắt buộc) Triển khai phương thức close() để giải phóng mọi tài nguyên trước khi tắt.
• (không bắt buộc) Tạo trình kết nối danh tính bằng SDK Trình kết nối nội dung.

Tạo trình kết nối duyệt qua biểu đồ bằng lớp mẫu

Hàng đợi lập chỉ mục Cloud Search dùng để lưu trữ mã nhận dạng và giá trị băm không bắt buộc cho từng mục trong kho lưu trữ. Trình kết nối duyệt qua biểu đồ đẩy mã mục vào hàng đợi lập chỉ mục của Google Cloud Search và truy xuất từng mã để lập chỉ mục. Google Cloud Search duy trì hàng đợi và so sánh nội dung hàng đợi để xác định trạng thái mục, chẳng hạn như liệu một mục đã bị xoá khỏi kho lưu trữ hay chưa. Để biết thêm thông tin về Hàng đợi lập chỉ mục của Cloud Search, hãy tham khảo bài viết Hàng đợi lập chỉ mục của Google Cloud Search.

Trong quá trình lập chỉ mục, nội dung mục được tìm nạp từ kho lưu trữ dữ liệu và mọi mã mục con sẽ được đẩy vào hàng đợi. Trình kết nối tiếp tục xử lý đệ quy các mã nhận dạng mẹ và con cho đến khi xử lý xong tất cả các mục.

Phần này của tài liệu đề cập đến các đoạn mã trong ví dụ GraphTraversalSample.

Triển khai điểm truy cập của trình kết nối

Điểm truy cập vào một trình kết nối là phương thức main(). Nhiệm vụ chính của phương thức này là tạo một thực thể của lớp Application và gọi phương thức start() để chạy trình kết nối.

Trước khi gọi application.start(), hãy sử dụng lớp IndexingApplication.Builder để tạo bản sao mẫu ListingConnector. ListingConnector chấp nhận đối tượng Repository có các phương thức mà bạn triển khai.

Đoạn mã sau đây cho biết cách tạo bản sao của ListingConnector và Repository liên kết với ListingConnector:

/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Trong nền, SDK gọi phương thức initConfig() sau khi phương thức main() của trình kết nối gọi Application.build. Phương thức initConfig():

1. Gọi phương thức Configuation.isInitialized() để đảm bảo rằng Configuration chưa được khởi chạy.
2. Khởi tạo đối tượng Configuration bằng các cặp khoá-giá trị do Google cung cấp. Mỗi cặp khoá-giá trị được lưu trữ trong một đối tượng ConfigValue trong đối tượng Configuration.

Triển khai giao diện Repository

Mục đích duy nhất của đối tượng Repository là thực hiện việc duyệt qua và lập chỉ mục các mục trong kho lưu trữ. Khi sử dụng mẫu, bạn chỉ cần ghi đè một số phương thức nhất định trong giao diện Repository để tạo trình kết nối nội dung. Các phương thức bạn ghi đè phụ thuộc vào mẫu và chiến lược duyệt qua mà bạn sử dụng. Đối với ListingConnector, bạn ghi đè các phương thức sau:

• Phương thức init(). Để thực hiện bất kỳ hoạt động thiết lập và khởi chạy kho lưu trữ dữ liệu nào, hãy ghi đè phương thức init().

• Phương thức getIds(). Để truy xuất mã nhận dạng và giá trị băm cho tất cả bản ghi trong kho lưu trữ, hãy ghi đè phương thức getIds().

• Phương thức getDoc(). Để thêm, cập nhật, sửa đổi hoặc xoá các mục khỏi chỉ mục, hãy ghi đè phương thức getDoc().

• (không bắt buộc) Phương thức getChanges(). Nếu kho lưu trữ của bạn hỗ trợ tính năng phát hiện thay đổi, hãy ghi đè phương thức getChanges(). Phương thức này được gọi một lần cho mỗi lần truy cập tăng dần theo lịch (do cấu hình của bạn xác định) để truy xuất các mục đã sửa đổi và lập chỉ mục các mục đó.

• (không bắt buộc) Phương thức close(). Nếu bạn cần dọn dẹp kho lưu trữ, hãy ghi đè phương thức close(). Phương thức này được gọi một lần trong quá trình tắt trình kết nối.

Mỗi phương thức của đối tượng Repository trả về một số loại đối tượng ApiOperation. Đối tượng ApiOperation thực hiện một hành động ở dạng một hoặc nhiều lệnh gọi IndexingService.indexItem() để thực hiện việc lập chỉ mục thực tế của kho lưu trữ.

Nhận tham số cấu hình tuỳ chỉnh

Trong quá trình xử lý cấu hình của trình kết nối, bạn sẽ cần lấy mọi tham số tuỳ chỉnh từ đối tượng Configuration. Tác vụ này thường được thực hiện trong phương thức init() của lớp Repository.

Lớp Configuration có một số phương thức để lấy các loại dữ liệu khác nhau từ một cấu hình. Mỗi phương thức trả về một đối tượng ConfigValue. Sau đó, bạn sẽ sử dụng phương thức get() của đối tượng ConfigValue để truy xuất giá trị thực tế. Đoạn mã sau đây, từ FullTraversalSample, cho biết cách truy xuất một giá trị số nguyên tuỳ chỉnh từ đối tượng Configuration:

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Để lấy và phân tích cú pháp một tham số chứa nhiều giá trị, hãy sử dụng một trong các trình phân tích cú pháp loại của lớp Configuration để phân tích cú pháp dữ liệu thành các phần riêng biệt. Đoạn mã sau đây, từ trình kết nối hướng dẫn sử dụng phương thức getMultiValue để lấy danh sách tên kho lưu trữ GitHub:

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Thực hiện việc duyệt qua biểu đồ

Ghi đè phương thức getIds() để truy xuất mã nhận dạng và giá trị băm cho tất cả bản ghi trong kho lưu trữ. Phương thức getIds() chấp nhận một điểm kiểm tra. Điểm kiểm tra được dùng để tiếp tục lập chỉ mục tại một mục cụ thể nếu quá trình này bị gián đoạn.

Tiếp theo, ghi đè phương thức getDoc() để xử lý từng mục trong Hàng đợi lập chỉ mục của Cloud Search.

Đẩy mã mặt hàng và giá trị băm

Ghi đè getIds() để tìm nạp mã nhận dạng mặt hàng và giá trị băm nội dung liên quan của các mã nhận dạng đó từ kho lưu trữ. Sau đó, các cặp giá trị hàm băm và mã nhận dạng được đóng gói vào yêu cầu thao tác đẩy vào Hàng đợi lập chỉ mục của Cloud Search. Mã gốc hoặc mã mẹ thường được đẩy trước, theo sau là mã con cho đến khi toàn bộ hệ phân cấp của các mục được xử lý.

Phương thức getIds() chấp nhận một điểm kiểm tra đại diện cho mục cuối cùng cần được lập chỉ mục. Bạn có thể sử dụng điểm kiểm tra để tiếp tục lập chỉ mục tại một mục cụ thể nếu quy trình bị gián đoạn. Đối với mỗi mục trong kho lưu trữ, hãy thực hiện các bước sau trong phương thức getIds():

• Lấy từng mã mặt hàng và giá trị băm liên kết từ kho lưu trữ.
• Đóng gói từng cặp mã nhận dạng và giá trị băm vào một PushItems.
• Kết hợp từng PushItems vào một trình lặp do phương thức getIds() trả về. Xin lưu ý rằng getIds() thực sự trả về một CheckpointCloseableIterable, là một vòng lặp của các đối tượng ApiOperation, mỗi đối tượng đại diện cho một yêu cầu API được thực hiện trên RepositoryDoc, chẳng hạn như đẩy các mục vào hàng đợi.

Đoạn mã sau đây cho biết cách lấy từng mã mặt hàng và giá trị băm rồi chèn các mã đó vào PushItems. PushItems là một yêu cầu ApiOperation để đẩy một mục vào Hàng đợi lập chỉ mục của Cloud Search.

PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);

Đoạn mã sau đây cho biết cách sử dụng lớp PushItems.Builder để đóng gói mã nhận dạng và giá trị băm vào một lệnh đẩy ApiOperation.

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();

Các mục sẽ được đẩy vào Hàng đợi lập chỉ mục của Cloud Search để xử lý thêm.

Truy xuất và xử lý từng mục

Ghi đè getDoc() để xử lý từng mục trong Hàng đợi lập chỉ mục Cloud Search. Một mục có thể là mới, đã sửa đổi, không thay đổi hoặc không còn tồn tại trong kho lưu trữ nguồn. Truy xuất và lập chỉ mục từng mục mới hoặc đã sửa đổi. Xoá các mục không còn tồn tại trong kho lưu trữ nguồn khỏi chỉ mục.

Phương thức getDoc() chấp nhận một Mục từ Hàng đợi lập chỉ mục của Cloud Search. Đối với mỗi mục trong hàng đợi, hãy thực hiện các bước sau trong phương thức getDoc():

1. Kiểm tra xem mã của mục trong hàng đợi lập chỉ mục của Cloud Search có tồn tại trong kho lưu trữ hay không. Nếu không, hãy xoá mục đó khỏi chỉ mục. Nếu mặt hàng đó tồn tại, hãy tiếp tục với bước tiếp theo.

2. Chỉ mục đã thay đổi hoặc mục mới:

   1. Thiết lập quyền.
   2. Đặt siêu dữ liệu cho mục mà bạn đang lập chỉ mục.
   3. Kết hợp siêu dữ liệu và mục vào một RepositoryDoc có thể lập chỉ mục.
   4. Đặt mã nhận dạng con trong Hàng đợi lập chỉ mục Cloud Search để tiếp tục xử lý.
   5. Trả về RepositoryDoc.

Xử lý các mục đã xoá

Đoạn mã sau đây cho biết cách xác định xem một mục có tồn tại trong chỉ mục hay không và nếu không, hãy xoá mục đó.

String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);

Đặt quyền cho một mục

Kho lưu trữ của bạn sử dụng Danh sách kiểm soát quyền truy cập (ACL) để xác định những người dùng hoặc nhóm có quyền truy cập vào một mục. ACL là danh sách mã nhận dạng cho các nhóm hoặc người dùng có thể truy cập vào mục.

Bạn phải sao chép ACL mà kho lưu trữ của bạn sử dụng để đảm bảo rằng chỉ những người dùng có quyền truy cập vào một mục mới có thể xem mục đó trong kết quả tìm kiếm. Bạn phải thêm ACL cho một mục khi lập chỉ mục mục đó để Google Cloud Search có thông tin cần thiết nhằm cung cấp đúng cấp truy cập vào mục đó.

SDK Trình kết nối nội dung cung cấp một bộ các lớp và phương thức ACL phong phú để mô hình hoá ACL của hầu hết các kho lưu trữ. Bạn phải phân tích ACL cho từng mục trong kho lưu trữ và tạo ACL tương ứng cho Google Cloud Search khi bạn lập chỉ mục một mục. Nếu ACL của kho lưu trữ sử dụng các khái niệm như kế thừa ACL, thì việc lập mô hình ACL đó có thể sẽ gặp khó khăn. Để biết thêm thông tin về ACL của Google Cloud Search, hãy tham khảo bài viết ACL của Google Cloud Search.

Lưu ý: API Lập chỉ mục Cloud Search hỗ trợ các ACL một miền. API này không hỗ trợ các ACL trên nhiều miền. Sử dụng lớp Acl.Builder để đặt quyền truy cập vào từng mục bằng ACL. Đoạn mã sau đây, lấy từ mẫu duyệt qua đầy đủ, cho phép tất cả người dùng hoặc "chủ sở hữu" (getCustomerPrincipal()) trở thành "người đọc" của tất cả các mục (.setReaders()) khi thực hiện tìm kiếm.

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Bạn cần hiểu về ACL để mô hình hoá ACL cho kho lưu trữ đúng cách. Ví dụ: bạn có thể đang lập chỉ mục các tệp trong một hệ thống tệp sử dụng một số loại mô hình kế thừa, trong đó các thư mục con kế thừa quyền từ thư mục mẹ. Để lập mô hình tính năng kế thừa ACL, bạn cần có thêm thông tin được đề cập trong phần ACL của Google Cloud Search

Đặt siêu dữ liệu cho một mục

Siêu dữ liệu được lưu trữ trong đối tượng Item. Để tạo Item, bạn cần có tối thiểu một mã nhận dạng chuỗi duy nhất, loại mục, ACL, URL và phiên bản cho mục đó. Đoạn mã sau đây cho biết cách tạo Item bằng lớp trình trợ giúp IndexingItemBuilder.

// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Tạo mục có thể lập chỉ mục

Sau khi đặt siêu dữ liệu cho mục, bạn có thể tạo mục có thể lập chỉ mục thực tế bằng cách sử dụng RepositoryDoc.Builder. Ví dụ sau đây cho thấy cách tạo một mục có thể lập chỉ mục.

// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);

RepositoryDoc là một loại ApiOperation thực hiện yêu cầu IndexingService.indexItem() thực tế.

Bạn cũng có thể sử dụng phương thức setRequestMode() của lớp RepositoryDoc.Builder để xác định yêu cầu lập chỉ mục là ASYNCHRONOUS hoặc SYNCHRONOUS:

ASYNCHRONOUS

Chế độ không đồng bộ dẫn đến độ trễ từ việc lập chỉ mục đến phân phát lâu hơn và đáp ứng hạn mức thông lượng lớn cho các yêu cầu lập chỉ mục. Bạn nên sử dụng chế độ không đồng bộ để lập chỉ mục ban đầu (lấp đầy) toàn bộ kho lưu trữ.

SYNCHRONOUS

Chế độ đồng bộ giúp giảm độ trễ từ việc lập chỉ mục đến phân phát và đáp ứng hạn mức thông lượng bị giới hạn. Bạn nên sử dụng chế độ đồng bộ để lập chỉ mục nội dung cập nhật và thay đổi đối với kho lưu trữ. Nếu bạn không chỉ định, chế độ yêu cầu sẽ mặc định là SYNCHRONOUS.

Đặt mã nhận dạng con trong hàng đợi lập chỉ mục Cloud Search

Đoạn mã sau đây cho biết cách đưa mã nhận dạng con, cho mục mẹ đang xử lý, vào hàng đợi để xử lý. Các mã nhận dạng này được xử lý sau khi mục mẹ được lập chỉ mục.

// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

Các bước tiếp theo

Sau đây là một số bước tiếp theo mà bạn có thể thực hiện:

• (không bắt buộc) Triển khai phương thức close() để giải phóng mọi tài nguyên trước khi tắt.
• (không bắt buộc) Tạo trình kết nối danh tính bằng SDK Trình kết nối danh tính.

Tạo trình kết nối nội dung bằng API REST

Các phần sau đây giải thích cách tạo trình kết nối nội dung bằng API REST.

Xác định chiến lược duyệt

Chức năng chính của trình kết nối nội dung là duyệt qua kho lưu trữ và lập chỉ mục dữ liệu của kho lưu trữ đó. Bạn phải triển khai chiến lược duyệt qua dựa trên kích thước và bố cục của dữ liệu trong kho lưu trữ. Sau đây là 3 chiến lược duyệt qua phổ biến:

Chiến lược truy cập toàn bộ

Chiến lược duyệt qua toàn bộ sẽ quét toàn bộ kho lưu trữ và lập chỉ mục mọi mục một cách mù quáng. Chiến lược này thường được dùng khi bạn có một kho lưu trữ nhỏ và có thể chi trả chi phí cho việc duyệt qua toàn bộ mỗi khi lập chỉ mục.

Chiến lược duyệt này phù hợp với các kho lưu trữ nhỏ chứa chủ yếu dữ liệu tĩnh, không phân cấp. Bạn cũng có thể sử dụng chiến lược duyệt này khi việc phát hiện thay đổi gặp khó khăn hoặc kho lưu trữ không hỗ trợ.

Chiến lược duyệt qua danh sách

Chiến lược duyệt qua danh sách sẽ quét toàn bộ kho lưu trữ, bao gồm cả tất cả các nút con, xác định trạng thái của từng mục. Sau đó, trình kết nối sẽ thực hiện một lượt truyền thứ hai và chỉ lập chỉ mục các mục mới hoặc đã được cập nhật kể từ lần lập chỉ mục gần đây nhất. Chiến lược này thường được dùng để thực hiện các lần cập nhật gia tăng cho một chỉ mục hiện có (thay vì phải thực hiện một lượt truy cập đầy đủ mỗi khi cập nhật chỉ mục).

Chiến lược duyệt này phù hợp khi việc phát hiện thay đổi gặp khó khăn hoặc kho lưu trữ không hỗ trợ, bạn có dữ liệu không phân cấp và bạn đang làm việc với các tập dữ liệu rất lớn.

Truy cập biểu đồ

Chiến lược duyệt qua biểu đồ sẽ quét toàn bộ nút mẹ để xác định trạng thái của từng mục. Sau đó, trình kết nối sẽ thực hiện một lượt thứ hai và chỉ lập chỉ mục các mục trong nút gốc là mới hoặc đã được cập nhật kể từ lần lập chỉ mục gần đây nhất. Cuối cùng, trình kết nối sẽ truyền mọi mã con rồi lập chỉ mục các mục trong các nút con mới hoặc đã được cập nhật. Trình kết nối tiếp tục đệ quy qua tất cả các nút con cho đến khi tất cả các mục được xử lý. Việc truy cập như vậy thường được dùng cho các kho lưu trữ phân cấp, trong đó việc liệt kê tất cả mã nhận dạng là không thực tế.

Chiến lược này phù hợp nếu bạn có dữ liệu phân cấp cần được thu thập dữ liệu, chẳng hạn như một loạt thư mục hoặc trang web.

Triển khai chiến lược duyệt qua và lập chỉ mục các mục

Mọi phần tử có thể lập chỉ mục cho Cloud Search đều được gọi là mục trong API Cloud Search. Một mục có thể là tệp, thư mục, dòng trong tệp CSV hoặc bản ghi cơ sở dữ liệu.

Sau khi đăng ký giản đồ, bạn có thể điền chỉ mục bằng cách:

1. (không bắt buộc) Sử dụng items.upload để tải các tệp lớn hơn 100 KiB lên nhằm mục đích lập chỉ mục. Đối với các tệp nhỏ hơn, hãy nhúng nội dung dưới dạng inlineContent bằng cách sử dụng items.index.

2. (không bắt buộc) Sử dụng media.upload để tải tệp phương tiện lên nhằm lập chỉ mục.

3. Sử dụng items.index để lập chỉ mục mục. Ví dụ: nếu giản đồ của bạn sử dụng định nghĩa đối tượng trong giản đồ phim, thì yêu cầu lập chỉ mục cho một mục sẽ có dạng như sau:

   {
     "name": "datasource/<data_source_id>/items/titanic",
     "acl": {
       "readers": [
         {
           "gsuitePrincipal": {
             "gsuiteDomain": true
           }
         }
       ]
     },
     "metadata": {
       "title": "Titanic",
       "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1",
       "objectType": "movie"
     },
     "structuredData": {
       "object": {
         "properties": [
           {
             "name": "movieTitle",
             "textValues": {
               "values": [
                 "Titanic"
               ]
             }
           },
           {
             "name": "releaseDate",
             "dateValues": {
               "values": [
                 {
                   "year": 1997,
                   "month": 12,
                   "day": 19
                 }
               ]
             }
           },
           {
             "name": "actorName",
             "textValues": {
               "values": [
                 "Leonardo DiCaprio",
                 "Kate Winslet",
                 "Billy Zane"
               ]
             }
           },
           {
             "name": "genre",
             "enumValues": {
               "values": [
                 "Drama",
                 "Action"
               ]
             }
           },
           {
             "name": "userRating",
             "integerValues": {
               "values": [
                 8
               ]
             }
           },
           {
             "name": "mpaaRating",
             "textValues": {
               "values": [
                 "PG-13"
               ]
             }
           },
           {
             "name": "duration",
             "textValues": {
               "values": [
                 "3 h 14 min"
               ]
             }
           }
         ]
       }
     },
     "content": {
       "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
       "contentFormat": "TEXT"
     },
     "version": "01",
     "itemType": "CONTENT_ITEM"
   }
   

4. (Không bắt buộc) Sử dụng lệnh gọi items.get để xác minh rằng một mục đã được lập chỉ mục.

Để thực hiện một lượt truy cập đầy đủ, bạn sẽ định kỳ lập chỉ mục lại toàn bộ kho lưu trữ. Để thực hiện việc duyệt qua danh sách hoặc biểu đồ, bạn cần triển khai mã để xử lý các thay đổi đối với kho lưu trữ.

Xử lý các thay đổi về kho lưu trữ

Bạn có thể định kỳ thu thập và lập chỉ mục từng mục trong kho lưu trữ để thực hiện việc lập chỉ mục đầy đủ. Mặc dù hiệu quả trong việc đảm bảo chỉ mục của bạn luôn mới nhất, nhưng việc lập chỉ mục đầy đủ có thể tốn kém khi xử lý các kho lưu trữ lớn hơn hoặc phân cấp.

Thay vì sử dụng các lệnh gọi chỉ mục để lập chỉ mục toàn bộ kho lưu trữ theo định kỳ, bạn cũng có thể sử dụng hàng đợi lập chỉ mục của Google Cloud làm cơ chế theo dõi các thay đổi và chỉ lập chỉ mục những mục đã thay đổi. Bạn có thể sử dụng các yêu cầu items.push để đẩy các mục vào hàng đợi để thăm dò ý kiến và cập nhật sau. Để biết thêm thông tin về Hàng đợi lập chỉ mục của Google Cloud, hãy tham khảo bài viết Hàng đợi lập chỉ mục của Google Cloud.

Để biết thêm thông tin về API Google Cloud Search, hãy tham khảo API Cloud Search.