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)

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ể nâng cao 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 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 "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 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ào true 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ào 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 vào true 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ào 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ặ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ặ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 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 sẽ 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"
  }
]

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 cụm từ 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 đồ.

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 các 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 .