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 để truyền dữ liệu trong một của Enterprise và điền sẵn một nguồn dữ liệu. Google cung cấp các dịch vụ sau để 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 trong 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 các trình kết nối. Để tạo nội dung trình kết nối bằng SDK, hãy tham khảo 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 thư viện API REST hoặc API REST cấp thấp. Sử dụng các tùy chọn này nếu bạn không trong Java hoặc nếu cơ sở mã của bạn phù hợp hơn với REST API hoặc một thư viện. Để tạo trình kết nối nội dung bằng API REST, hãy tham khảo đến Tạo trình kết nối nội dung bằng API REST.

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 tham số cấu hình.
  2. Lấy các phần dữ liệu riêng biệt có thể lập chỉ mục, được gọi là "items", từ bên thứ ba kho lưu trữ nội dung.
  3. Kết hợp các 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 cho nguồn dữ liệu Cloud Search.
  5. (không bắt buộc) Nghe các thông báo thay đổi từ nội dung của bên thứ ba kho lưu trữ. Thông báo thay đổi sẽ được chuyển đổi thành yêu cầu lập chỉ mục để giữ lại nguồn dữ liệu trên Cloud Search đồng bộ hoá với kho lưu trữ của bên thứ ba. Chiến lược phát hành đĩa đơn trình kết nối chỉ thực hiện tác 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 chuột trên thẻ dưới đây để xem các phần phụ thuộc cho môi trường tạo bản dựng:

Maven

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

Gradle

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 có một tệp cấu hình chứa các thông số được sử dụng bởi trình kết nối, 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 định nghĩa là các cặp khoá-giá trị, chẳng hạn như api.sourceId=1234567890abcdef.

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

  • Đố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ì những thông số này xác định vị trí kho lưu trữ và khoá riêng tư cần thiết để truy cập 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 là trình kết nối danh tính thông số này xác định vị trí của nguồn nhận dạng bên ngoài. Nếu bạn khi đồng bộ hoá người dùng, bạn cũng phải khai báo api.customerId là mã nhận dạng duy nhất cho tài khoản Google Workspace của doanh nghiệp bạn.

Trừ phi bạn muốn ghi đè các giá trị mặc định của các nền tảng khác do Google cung cấp tham số, bạn không cần khai báo chúng 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 Các 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 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 vào trình kết nối. Bạn có thể đặt thuộc tính này bằng cách sử dụng đối số -D khi bắt đầu trình kết nối. Ví dụ: lệnh sau đây sẽ khởi động trình kết nối với tệp cấu hình MyConfig.properties:

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

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

Xác định chiến lược truyền tải của bạn

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

Toàn bộ chiến lược truyền tải

Chiến lược truyền tải đầy đủ sẽ quét toàn bộ kho lưu trữ và lập chỉ mục một cách mù quáng mọi mục. 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ể đảm bảo chi phí thực hiện truyền tải đầy đủ mỗi lần bạn lập chỉ mục.

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

Liệt kê chiến lược truyền tải

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

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

Truyền tải biểu đồ

Chiến lược truyền tải biểu đồ 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 mất lần truyền thứ hai và chỉ lập chỉ mục các mục trong nút gốc là 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. Cuối cùng, trình kết nối truyền mọi mã nhận dạng 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 xử lý xong tất cả các mục. Việc truyền tải như vậy thường được dùng cho các kho lưu trữ phân cấp, trong đó danh sách tất cả mã nhận dạng không được liệt kê thiết thực.

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 thông tin, chẳng hạn như một loạt thư mục hoặc trang web.

Mỗi chiến lược truyền tải này do một trình kết nối mẫu triển khai trong SDK. Mặc dù bạn có thể triển khai chiến lược truyền tải của riêng mình, nhưng các mẫu giúp tăng tốc đáng kể sự phát triển trình kết nối của bạn. Người nhận tạo trình kết nối bằng cách sử dụng mẫu, được xử lý với phần tương ứng với chiến lược truyền tải của bạn:

