Tạo giao diện tìm kiếm với API truy vấn

API truy vấn cung cấp phương thức tìm kiếm và đề xuất để tạo một 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 tạo giao diện tìm kiếm tối thiểu cần một số bước:

  1. Định cấu hình ứng dụng tìm kiếm
  2. Tạo thông tin xác thực OAuth cho ứng dụng
  3. Truy vấn chỉ mục
  4. Hiển thị kết quả truy vấn

Bạn có thể nâng cao hơn nữa 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, 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 giao diện tìm kiếm mà bạn tạo. Ứng dụng tìm kiếm cung cấp các thông số mặc định cho một truy vấn, chẳng hạn như các 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 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 xác thực bạn tạo phụ thuộc vào ngữ cảnh API được sử 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 tuỳ chọn OAuth và thư viện ứng dụng, hãy xem [Google Identity Platform](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 theo chỉ mục.

Mỗi yêu cầu phải bao gồm hai thông tin: văn bản query để so khớp các mục và searchApplicationId xác định mã nhận dạng để ứng dụng tìm kiếm sử dụng.

Đoạn mã sau đây cho thấy truy vấn về nguồn dữ liệu phim của bộ phim Titanic:

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  },
}

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

Theo dự kiến, giao diện tìm kiếm ít nhất 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 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 các 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 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 số kết quả cho truy vấn gốc đượ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, 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 của REPLACE, bạn có thể hiển thị chuỗi "Nội dung tìm kiếm ban đầu của bạn không khớp với bất kỳ kết quả nào. Hiện 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 cụm từ tìm kiếm ban đầu không khớp với đủ kết quả. Bao gồm kết quả cho các truy vấn tương tự."

Xử lý kết quả của mọi người

Cloud Search trả về hai loại "kết quả về người": tài liệu liên quan đến người có tên được sử dụng trong truy vấn và thông tin nhân viên cho người có tên trong truy vấn. Loại kết quả sau này là một hàm của tính năng Tìm người trong Cloud Search và kết quả cho một truy vấn như vậy có thể tìm thấy trong trường structuredResults của phản hồi API truy vấn:

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

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 tất cả tính năng tối ưu hoá hoặc chỉ kết quả bổ sung ở cả ứng dụng tìm kiếm và cấp truy vấn:

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

Đối với các mục được trả về chứa nội dung được lập chỉ mục hoặc văn bản đã lập chỉ mục, một đoạn trích 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 thuật ngữ truy vấn có trong đoạn mã, một hoặc nhiều phạm vi so khớp sẽ xác định vị trí của từ khoá cũng được trả về.

Sử dụng matchRanges để làm nổi bật văn bản phù hợp khi hiển thị kết quả. Ví dụ về JavaScript sau đây sẽ chuyển đổi đoạn mã thành mã đánh dấu HTML có từng phạm vi trùng 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 đ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 về màn hình

Sử dụng trường metadata để hiển thị thêm thông tin về mục được trả về có thể phù hợp với 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 nhóm metalines. Mỗi dòng meta là một mảng 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 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 mỗi trang bằng trường pageSize.

Để hiển thị số lượng mục được trả về hoặc để hiển thị các tuỳ chọn đ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ả, hệ thống sẽ cung cấp giá trị thực tế hoặc giá trị ước tính.

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ó hai 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 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ình đẳ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 không có thứ tự sắp xếp nào được chỉ định trong truy vấn, 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ế hơn nữa kết quả bằng cách áp dụng các 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:

  • Thông qua thuộc tính filterOptions[].objectType, bộ lọc đối tượng sẽ hạn chế các mục trùng khớp thuộc loại được chỉ định như đã 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ị đã cung cấp.

Bộ lọc tổng hợp cho phép kết hợp nhiều bộ lọc giá trị thành biểu thức logic cho nhiều truy vấn phức tạp hơn.

Trong ví dụ 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 phim có sẵn dựa trên xếp hạng 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 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ọ một cách tương tác và tìm các mục liên quan nhanh hơn.

Các thuộc tính có thể được xác định trong ứng dụng tìm kiếm và bị ghi đè bởi các chế độ cài đặt trong truy vấn của bạn.

Khi yêu cầu 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 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 với các thuộc tính là:

  1. 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.
  2. Hiển thị kết quả tìm kiếm và thuộc tính.
  3. Người dùng chọn một hoặc nhiều giá trị thuộc tính để tinh chỉnh kết quả.
  4. Lặp lại truy vấn bằng một bộ lọc dựa trên các giá trị đã chọn.

Ví dụ: để cho phép tinh chỉnh truy vấn phim theo năm và xếp hạng của MPAA, hãy đư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ể tìm thấy 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à đáng tin cậy để tinh chỉnh kết quả cho nội dung 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 tùy chọn bộ chứa tương ứng vào integerPropertyOptions. Việc này đảm bảo rằng mọi thuộc tính có thể so sánh được số nguyên đều có các tuỳ chọn phân bộ mặc định.

Khi xác định logic tùy chọn phân bộ chứa, hãy cung cấp một loạt các giá trị tăng dần biểu thị phạm vi. Ví dụ: nếu người dùng cuối chỉ định phạm vi 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 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ùng một tùy chọn phân nhóm 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ộ đượ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ác tuỳ chọn thuộc tính. Các thuộc tính được xác định trong truy vấn sẽ được ưu tiên hơn các thuộc tính được 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ẽ được ưu tiên hơn các thuộc tính được xác định trong giản đồ.

Thuộc tính kết quả theo kích thước hoặc ngày của tài liệu

Bạn có thể sử dụng toán tử đặt trước để 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 hoặc sửa đổi tài liệu. 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 FacetOptions của ứng dụng tìm kiếm.

  • Để phân chia theo kích thước tài liệu, hãy sử dụng itemsize và xác định các tùy chọn phân bộ chứa.
  • Để phân mặt theo ngày tạo tài liệu, hãy sử dụng createddatetimestamp.
  • Để hiển thị 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 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 từng 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 mỗi thuộc tính được yêu cầu. Danh sách giá trị (buckets) cho mỗi thuộc tính sẽ được cung cấp. Các giá trị thường xuyên xảy ra 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 thành 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ư địa chỉ liên hệ và kho tài liệu của họ.

Ví dụ: lệnh gọi sau đây đưa ra các đề xuất cho một 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ị các đề xuất kết quả phù hợp với ứng dụng của mình.