本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 部署 Amazon Kendra
**注意**
功能支援會因索引類型和正在使用的搜尋 API 而有所不同。若要查看您正在使用的索引類型和搜尋 API 是否支援此功能，請參閱[索引類型](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html)。
將 Amazon Kendra 搜尋部署到您的網站時，我們會提供原始程式碼，供您搭配 React 使用，讓您的應用程式快速上手。原始碼是根據修改後的 MIT 授權免費提供。您可以照原樣使用它，或根據自己的需求進行變更。提供的 React 應用程式是協助您開始使用的範例。它不是生產就緒的應用程式。
若要部署沒有程式碼的搜尋應用程式，並使用存取控制產生端點 URL 到您的搜尋頁面，請參閱[Amazon Kendra 體驗建置器](https://docs.aws.amazon.com/kendra/latest/dg/deploying-search-experience-no-code.html)。
下列範例程式碼會將 Amazon Kendra 搜尋新增至現有的 React Web 應用程式：
+ [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 版或更新版本。
+ Python 3 或 Python 2 [已下載並安裝](https://www.python.org/downloads/)。
+ [適用於 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) 進行 API 呼叫 Amazon Kendra。
+ 現有的 React Web 應用程式。範例程式碼包含讀我檔案，其中包含如何設定新 React 開發環境的步驟，包括使用必要的架構/程式庫。您也可以遵循 [React 文件中有關建立 React Web 應用程式的](https://create-react-app.dev/docs/getting-started)快速入門說明。
+ 在您的開發環境中設定的必要程式庫和相依性。範例程式碼包含讀我檔案，列出所需的程式庫和套件相依性。請注意， `sass` 是必要的，因為 `node-sass` 已棄用。如果您先前已安裝 `node-sass`，請解除安裝此 並安裝 `sass`。
## 設定範例
將 Amazon Kendra 搜尋新增至 React 應用程式的完整程序位於程式碼範例中包含的讀我檔案。
**開始使用 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`) 包含所有搜尋元件範例。它包含用於輸出的搜尋列元件、用於顯示[查詢](https://docs.aws.amazon.com/kendra/latest/APIReference/API_Query.html) API 回應的結果元件，以及用於分頁通過回應的分頁元件。
## 搜尋元件
搜尋元件提供文字方塊以輸入查詢文字。`onSearch` 函數是 中呼叫主要函數的勾點`Search.tsx`，用於進行[查詢](https://docs.aws.amazon.com/kendra/latest/APIReference/API_Query.html) API Amazon Kendra 呼叫。
## 結果元件
結果元件會顯示來自 `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。
## 搜尋體驗建置器的運作方式
建立搜尋體驗的整體程序如下：
1. 您可以透過提供名稱、描述並選擇您要用於搜尋體驗的資料來源，來建立您的搜尋體驗。
1. 您可以在 中設定使用者和群組的清單， AWS IAM Identity Center 然後將存取權指派給他們以進行搜尋。您可以將自己納入體驗的擁有者。如需詳細資訊，請參閱[提供對搜尋頁面的存取](#access-search-experience)。
1. 您可以開啟 Amazon Kendra Experience Builder 來設計和調整搜尋頁面。您可以與指派自有編輯存取權限或檢視搜尋存取權限的其他人共用搜尋體驗的端點 URL。
您可以呼叫 [CreateExperience](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateExperience.html) API 來建立和設定您的搜尋體驗。如果您使用 主控台，請選取您的索引，然後在導覽功能表中選取**體驗**來設定您的體驗。
## 設計和調整您的搜尋體驗
建立並設定搜尋體驗後，您可以使用端點 URL 開啟搜尋體驗，以具有編輯器存取權的擁有者身分開始自訂搜尋。您可以在搜尋方塊中輸入您的查詢，然後使用側邊面板上的編輯選項自訂您的搜尋，以查看它們如何套用至您的頁面。當您準備好發佈時，請選取**發佈**。您也可以在**切換到即時檢視**、檢視最新發佈版本的搜尋頁面，以及**切換到建置模式**，以編輯或自訂您的搜尋頁面。
以下是您可以自訂搜尋體驗的方式。
### 篩選條件
依文件屬性新增面向搜尋或篩選條件。這包括自訂屬性。您可以使用自己設定的中繼資料欄位來新增篩選條件。例如，若要依每個城市類別進行面向搜尋，請使用包含所有城市類別的`_category`自訂文件屬性。
### 建議的答案
將機器學習產生的答案新增至使用者的查詢。例如，*「此課程有多困難？」*。 Amazon Kendra 可以擷取所有參考課程困難之文件中最相關的文字，並建議最相關的答案。
### 常見問答集
新增常見問答集文件，以提供常見問題的答案。例如，*「要完成此課程多少小時？」*。 Amazon Kendra 可以使用包含此問題答案的常見問答集文件，並提供正確的答案。
### Sort
新增搜尋結果的排序，讓使用者可以依相關性、建立時間、上次更新時間和其他排序條件來組織結果。
### 文件
設定文件或搜尋結果在搜尋頁面上的顯示方式。您可以設定頁面上顯示的結果數量、包含分頁，例如頁碼、啟用使用者意見回饋按鈕，以及排列文件中繼資料欄位在搜尋結果中的顯示方式。
### Language
選取語言以篩選所選語言的搜尋結果或文件。
### 搜尋方塊
設定搜尋方塊的大小和預留位置文字，並允許查詢建議。
### 關聯性調校
新增提升以記錄中繼資料欄位，以便在使用者搜尋文件時對這些欄位設定更多權重。您可以新增從 1 開始並遞增到 10 的權重。您可以提升文字、日期和數值欄位類型。例如，若要給予 `_last_updated_at` 和比其他欄位`_created_at`更多的權重或重要性，請根據這些欄位的重要性為這些欄位提供 1 到 10 的權重。您可以為每個搜尋應用程式或體驗套用不同的相關性調校組態。
## 提供對搜尋頁面的存取
透過 IAM Identity Center 存取您的搜尋體驗。當您設定搜尋體驗時，您可以授予 Identity Center 目錄中列出的其他人存取您的 Amazon Kendra 搜尋頁面。他們會收到一封電子郵件，指示他們使用 IAM Identity Center 中的登入資料來存取搜尋頁面。您必須在組織層級或帳戶持有人層級設定 IAM Identity Center AWS Organizations。如需設定 IAM Identity Center 的詳細資訊，請參閱 [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 體驗。您可以指定包含使用者識別符的欄位名稱，例如使用者名稱或電子郵件地址。然後，您可以使用 [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) API 將其許可定義為*檢視器*或*擁有者*。您可以使用 [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 角色的詳細資訊，請參閱 [IAM 角色以取得 Amazon Kendra 體驗](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html)。
1. 在**從身分中心目錄確認您的身分**頁面上，選取您的使用者 ID，例如您的電子郵件。如果您沒有 Identity Center 目錄，只需輸入您的全名和電子郵件即可建立 Identity Center 目錄。這包括身為體驗使用者的您，並自動指派擁有者存取權。
1. 在**檢閱以開啟體驗建置器**頁面上，檢閱您的組態詳細資訊，然後選取**建立體驗並開啟體驗建置器**以開始編輯您的搜尋頁面。
------
#### [ 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.");
}
}
```
------