Tạo trình kết nối truyền tải đầy đủ bằng cách sử dụng lớp mẫu

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

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

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

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

FullTraversalSample.java
/**
 * 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();
}

Đằng sau đó, SDK gọi initConfig() sau khi phương thức main() của trình kết nối được gọi Application.build. Chiến lược phát hành đĩa đơn initConfig() phương thức thực hiện những tác vụ sau:

  1. Gọi hàm Configuation.isInitialized() để đảm bảo rằng Configuration chưa được khởi chạy.
  2. Khởi động đối tượng Configuration bằng khoá-giá trị do Google cung cấp cặp. Mỗi cặp khoá-giá trị được lưu trữ trong một 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 truyền tải và truyền tải lập chỉ mục các mục trong kho lưu trữ. Khi sử dụng một mẫu, bạn chỉ cần ghi đè một số phương thức nhất định trong 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à bạn sử dụng. Đối với FullTraversalConnector , hãy ghi đè các phương thức sau:

  • Chiến lược phát hành đĩa đơn init() . Để thực hiện thao tác thiết lập và khởi tạo kho dữ liệu bất kỳ, hãy ghi đè phương thức init().

  • Chiến lược phát hành đĩa đơn getAllDocs() . Để truyền tải 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ền tải theo lịch (như được xác định trong cấu hình của bạn).

  • (không bắt buộ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 đè getChanges(). Phương thức này được gọi một lần cho mỗi mức tăng theo lịch truyền tải (như được xác định theo cấu hình của bạn) để truy xuất các mục đã sửa đổi và lập chỉ mục chúng.

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

Mỗi phương thức của phần Đối tượng Repository trả về một số loại ApiOperation . Đối tượng ApiOperation thực hiện một thao tác dưới dạng một đối tượng duy nhất, hoặc có thể là nhiều, IndexingService.indexItem() để thực hiện việc lập chỉ mục thực tế cho kho lưu trữ của bạn.

Nhận thông 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 cần tải mọi thông số tùy chỉnh từ Configuration . Tác vụ này thường được thực hiện trong Repository của lớp init().

Lớp Configuration có một số phương thức để lấy nhiều loại dữ liệu 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ẽ hãy dùng thông số của đối tượng ConfigValue get() để truy xuất giá trị thực. Đoạn mã sau, 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:

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

Để tải 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 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 đoạn riêng biệt. Đoạn mã sau đây, từ trình kết nối hướng dẫn sử dụng getMultiValue để lấy danh sách tên kho lưu trữ GitHub:

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

Thực hiện truyền tải toàn bộ

Ghi đè getAllDocs() để thực hiện truyền tải toàn bộ và lập chỉ mục kho lưu trữ của bạn. getAllDocs() sẽ chấp nhận một điểm kiểm tra. Điểm kiểm tra này được dùng để tiếp tục lập chỉ mục tại mục cụ thể nếu quá trình này 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 này trong phương thức getAllDocs():

  1. Thiết lập quyền.
  2. Thiết lập 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 thành một chỉ mục có thể lập chỉ mục RepositoryDoc.
  4. Đóng gói từng mục có thể lập chỉ mục vào một biến lặp do getAllDocs() trả về . Xin lưu ý rằng getAllDocs() thực sự trả về một CheckpointCloseableIterable là phép lặp lại của 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 trang đó.

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

Thiết lập 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) để nhận dạng người dùng hoặc các nhóm có quyền truy cập vào một mục. Danh sách kiểm soát quyền truy cập (ACL) là danh sách mã nhận dạng cho nhóm hoặc người dùng có thể truy cập vào mục.

Bạn phải sao chép Danh sách kiểm soát quyền truy cập (ACL) mà kho lưu trữ của bạn sử dụng để đảm bảo chỉ những người dùng đó có quyền truy cập vào một mục có thể xem mục đó trong kết quả tìm kiếm. Chiến lược phát hành đĩa đơn Danh sách kiểm soát quyền truy cập (ACL) cho một mục phải được bao gồm khi lập chỉ mục một mục để Google Cloud Search có thông tin cần thiết nhằm cung cấp cấp truy cập chính xác mục đó.

SDK Trình kết nối nội dung cung cấp một tập hợp phong phú các lớp và phương thức ACL để lập mô hình danh sách kiểm soát quyền truy cập (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ữ của bạn và tạo một 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ữ của bạn sử dụng các khái niệm như ACL tính kế thừa, việc lập mô hình ACL có thể là một việc phức tạp. Để biết thêm thông tin về Google Danh sách kiểm soát quyền truy cập (ACL) của Cloud Search, tham khảo Danh sách kiểm soát quyền truy cập (ACL) của Google Cloud Search.

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

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

Bạn cần phải hiểu các ACL để lập mô hình chính xác các ACL cho kho lưu trữ. Cho Ví dụ: có thể bạn đang lập chỉ mục các tệp trong hệ thống tệp sử dụng một số loại mô hình kế thừa, theo đó thư mục con kế thừa quyền khỏi các thư mục mẹ. Yêu cầu bổ sung thông tin bổ sung khi kế thừa danh sách kiểm soát quyền truy cập (ACL) của tính năng lập mô hình được đề cập trong Danh sách kiểm soát quyền truy cập (ACL) của Google Cloud Search

Đặt siêu dữ liệu cho một mặt hàng

Siêu dữ liệu được lưu trữ trong đối tượng Item. Để tạo Item, bạn cần có một tối thiểu một chuỗi ID 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 IndexingItemBuilder lớp trợ giúp.

FullTraversalSample.java
// 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 siêu dữ liệu có thể lập chỉ mục thực tế mục bằng cách sử dụng RepositoryDoc.Builder . Ví dụ sau đây trình bày cách tạo một mục có thể lập chỉ mục.

FullTraversalSample.java
// 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 IndexingService.indexItem().

Bạn cũng có thể sử dụng Phương thức setRequestMode() của phương thức 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ộ sẽ khiến quá trình lập chỉ mục đến phân phát bị chậm 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. Chế độ không đồng bộ là nên dùng cho việc lập chỉ mục ban đầu (chèn lấp) của toàn bộ kho lưu trữ.
SYNCHRONOUS
Chế độ đồng bộ dẫn đến thời gian chờ ngắn hơn từ khi lập chỉ mục đến phân phát và đáp ứng hạn mức thông lượng giới hạn. Chế độ đồng bộ là được đề xuất cho việc lập chỉ mục các bản cập nhật và thay đổi đối với kho lưu trữ. Nếu chưa chỉ định, chế độ yêu cầu mặc định là SYNCHRONOUS.

Đóng gói từng mục có thể lập chỉ mục trong một biến lặp

getAllDocs() trả về một Iterator, cụ thể là một CheckpointCloseableIterable! trong số RepositoryDoc . Bạn có thể sử dụng CheckpointClosableIterableImpl.Builder để tạo và trả về một biến lặp. Đoạn mã sau đây cho biết cách để tạo và trả về một biến lặp.

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

SDK thực thi từng lệnh gọi lập chỉ mục có trong biến lặp.

Các bước tiếp theo

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

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

Hàng đợi lập chỉ mục Cloud Search dùng để lưu giữ mã nhận dạng và hàm băm không bắt buộc cho mỗi mặt hàng trong kho lưu trữ. Trình kết nối truyền tải danh sách đẩy trình kết nối mã mục vào Hàng đợi lập chỉ mục Google Cloud Search và truy xuất từng mã mục thời gian lập chỉ mục. Google Cloud Search duy trì hàng đợi và so sánh nội dung trong 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ữ. Để biết thêm thông tin về Cloud Search Hàng đợi lập chỉ mục, tham khảo Danh sách chờ lập chỉ mục của Cloud Search.

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

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

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

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

ListTraversalSample.java
/**
 * 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();
}

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

  1. Gọi hàm Configuation.isInitialized() để đảm bảo rằng Configuration chưa được khởi chạy.
  2. Khởi động đối tượng Configuration bằng khoá-giá trị do Google cung cấp cặp. Mỗi cặp khoá-giá trị được lưu trữ trong một 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 truyền tải và truyền tải lập chỉ mục các mục trong kho lưu trữ. Khi dùng mẫu, bạn chỉ cần ghi đè một số phương thức trong giao diện Repository để tạo trình kết nối nội dung. Các phương thức mà bạn ghi đè phụ thuộc vào mẫu và chiến lược truyền tải mà bạn sử dụng. Đối với ListingConnector! ghi đè các phương thức sau:

  • Chiến lược phát hành đĩa đơn init() . Để thực hiện thao tác thiết lập và khởi tạo kho dữ liệu bất kỳ, hãy ghi đè phương thức init().

  • 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ữ, ghi đè phương thức getIds().

  • getDoc() . Để thêm mới, cập nhật, sửa đổi hoặc xóa mục khỏi chỉ mục, hãy ghi đè getDoc().

  • (không bắt buộ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 đè getChanges(). Phương thức này được gọi một lần cho mỗi mức tăng theo lịch truyền tải (như được xác định theo cấu hình của bạn) để truy xuất các mục đã sửa đổi và lập chỉ mục chúng.

  • (không bắt buộc) close() . Nếu bạn cần dọn dẹp kho lưu trữ, hãy ghi đè close() . Phương thức này được gọi một lần trong khi 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 ApiOperation . Đối tượng ApiOperation thực hiện một thao tác dưới dạng một đối tượng duy nhất, hoặc có thể là nhiều, IndexingService.indexItem() để thực hiện việc lập chỉ mục thực tế cho kho lưu trữ của bạn.

Nhận thông 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 cần tải mọi thông số tùy chỉnh từ Configuration . Tác vụ này thường được thực hiện trong Repository của lớp init().

Lớp Configuration có một số phương thức để lấy nhiều loại dữ liệu 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ẽ hãy dùng thông số của đối tượng ConfigValue get() để truy xuất giá trị thực. Đoạn mã sau, 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:

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

Để tải 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 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 đoạn riêng biệt. Đoạn mã sau đây, từ trình kết nối hướng dẫn sử dụng getMultiValue để lấy danh sách tên kho lưu trữ GitHub:

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

Thực hiện việc truyền tải danh sách

Ghi đè 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 này được dùng để tiếp tục lập chỉ mục một mục cụ thể nếu quá trình này bị gián đoạn.

Tiếp theo, hãy ghi đè getDoc() để xử lý từng mục trong Hàng đợi lập chỉ mục Cloud Search.

Đẩy mã mục và giá trị băm

Ghi đè getIds() để tìm nạp mã mặt hàng và các giá trị hàm băm nội dung liên quan từ kho lưu trữ. Sau đó, cặp giá trị mã nhận dạng và giá trị hàm băm được đóng gói vào thao tác đẩy yêu cầu vào Hàng đợi lập chỉ mục Cloud Search. Mã nhận dạng gốc hoặc mã nhận dạng gốc thường là được đẩy lên trước tiên là ID con cho đến khi toàn bộ hệ thống phân cấp 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. Điểm kiểm tra đó có thể được dùng để tiếp tục lập chỉ mục một mục cụ thể bị gián đoạn. Đối với mỗi mặt hàng trong kho lưu trữ, hãy thực hiện các thao tác này các bước trong phương thức getIds():

  • Lấy từng mã mặt hàng và giá trị băm liên quan 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 thành một biến lặp do hàm getIds() . Xin lưu ý rằng getIds() thực sự trả về một CheckpointCloseableIterable là phép lặp lại của 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, giá trị hàm băm và chèn chúng vào PushItems. PushItems là một yêu cầu ApiOperation để đẩy một mục lên Cloud Search Hàng đợi lập chỉ mục.

ListTraversalSample.java
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 PushItems.Builder để đóng gói các mã nhận dạng và giá trị băm vào một thao tác đẩy ApiOperation.

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

Các mục sẽ được đưa vào Hàng đợi lập chỉ mục Cloud Search để tiếp tục xử lý.

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ục mới, đã sửa đổi, không thay đổi hoặc không còn tồn tại trong nguồn kho lưu trữ. Truy xuất và lập chỉ mục từng mục mới hoặc đã sửa đổi. Xoá mục từ chỉ mục không còn tồn tại trong kho lưu trữ nguồn.

Phương thức getDoc() chấp nhận một Mục từ Google Cloud Search Hàng đợi lập chỉ mục. Đối với mỗi mục trong hàng đợi, thực hiện các bước này 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 Cloud Search có tồn tại hay không trong kho lưu trữ. Nếu không, hãy xoá mục này khỏi chỉ mục.

  2. Thăm dò chỉ mục để biết trạng thái của mục. Nếu mục không thay đổi (ACCEPTED), thì đừng làm bất cứ việc gì.

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

    1. Thiết lập quyền.
    2. Thiết lập 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 thành một chỉ mục có thể lập chỉ mục RepositoryDoc.
    4. Trả về RepositoryDoc.

Lưu ý: Mẫu ListingConnector không hỗ trợ trả về null trên phương thức getDoc(). Trả về kết quả null trong một 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ặt hàng có tồn tại trong kho lưu trữ và nếu không có thì xoá đi.

ListTraversalSample.java
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 ý 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, 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 của mục trong Cloud Search Hàng đợi lập chỉ mục và xử lý một mục không thay đổi.

ListTraversalSample.java
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ó phải chưa được sửa đổi hay không, hãy kiểm tra trạng thái của mục. như các siêu dữ liệu khác có thể cho biết sự thay đổi. Trong ví dụ này, siêu dữ liệu hàm băm được dùng để xác định xem mục đã được thay đổi hay chưa.

ListTraversalSample.java
/**
 * 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);
}

Thiết lập 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) để nhận dạng người dùng hoặc các nhóm có quyền truy cập vào một mục. Danh sách kiểm soát quyền truy cập (ACL) là danh sách mã nhận dạng cho nhóm hoặc người dùng có thể truy cập vào mục.

Bạn phải sao chép Danh sách kiểm soát quyền truy cập (ACL) mà kho lưu trữ của bạn sử dụng để đảm bảo chỉ những người dùng đó có quyền truy cập vào một mục có thể xem mục đó trong kết quả tìm kiếm. Chiến lược phát hành đĩa đơn Danh sách kiểm soát quyền truy cập (ACL) cho một mục phải được bao gồm khi lập chỉ mục một mục để Google Cloud Search có thông tin cần thiết nhằm cung cấp cấp truy cập chính xác mục đó.

SDK Trình kết nối nội dung cung cấp một tập hợp phong phú các lớp và phương thức ACL để lập mô hình danh sách kiểm soát quyền truy cập (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ữ của bạn và tạo một 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ữ của bạn sử dụng các khái niệm như ACL tính kế thừa, việc lập mô hình ACL có thể là một việc phức tạp. Để biết thêm thông tin về Google Danh sách kiểm soát quyền truy cập (ACL) của Cloud Search, tham khảo Danh sách kiểm soát quyền truy cập (ACL) của Google Cloud Search.

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

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

Bạn cần phải hiểu các ACL để lập mô hình chính xác các ACL cho kho lưu trữ. Cho Ví dụ: có thể bạn đang lập chỉ mục các tệp trong hệ thống tệp sử dụng một số loại mô hình kế thừa, theo đó thư mục con kế thừa quyền khỏi các thư mục mẹ. Yêu cầu bổ sung thông tin bổ sung khi kế thừa danh sách kiểm soát quyền truy cập (ACL) của tính năng lập mô hình được đề cập trong Danh sách kiểm soát quyền truy cập (ACL) của Google Cloud Search

Đặt siêu dữ liệu cho một mặt hàng

Siêu dữ liệu được lưu trữ trong đối tượng Item. Để tạo Item, bạn cần có một tối thiểu một chuỗi ID 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 IndexingItemBuilder lớp trợ giúp.

ListTraversalSample.java
// 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ột 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 siêu dữ liệu có thể lập chỉ mục thực tế mục bằng cách sử dụng RepositoryDoc.Builder. Ví dụ sau đây trình bày cách tạo một mục có thể lập chỉ mục.

ListTraversalSample.java
// 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 IndexingService.indexItem() của bạn.

Bạn cũng có thể sử dụng Phương thức setRequestMode() của phương thức 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ộ sẽ khiến quá trình lập chỉ mục đến phân phát bị chậm 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. Chế độ không đồng bộ là nên dùng cho việc lập chỉ mục ban đầu (chèn lấp) của toàn bộ kho lưu trữ.
SYNCHRONOUS
Chế độ đồng bộ dẫn đến thời gian chờ ngắn hơn từ khi lập chỉ mục đến phân phát và đáp ứng hạn mức thông lượng giới hạn. Chế độ đồng bộ là được đề xuất cho việc lập chỉ mục các bản cập nhật và thay đổi đối với kho lưu trữ. Nếu chưa chỉ định, chế độ yêu cầu mặc định là SYNCHRONOUS.

Các bước tiếp theo

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

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

Tạo trình kết nối truyền tải biểu đồ bằng cách sử dụng lớp mẫu

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

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

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

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

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

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

Đoạn mã sau đây cho biết cách tạo thực thể cho ListingConnector và Repository liên kết:

GraphTraversalSample.java
/**
 * 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();
}

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

  1. Gọi hàm Configuation.isInitialized() để đảm bảo rằng Configuration chưa được khởi chạy.
  2. Khởi động đối tượng Configuration bằng khoá-giá trị do Google cung cấp cặp. Mỗi cặp khoá-giá trị được lưu trữ trong một 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 dùng để thực hiện việc truyền tải và lập chỉ mục kho lưu trữ mục. 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 truyền tải mà bạn sử dụng. Đối với ListingConnector! bạn sẽ ghi đè các phương thức sau:

  • Chiến lược phát hành đĩa đơn init() . Để thực hiện thao tác thiết lập và khởi tạo kho dữ liệu bất kỳ, hãy ghi đè phương thức init().

  • 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ữ, ghi đè phương thức getIds().

  • getDoc() . Để thêm mới, cập nhật, sửa đổi hoặc xóa mục khỏi chỉ mục, hãy ghi đè getDoc().

  • (không bắt buộ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 đè getChanges(). Phương thức này được gọi một lần cho mỗi mức tăng theo lịch truyền tải (như được xác định theo cấu hình của bạn) để truy xuất các mục đã sửa đổi và lập chỉ mục chúng.

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

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

Nhận thông 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 cần tải mọi thông số tùy chỉnh từ Configuration . Tác vụ này thường được thực hiện trong Repository của lớp init().

Lớp Configuration có một số phương thức để lấy nhiều loại dữ liệu 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ẽ hãy dùng thông số của đối tượng ConfigValue get() để truy xuất giá trị thực. Đoạn mã sau, 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:

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

Để tải 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 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 đoạn riêng biệt. Đoạn mã sau đây, từ trình kết nối hướng dẫn sử dụng getMultiValue để lấy danh sách tên kho lưu trữ GitHub:

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

Thực hiện truyền tải biểu đồ

Ghi đè 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 này được dùng để tiếp tục lập chỉ mục một mục cụ thể nếu quá trình này bị gián đoạn.

Tiếp theo, hãy ghi đè getDoc() để xử lý từng mục trong Hàng đợi lập chỉ mục Cloud Search.

Đẩy mã mục và giá trị băm

Ghi đè getIds() để tìm nạp mã mặt hàng và các giá trị hàm băm nội dung liên quan từ kho lưu trữ. Sau đó, cặp giá trị mã nhận dạng và giá trị hàm băm được đóng gói vào thao tác đẩy yêu cầu vào Hàng đợi lập chỉ mục Cloud Search. Mã nhận dạng gốc hoặc mã nhận dạng gốc thường là được đẩy lên trước tiên là ID con cho đến khi toàn bộ hệ thống phân cấp 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. Điểm kiểm tra đó có thể được dùng để tiếp tục lập chỉ mục một mục cụ thể bị gián đoạn. Đối với mỗi mặt hàng trong kho lưu trữ, hãy thực hiện các thao tác này các bước trong phương thức getIds():

  • Lấy từng mã mặt hàng và giá trị băm liên quan 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 thành một biến lặp do hàm getIds(). Xin lưu ý rằng getIds() thực sự trả về một CheckpointCloseableIterable là phép lặp lại của 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, giá trị hàm băm và chèn chúng vào PushItems. PushItems là một ApiOperation yêu cầu đẩy một mục vào Hàng đợi lập chỉ mục Cloud Search.

GraphTraversalSample.java
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 PushItems.Builder để đóng gói các mã nhận dạng và giá trị băm vào một thao tác đẩy ApiOperation.

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

Các mục sẽ được đưa vào Hàng đợi lập chỉ mục Cloud Search để tiếp tục xử lý.

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ục mới, đã sửa đổi, không thay đổi hoặc không còn tồn tại trong nguồn kho lưu trữ. Truy xuất và lập chỉ mục từng mục mới hoặc đã sửa đổi. Xoá mục từ chỉ mục không còn tồn tại trong kho lưu trữ nguồn.

Phương thức getDoc() chấp nhận một Mục từ hoạt động lập chỉ mục Cloud Search Danh sách chờ. Đối với mỗi mục trong hàng đợi, thực hiện các bước này 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 Cloud Search có tồn tại trong kho lưu trữ. Nếu không, hãy xoá mục này khỏi chỉ mục. Nếu mục đó tồn tại, tiếp tục với bước tiếp theo.

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

    1. Thiết lập quyền.
    2. Thiết lập 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 thành một chỉ mục có thể lập chỉ mục RepositoryDoc.
    4. Đặt mã con vào Hàng đợi lập chỉ mục Cloud Search để xử lý thêm.
    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à không xoá được.

GraphTraversalSample.java
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);

Thiết lập 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) để nhận dạng người dùng hoặc các nhóm có quyền truy cập vào một mục. Danh sách kiểm soát quyền truy cập (ACL) là danh sách mã nhận dạng cho nhóm hoặc người dùng có thể truy cập vào mục.

Bạn phải sao chép Danh sách kiểm soát quyền truy cập (ACL) mà kho lưu trữ của bạn sử dụng để đảm bảo chỉ những người dùng đó có quyền truy cập vào một mục có thể xem mục đó trong kết quả tìm kiếm. Chiến lược phát hành đĩa đơn Danh sách kiểm soát quyền truy cập (ACL) cho một mục phải được bao gồm khi lập chỉ mục một mục để Google Cloud Search có thông tin cần thiết nhằm cung cấp cấp truy cập chính xác mục đó.

SDK Trình kết nối nội dung cung cấp một tập hợp phong phú các lớp và phương thức ACL để lập mô hình danh sách kiểm soát quyền truy cập (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ữ của bạn và tạo một 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ữ của bạn sử dụng các khái niệm như ACL tính kế thừa, việc lập mô hình ACL có thể là một việc phức tạp. Để biết thêm thông tin về Google Danh sách kiểm soát quyền truy cập (ACL) của Cloud Search, tham khảo Danh sách kiểm soát quyền truy cập (ACL) của Google Cloud Search.

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

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

Bạn cần phải hiểu các ACL để lập mô hình chính xác các ACL cho kho lưu trữ. Cho Ví dụ: có thể bạn đang lập chỉ mục các tệp trong hệ thống tệp sử dụng một số loại mô hình kế thừa, theo đó thư mục con kế thừa quyền khỏi các thư mục mẹ. Yêu cầu bổ sung thông tin bổ sung khi kế thừa danh sách kiểm soát quyền truy cập (ACL) của tính năng lập mô hình được đề cập trong Danh sách kiểm soát quyền truy cập (ACL) của Google Cloud Search

Đặt siêu dữ liệu cho một mặt hàng

Siêu dữ liệu được lưu trữ trong đối tượng Item. Để tạo Item, bạn cần có một tối thiểu một chuỗi ID 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 IndexingItemBuilder lớp trợ giúp.

GraphTraversalSample.java
// 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 siêu dữ liệu có thể lập chỉ mục thực tế mục bằng cách sử dụng RepositoryDoc.Builder. Ví dụ sau đây trình bày cách tạo một mục có thể lập chỉ mục.

GraphTraversalSample.java
// 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 IndexingService.indexItem().

Bạn cũng có thể sử dụng Phương thức setRequestMode() của phương thức 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ộ sẽ khiến quá trình lập chỉ mục đến phân phát bị chậm 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. Chế độ không đồng bộ là nên dùng cho việc lập chỉ mục ban đầu (chèn lấp) của toàn bộ kho lưu trữ.
SYNCHRONOUS
Chế độ đồng bộ dẫn đến thời gian chờ ngắn hơn từ khi lập chỉ mục đến phân phát và đáp ứng hạn mức thông lượng giới hạn. Chế độ đồng bộ là được đề xuất cho việc lập chỉ mục các bản cập nhật và thay đổi đối với kho lưu trữ. Nếu chưa chỉ định, chế độ yêu cầu mặc định là SYNCHRONOUS.

Đặt mã con vào hàng đợi lập chỉ mục Cloud Search

Đoạn mã sau đây cho biết cách đưa mã con vào, cho hiện đang xử lý mục gốc, vào hàng đợi xử lý. Các mã này sẽ được xử lý sau khi mục gốc được lập chỉ mục.

GraphTraversalSample.java
// 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

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

  • (không bắt buộc) Triển khai close() để giải phóng bất kỳ tài nguyên nào trước khi tắt.
  • (không bắt buộc) Tạo trình kết nối danh tính bằng cách sử dụ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 truyền tải của bạn

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

Toàn bộ chiến lược truyền tải

Chiến lược truyền tải đầy đủ sẽ quét toàn bộ kho lưu trữ và lập chỉ mục một cách mù quáng mọi mục. 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ể đảm bảo chi phí thực hiện truyền tải đầy đủ mỗi lần bạn lập chỉ mục.

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

Liệt kê chiến lược truyền tải

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

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

Truyền tải biểu đồ

Chiến lược truyền tải biểu đồ 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 mất lần truyền 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 truyền mọi mã nhận dạng 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 xử lý xong tất cả các mục. Việc truyền tải như vậy thường được dùng cho các kho lưu trữ phân cấp, trong đó danh sách tất cả mã nhận dạng không được liệt kê thiết thực.

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 thông tin, chẳng hạn như thư mục bộ sách hoặc trang web.

Triển khai chiến lược truyền tải và các mục trong chỉ mục

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

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

  1. (không bắt buộc) Sử dụng items.upload tải tệp lớn hơn 100KiB lên nhằm 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 đang sử dụng items.index.

  2. (không bắt buộc) Sử dụng media.upload tải các tệp đa phương tiện lên để 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 phim schema, một yêu cầu lập chỉ mục cho một mục sẽ trông giố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 items.get cuộc gọi để xác minh một mặt hàng đã được lập chỉ mục.

Để thực hiện truyền tải đầy đủ, bạn sẽ định kỳ lập chỉ mục lại toàn bộ kho lưu trữ. Để thực hiện truyền tải qua danh sách hoặc biểu đồ, bạn cần triển khai để xử lý các thay đổi về 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 từ kho lưu trữ để thực hiện lập chỉ mục toàn bộ. Mặc dù hiệu quả trong việc đảm bảo chỉ mục của bạn luôn được cập nhật, nhưng việc lập chỉ mục có thể tốn kém khi xử lý các kho lưu trữ lớn hơn hoặc kho lưu trữ phân cấp.

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

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