Trang này được dịch bởi Cloud Translation API.

Tạo giao diện tìm kiếm bằng Query API (API Truy vấn)

Query API cung cấp các phương thức tìm kiếm và đề xuất để tạo giao diện tìm kiếm hoặc nhúng kết quả tìm kiếm vào 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 bài viết Tạo giao diện tìm kiếm bằng tiện ích tìm kiếm

Tạo giao diện tìm kiếm

Để tạo một giao diện tìm kiếm tối giản, bạn cần thực hiện một số bước:

Định cấu hình ứng dụng tìm kiếm
Tạo thông tin xác thực 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 thêm giao diện tìm kiếm bằng các tính năng như phân trang, sắp xếp, lọc, khía cạnh và đề xuất tự động.

Đị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 giao diện tìm kiếm mà bạn tạo. Ứng dụng tìm kiếm cung cấp các tham số mặc định cho một 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à khía cạnh cần yêu cầu. Nếu cần, bạn có thể ghi đè các thông số này bằ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 xác thực OAuth cho ứng dụng

Ngoài các bước trong phần Định cấu hình quyền truy cập vào API Google Cloud Search, 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 mà API được dùng.

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 lựa 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 phần 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 cần sử dụng.

Đoạn mã sau đây cho thấy 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

Ít nhất, các giao diện tìm kiếm phải hiển thị mục title cũng như đường liên kết đến mục ban đầu. Bạn có thể cải thiện hơn nữa cách 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, 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 sẽ trả về kết quả bổ sung khi không có đủ kết quả cho cụm từ tìm kiếm 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ỉ có kết quả bổ sung được trả về, 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 kết quả bổ sung, thì InterpretationType sẽ được đặt thành BLEND. Trong cả hai trường hợp 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 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 "Cụm từ tìm kiếm ban đầu của bạn không khớp với kết quả nào. Đang hiển thị kết quả cho những 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 "Cụm từ tìm kiếm của bạn cho cụm từ tìm kiếm ban đầu không khớp với đủ kết quả. Bao gồm cả 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 dùng": tài liệu liên quan đến một người có tên được dùng trong cụm từ tìm kiếm và thông tin nhân viên của một người có tên được dùng trong cụm từ tìm kiếm. 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 dùng của Cloud Search và kết quả cho truy vấn như vậy có thể được tìm thấy trong trường structuredResults của phản hồi API truy vấn:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

So khớp nhân viên cấp dưới trực tiếp

Tính năng Tìm kiếm nhân viên cấp dưới trực tiếp là một tính năng Tìm kiếm người dùng của Cloud Search, cho phép người dùng xem nhân viên cấp dưới trực tiếp của một người trong 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 của một người, câu trả lời sẽ có biểu tượng 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ế. Kết quả này chứa subject (người có trong cụm từ tìm kiếm) và relatedPeople là nhóm người có liên quan đến chủ đề. Trường relationType trả về giá trị MANAGER hoặc DIRECT_REPORTS.

Đoạn mã sau đây cho thấy một phản hồi mẫu cho truy vấn so khớp 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 các chế độ tối ưu hoá, bao gồm cả kết quả bổ sung

Theo mặc định, các hoạt độ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 tất cả các hoạt động tối ưu hoá hoặc chỉ tắt 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 tất cả các hoạt độ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à lỗi chính tả, hãy đặt QueryInterpretationConfig.force_verbatim_mode thành true trong các ứng dụng tìm kiếm.
Để tắt tất cả các hoạt độ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à lỗi chính tả, hãy đặt QueryInterpretationOptions.enableVerbatimMode thành true 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ành true 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ành true 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 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ặt hàng được trả về.

Nếu có các cụm từ tìm kiếm trong đoạn trích, thì một hoặc nhiều dải trùng khớp xác định vị trí của các cụm từ đó cũng sẽ được trả về.

Sử dụng matchRanges để làm nổi bật văn bản trùng khớp khi hiển thị kết quả. Ví dụ sau đây về javascript sẽ chuyển đổi đoạn mã thành mã đánh dấu HTML, trong đó mỗi dải ô khớp được gói trong 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 trước đoạn mã:

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

Chuỗi HTML kết quả 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ị thông tin bổ sung về mặt hàng đượ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ặ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ặt hàng.

Để 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 dòng siêu dữ liệu 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 thêm kết quả

Để truy xuất thêm kết quả, 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 thị số lượng mặt hàng được trả về hoặc hiển thị các chế độ kiểm soát phân trang để phân trang qua các mặt hàng được trả về, hãy sử dụng trường resultCount. Tuỳ thuộc vào quy mô của tập kết quả, giá trị thực tế hoặc giá trị ước tính sẽ được cung cấp.

Phân loại 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ử cho thuộc tính dữ liệu có cấu trúc để sắp xếp theo. Đố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 toán tử so sánh bằng chính.
sortOrder – hướng sắp xếp, có thể là ASCENDING hoặc DESCENDING.

Mức độ liên quan cũng được dùng làm khoá sắp xếp phụ. Nếu bạn không chỉ định thứ tự sắp xếp trong một cụm từ tìm kiếm, thì kết quả 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 bộ lọc trong cả ứng dụng tìm kiếm cũng như trong yêu cầu tìm kiếm.

Để thêm bộ lọc trong một 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:

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 theo loại được chỉ định như được xác định trong một giản đồ tuỳ chỉnh.
Bộ lọc giá trị – hạn chế các mục phù hợp dựa trên toán tử truy vấn và giá trị được cung cấp.

Bộ lọc kết hợp cho phép kết hợp nhiều bộ lọc giá trị thành các 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 một ràng buộc về độ tuổi dựa trên người dùng hiện tại và hạn chế những 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ả bằng các khía cạnh

