Trình kết nối nội dung là một chương trình phần mềm dùng để truyền tải dữ liệu trong kho lưu trữ của doanh nghiệp và điền sẵn vào 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 thích hợp nếu bạn 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 các 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.
Các thư viện API REST hoặc API REST cấp thấp. 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 bài viết 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:
- Đọc và xử lý các tham số cấu hình.
- 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ừ kho lưu trữ nội dung của bên thứ ba.
- 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.
- Lập chỉ mục các mục cho nguồn dữ liệu Cloud Search.
- (không bắt buộc) Nghe các thay đổi về thông báo 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 để đồng bộ hoá nguồn dữ liệu trên 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 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. Hãy nhấp vào một thẻ bên dưới để xem các phần phụ thuộc cho môi trường tạo bản dựng của bạn:
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 đề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. Thông số được xác định 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ố tham số cấu hình do Google cung cấp mà tất cả các trình kết nối sử dụng. Bạn phải khai báo các tham 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áoapi.customerId
là mã nhận dạng duy nhất cho tài khoản Google Workspace của doanh nghiệp.
Bạn không cần phải khai báo các tham số đó trong tệp cấu hình, trừ phi muốn ghi đè các giá trị mặc định của các tham số khác do Google cung cấp. Để biết thêm thông tin về tham 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 tham 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 của bạn. Bạn có thể đặt thuộc tính 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 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, thì SDK sẽ cố gắng truy cập vào tệp cấu hình mặc định có tên là 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 qua kho lưu trữ và lập chỉ mục dữ liệu trong kho lưu trữ đó. 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 mình. 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:
- 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 cho 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ể chi trả chi phí cho việc thực hiện truyền tải toàn bộ 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 dữ liệu chủ yếu là tĩnh, không phân cấp. Bạn cũng có thể sử 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 hỗ trợ tính năng này.
- 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 cả mọi nút con, giúp 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 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 nhất. Chiến lược này thường dùng để cập nhật dần một chỉ mục hiện có (thay vì phải truyền tải toàn bộ mỗi khi bạn cập nhật chỉ mục).
Chiến lược truyền tải này phù hợp khi khó 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 đang 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 sẽ truyền lầ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 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 tất cả các mục được xác định địa chỉ. Phương thứ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 đó việc liệt kê tất cả mã nhận dạng là không cần thiế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 truyền tải này do một lớp 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 những mẫu này sẽ giúp tăng tốc đáng kể quá trình phát triển trình kết nối của bạn. Để tạo 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 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
- Tạo trình kết nối truyền tải danh sách bằng một lớp mẫu
- 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
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 đề 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 đến 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 bản sao 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 thực thể cho 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 biết cách triển khai phương thức main()
:
Trong thực tế, SDK sẽ 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()
sẽ thực hiện các tác vụ sau:
- Gọi phương thức
Configuation.isInitialized()
để đảm bảo rằngConfiguration
chưa được khởi động. - Khởi động đố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ượngConfigValue
bên trong đối tượngConfiguration
.
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à 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 giao diện Repository
để tạo một 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 FullTraversalConnector
, hãy ghi đè các phương thức sau:
Phương thức
init()
. Để thực hiện thao tác thiết lập và khởi chạy kho dữ liệu bất kỳ, hãy ghi đè phương thứcinit()
.Phương thức
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ứcgetAllDocs()
. 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) 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ứcgetChanges()
. Phương thức này được gọi một lần cho mỗi lần truyền tải gia tăng theo lịch (như được xác định trong cấu hình của bạn) để 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ứcclose()
. 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
sẽ trả về một số kiểu đối tượng ApiOperation
. Đối tượng ApiOperation
thực hiện một hành động dưới dạng một hoặc có thể nhiều lệnh gọi IndexingService.indexItem()
để lập chỉ mục kho lưu trữ trên thực tế.
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 lấy mọi thông số tuỳ chỉnh từ đối tượng Configuration
. Tác vụ này thường được thực hiện theo 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 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
:
Để 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:
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. Phương thức getAllDocs()
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. Đố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()
:
- Thiết lập quyền.
- Thiết lập siêu dữ liệu cho mục mà bạn đang lập chỉ mục.
- Kết hợp siêu dữ liệu và mục vào một
RepositoryDoc
có thể lập chỉ mục. - Đóng gói từng mục có thể lập chỉ mục vào một biến lặp do phương thức
getAllDocs()
trả về. Xin lưu ý rằnggetAllDocs()
thực sự trả về mộtCheckpointCloseableIterable
là một đối tượng lặp lại của các đối tượngApiOperation
, mỗi đối tượng đại diện cho một yêu cầu API được thực hiện trênRepositoryDoc
, 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 khác có thể 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) để 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. Danh sách kiểm soát quyền truy cập (ACL) là danh sách mã nhận dạng của 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 chỉ những người dùng có quyền truy cập vào một mục mới có thể thấy mục đó trong kết quả tìm kiếm. Bạn phải bao gồm ACL cho một mục 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 cho 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 các 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 mình 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ư tính kế thừa ACL, thì việc lập mô hình ACL đó có thể khó khăn. Để biết thêm thông tin về ACL của Google Cloud Search, hãy 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. Phiên bản này không hỗ trợ Danh sách kiểm soát quyền truy cập (ACL) giữa 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 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()
) 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.
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ữ. Ví dụ: bạn có thể 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 đó thư mục con kế thừa quyền từ thư mục mẹ. Để kế thừa ACL tính năng lập mô hình, bạn cần cung cấp thêm thông tin 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 một Item
, bạn cần có một mã nhận dạng chuỗi duy nhất, loại mục, Danh sách kiểm soát quyền truy cập (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ợ giúp IndexingItemBuilder
.
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 trình bày cách tạo một mục có thể lập chỉ mục.
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ộ sẽ khiến độ trễ lập chỉ mục đến phân phát lâu hơn và đáp ứng hạn mức công suất 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ộ cho hoạt động lập chỉ mục ban đầu (chèn lấp) của toàn bộ kho lưu trữ.
SYNCHRONOUS
- Chế độ đồng bộ giúp thời gian chờ từ khi lập chỉ mục đến phân phát ngắn hơn và đáp ứng hạn mức công suất giới hạn. Bạn nên dùng chế độ đồng bộ để 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 không được 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 biến 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 đối tượng lặp. Đoạn mã sau đây cho biết cách tạo và trả về một biến lặp.
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:
- (không bắt buộc) Nếu tốc độ lập chỉ mục của bạn 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 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 được dùng để lưu giữ mã nhận dạng và giá trị băm không bắt buộc cho mỗi mục trong kho lưu trữ. Trình kết nối truyền tải 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ục một để 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 đã 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 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 đến 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 bản sao 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 thực thể cho 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 thực thể cho ListingConnector
và Repository
liên kết với nó:
Trong thực tế, SDK sẽ 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()
:
- Gọi phương thức
Configuation.isInitialized()
để đảm bảo rằngConfiguration
chưa được khởi động. - Khởi động đố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ượngConfigValue
bên trong đối tượngConfiguration
.
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à 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 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
, hãy ghi đè các phương thức sau:
Phương thức
init()
. Để thực hiện thao tác thiết lập và khởi chạy kho dữ liệu bất kỳ, hãy ghi đè phương thứcinit()
.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ứcgetIds()
.Phương thức
getDoc()
. Để thêm mới, 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ứcgetDoc()
.(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ứcgetChanges()
. Phương thức này được gọi một lần cho mỗi lần truyền tải gia tăng theo lịch (như được xác định trong cấu hình của bạn) để 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ứcclose()
. 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
sẽ trả về một số kiểu đối tượng ApiOperation
. Đối tượng ApiOperation
thực hiện một hành động dưới dạng một hoặc có thể nhiều lệnh gọi IndexingService.indexItem()
để lập chỉ mục kho lưu trữ trên thực tế.
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 lấy mọi thông số tuỳ chỉnh từ đối tượng Configuration
. Tác vụ này thường được thực hiện theo 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 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
:
Để 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:
Thực hiện việc truyền tải 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 một mục cụ thể nếu quá trình bị gián đoạn.
Tiếp theo, hãy ghi đè phương thức 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à giá trị băm nội dung liên quan của các mã đó từ kho lưu trữ. Sau đó, các cặp giá trị mã nhận dạng và hàm băm được đóng gói vào yêu cầu thao tác đẩy đến 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 được đẩy lên trước tiên rồi mới đến mã nhận dạng con, cho đến khi hệ thống xử lý xong toàn bộ hệ phân cấp các mục.
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 sẽ được lập chỉ mục. Bạn có thể dùng điểm kiểm tra này để tiếp tục lập chỉ mục một mục cụ thể nếu quá 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 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
vào một đối tượng lặp do phương thứcgetIds()
trả về. Xin lưu ý rằnggetIds()
thực sự trả về mộtCheckpointCloseableIterable
là một đối tượng lặp lại của các đối tượngApiOperation
, mỗi đối tượng đại diện cho một yêu cầu API được thực hiện trênRepositoryDoc
, 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ị hàm băm, cũng như cách chèn các dữ liệu đó 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.
Đoạn mã sau đây cho biết cách sử dụng lớp 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
.
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ới, được 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ỏi 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 trong 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()
:
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 này khỏi chỉ mục.
Thăm dò 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
), đừng làm gì cả.Chỉ mục đã thay đổi hoặc các mục mới:
- Thiết lập quyền.
- Thiết lập siêu dữ liệu cho mục mà bạn đang lập chỉ mục.
- Kết hợp siêu dữ liệu và mục vào một
RepositoryDoc
có thể lập chỉ mục. - 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 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ục có tồn tại trong kho lưu trữ hay không và nếu không có thì hãy xoá mục đó.
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
, 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 của mục trong Hàng đợi lập chỉ mục của Cloud Search và xử lý một mục không thay đổi.
Để xác định xem mục có phải chưa bị sửa đổi hay không, hãy kiểm tra trạng thái của mục cũng như các siêu dữ liệu khác có thể cho biết có thay đổi. 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.
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) để 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. Danh sách kiểm soát quyền truy cập (ACL) là danh sách mã nhận dạng của 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 chỉ những người dùng có quyền truy cập vào một mục mới có thể thấy mục đó trong kết quả tìm kiếm. Bạn phải bao gồm ACL cho một mục 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 cho 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 các 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 mình 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ư tính kế thừa ACL, thì việc lập mô hình ACL đó có thể khó khăn. Để biết thêm thông tin về ACL của Google Cloud Search, hãy 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. Phiên bản này không hỗ trợ Danh sách kiểm soát quyền truy cập (ACL) giữa 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 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()
) 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.
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ữ. Ví dụ: bạn có thể 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 đó thư mục con kế thừa quyền từ thư mục mẹ. Để kế thừa ACL tính năng lập mô hình, bạn cần cung cấp thêm thông tin 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 một Item
, bạn cần có một mã nhận dạng chuỗi duy nhất, loại mục, Danh sách kiểm soát quyền truy cập (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ợ giúp IndexingItemBuilder
.
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 mục thực tế mà có thể lập chỉ 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.
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ộ sẽ khiến độ trễ lập chỉ mục đến phân phát lâu hơn và đáp ứng hạn mức công suất 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ộ cho hoạt động lập chỉ mục ban đầu (chèn lấp) của toàn bộ kho lưu trữ.
SYNCHRONOUS
- Chế độ đồng bộ giúp thời gian chờ từ khi lập chỉ mục đến phân phát ngắn hơn và đáp ứng hạn mức công suất giới hạn. Bạn nên dùng chế độ đồng bộ để 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 không được chỉ định, chế độ yêu cầu sẽ 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 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 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 được dùng để lưu giữ 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 truyền tải biểu đồ đẩy 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 để 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 đã 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 Cloud Search, hãy tham khảo Hàng đợi lập chỉ mục Google Cloud Search.
Trong 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 đều được đẩy đến hàng đợi. Trình kết nối tiếp tục xử lý đệ quy mã nhận dạng mẹ và mã con cho đến khi tất cả các mục được xử lý.
Phần này của tài liệu đề cập đến các đoạn mã trong ví dụ về GraphTraversalSample.
Triển khai điểm truy cập của trình kết nối
Điểm truy cập đến 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 bản sao 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 thực thể cho 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 thực thể cho ListingConnector
và Repository
liên kết với nó:
Trong thực tế, SDK sẽ 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()
:
- Gọi phương thức
Configuation.isInitialized()
để đảm bảo rằngConfiguration
chưa được khởi động. - Khởi động đố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ượngConfigValue
bên trong đối tượngConfiguration
.
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à 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 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:
Phương thức
init()
. Để thực hiện thao tác thiết lập và khởi chạy kho dữ liệu bất kỳ, hãy ghi đè phương thứcinit()
.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ứcgetIds()
.Phương thức
getDoc()
. Để thêm mới, 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ứcgetDoc()
.(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ứcgetChanges()
. Phương thức này được gọi một lần cho mỗi lần truyền tải gia tăng theo lịch (như được xác định trong cấu hình của bạn) để 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ứcclose()
. 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
sẽ 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ưới dạng một hoặc có thể nhiều lệnh gọi IndexingService.indexItem()
để lập chỉ mục kho lưu trữ trên thực tế.
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 lấy mọi thông số tuỳ chỉnh từ đối tượng Configuration
. Tác vụ này thường được thực hiện theo 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 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
:
Để 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:
Thực hiện truyền tải 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 một mục cụ thể nếu quá trình bị gián đoạn.
Tiếp theo, hãy ghi đè phương thức 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à giá trị băm nội dung liên quan của các mã đó từ kho lưu trữ. Sau đó, các cặp giá trị mã nhận dạng và hàm băm được đóng gói vào yêu cầu thao tác đẩy đến 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 được đẩy lên trước tiên rồi mới đến mã nhận dạng con, cho đến khi hệ thống xử lý xong toàn bộ hệ phân cấp các mục.
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 sẽ được lập chỉ mục. Bạn có thể dùng điểm kiểm tra này để tiếp tục lập chỉ mục một mục cụ thể nếu quá 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 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
vào một biến lặp do phương thứcgetIds()
trả về. Xin lưu ý rằnggetIds()
thực sự trả về mộtCheckpointCloseableIterable
là một đối tượng lặp lại của các đối tượngApiOperation
, mỗi đối tượng đại diện cho một yêu cầu API được thực hiện trênRepositoryDoc
, 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ị hàm băm cũng như chèn các thông tin đó 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.
Đoạn mã sau đây cho biết cách sử dụng lớp 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
.
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ới, được 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ỏi 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 trong Hàng đợi lập chỉ mục trên 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()
:
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 này khỏi chỉ mục. Nếu mục đó tồn tại, hãy tiếp tục thực hiện bước tiếp theo.
Chỉ mục đã thay đổi hoặc các mục mới:
- Thiết lập quyền.
- Thiết lập siêu dữ liệu cho mục mà bạn đang lập chỉ mục.
- Kết hợp siêu dữ liệu và mục vào một
RepositoryDoc
có thể lập chỉ mục. - Đặt mã con vào Hàng đợi lập chỉ mục Cloud Search để xử lý thêm.
- 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à xoá mục đó đi.
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) để 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. Danh sách kiểm soát quyền truy cập (ACL) là danh sách mã nhận dạng của 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 chỉ những người dùng có quyền truy cập vào một mục mới có thể thấy mục đó trong kết quả tìm kiếm. Bạn phải bao gồm ACL cho một mục 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 cho 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 các 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 mình 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ư tính kế thừa ACL, thì việc lập mô hình ACL đó có thể khó khăn. Để biết thêm thông tin về ACL của Google Cloud Search, hãy 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. Phiên bản này không hỗ trợ Danh sách kiểm soát quyền truy cập (ACL) giữa 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 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()
) 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.
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ữ. Ví dụ: bạn có thể 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 đó thư mục con kế thừa quyền từ thư mục mẹ. Để kế thừa ACL tính năng lập mô hình, bạn cần cung cấp thêm thông tin 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 một Item
, bạn cần có một mã nhận dạng chuỗi duy nhất, loại mục, Danh sách kiểm soát quyền truy cập (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ợ giúp IndexingItemBuilder
.
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ế mà có thể lập chỉ 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.
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ộ sẽ khiến độ trễ lập chỉ mục đến phân phát lâu hơn và đáp ứng hạn mức công suất 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ộ cho hoạt động lập chỉ mục ban đầu (chèn lấp) của toàn bộ kho lưu trữ.
SYNCHRONOUS
- Chế độ đồng bộ giúp thời gian chờ từ khi lập chỉ mục đến phân phát ngắn hơn và đáp ứng hạn mức công suất giới hạn. Bạn nên dùng chế độ đồng bộ để 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 không được chỉ định, chế độ yêu cầu sẽ 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 các mã nhận dạng con của mục mẹ hiện đ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 gốc được lập chỉ mục.
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 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 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 qua kho lưu trữ và lập chỉ mục dữ liệu trong kho lưu trữ đó. 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 mình. Sau đây là 3 chiến lược truyền tải phổ biến:
- 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 cho 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ể chi trả chi phí cho việc thực hiện truyền tải toàn bộ 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 dữ liệu chủ yếu là tĩnh, không phân cấp. Bạn cũng có thể sử 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 hỗ trợ tính năng này.
- 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 cả mọi nút con, giúp 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 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 nhất. Chiến lược này thường dùng để cập nhật dần một chỉ mục hiện có (thay vì phải truyền tải toàn bộ mỗi khi bạn cập nhật chỉ mục).
Chiến lược truyền tải này phù hợp khi khó 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 đang 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 sẽ truyền lầ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 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 tất cả các mục được xác định địa chỉ. Phương thứ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 đó việc liệt kê tất cả mã nhận dạng là không cần thiế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ư 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:
(không bắt buộc) Sử dụng
items.upload
để tải các 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 bằngitems.index
.(không bắt buộc) Sử dụng
media.upload
để tải các tệp đa phương tiện lên cho việc lập chỉ mục.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ặt hàng 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" }
(Không bắt buộc) Sử dụng các lệnh gọi items.get để xác minh một mục đã được lập chỉ mục.
Để thực hiện việc truyền tải toàn bộ, bạn nên định kỳ lập chỉ mục lại toàn bộ kho lưu trữ. Để thực hiện truyền tải danh sách hoặc biểu đồ, bạn cần triển khai mã để 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ể thu thập và lập chỉ mục định kỳ từng mục từ kho lưu trữ để thực hiện lập chỉ mục đầy đủ. Mặc dù có 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 đầy đủ có thể gây tốn kém khi xử lý các kho lưu trữ lớn hơn hoặc có hệ phân cấp.
Thay vì thường xuyên sử dụng các 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ể 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ò và cập nhật sau. Để biết thêm thông tin về Hàng đợi lập chỉ mục Google Cloud, hãy tham khảo Hàng đợi lập chỉ mục Google Cloud.
Để biết thêm thông tin về API Google Cloud Search, hãy tham khảo API Cloud Search.