本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 正在部署 Amazon Kendra
**注意**
功能支持因所用索引类型和搜索 API 而异。要查看您使用的索引类型和搜索 API 是否支持此功能，请参阅[索引类型](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html)。
当需要将 Amazon Kendra 搜索部署到您的网站时，我们会提供源代码，您可以在 React 中使用这些源代码，以便在应用程序上抢占先机。根据 MIT 许可修订版，源代码免费提供。您可以按原样使用，也可以根据自己的需求进行更改。提供的 React 应用程序是帮助您入门的示例。该应用程序不能用于生产。
要部署无代码的搜索应用程序并生成具有访问控制功能的搜索页面的端点 URL，请参阅 [Amazon Kendra Experience Builder](https://docs.aws.amazon.com/kendra/latest/dg/deploying-search-experience-no-code.html)。
以下示例代码为现有的 React Web 应用程序添加了 Amazon Kendra 搜索功能：
+ [https://kendrasamples.s3.amazonaws.com/kendrasamples-react-app.zip](https://kendrasamples.s3.amazonaws.com/kendrasamples-react-app.zip) —开发人员可用于在其现有的 React Web 应用程序中构建功能搜索体验的示例文件。
这些示例以 Amazon Kendra 控制台的搜索页面为蓝本。它们具有相同的搜索和显示搜索结果的功能。您可以使用整个示例，也可以只选择其中一个功能来供自己使用。
要在 Amazon Kendra 控制台中查看搜索页面的三个组成部分，请从右侧菜单中选择代码图标 (****)。将鼠标指针悬停在各个部分上可查看组件的简短描述并获取组件源代码的 URL。
**Topics**
+ [
## 概述
](#example-overview)
+ [
## 先决条件
](#example-prereqs)
+ [
## 设置示例
](#example-install)
+ [
## 主搜索页面
](#main-component)
+ [
## 搜索组件
](#search-component)
+ [
## 结果组件
](#results-component)
+ [
## 分面组件
](#facets-component)
+ [
## 分页组件
](#pagination-component)
+ [
# 无需代码即可打造搜索体验
](deploying-search-experience-no-code.md)
## 概述
您可以将示例代码添加到现有 React Web 应用程序中来激活搜索。示例代码包括一个自述文件，其中包含设置新 React 开发环境的步骤。示例代码中的示例数据可用于演示搜索。示例代码中的搜索文件和组件结构如下：
+ 主搜索页面（`Search.tsx`）- 这是包含所有组件的主页。在这里，您可以将应用程序与 Amazon Kendra API 集成。
+ 搜索栏 - 这是用户输入搜索词并调用搜索功能的组件。
+ 结果-这是显示结果的组件。 Amazon Kendra它由三个部分组成：建议答案、常见问题解答结果和推荐文档。
+ 分面 - 该组件在搜索结果中显示分面，并允许您选择一个分面来缩小搜索范围。
+ 分页 - 这是对来自 Amazon Kendra的响应进行分页的组件。
## 先决条件
在开始之前，您需要：
+ [已安装](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) Node.js 和 npm。需要使用 Node.js 版本 19 或更早版本。
+ [已下载和安装](https://www.python.org/downloads/) Python 3 或 Python 2。
+ [适用于 Java 的 SDK](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html) 或 [适用于 JavaScript 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-javascript/latest/developer-guide/welcome.html)，以便对 Amazon Kendra调用 API。
+ 现有 React Web 应用程序。示例代码包括一个自述文件，其中包含有关如何设置新 React 开发环境的步骤（包括使用所需的框架/库）。您也可以按照 [React 文档中的快速入门说明创建 React Web 应用程序](https://create-react-app.dev/docs/getting-started)。
+ 在开发环境中配置的必需库和依赖项。示例代码包括一个自述文件，其中列出了所需的库和软件包依赖关系。请注意，`sass` 是必需的，因为已弃用 `node-sass`。如果您之前安装过 `node-sass`，请将其卸载并安装 `sass`。
## 设置示例
向 React 应用程序添加 Amazon Kendra 搜索功能的完整过程见代码示例中包含的自述文件。
**要开始使用 kendrasamples-react-app .zip**
1. 确保您已经完成[先决条件](#example-prereqs)，包括下载和安装 Node.js 和 npm。
1. 下载 kendrasamples-react-app .zip 并解压缩。
1. 打开您的终端并转到 `aws-kendra-example-react-app/src/services/`。打开 `local-dev-credentials.json` 并提供您的凭证。不要将此文件添加到任何公共存储库中。
1. 转到 `aws-kendra-example-react-app` 并在 `package.json` 中安装依赖项。运行 `npm install`。
1. 在本地服务器上启动应用程序的演示版。运行 `npm start`。在键盘上输入 `Cmd/Ctrl + C` 可停止本地服务器。
1. 您可以通过访问 `package.json` 并更新主机和端口来更改端口或主机（例如，IP 地址）：`"start": "HOST=[host] PORT=[port] react-scripts start"`。如果您使用的是 Windows：`"start": "set HOST=[host] && set PORT=[port] && react-scripts start"`。
1. 如果您有注册的网站域名，则可以在应用程序名称后的 `package.json` 中指定域名。例如 `"homepage": "https://mywebsite.com"`。必须再次运行 `npm install` 才能更新新的依赖项，然后运行 `npm start`。
1. 要构建应用程序，请运行 `npm build`。将构建目录中的内容上传到您的托管服务提供商。
**警告**
React 应用程序**未**准备好投入生产。这是部署用于 Amazon Kendra 搜索的应用程序的示例。
## 主搜索页面
主搜索页面（`Search.tsx`）包含所有示例搜索组件。它包括用于输出的搜索栏组件、用于显示来自 [Query](https://docs.aws.amazon.com/kendra/latest/APIReference/API_Query.html) API 的响应的结果组件，以及用于分页浏览响应的分页组件。
## 搜索组件
搜索组件提供了一个用于输入查询文本的文本框。`onSearch` 函数是一个钩子，它可以在 `Search.tsx` 中调用主函数来进行 Amazon Kendra [Query](https://docs.aws.amazon.com/kendra/latest/APIReference/API_Query.html) API 调用。
## 结果组件
结果组件显示来自 `Query` API 的响应。结果显示在三个不同的区域中。
+ 建议答案 - 这些是 `Query` API 返回的热门结果。它最多包含三个建议的答案。在响应中，它们的结果类型为 `ANSWER`。
+ 常见问题答案-这些是回复返回的常见问题解答结果。 FAQs 分别添加到索引中。在响应中，它们的类型为 `QUESTION_ANSWER`。有关更多信息，请参阅[问题和答案](https://docs.aws.amazon.com/kendra/latest/dg/in-creating-faq.html)。
+ 推荐文档-这些是回复中 Amazon Kendra 返回的其他文档。在 `Query` API 的响应中，它们的类型为 `DOCUMENT`。
结果组件共享一组用于突出显示、标题、链接等功能的组件。必须存在共享组件才能让结果组件正常工作。
## 分面组件
分面组件列出了搜索结果中可用的分面。每个分面都按特定的维度（例如，作者）来对响应进行分类。通过从列表中选择一个分面，您可以将搜索范围缩小到特定的分面。
选择一个分面后，该组件会使用属性筛选条件调用 `Query`，该筛选条件将搜索范围限制为与该分面匹配的文档。
## 分页组件
分页组件允许您在多个页面中显示来自 `Query` API 的搜索结果。它使用 `PageSize` 和 `PageNumber` 参数调用 `Query` API 以获取特定页面的结果。
# 无需代码即可打造搜索体验
无需任何前端代码即可构建和部署 Amazon Kendra 搜索应用程序。 Amazon Kendra 只需点击几下，*Experience Builder* 即可帮助您构建和部署功能齐全的搜索应用程序，这样您就可以立即开始搜索。您可以自定义设计搜索页面并调整搜索，以根据用户的需求量身定制体验。 Amazon Kendra 为您的搜索页面生成一个唯一的、完全托管的端点 URL，以开始搜索您的文档，然后 FAQs。您可以快速建立搜索体验的概念证明，并与他人分享。
您可以使用构建器中提供的搜索体验模板来自定义搜索。您可以邀请其他人合作打造您的搜索体验，也可以评估搜索结果以进行调整。一旦您的搜索体验准备就绪，可供用户开始搜索，就只需共享安全端点 URL。
## 搜索 Experience Builder 的工作原理
构建搜索体验的总体过程如下所述：
1. 您可以通过为搜索体验命名、描述并选择要用于搜索体验的数据来源来创建搜索体验。
1. 您可以在中配置您的用户和群组列表， AWS IAM Identity Center 然后为他们分配搜索体验的访问权限。您将自己列为体验的所有者。有关更多信息，请参阅 [提供对搜索页面的访问权限](#access-search-experience)。
1. 您可以打开 Amazon Kendra 体验生成器来设计和调整搜索页面。您可以与您分配了自己的编辑访问权限或查看搜索访问权限的其他人共享您的搜索体验的端点 URL。
您可以调用 [CreateExperience](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateExperience.html)API 来创建和配置您的搜索体验。如果您使用控制台，则可以选择您的索引，然后在导航菜单中选择**体验** 来配置您的体验。
## 设计和调整您的搜索体验
创建和配置搜索体验后，您可以使用端点 URL 来打开搜索体验，以拥有编辑者访问权限的所有者的身份开始自定义搜索。在搜索框中键入查询，然后使用侧面板上的编辑选项对搜索进行自定义，以查看它们如何应用于您的页面。准备好发布时，选择**发布**。您还可以在**切换到实时视图**（查看搜索页面的最新发布版本）和**切换到构建模式**（编辑或自定义搜索页面）之间切换。
以下是您可以自定义搜索体验的方法。
### 筛选条件
添加分面搜索或按文档属性筛选。这包括自定义属性。您可以使用自己配置的元数据字段添加筛选条件。例如，要按每个城市类别进行分面搜索，请使用包含所有城市类别的 `_category` 自定义文档属性。
### 建议的答案
将机器学习生成的答案添加到用户的查询中。例如，*“这门课程有多难？*” 。 Amazon Kendra 可以检索所有涉及课程难度的文档中最相关的文本，并提出最相关的答案。
### 常见问题解答
添加常见问题解答文档以提供常见问题的答案。例如，*“完成这门课程需要多少小时？*” 。 Amazon Kendra 可以使用包含此问题答案的常见问题解答文档并给出正确的答案。
### 排序
添加对搜索结果的排序，以便您的用户可以按相关性、创建时间、上次更新时间和其他排序标准来组织结果。
### 文档
配置文档或搜索结果在搜索页面上的显示方式。您可以配置页面上显示多少结果，包括页码等分页，激活用户反馈按钮，以及安排文档元数据字段在搜索结果中的显示方式。
### 语言
选择一种语言来筛选所选语言的搜索结果或文档。
### 搜索框
配置搜索框的大小和占位符文本，并允许提出查询建议。
### 相关性优化
为文档元数据字段添加增强功能，以便在用户搜索文档时提高这些字段的权重。您可以添加从 1 开始并逐渐增加到 10 的权重。您可以增强文本、日期和数值字段的类型。例如，要赋予 `_last_updated_at` 和 `_created_at` 比其他字段更高的权重或重要性，请根据这些字段的重要性将这些字段的权重设为 1 到 10。您可以为每个搜索应用程序或体验应用不同的相关性调整配置。
## 提供对搜索页面的访问权限
通过 IAM 身份中心访问您的搜索体验。配置搜索体验时，您授予身份中心目录中列出的其他人访问您的 Amazon Kendra 搜索页面的权限。他们会收到一封电子邮件，指示他们使用自己在 IAM Identity Center 中的证书登录以访问搜索页面。您必须在 AWS Organizations中的组织级别或账户持有人级别设置 IAM 身份中心。有关设置 IAM IAM Identy 的更多信息，请参阅 [IAM Identity Center 入门](https://docs.aws.amazon.com/kendra/latest/dg/getting-started-aws-sso.html)。
您可以根据自己的搜索体验在 IAM Identity Center 中激活用户身份，并使用 API 或控制台分配*查看者*或*所有者*访问权限。
+ **查看者**：允许发布查询、接收与搜索相关的建议答案，并向 Amazon Kendra 提供反馈，以便不断改进搜索。
+ **所有者**：允许自定义搜索页面的设计、调整搜索以及将搜索应用程序用作*查看器*。目前不支持在控制台中禁用查看者的访问权限。
要为其他人分配访问您的搜索体验的访问权限，您首先需要使用[ExperienceConfiguration](https://docs.aws.amazon.com/kendra/latest/APIReference/API_ExperienceConfiguration.html)对象在 IAM Identity Center 中激活用户身份以及您的 Amazon Kendra 体验。您可以指定包含用户标识符（例如用户名或电子邮件地址）的字段名称。然后，您可以使用 API 向您的用户列表授予访问您的搜索体验的权限，并使用 [AssociateEntitiesToExperience](https://docs.aws.amazon.com/kendra/latest/APIReference/API_AssociateEntitiesToExperience.html)API 将他们的权限定义为*查看**者或所有者*。[AssociatePersonasToEntities](https://docs.aws.amazon.com/kendra/latest/APIReference/API_AssociatePersonasToEntities.html)您可以指定使用该[EntityConfiguration](https://docs.aws.amazon.com/kendra/latest/APIReference/API_EntityConfiguration.html)对象的每个用户或组，以及该用户或组是使用该[EntityPersonaConfiguraton](https://docs.aws.amazon.com/kendra/latest/APIReference/API_EntityPersonaConfiguration.html)对象的*查看**者还是所有者*。
要使用控制台向其他人分配访问您的搜索体验的权限，您首先需要创建体验并确认您的身份以及您是所有者。然后，您可以将其他用户或组指定为查看者或所有者。在控制台中，选择您的索引，然后在导航菜单中选择**体验**。创建体验后，您可以从列表中选择您的体验。转到**访问权限管理**，将用户或组分配为查看者或所有者。
## 配置搜索体验
以下是配置或创建搜索体验的示例。
------
#### [ Console ]
**创建 Amazon Kendra 搜索体验**
1. 在左侧导航窗格的**索引**下，选择**体验**，然后选择**创建体验**。
1. 在**配置体验**页面上，输入体验的名称和描述，选择您的内容来源，然后为您的体验选择 IAM 角色。有关 IAM 角色的更多信息，请参阅[Amazon Kendra 体验版 IAM 角色](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html)。
1. 在**通过 Identity Center 目录确认您的身份**页面上，选择您的用户 ID，例如，您的电子邮件地址。如果您没有 Identity Center 目录，只需输入您的全名和电子邮件即可创建身份中心目录。这包括作为体验用户的您，并会自动为您分配所有者访问权限。
1. 在**查看以打开 Experience Builder** 页面上，查看您的配置详细信息，然后选择**创建体验并打开 Experience Builder** 以开始编辑您的搜索页面。
------
#### [ CLI ]
**创建 Amazon Kendra 体验**
```
aws kendra create-experience \
--name experience-name \
--description "experience description" \
--index-id index-id \
--role-arn arn:aws:iam::account-id:role/role-name \
--configuration '{"ExperienceConfiguration":[{"ContentSourceConfiguration":{"DataSourceIds":["data-source-1","data-source-2"]}, "UserIdentityConfiguration":"identity attribute name"}]}'
aws kendra describe-experience \
--endpoints experience-endpoint-URL(s)
```
------
#### [ Python ]
**创建 Amazon Kendra 体验**
```
import boto3
from botocore.exceptions import ClientError
import pprint
import time
kendra = boto3.client("kendra")
print("Create an experience.")
# Provide a name for the experience
name = "experience-name"
# Provide an optional description for the experience
description = "experience description"
# Provide the index ID for the experience
index_id = "index-id"
# Provide the IAM role ARN required for Amazon Kendra experiences
role_arn = "arn:aws:iam::${account-id}:role/${role-name}"
# Configure the experience
configuration = {"ExperienceConfiguration":
[{
"ContentSourceConfiguration":{"DataSourceIds":["data-source-1","data-source-2"]},
"UserIdentityConfiguration":"identity attribute name"
}]
}
try:
experience_response = kendra.create_experience(
Name = name,
Description = description,
IndexId = index_id,
RoleArn = role_arn,
Configuration = configuration
)
pprint.pprint(experience_response)
experience_endpoints = experience_response["Endpoints"]
print("Wait for Amazon Kendra to create the experience.")
while True:
# Get the details of the experience, such as the status
experience_description = kendra.describe_experience(
Endpoints = experience_endpoints
)
status = experience_description["Status"]
print(" Creating experience. Status: "+status)
time.sleep(60)
if status != "CREATING":
break
except ClientError as e:
print("%s" % e)
print("Program ends.")
```
------
#### [ Java ]
**要创建 Amazon Kendra**
```
package com.amazonaws.kendra;
import java.util.concurrent.TimeUnit;
import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.CreateExperienceRequest;
import software.amazon.awssdk.services.kendra.model.CreateExperienceResponse;
import software.amazon.awssdk.services.kendra.model.DescribeExperienceRequest;
import software.amazon.awssdk.services.kendra.model.DescribeExperienceResponse;
import software.amazon.awssdk.services.kendra.model.ExperienceStatus;
public class CreateExperienceExample {
public static void main(String[] args) throws InterruptedException {
System.out.println("Create an experience");
String experienceName = "experience-name";
String experienceDescription = "experience description";
String indexId = "index-id";
String experienceRoleArn = "arn:aws:iam::account-id:role/role-name";
KendraClient kendra = KendraClient.builder().build();
CreateExperienceRequest createExperienceRequest = CreateExperienceRequest
.builder()
.name(experienceName)
.description(experienceDescription)
.roleArn(experienceRoleArn)
.configuration(
ExperienceConfiguration
.builder()
.contentSourceConfiguration(
ContentSourceConfiguration(
.builder()
.dataSourceIds("data-source-1","data-source-2")
.build()
)
)
.userIdentityConfiguration(
UserIdentityConfiguration(
.builder()
.identityAttributeName("identity-attribute-name")
.build()
)
).build()
).build();
CreateExperienceResponse createExperienceResponse = kendra.createExperience(createExperienceRequest);
System.out.println(String.format("Experience response %s", createExperienceResponse));
String experienceEndpoints = createExperienceResponse.endpoints();
System.out.println(String.format("Wait for Kendra to create the experience.", experienceEndpoints));
while (true) {
DescribeExperienceRequest describeExperienceRequest = DescribeExperienceRequest.builder().endpoints(experienceEndpoints).build();
DescribeExperienceResponse describeEpxerienceResponse = kendra.describeExperience(describeExperienceRequest);
ExperienceStatus status = describeExperienceResponse.status();
TimeUnit.SECONDS.sleep(60);
if (status != ExperienceStatus.CREATING) {
break;
}
}
System.out.println("Experience creation is complete.");
}
}
```
------