此页面由 Cloud Translation API 翻译。

使用 Query API 创建搜索界面

Query API 提供搜索和建议方法，用于构建搜索界面或在应用中嵌入搜索结果。

对于要求最低的 Web 应用，请考虑使用搜索微件。如需了解详情，请参阅使用搜索微件创建搜索界面

构建搜索界面

构建最小的搜索界面需要执行以下几个步骤：

配置搜索应用
为应用生成 OAuth 凭据
查询索引
显示查询结果

此外，您可以进一步增强搜索界面，为其添加分页、排序、过滤、属性和自动建议等功能。

配置搜索应用

您必须创建至少一个搜索应用以便关联您创建的每个搜索界面。搜索应用会提供默认的查询参数，例如要使用的数据源、排序顺序过滤条件和要请求的分面。如果需要，您可以替换这些参数查询 API。

有关搜索应用的详细信息，请参阅自定义 Cloud Search 中的搜索体验。

为应用生成 OAuth 凭据

除了配置对 Google Cloud Search API 的访问权限。您还必须为 Web 应用生成 OAuth 凭据。您创建的凭据类型取决于使用 API 的上下文。

使用这些凭据即可代表用户请求授权。使用请求范围为 https://www.googleapis.com/auth/cloud_search.query 时授权。

如需详细了解 OAuth 选项和客户端库，请参阅 [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}）。

查询索引

使用 search 方法对索引执行搜索。

每个请求必须包含两条信息：query 以及用于标识商品 ID 的 searchApplicationId 要使用的搜索应用。

以下代码段展示了对电影《泰坦尼克号》的电影数据源的查询：

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

显示查询结果

搜索界面至少应将商品 title 显示为以及指向原始内容的链接。您可以进一步增强通过利用搜索结果中的其他信息来获得搜索结果例如代码段和元数据

处理补充结果

默认情况下，如果存在以下情况，Cloud Search 会返回补充结果用户的查询结果不足。通过 queryInterpretation 字段指明何时返回补充结果。如果仅系统会返回补充结果，此时 InterpretationType 会设置为 REPLACE。如果系统会返回原始查询的一些结果，结果，InterpretationType 设置为 BLEND。无论是哪种情况 QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY。

返回一些补充结果时，请考虑提供文本来指示已返回补充结果。例如，假设 REPLACE，则可以显示字符串“Your search for your original query was 与任何结果都不匹配。目前显示的是类似查询的搜索结果。”

对于 BLEND，您可能要显示字符串“您的搜索没有匹配的结果。包含类似内容的搜索结果查询。”

处理人员搜索结果

Cloud Search 会返回两种类型的“人员搜索结果”：查询中使用的姓名和某个人的员工信息查询中使用了该实体的名称。后一种结果类型是 Cloud Google 搜索的人物搜索功能以及此类查询的结果可在以下位置找到： structuredResults 字段：

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

直接下属匹配

直接报告匹配是 Cloud Search 的人物搜索功能，用户可以看到其组织中某个人的直接下属。结果可在 structuredResults 字段中获取。

对于与某人的经理或直接下属有关的查询，响应中包含 structuredResults 中的 assistCardProtoHolder。通过 assistCardProtoHolder 具有一个名为 cardType 的字段，该字段等于 RELATED_PEOPLE_ANSWER_CARD。assistCardProtoHolder包含一张卡片名为 relatedPeopleAnswerCard，其中包含实际响应。它包含 subject（查询中包含的人员）和 relatedPeople 表示与主题相关的一组人员。通过 relationType 字段返回值 MANAGER 或 DIRECT_REPORTS。

以下代码展示了与直接下属匹配的查询：

{
  "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",
        }
      }
    }
  }]
}

停用优化功能，包括补充结果

默认情况下，系统会启用优化（例如补充结果）。您可以但是，请在搜索应用和查询级别：

要在搜索应用一级停用所有优化功能，包括包括补充结果、同义词和拼写更正, 设置 QueryInterpretationConfig.force_verbatim_mode true。
要在搜索查询一级停用所有优化功能，包括补充结果、同义词和拼写更正，设置 QueryInterpretationOptions.enableVerbatimMode true。
要在搜索应用级别关闭补充结果，请将 QueryInterpretationOptions.forceDisableSupplementalResults true。
要在搜索查询级别关闭补充结果，请将 QueryInterpretationOptions.disableSupplementalResults true。

突出显示片段

对于包含已编入索引的文本或 HTML 内容的返回项，界面将返回内容摘要。此内容可帮助用户确定返回项的相关性。

如果摘要中存在查询字词，则界面还会返回标识字词位置的一个或多个匹配范围。

在渲染时使用 matchRanges 突出显示匹配的文本结果。以下 JavaScript 示例将代码段转换为 HTML 标记，每个匹配范围都包含在 <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;
}