Các khía cạnh là những 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 khía cạnh để giúp người dùng tinh chỉnh cụm từ tìm kiếm một cách tương tác và tìm thấy các mặt hàng có liên quan nhanh hơn.

Bạn có thể xác định các khía cạnh trong ứng dụng tìm kiếm và ghi đè bằng các chế độ cài đặt trong truy vấn.

Khi yêu cầu các khía cạ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 phù hợp. Những giá trị này được trả về trong phản hồi. Sử dụng các giá trị này để tạo bộ lọc giúp thu hẹp kết quả trong các truy vấn tiếp theo.

Mẫu tương tác điển hình với các khía cạnh là:

Đưa ra một truy vấn ban đầu chỉ định những thuộc tính cần đưa vào kết quả của khía cạnh.
Kết xuất kết quả tìm kiếm và kết quả theo khía cạnh.
Người dùng chọn một hoặc nhiều giá trị khía cạnh để tinh chỉnh kết quả.
Lặp lại truy vấn với bộ lọc dựa trên các giá trị đã chọn.

Ví dụ: để cho phép tinh chỉnh các cụm từ tìm kiếm về phim theo năm và mức phân loại của Hiệp hội điện ảnh Hoa Kỳ (MPAA), hãy thêm thuộc tính facetOptions vào cụm từ tìm kiếm.

"facetOptions": [
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "year"
  },
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "rated"
  }
]

Bạn cũng có thể phân nhóm kết quả yêu cầu bằng 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ể phân loại để tinh chỉnh kết quả cho một cụm từ tìm kiếm về sách có "100-200" trang.

Khi bạn 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 lựa 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ể phân loại theo khía cạnh số nguyên đều có các lựa chọn phân nhóm mặc định được xác định.

Khi xác định logic của 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ị các dải giá trị. Ví dụ: nếu người dùng cuối chỉ định các dải là 2, 5, 10, 100, thì các khía cạnh cho <2, [2-5), [5-10), [10-100), >=100 sẽ được tính toán.

Bạn có thể ghi đè các khía cạnh dựa trên số nguyên bằng cách xác định các lựa chọn phân nhóm tương tự cho facetOptions trong yêu cầu. Nếu cần, Cloud Search sẽ sử dụng các lựa chọn phân nhóm đượ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ó các lựa chọn khía cạnh được xác định. Các khía cạnh được xác định trong truy vấn sẽ được ưu tiên hơn các khía cạnh được xác định trong ứng dụng tìm kiếm, còn các khía cạnh được xác định trong ứng dụng tìm kiếm sẽ được ưu tiên hơn các khía cạnh được xác định trong giản đồ.

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 (tính 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 một giản đồ tuỳ chỉnh, nhưng bạn cần chỉ định giá trị operatorName trong FacetOptions của ứng dụng tìm kiếm.

Để phân loại theo kích thước tài liệu, hãy sử dụng itemsize và xác định các lựa chọn phân loại.
Để phân loại theo ngày tạo tài liệu, hãy sử dụng createddatetimestamp.
Để phân nhóm 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ủa cụm từ tìm kiếm bao gồm yêu cầu 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 khía cạnh không dựa trên số nguyên, facetResults bao gồm một mục 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 giá trị (gọi là buckets) sẽ được cung cấp. Các giá trị xuất hiện 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 thành cho các cụm từ tìm kiếm dựa trên nhật ký cụm từ tìm kiếm cá nhân của người dùng cũng như danh bạ và kho tài liệu của họ.

Ví dụ: lệnh gọi sau đây sẽ đưa ra các đề 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 một cách phù hợp cho ứng dụng của mình.

Tạo giao diện tìm kiếm bằng Query API (API Truy vấn)

Tạo giao diện tìm kiếm

Định cấu hình ứng dụng tìm kiếm

Tạo thông tin xác thực OAuth cho ứng dụng

Truy vấn chỉ mục

Hiển thị kết quả truy vấn

Xử lý kết quả bổ sung

Xử lý kết quả về người

So khớp nhân viên cấp dưới trực tiếp

Tắt các chế độ tối ưu hoá, bao gồm cả kết quả bổ sung

Làm nổi bật đoạn trích

Siêu dữ liệu đang hiển thị

Truy xuất thêm kết quả

Phân loại kết quả

Thêm bộ lọc

Tinh chỉnh kết quả bằng các khía cạnh

Kết quả phân loại theo khía cạnh có các trường dựa trên số nguyên

Phân loại kết quả theo kích thước hoặc ngày của tài liệu

Diễn giải nhóm thuộc tính

Thêm đề xuất

Tạo giao diện tìm kiếm bằng Query API (API Truy vấn) Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Tạo giao diện tìm kiếm

Định cấu hình ứng dụng tìm kiếm

Tạo thông tin xác thực OAuth cho ứng dụng

Truy vấn chỉ mục

Hiển thị kết quả truy vấn

Xử lý kết quả bổ sung

Xử lý kết quả về người

So khớp nhân viên cấp dưới trực tiếp

Tắt các chế độ tối ưu hoá, bao gồm cả kết quả bổ sung

Làm nổi bật đoạn trích

Siêu dữ liệu đang hiển thị

Truy xuất thêm kết quả

Phân loại kết quả

Thêm bộ lọc

Tinh chỉnh kết quả bằng các khía cạnh

Kết quả phân loại theo khía cạnh có các trường dựa trên số nguyên

Phân loại kết quả theo kích thước hoặc ngày của tài liệu

Diễn giải nhóm thuộc tính

Thêm đề xuất

Tạo giao diện tìm kiếm bằng Query API (API Truy vấn)