API Truy vấn cung cấp phương thức tìm kiếm và đề xuất để tạo một lượt tìm kiếm giao diện 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 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 tiế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, 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 mỗi ứng dụng giao diện tìm kiếm bạn tạo. Ứng dụng tìm kiếm cung cấp chế độ cài đặt mặc định tham số cho truy vấn, chẳng hạn như nguồn dữ liệu cần sử dụng, thứ tự sắp xếp, bộ lọc và thuộc tính muốn yêu cầu. Nếu cần, bạn có thể ghi đè các thông số này thông qua 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 Tùy 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 Đị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 đăng nhập 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 danh tính của Google](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.
Truy vấn chỉ mục
Sử dụng 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 hai thông tin: một văn bản query
để so khớp các mục với searchApplicationId
và xác định mã nhận dạng cho
ứng dụng tìm kiếm để sử 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
dưới dạng
cũng như đường liên kết đến tin gốc. Bạn có thể cải thiện hơn nữa hiển thị của
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
chẳng hạn 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 có
không đủ kết quả cho truy vấn của người dùng. Chiến lược phát hành đĩa đơn
queryInterpretation
trong phản hồi cho biết thời điểm kết quả bổ sung được trả về. Nếu chỉ
kết quả bổ sung được trả về, InterpretationType
được thiết lập 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 thông tin bổ sung
kết quả, InterpretationType
được đặt thành BLEND
. Trong cả hai trường hợp
QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
.
Khi hệ thống trả về một số kết quả bổ sung, hãy cân nhắc việc cung cấp nội dung
để cho biết 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 "Bạn đã tìm kiếm cụm từ tìm kiếm ban đầu của mình
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 "Bạn đã tìm kiếm
truy vấn ban đầu không phù hợp với đủ kết quả. Bao gồm kết quả cho các cụm từ tương tự
truy vấn."
Xử lý kết quả về người
Cloud Search trả về hai loại "kết quả về người": tài liệu liên quan đến một
người có tên được sử dụng trong truy vấn và thông tin về nhân viên của một người
có tên được sử dụng trong truy vấn. Loại kết quả thứ hai là một hàm của Đám mây
Tính năng Tìm kiếm người của Google Tìm kiếm và các kết quả cho truy vấn như vậy có thể được tìm thấy trong
thời gian
structuredResults
trường của một phản hồi API truy vấn:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
So khớp báo cáo trực tiếp
Đối sánh báo cáo trực tiếp là tính năng Tìm kiếm người của Cloud Search cho phép
người dùng xem báo cáo trực tiếp của từng người trong tổ chức của họ.
Kết quả có trong trường structuredResults
.
Đối với các câu hỏi 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, câu trả lời sẽ có
assistCardProtoHolder
trong structuredResults
. Chiến lược phát hành đĩa đơn
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ế.
Tệp này chứa subject
(người được đưa vào truy vấn) và
relatedPeople
là nhóm người có liên quan đến chủ đề này. Chiến lược phát hành đĩa đơn
Trường relationType
trả về giá trị MANAGER
hoặc DIRECT_REPORTS
.
Mã sau đây là một phản hồi mẫu cho một báo cáo trực tiếp khớp với truy vấn:
{
"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. Bạn có thể tuy nhiên, hãy tắt tất cả tính năng tối ưu hoá hoặc chỉ kết quả bổ sung ở cấp ứng dụng tìm kiếm và cấp truy vấn:
Để tắt tất cả tính năng tối ưu hoá ở cấp ứng dụng tìm kiếm, bao gồm bao gồm kết quả bổ sung, từ đồng nghĩa, và sửa lỗi chính tả, đặt
QueryInterpretationConfig.force_verbatim_mode
vàotrue
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 kết quả bổ sung, từ đồng nghĩa và sửa lỗi chính tả, đặt
QueryInterpretationOptions.enableVerbatimMode
vàotrue
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
vàotrue
trong cụm từ tìm kiếm.Để tắt kết quả bổ sung ở cấp truy vấn tìm kiếm, hãy đặt
QueryInterpretationOptions.disableSupplementalResults
vàotrue
trong cụm từ tìm kiếm.
Làm nổi bật đoạn trích
Đối với các mặt hàng được trả về có chứa văn bản được lập chỉ mục hoặc nội dung HTML, hãy viết một đoạn mã của nội dung đượ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ả lại.
Nếu cụm từ truy vấn có trong đoạn mã, thì một hoặc nhiều phạm vi kết hợp sẽ xác định vị trí của các cụm từ cũng được trả về.
Sử dụng matchRanges
để đánh dấu văn bản trùng khớp khi kết xuất
kết quả. Ví dụ javascript sau đây chuyển đổi đoạn mã thành
Mã đánh dấu HTML với 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 metadata
để hiển thị thêm thông tin về mặt hàng được trả lại mà có thể liên quan
cho người dùng. Trường metadata
bao gồm createTime
và
updateTime
của mặt hàng cũng như mọi dữ liệu có cấu trúc có thể trả về được liên kết
với mục đó.
Để hiển thị dữ liệu có cấu trúc, hãy sử dụ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 các nhãn hiển thị và
các 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 start
trong yêu cầu đến độ lệch mong muốn. Bạn có thể điều chỉnh kích thước
của mỗi trang có pageSize
.
Để hiện số lượng mục được trả về hoặc để hiển thị các chế độ điều khiển phân trang
thông qua các mục trả về, hãy sử dụng
resultCount
. Tuỳ thuộc vào kích thước của nhóm kết quả, giá trị thực tế hoặc
thì giá trị ước tính sẽ được cung cấp.
Phân loại kết quả
Sử dụng sortOptions
để chỉ định thứ tự các mặt hàng được trả lại. Giá trị sortOptions
là một đối tượng có hai 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 những thuộc tính có nhiều toán tử, bạn chỉ có thể sắp xếp bằng cách sử dụng phương trình chính toán tử.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 một cụm từ tìm kiếm, các kết quả chỉ được xếp hạng theo mức độ phù hợp.
"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ế hơn nữa kết quả bằng cách áp dụng bộ lọc. Bạn có thể chỉ định 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
— các hạn chế so khớp các mục với loại được chỉ định như được xác định trong giản đồ tùy 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 để có thêm các truy vấn phức tạp.
Trong ví dụ về giản đồ phim, bạn có thể áp dụng giới hạn độ 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
Các 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 kết quả. Sử dụng các thuộc tính để giúp người dùng tinh chỉnh cụm từ tìm kiếm và tìm kiếm theo cách tương tác 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 của Google. và bị ghi đè bởi chế độ cài đặt trong truy vấn của bạn.
Khi yêu cầu các thuộc tính, Cloud Search tính toán các giá trị thường xuyên nhất cho các thuộc tính thuộc tính được yêu cầu trong số các mục phù hợp. Các được trả về trong phản hồi. Sử dụng các giá trị này để tạo bộ lọc để thu hẹp kết quả ở 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 thuộc tính nào cần đưa vào thuộc tính kết quả.
- 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,
đưa 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ả tìm kiếm về những cuốn sách có "100-200" .
Khi bạn thiết lập giản đồ trường thuộc tính số nguyên, hãy đặt
isFacetable
vào true
rồi thêm các tuỳ chọn phân nhóm tương ứng vào
integerPropertyOptions
.
Điều này đảm bảo rằng mọi thuộc tính có thể tương tác với số nguyên đều có bộ chứa mặc định
đã xác định các tùy chọn.
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
phạm vi biểu thị. Ví dụ: nếu người dùng cuối chỉ định các dải ô là
2, 5, 10, 100
, sau đó là các thuộc tính cho <2
, [2-5)
, [5-10)
, [10-100)
, >=100
được tính toán.
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 nhóm tương tự cho
facetOptions
trong yêu cầu. Nếu được yêu cầu, 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 có thuộc tính
đã xác định các tùy chọn. 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 đã xác định
trong ứng dụng tìm kiếm và các thuộc tính được xác định trong ứng dụng tìm kiếm sẽ
mức độ ưu tiên so với 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
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ài liệu đã được tạo hoặc sửa đổi. Bạn không cần xác định giản đồ tuỳ chỉnh,
nhưng bạn cần chỉ định giá trị operatorName
trong thẻ
FacetOptions
.
- Để 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
facetResults
thuộc tính trong phản hồi truy vấn 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
bao gồm một mục nhập cho
từng thuộc tính được yêu cầu. Đối với mỗi thuộc tính, một danh sách các giá trị hoặc dải ô được gọi là
buckets
, đã được cung cấp. 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 API một lần nữa.
Thêm đề xuất
Sử dụng API Đề xuất để cung cấp tính năng tự động hoàn tất cho truy vấn dựa trên thông tin cá nhân của người dùng lịch sử truy vấn cũng như địa chỉ liên hệ và tập sao lục tài liệu của họ.
Ví dụ: lệnh gọi sau đưa ra đề xuất cho phần cụm từ jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Sau đó, bạn có thể hiển thị đề xuất thu được khi phù hợp với .