对于下面的片段：

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

生成的 HTML 字符串为：

This is an <span class="highlight">example</span> snippet...

显示元数据

使用 metadata 字段，用于显示可能相关的退货商品的其他信息。metadata 字段包含 createTime 和 updateTime 以及任何与之相关的可返回的结构化数据属性。

如需显示结构化数据，请使用 displayOptions 字段。displayOptions 字段包含对象类型的显示标签和一组 metalines。每个 Metaline 都是一个显示标签数组，值对（如架构中配置）。

检索其他结果

如需检索其他结果，请设置 start 字段设置为所需的偏移量。您可以调整 pageSize 字段。

显示返回项的数量或向对退货商品进行分页，使用 resultCount 字段。提供的值可能为实际值，也可能为估计值，具体取决于结果集的大小。

对结果排序

使用 sortOptions 字段以指定返回商品的顺序。sortOptions 值是一个包含两个字段的对象：

operatorName - 用于排序的结构化数据属性的运算符。对于具有多个运算符的属性，只能使用主相等性进行排序运算符。
sortOrder - 排序方向（ASCENDING 或 DESCENDING）。

相关性也会用作辅助排序键。如果查询中未指定排序顺序，则结果仅按相关性排序。

"sortOptions": {
  "operatorName": "priority",
  "sortOrder": "DESCENDING"
}

添加过滤条件

除了查询表达式之外，您还可以对结果应用过滤条件。您可以在搜索应用以及搜索请求中的结果。

要在请求或搜索应用中添加过滤器，请将过滤器添加到 dataSourceRestrictions.filterOptions[] 字段。

您可以通过以下两种主要方法进一步过滤数据源：

对象过滤条件，通过 filterOptions[].objectType 属性 - 限制将商品与自定义架构中定义的指定类型进行匹配。
值过滤条件 — 根据查询运算符和提供的值。

复合过滤器允许将多个值过滤器合并到逻辑表达式中，以实现更复杂的查询。

在电影架构示例中，您可以针对当前用户应用年龄限制，并根据 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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

使用属性优化结果

属性是指已编入索引的属性，表示用于优化搜索结果的类别。使用属性可以帮助用户以交互的方式优化查询，更快地查找相关项。

您可以在搜索应用。并被查询中的设置替换

在请求属性时，Cloud Search 会在匹配项中计算所请求属性最常出现的值。这些值会在响应中返回。您可以使用这些值构造过滤器，以便在后续查询中缩小结果范围。

属性的典型交互模式如下：

进行初始查询，指定要在属性结果中包含哪些属性。
呈现搜索和属性结果。
用户选择一个或多个属性值以优化结果。
根据所选的值构造过滤器，然后使用该过滤器重复查询。

。

例如，要按年份和 MPAA 分级优化电影查询，在查询中添加 facetOptions 属性。

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

您还可以使用基于整数的字段分面请求结果。例如，您可能会将名为 book_pages 的整数属性标记为可分面以进行优化搜索“100-200”图书的相关结果页面。

设置整数属性字段架构时，请将 isFacetable true，并将相应的分桶选项添加到 integerPropertyOptions。这可确保每个整数表属性都具有默认的分桶选项。

定义分桶选项逻辑时，请提供增量值数组表示范围。例如，如果最终用户将范围指定为 2, 5, 10, 100，然后是“<2”、“[2-5)”、“[5-10)”、“[10-100)”、“>=100”的分面。

您可以通过定义相同的分桶选项来替换基于整数的分面， facetOptions 。如果需要，Cloud Search 会使用搜索应用和查询请求都没有分面时的架构选项。查询中定义的商品详情优先于定义的商品详情，而搜索应用中定义的商品详情则采用优先级高于架构中定义的构面。

您可以使用预留运算符可按文档的文件大小、以字节为单位或者按照创建或修改了文档。您无需定义自定义架构但您需要在搜索应用的operatorName FacetOptions。

如需按文档大小分面，请使用 itemsize 并定义分桶选项。
如需按文档创建日期进行分面，请使用 createddatetimestamp。
如需按文档修改日期进行分面，请使用 lastmodified。

解读构面范围

facetResults 属性包含用户的确切过滤请求填写每个字段的filter字段 bucket。

对于并非基于整数的分面，facetResults 包含请求的每个属性。对于每个属性，都包含一个值或范围的列表，称为已提供 buckets。最常出现的值会优先显示。

当用户选择一个或多个值进行过滤时，使用所选过滤器构造新查询并再次查询 API。

添加建议

使用建议 API 根据用户的个人查询历史记录以及联系人及其文档语料库为查询提供自动补全功能。

例如，以下调用为部分短语 jo 提供了建议。

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

然后，您可以显示适合您的应用的建议。