API Truy vấn cung cấp các phương thức tìm kiếm và đề xuất để xây dựng giao diện tìm kiếm hoặc nhúng kết quả tìm kiếm trong một ứng dụng.
Đối với các ứng dụng web có yêu cầu tối thiểu, hãy cân nhắc sử dụng tiện ích tìm kiếm. Để biết thêm thông tin, hãy xem phần Tạo giao diện tìm kiếm bằng tiện ích tìm kiếm
Xây dựng giao diện tìm kiếm
Việc xây dựng một giao diện tìm kiếm tối giản cần vài bước:
- Định cấu hình ứng dụng tìm kiếm
- Tạo thông tin đăng nhập OAuth cho ứng dụng
- Truy vấn chỉ mục
- Hiển thị kết quả truy vấn
Bạn có thể cải thiện giao diện tìm kiếm hơn nữa bằng các tính năng như phân trang, sắp xếp, lọc, các thuộc tính và tự động đề xuất.
Định cấu hình ứng dụng tìm kiếm
Bạn phải tạo ít nhất một ứng dụng tìm kiếm để liên kết với từng giao diện tìm kiếm do bạn tạo. Ứng dụng tìm kiếm cung cấp các tham số mặc định cho truy vấn, chẳng hạn như nguồn dữ liệu sẽ sử dụng, thứ tự sắp xếp, bộ lọc và các thuộc tính để yêu cầu. Nếu cần, bạn có thể ghi đè các tham số này bằng cách sử dụng API truy vấn.
Để biết thêm thông tin về các ứng dụng tìm kiếm, hãy tham khảo bài viết Tuỳ chỉnh trải nghiệm tìm kiếm trong Cloud Search.
Tạo thông tin đăng nhập OAuth cho ứng dụng
Ngoài các bước trong bài viết Định cấu hình quyền truy cập vào Google Cloud Search API, bạn cũng phải tạo thông tin xác thực OAuth cho ứng dụng web. Loại thông tin xác thực mà bạn tạo phụ thuộc vào ngữ cảnh sử dụng API.
Sử dụng thông tin đăng nhập để yêu cầu uỷ quyền thay mặt cho người dùng. Sử dụng phạm vi https://www.googleapis.com/auth/cloud_search.query
khi yêu cầu uỷ quyền.
Để biết thêm thông tin về các tuỳ chọn OAuth và thư viện ứng dụng, hãy xem [Nền tảng nhận dạng của Google](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.
Truy vấn chỉ mục
Sử dụng phương thức search
để thực hiện tìm kiếm dựa trên chỉ mục.
Mỗi yêu cầu phải bao gồm 2 thông tin: một văn bản query
để so khớp các mục và một searchApplicationId
xác định mã nhận dạng cho ứng dụng tìm kiếm dùng.
Đoạn mã sau đây hiển thị một truy vấn đến nguồn dữ liệu phim cho bộ phim Titanic:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
Hiển thị kết quả truy vấn
Ở mức tối thiểu, giao diện tìm kiếm dự kiến sẽ hiển thị mục title
cũng như đường liên kết đến mục gốc. Bạn có thể cải thiện hơn nữa khả năng hiển thị kết quả tìm kiếm bằng cách tận dụng thông tin bổ sung có trong kết quả tìm kiếm như đoạn trích và siêu dữ liệu.
Xử lý kết quả bổ sung
Theo mặc định, Cloud Search trả về các kết quả bổ sung khi không có đủ kết quả cho truy vấn của người dùng. Trường queryInterpretation
trong phản hồi cho biết thời điểm kết quả bổ sung được trả về. Nếu chỉ trả về kết quả bổ sung, InterpretationType
sẽ được đặt thành REPLACE
. Nếu một vài kết quả cho truy vấn ban đầu được trả về cùng với các kết quả bổ sung, thì InterpretationType
sẽ được đặt thành BLEND
. Trong cả hai trường hợp là QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
.
Khi một số kết quả bổ sung được trả về, hãy cân nhắc cung cấp văn bản để cho biết các kết quả bổ sung đã được trả về. Ví dụ: trong trường hợp REPLACE
, bạn có thể hiển thị chuỗi "Nội dung tìm kiếm của bạn cho truy vấn ban đầu không khớp với bất kỳ kết quả nào. Đang hiển thị kết quả cho các cụm từ tìm kiếm tương tự.”
Trong trường hợp BLEND
, bạn có thể hiển thị chuỗi "Nội dung tìm kiếm của bạn cho truy vấn ban đầu không khớp với đủ kết quả. Bao gồm kết quả cho các cụm từ tìm kiếm tương tự."
Xử lý kết quả về người
Cloud Search trả về 2 loại "kết quả về người": tài liệu liên quan đến một người có tên được dùng trong truy vấn và thông tin nhân viên của người có tên được dùng trong truy vấn. Loại kết quả thứ hai là một chức năng của tính năng Tìm kiếm người của Cloud Search và bạn có thể tìm thấy kết quả cho truy vấn như vậy trong trường structuredResults
của phản hồi API truy vấn:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
So khớp báo cáo trực tiếp
So khớp báo cáo trực tiếp là một tính năng Tìm kiếm người của Cloud Search, cho phép người dùng xem các báo cáo trực tiếp của một người thuộc tổ chức của họ.
Kết quả có trong trường structuredResults
.
Đối với các truy vấn về người quản lý hoặc nhân viên cấp dưới trực tiếp của một người, phản hồi sẽ có assistCardProtoHolder
trong structuredResults
. assistCardProtoHolder
có một trường tên là cardType
sẽ bằng RELATED_PEOPLE_ANSWER_CARD
. assistCardProtoHolder
chứa một thẻ có tên là relatedPeopleAnswerCard
chứa phản hồi thực tế.
Thuộc tính này chứa subject
(người có trong truy vấn) và relatedPeople
là tập hợp những người có liên quan đến chủ đề. Trường relationType
trả về giá trị MANAGER
hoặc DIRECT_REPORTS
.
Mã sau đây là phản hồi mẫu cho một truy vấn khớp với báo cáo trực tiếp:
{
"results": [],
"structuredResults": [{
"assistCardProtoHolder": {
"extensions": {
"@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
"cardMetadata": {
"cardCategory": "ANSWER"
},
"cardType": "RELATED_PEOPLE_ANSWER_CARD",
"relatedPeopleAnswerCard": {
"subject": {
"email": "AdamStanford@psincs-test01.newjnj.com",
"displayName": "Adam Stanford"
"manager": {
"email": "simonsais@psincs-test01.newjnj.com"
}
},
"relatedPeople": [{
"email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
"displayName": "Edgar Mountain Ramirez"
}, {
"email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
"displayName": "Francisco Jose Martinez"
}],
"relationType": "DIRECT_REPORTS",
}
}
}
}]
}
Tắt tính năng tối ưu hoá, bao gồm cả kết quả bổ sung
Theo mặc định, các tính năng tối ưu hoá (chẳng hạn như kết quả bổ sung) sẽ được bật. Tuy nhiên, bạn có thể tắt mọi chế độ tối ưu hoá hoặc chỉ tắt các kết quả bổ sung ở cả cấp ứng dụng tìm kiếm và cấp cụm từ tìm kiếm:
Để tắt mọi tính năng tối ưu hoá ở cấp ứng dụng tìm kiếm (bao gồm cả kết quả bổ sung, từ đồng nghĩa và sửa lỗi chính tả), hãy đặt
QueryInterpretationConfig.force_verbatim_mode
thànhtrue
trong ứng dụng tìm kiếm.Để tắt tất cả tính năng tối ưu hoá ở cấp cụm từ tìm kiếm (bao gồm cả kết quả bổ sung, từ đồng nghĩa và sửa lỗi chính tả), hãy đặt
QueryInterpretationOptions.enableVerbatimMode
thànhtrue
trong cụm từ tìm kiếm.Để tắt kết quả bổ sung ở cấp ứng dụng tìm kiếm, hãy đặt
QueryInterpretationOptions.forceDisableSupplementalResults
thànhtrue
trong cụm từ tìm kiếm.Để tắt kết quả bổ sung ở cấp cụm từ tìm kiếm, hãy đặt
QueryInterpretationOptions.disableSupplementalResults
thànhtrue
trong cụm từ tìm kiếm.
Làm nổi bật đoạn trích
Đối với các mục được trả về có chứa văn bản được lập chỉ mục hoặc nội dung HTML, một đoạn mã của nội dung sẽ được trả về. Nội dung này giúp người dùng xác định mức độ liên quan của mục được trả về.
Nếu cụm từ truy vấn có trong đoạn mã, thì một hoặc nhiều phạm vi khớp xác định vị trí của cụm từ cũng sẽ được trả về.
Sử dụng matchRanges
để đánh dấu văn bản trùng khớp khi hiển thị kết quả. Ví dụ JavaScript sau đây chuyển đổi đoạn mã thành mã đánh dấu HTML, trong đó mỗi dải ô phù hợp được đặt trong một thẻ <span>
.
function highlightSnippet(snippet) {
let text = snippet.snippet;
let formattedText = text;
if (snippet.matchRanges) {
let parts = [];
let index = 0;
for (let match of snippet.matchRanges) {
let start = match.start || 0; // Default to 0 if omitted
let end = match.end;
if (index < start) { // Include any leading text before/between ranges
parts.push(text.slice(index, start));
}
parts.push('<span class="highlight">');
parts.push(text.slice(start, end));
parts.push('</span>');
index = end;
}
parts.push(text.slice(index)); // Include any trailing text after last range
formattedText = parts.join('');
}
return formattedText;
}
Cho đoạn mã:
{
"snippet": "This is an example snippet...",
"matchRanges": [
{
"start": 11,
"end": 18
}
]
}
Chuỗi HTML thu được là:
This is an <span class="highlight">example</span> snippet...
Siêu dữ liệu đang hiển thị
Sử dụng trường metadata
để hiện thêm thông tin về mục được trả về có thể liên quan đến người dùng. Trường metadata
bao gồm createTime
và updateTime
của mục cũng như mọi dữ liệu có cấu trúc có thể trả về liên kết với mục đó.
Để hiển thị dữ liệu có cấu trúc, hãy sử dụng trường displayOptions
. Trường displayOptions
chứa nhãn hiển thị cho loại đối tượng và một tập hợp metalines
. Mỗi metaline là một mảng gồm các nhãn hiển thị và cặp giá trị như được định cấu hình trong giản đồ.
Truy xuất kết quả bổ sung
Để truy xuất kết quả bổ sung, hãy đặt trường start
trong yêu cầu thành độ lệch mong muốn. Bạn có thể điều chỉnh kích thước của từng trang bằng trường pageSize
.
Để hiện số lượng mục được trả về hoặc để hiện các chế độ điều khiển phân trang cho trang thông qua các mục được trả về, hãy sử dụng trường resultCount
. Tuỳ thuộc vào kích thước của tập hợp kết quả, giá trị thực tế hoặc giá trị ước tính sẽ được cung cấp.
Sắp xếp kết quả
Sử dụng trường sortOptions
để chỉ định thứ tự của các mục được trả về. Giá trị sortOptions
là một đối tượng có 2 trường:
operatorName
– một toán tử để sắp xếp theo thuộc tính dữ liệu có cấu trúc. Đối với các thuộc tính có nhiều toán tử, bạn chỉ có thể sắp xếp bằng toán tử bằng chính.sortOrder
– hướng để sắp xếp,ASCENDING
hoặcDESCENDING
.
Mức độ liên quan cũng được dùng làm khoá sắp xếp phụ. Nếu không có thứ tự sắp xếp nào được chỉ định trong truy vấn, các kết quả sẽ chỉ được xếp hạng theo mức độ liên quan.
"sortOptions": {
"operatorName": "priority",
"sortOrder": "DESCENDING"
}
Thêm bộ lọc
Ngoài biểu thức truy vấn, bạn có thể hạn chế thêm kết quả bằng cách áp dụng bộ lọc. Bạn có thể chỉ định các bộ lọc cả trong ứng dụng tìm kiếm cũng như trong yêu cầu tìm kiếm.
Để thêm bộ lọc vào yêu cầu hoặc ứng dụng tìm kiếm, hãy thêm bộ lọc vào trường dataSourceRestrictions.filterOptions[]
.
Có 2 cách chính để lọc thêm một nguồn dữ liệu:
- Các bộ lọc đối tượng, thông qua thuộc tính
filterOptions[].objectType
— hạn chế các mục trùng khớp với loại đã chỉ định như được xác định trong giản đồ tuỳ chỉnh. - Bộ lọc giá trị – hạn chế các mục trùng khớp dựa trên toán tử truy vấn và giá trị được cung cấp.
Bộ lọc tổng hợp cho phép kết hợp nhiều bộ lọc giá trị vào biểu thức logic cho các truy vấn phức tạp hơn.
Trong ví dụ về giản đồ phim, bạn có thể áp dụng giới hạn về độ tuổi dựa trên người dùng hiện tại và hạn chế các bộ phim có sẵn dựa trên mức phân loại của MPAA.
{
"query": "adventure",
"requestOptions": {
"searchApplicationId": "<search_app_id>"
},
"dataSourceRestrictions": [
{
"source": {
"name": "datasources/<data_source_id>"
},
"filterOptions": [
{
"objectType": "movie",
"filter": {
"compositeFilter": {
"logicOperator": "AND"
"subFilters": [
{
"compositeFilter": {
"logicOperator": "OR"
"subFilters": [
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "G"
}
}
},
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "PG"
}
}
}
]
}
]
}
}
}
]
}
]
}
Tinh chỉnh kết quả với các thuộc tính
Thuộc tính là các thuộc tính được lập chỉ mục, đại diện cho các danh mục để tinh chỉnh kết quả tìm kiếm. Sử dụng các thuộc tính để giúp người dùng tinh chỉnh truy vấn của họ theo cách tương tác và tìm thấy các mục liên quan nhanh hơn.
Bạn có thể xác định các thuộc tính trong ứng dụng tìm kiếm và bị chế độ cài đặt trong truy vấn ghi đè.
Khi yêu cầu các thuộc tính, Cloud Search sẽ tính toán các giá trị thường xuyên nhất cho các thuộc tính được yêu cầu trong số các mục trùng khớp. Các giá trị này được trả về trong phản hồi. Hãy sử dụng các giá trị này để tạo bộ lọc nhằm thu hẹp kết quả cho các truy vấn tiếp theo.
Mẫu tương tác điển hình có các thuộc tính là:
- Tạo một truy vấn ban đầu chỉ định những thuộc tính cần đưa vào kết quả thuộc tính.
- Hiển thị kết quả tìm kiếm và thuộc tính.
- Người dùng chọn một hoặc nhiều giá trị thuộc tính để tinh chỉnh kết quả.
- Lặp lại truy vấn với một bộ lọc dựa trên các giá trị đã chọn.
Ví dụ: để bật tính năng tinh chỉnh các truy vấn phim theo năm và mức phân loại của MPAA, hãy thêm thuộc tính facetOptions
vào truy vấn.
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
Kết quả thuộc tính với các trường dựa trên số nguyên
Bạn cũng có thể thuộc tính kết quả yêu cầu với các trường dựa trên số nguyên. Ví dụ: bạn có thể đánh dấu một thuộc tính số nguyên có tên là book_pages
là có thể chỉnh sửa để tinh chỉnh kết quả cho lượt tìm kiếm về sách có trang "100-200".
Khi thiết lập giản đồ trường thuộc tính số nguyên, hãy đặt isFacetable
thành true
và thêm các tuỳ chọn phân bộ chứa tương ứng vào integerPropertyOptions
.
Điều này đảm bảo rằng mọi thuộc tính có thể định dạng số nguyên đều có các tuỳ chọn phân nhóm mặc định được xác định.
Khi xác định logic các lựa chọn phân nhóm, hãy cung cấp một mảng các giá trị gia tăng biểu thị phạm vi. Ví dụ: nếu người dùng cuối chỉ định các dải ô là 2, 5, 10, 100
, thì các thuộc tính cho <2
, [2-5)
, [5-10)
, [10-100)
, >=100
sẽ được tính.
Bạn có thể ghi đè các thuộc tính dựa trên số nguyên bằng cách xác định các tuỳ chọn phân bộ chứa tương tự cho facetOptions
trong yêu cầu. Nếu cần, Cloud Search sẽ sử dụng các tuỳ chọn phân bộ chứa được xác định trong giản đồ khi cả ứng dụng tìm kiếm và yêu cầu truy vấn đều không xác định các tuỳ chọn thuộc tính. Các thuộc tính được xác định trong truy vấn được ưu tiên hơn các thuộc tính được xác định trong ứng dụng tìm kiếm, còn các thuộc tính được xác định trong ứng dụng tìm kiếm được ưu tiên hơn các thuộc tính được xác định trong giản đồ.
Kết quả thuộc tính theo ngày hoặc kích thước tài liệu
Bạn có thể sử dụng các toán tử dành riêng để tinh chỉnh kết quả tìm kiếm theo kích thước tệp của tài liệu, được đo bằng byte hoặc theo thời điểm tạo hay sửa đổi tài liệu. Bạn không cần xác định giản đồ tuỳ chỉnh, nhưng cần chỉ định giá trị operatorName
trong FacetOptions
của ứng dụng tìm kiếm.
- Để phân lớp theo kích thước tài liệu, hãy sử dụng
itemsize
và xác định các tuỳ chọn phân bộ chứa. - Để thêm khía cạnh theo ngày tạo tài liệu, hãy sử dụng
createddatetimestamp
. - Để chỉnh sửa khía cạnh theo ngày sửa đổi tài liệu, hãy sử dụng
lastmodified
.
Diễn giải nhóm thuộc tính
Thuộc tính facetResults
trong phản hồi cụm từ tìm kiếm bao gồm yêu cầu bộ lọc chính xác của người dùng trong trường filter
cho mỗi bucket
.
Đối với các thuộc tính không dựa trên số nguyên, facetResults
sẽ bao gồm một mục nhập cho từng thuộc tính được yêu cầu. Một danh sách các giá trị hoặc dải ô có tên là buckets
sẽ được cung cấp cho mỗi thuộc tính. Các giá trị xảy ra thường xuyên nhất sẽ xuất hiện đầu tiên.
Khi người dùng chọn một hoặc nhiều giá trị để lọc, hãy tạo một truy vấn mới bằng các bộ lọc đã chọn và truy vấn lại API.
Thêm đề xuất
Sử dụng API đề xuất để cung cấp tính năng tự động hoàn tất cho các truy vấn dựa trên nhật ký truy vấn cá nhân của người dùng cũng như danh bạ và tập sao lục tài liệu của họ.
Ví dụ: lệnh gọi sau đây đưa ra đề xuất cho cụm từ một phần jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Sau đó, bạn có thể hiển thị các đề xuất thu được phù hợp với ứng dụng của mình.