本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 建立 索引
<a name="create-index"></a>

您可以使用 主控台或呼叫 [CreateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateIndex.html) API 來建立索引。您可以搭配 API 使用 AWS Command Line Interface (AWS CLI) 或 SDK。建立索引之後，您可以直接新增文件或從資料來源新增文件。

若要建立索引，您必須提供 () 角色的 Amazon Resource Name AWS Identity and Access Management (ARN IAM)，索引才能存取 CloudWatch。如需詳細資訊，請參閱[IAM 索引的角色](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html#iam-roles-index)。

下列索引標籤提供使用 建立索引的程序 AWS 管理主控台，以及使用 的程式碼範例 AWS CLI，以及 Python 和 Java SDKs。

------
#### [ Console ]

**建立 索引**

1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/kendra/](https://console.aws.amazon.com/kendra/) 開啟 Amazon Kendra 主控台。

1. 在**索引區段中選取建立****索引**。

1. 在**指定索引詳細資訊**中，為您的索引指定名稱和描述。

1. **IAM 角色**提供 IAM 角色。若要尋找角色，請從您帳戶中包含「kendra」一詞的角色中選擇，或輸入另一個角色的名稱。如需角色所需許可的詳細資訊，請參閱[IAM 索引的角色](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html#iam-roles-index)。

1. 選擇**下一步**。

1. 在**設定使用者存取控制**頁面上，選擇**下一步**。您可以在建立索引之後，更新您的索引以使用字符進行存取控制。如需詳細資訊，請參閱[控制文件的存取](https://docs.aws.amazon.com/kendra/latest/dg/create-index-access-control.html)。

1. 在**佈建詳細資訊**頁面上，選擇**建立**。

1. 可能需要一些時間才能建立索引。檢查索引清單，以監看建立索引的進度。當索引的狀態為 時`ACTIVE`，您的索引即可使用。

------
#### [ AWS CLI ]

**建立 索引**

1. 使用下列命令來建立索引。`role-arn` 必須是可執行 Amazon Kendra 動作之 IAM 角色的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱 [IAM 角色](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html)。

   命令已針對 Linux 和 macOS 格式化。如果您使用的是 Windows，請將 Unix 行接續字元 (\$1) 取代為插入符號 (^)。

   ```
   aws kendra create-index \
    --name index name \
    --description "index description" \
    --role-arn arn:aws:iam::account ID:role/role name
   ```

1. 可能需要一些時間才能建立索引。若要檢查索引的狀態，請使用 傳回的索引 ID `create-index`搭配下列命令。當索引的狀態為 時`ACTIVE`，您的索引即可使用。

   ```
   aws kendra describe-index \
    --index-id index ID
   ```

------
#### [ Python ]

**建立 索引**
+ 在下列程式碼範例中提供下列變數的值：
  + `description`- 您正在建立之索引的描述。這是選用的。
  + `index_name`- 您正在建立的索引名稱。
  + `role_arn`- 可執行 Amazon Kendra APIs之角色的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱 [IAM 角色](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html)。

  ```
  import boto3
  from botocore.exceptions import ClientError
  import pprint
  import time
  
  kendra = boto3.client("kendra")
  
  print("Create an index.")
  
  # Provide a name for the index
  index_name = "index-name"
  # Provide an optional description for the index
  description = "index description"
  # Provide the IAM role ARN required for indexes
  role_arn = "arn:aws:iam::${account id}:role/${role name}"
  
  try:
      index_response = kendra.create_index(
          Name = index_name,
          Description = description,
          RoleArn = role_arn
      )
  
      pprint.pprint(index_response)
  
      index_id = index_response["Id"]
  
      print("Wait for Amazon Kendra to create the index.")
  
      while True:
          # Get the details of the index, such as the status
          index_description = kendra.describe_index(
              Id = index_id
          )
          # If status is not CREATING, then quit
          status = index_description["Status"]
          print(" Creating index. Status: "+status)
          if status != "CREATING":
              break
          time.sleep(60)
  
  except  ClientError as e:
          print("%s" % e)
  
  print("Program ends.")
  ```

------
#### [ Java ]

**建立 索引**
+ 在下列程式碼範例中提供下列變數的值：
  + `description`- 您正在建立之索引的描述。這是選用的。
  + `index_name`- 您正在建立的索引名稱。
  + `role_arn`- 可執行 Amazon Kendra APIs之角色的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱 [IAM 角色](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html)。

  ```
  package com.amazonaws.kendra;
  
  import java.util.concurrent.TimeUnit;
  import software.amazon.awssdk.services.kendra.KendraClient;
  import software.amazon.awssdk.services.kendra.model.CreateIndexRequest;
  import software.amazon.awssdk.services.kendra.model.CreateIndexResponse;
  import software.amazon.awssdk.services.kendra.model.DescribeIndexRequest;
  import software.amazon.awssdk.services.kendra.model.DescribeIndexResponse;
  import software.amazon.awssdk.services.kendra.model.IndexStatus;
  
  
  public class CreateIndexExample {
  
      public static void main(String[] args) throws InterruptedException {
  
          String indexDescription = "Getting started index for Kendra";
          String indexName = "java-getting-started-index";
          String indexRoleArn = "arn:aws:iam::<your AWS account ID>:role/KendraRoleForGettingStartedIndex";
  
          System.out.println(String.format("Creating an index named %s", indexName));
          CreateIndexRequest createIndexRequest = CreateIndexRequest
              .builder()
              .description(indexDescription)
              .name(indexName)
              .roleArn(indexRoleArn)
              .build();
          KendraClient kendra = KendraClient.builder().build();
          CreateIndexResponse createIndexResponse = kendra.createIndex(createIndexRequest);
          System.out.println(String.format("Index response %s", createIndexResponse));
  
          String indexId = createIndexResponse.id();
  
          System.out.println(String.format("Waiting until the index with ID %s is created.", indexId));
          while (true) {
              DescribeIndexRequest describeIndexRequest = DescribeIndexRequest.builder().id(indexId).build();
              DescribeIndexResponse describeIndexResponse = kendra.describeIndex(describeIndexRequest);
              IndexStatus status = describeIndexResponse.status();
              if (status != IndexStatus.CREATING) {
                  break;
              }
  
              TimeUnit.SECONDS.sleep(60);
          }
  
          System.out.println("Index creation is complete.");
      }
  }
  ```

------

建立索引之後，您可以將文件新增至索引。您可以直接新增或建立資料來源，以定期更新索引。

**Topics**
+ [使用批次上傳將文件直接新增至索引](in-adding-documents.md)
+ [將常見問答集 FAQs) 新增至索引](in-creating-faq.md)
+ [建立自訂文件欄位](custom-attributes.md)
+ [使用字符控制使用者對文件的存取](create-index-access-control.md)

# 使用批次上傳將文件直接新增至索引
<a name="in-adding-documents"></a>

您可以使用 [BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument.html) API 將文件直接新增至索引。您無法直接使用 主控台新增文件。如果您使用 主控台，您可以連線到資料來源，將文件新增至您的索引。您可以從 S3 儲存貯體新增文件，或以二進位資料的形式提供。如需 支援的文件類型清單， Amazon Kendra 請參閱[文件類型](https://docs.aws.amazon.com/kendra/latest/dg/index-document-types.html)。

使用 將文件新增至索引`BatchPutDocument`是一種非同步操作。呼叫 `BatchPutDocument` API 之後，您可以使用 [BatchGetDocumentStatus](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchGetDocumentStatus) API 來監控編製文件索引的進度。當您使用文件 IDs清單呼叫 `BatchGetDocumentStatus` API 時，它會傳回文件的狀態。當文件的狀態為 `INDEXED`或 時`FAILED`，文件的處理即完成。當狀態為 時`FAILED`，`BatchGetDocumentStatus`API 會傳回文件無法編製索引的原因。

如果您想要在文件擷取程序期間變更內容和文件中繼資料欄位或屬性，請參閱[Amazon Kendra 自訂文件擴充](https://docs.aws.amazon.com/kendra/latest/dg/custom-document-enrichment.html)。如果您想要使用自訂資料來源，您使用 `BatchPutDocument` API 提交的每個文件都需要資料來源 ID 和執行 ID 做為屬性或欄位。如需詳細資訊，請參閱[自訂資料來源的必要屬性](https://docs.aws.amazon.com/kendra/latest/dg/data-source-custom.html#custom-required-attributes)。

**注意**  
每個文件 ID 在每個索引中必須是唯一的。您無法建立資料來源以使用其唯一 IDs為文件編製索引，然後使用 `BatchPutDocument` API 為相同的文件編製索引，反之亦然。您可以刪除資料來源，然後使用 `BatchPutDocument` API 為相同的文件編製索引，反之亦然。將 `BatchPutDocument`和 `BatchDeleteDocument` APIs與 Amazon Kendra 同一組文件的資料來源連接器結合使用，可能會導致資料不一致。反之，我們建議您使用[Amazon Kendra 自訂資料來源連接器](https://docs.aws.amazon.com/kendra/latest/dg/data-source-custom.html)。

下列開發人員指南文件示範如何將文件直接新增至 索引。

**Topics**
+ [使用 BatchPutDocument API 新增文件](#in-adding-binary-doc)
+ [從 S3 儲存貯體新增文件](#in-adding-plain-text)

## 使用 BatchPutDocument API 新增文件
<a name="in-adding-binary-doc"></a>

下列範例會呼叫 [BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument)，將文字 Blob 新增至索引。您可以使用 `BatchPutDocument` API 直接將文件新增至您的索引。如需 支援的文件類型清單， Amazon Kendra 請參閱[文件類型](https://docs.aws.amazon.com/kendra/latest/dg/index-document-types.html)。

如需使用 AWS CLI 和 SDKs 建立索引的範例，請參閱[建立索引](https://docs.aws.amazon.com/kendra/latest/dg/create-index.html)。若要設定 CLI 和 SDKs，請參閱[設定 Amazon Kendra](https://docs.aws.amazon.com/kendra/latest/dg/setup.html)。

**注意**  
新增至索引的檔案必須位於 UTF-8 編碼的位元組串流中。

在下列範例中，UTF-8 編碼的文字會新增至索引。

------
#### [ CLI ]

在 中 AWS Command Line Interface，使用下列命令。命令已針對 Linux 和 macOS 格式化。如果您使用的是 Windows，請將 Unix 行接續字元 (\$1) 取代為插入符號 (^)。

```
aws kendra batch-put-document \
   --index-id index-id \
   --documents '{"Id":"doc-id-1", "Blob":"Amazon.com is an online retailer.", "ContentType":"PLAIN_TEXT", "Title":"Information about Amazon.com"}'
```

------
#### [ Python ]

```
import boto3

kendra = boto3.client("kendra")

# Provide the index ID
index_id = "index-id"

# Provide the title and text
title = "Information about Amazon.com"
text = "Amazon.com is an online retailer."

document = {
    "Id": "1",
    "Blob": text,
    "ContentType": "PLAIN_TEXT",
    "Title": title
}

documents = [
    document
]

result = kendra.batch_put_document(
    IndexId = index_id,
    Documents = documents
)

print(result)
```

------
#### [ Java ]

```
package com.amazonaws.kendra;


import software.amazon.awssdk.core.SdkBytes;
import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.BatchPutDocumentRequest;
import software.amazon.awssdk.services.kendra.model.BatchPutDocumentResponse;
import software.amazon.awssdk.services.kendra.model.ContentType;
import software.amazon.awssdk.services.kendra.model.Document;

public class AddDocumentsViaAPIExample {
    public static void main(String[] args) {
        KendraClient kendra = KendraClient.builder().build();

        String indexId = "yourIndexId";

        Document testDoc = Document
            .builder()
            .title("The title of your document")
            .id("a_doc_id")
            .blob(SdkBytes.fromUtf8String("your text content"))
            .contentType(ContentType.PLAIN_TEXT)
            .build();

        BatchPutDocumentRequest batchPutDocumentRequest = BatchPutDocumentRequest
            .builder()
            .indexId(indexId)
            .documents(testDoc)
            .build();

        BatchPutDocumentResponse result = kendra.batchPutDocument(batchPutDocumentRequest);

        System.out.println(String.format("BatchPutDocument Result: %s", result));
    }
}
```

------

## 從 S3 儲存貯體新增文件
<a name="in-adding-plain-text"></a>

您可以使用 [BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument) API，直接從 儲存 Amazon S3 貯體將文件新增至索引。您最多可以在相同的呼叫中新增 10 個文件。使用 S3 儲存貯體時，您必須提供 IAM 角色存取包含您文件之儲存貯體的許可。您可以在 `RoleArn` 參數中指定角色。

使用 [BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument) API 從 儲存 Amazon S3 貯體新增文件是一次性操作。若要讓索引與儲存貯體的內容保持同步，請建立 Amazon S3 資料來源。如需詳細資訊，請參閱[Amazon S3 資料來源](https://docs.aws.amazon.com/kendra/latest/dg/data-source-s3.html)。

如需使用 AWS CLI 和 SDKs 建立索引的範例，請參閱[建立索引](https://docs.aws.amazon.com/kendra/latest/dg/create-index.html)。若要設定 CLI 和 SDKs，請參閱[設定 Amazon Kendra](https://docs.aws.amazon.com/kendra/latest/dg/setup.html)。如需建立 S3 儲存貯體的資訊，請參閱 [Amazon Simple Storage Service 文件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)。

在下列範例中，會使用 `BatchPutDocument` API 將兩個 Microsoft Word 文件新增至索引。

------
#### [ Python ]

```
import boto3

kendra = boto3.client("kendra")

# Provide the index ID
index_id = "index-id"
# Provide the IAM role ARN required to index documents in an S3 bucket
role_arn = "arn:aws:iam::${acccountID}:policy/${roleName}"

doc1_s3_file_data = {
    "Bucket": "bucket-name",
    "Key": "document1.docx"
}

doc1_document = {
    "S3Path": doc1_s3_file_data,
    "Title": "Document 1 title",
    "Id": "doc_1"
}

doc2_s3_file_data = {
    "Bucket": "bucket-name",
    "Key": "document2.docx"
}

doc2_document = {
    "S3Path": doc2_s3_file_data,
    "Title": "Document 2 title",
    "Id": "doc_2"
}

documents = [
    doc1_document,
    doc2_document
]

result = kendra.batch_put_document(
    Documents = documents,
    IndexId = index_id,
    RoleArn = role_arn
)

print(result)
```

------
#### [ Java ]

```
package com.amazonaws.kendra;

import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.BatchPutDocumentRequest;
import software.amazon.awssdk.services.kendra.model.BatchPutDocumentResponse;
import software.amazon.awssdk.services.kendra.model.Document;
import software.amazon.awssdk.services.kendra.model.S3Path;

public class AddFilesFromS3Example {
    public static void main(String[] args) {
        KendraClient kendra = KendraClient.builder().build();

        String indexId = "yourIndexId";
        String roleArn = "yourIndexRoleArn";

        Document pollyDoc = Document
            .builder()
            .s3Path(
                S3Path.builder()
                .bucket("amzn-s3-demo-bucket")
                .key("What is Amazon Polly.docx")
                .build())
            .title("What is Amazon Polly")
            .id("polly_doc_1")
            .build();

        Document rekognitionDoc = Document
            .builder()
            .s3Path(
                S3Path.builder()
                .bucket("amzn-s3-demo-bucket")
                .key("What is Amazon Rekognition.docx")
                .build())
            .title("What is Amazon rekognition")
            .id("rekognition_doc_1")
            .build();

        BatchPutDocumentRequest batchPutDocumentRequest = BatchPutDocumentRequest
            .builder()
            .indexId(indexId)
            .roleArn(roleArn)
            .documents(pollyDoc, rekognitionDoc)
            .build();

        BatchPutDocumentResponse result = kendra.batchPutDocument(batchPutDocumentRequest);

        System.out.println(String.format("BatchPutDocument result: %s", result));
    }
}
```

------

# 將常見問答集 FAQs) 新增至索引
<a name="in-creating-faq"></a>

**注意**  
功能支援會因索引類型和正在使用的搜尋 API 而有所不同。若要查看您正在使用的索引類型和搜尋 API 是否支援此功能，請參閱[索引類型](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html)。

您可以使用主控台或 [CreateFaq](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateFaq.html) API，直接將常見問答集 (FAQs) 新增至您的索引。將FAQs新增至索引是一種非同步操作。您可以將常見問答集的資料放在存放在 儲存 Amazon Simple Storage Service 貯體的檔案中。您可以使用 CSV 或 JSON 檔案做為常見問答集的輸入：
+ 基本 CSV - CSV 檔案，其中每一列都包含問題、答案和選用的來源 URI。
+ 自訂 CSV - CSV 檔案，其中包含自訂欄位/屬性的問題、答案和標頭，可用於構面、顯示或排序常見問答集回應。您也可以定義存取控制欄位，將常見問答集回應限制為允許查看常見問答集回應的特定使用者和群組。
+ JSON—JSON 檔案，其中包含問題、答案和自訂欄位/屬性，可用於構面、顯示或排序常見問答集回應。您也可以定義存取控制欄位，將常見問答集回應限制為允許查看常見問答集回應的特定使用者和群組。

例如，以下是基本 CSV 檔案，提供有關美國華盛頓州斯波坎市和美國密蘇里州山景檢視免費診所問題的解答。

```
How many free clinics are in Spokane WA?, 13
How many free clinics are there in Mountain View Missouri?, 7
```

**注意**  
常見問答集檔案必須是 UTF-8-encoded的檔案。

**Topics**
+ [建立常見問答集檔案的索引欄位](#in-custom-fields-faq)
+ [基本 CSV 檔案](#faq-basic-csv)
+ [自訂 CSV 檔案](#faq-custom-csv)
+ [JSON 檔案](#faq-custom-json)
+ [使用您的常見問答集檔案](#using-faq-file)
+ [英文以外語言的常見問答集檔案](#faq-languages)

## 建立常見問答集檔案的索引欄位
<a name="in-custom-fields-faq"></a>

**注意**  
功能支援會因索引類型和正在使用的搜尋 API 而有所不同。若要查看您正在使用的索引類型和搜尋 API 是否支援此功能，請參閱[索引類型](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html)。

當您使用[自訂 CSV](https://docs.aws.amazon.com/kendra/latest/dg/in-creating-faq.html#faq-custom-csv) 或 [JSON](https://docs.aws.amazon.com/kendra/latest/dg/in-creating-faq.html#faq-custom-json) 檔案進行輸入時，您可以為常見問答集問題宣告自訂欄位。例如，您可以建立自訂欄位，將每個常見問答集問題指派給業務單位。在回應中傳回 FAQ 時，您可以使用 部門做為構面，將搜尋縮小為僅限「HR」或「財務」。

自訂欄位必須對應至索引欄位。在 主控台中，您可以使用**面向定義**頁面來建立索引欄位。使用 API 時，您必須先使用 [UpdateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_UpdateIndex.html) API 建立索引欄位。

常見問答集檔案中的欄位/屬性類型必須符合相關聯的索引欄位類型。例如，「部門」欄位是`STRING_LIST`類型欄位。因此，您必須提供部門欄位的值做為常見問答集檔案中的字串清單。您可以使用 主控台中的**面向定義**頁面或使用 [DescribeIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_DescribeIndex.html) API 來檢查索引欄位的類型。

當您建立映射到自訂屬性的索引欄位時，您可以標記它可顯示、可面向或可排序。您無法將自訂屬性設為可搜尋。

除了自訂屬性之外，您也可以使用 Amazon Kendra 自訂 CSV 或 JSON 檔案中的預留或常用欄位。如需詳細資訊，請參閱[文件屬性或欄位](https://docs.aws.amazon.com/kendra/latest/dg/hiw-document-attributes.html)。

## 基本 CSV 檔案
<a name="faq-basic-csv"></a>

當您想要為FAQs使用簡單的結構時，請使用基本 CSV 檔案。在基本 CSV 檔案中，每一列有兩個或三個欄位：問題、答案和選用來源 URI，指向具有更多資訊的文件。

檔案的內容必須遵循[逗號分隔值 (CSV) 檔案的 RFC 4180 常見格式和 MIME 類型](https://tools.ietf.org/html/rfc4180)。

以下是基本 CSV 格式的常見問答集檔案。

```
How many free clinics are in Spokane WA?, 13, https://s3.region.company.com/bucket-name/directory/faq.csv
How many free clinics are there in Mountain View Missouri?, 7, https://s3.region.company.com/bucket-name/directory/faq.csv
```

## 自訂 CSV 檔案
<a name="faq-custom-csv"></a>

當您想要將自訂欄位/屬性新增至常見問答集問題時，請使用自訂 CSV 檔案。對於自訂 CSV 檔案，您可以使用 CSV 檔案中的標頭列來定義其他屬性。

CSV 檔案必須包含下列兩個必要欄位：
+ `_question`- 常見問答集
+ `_answer`- 常見問題的答案

您的自訂 CSV 檔案可以同時包含 Amazon Kendra 預留欄位 (`_faq_id`、`_document_title`、 `_data_source_id`和 除外`_file_type`) 和任何自訂欄位。

 以下是自訂 CSV 檔案的範例。

```
_question,_answer,_last_updated_at,custom_string
How many free clinics are in Spokane WA?, 13, 2012-03-25T12:30:10+01:00, Note: Some free clinics require you to meet certain criteria in order to use their services
How many free clinics are there in Mountain View Missouri?, 7, 2012-03-25T12:30:10+01:00, Note: Some free clinics require you to meet certain criteria in order to use their services
```

自訂檔案的內容必須遵循[逗號分隔值 (CSV) 檔案的 RFC 4180 常見格式和 MIME 類型](https://tools.ietf.org/html/rfc4180)。

以下列出自訂欄位的類型：
+ 日期 - ISO 8601 編碼的日期和時間值。

  例如，2012-03-25T12:30:10\$101:00 表示以 ISO 8601 格式記錄的時間：歐洲中部時間 2012 年 3 月 25 日 12:30 (加 10 秒)。
+ 長 - 數字，例如 `1234`。
+ String - 字串值。如果您的字串包含逗號，請以雙引號 (") 括住整個值 （例如 `"custom attribute, and more"`)。
+ 字串清單 - 字串值的清單。列出逗號分隔清單中以引號 (") 括住的值 （例如 `"item1, item2, item3"`)。如果清單只包含單一項目，您可以省略引號 （例如 `item1`)。

自訂 CSV 檔案可包含使用者存取控制欄位。您可以使用這些欄位，將常見問答集的存取權限制在特定使用者和群組。若要篩選使用者內容，使用者必須在查詢中提供使用者和群組資訊。否則，會傳回所有相關FAQs。如需詳細資訊，請參閱[使用者內容篩選](https://docs.aws.amazon.com/kendra/latest/dg/user-context-filter.html)。

以下列出FAQs的使用者內容篩選條件：
+ `_acl_user_allow`- 允許清單中的使用者可以在查詢回應中查看常見問答集。常見問答集不會傳回給其他使用者。
+ `_acl_user_deny`- 拒絕清單中的使用者看不到查詢回應中的常見問答集。當與查詢相關時，常見問答集會傳回給所有其他使用者。
+ `_acl_group_allow`—身為允許群組成員的使用者可以在查詢回應中查看常見問答集。常見問答集不會傳回給屬於另一個群組的使用者。
+ `_acl_group_deny`- 拒絕群組成員的使用者在查詢回應中看不到常見問答集。常見問答集會在與查詢相關時傳回給其他群組。

在以引號括住的逗號分隔清單中提供允許和拒絕清單的值 （例如，`"user1,user2,user3"`)。您可以在允許清單或拒絕清單中包含使用者或群組，但不能同時包含個別允許相同使用者但也拒絕群組的使用者。如果您在兩者中都包含使用者或群組，您會收到錯誤。

以下是具有使用者內容資訊的自訂 CSV 檔案範例。

```
_question, _answer, _acl_user_allow, _acl_user_deny, _acl_group_allow, _acl_group_deny
How many free clinics are in Spokane WA?, 13, "userID6201,userID7552", "userID1001,userID2020", groupBasicPlusRate, groupPremiumRate
```

## JSON 檔案
<a name="faq-custom-json"></a>

您可以使用 JSON 檔案來提供索引的問題、答案和欄位。您可以將任何 Amazon Kendra 預留欄位或自訂欄位新增至常見問答集。

以下是 JSON 檔案的結構描述。

```
{
    "SchemaVersion": 1,
    "FaqDocuments": [
        {
            "Question": string,
            "Answer": string,
            "Attributes": {
                string: object
                additional attributes
            },
            "AccessControlList": [
               {
                   "Name": string,
                   "Type": enum( "GROUP" | "USER" ),
                   "Access": enum( "ALLOW" | "DENY" )
               },
               additional user context
            ]
        },
        additional FAQ documents
    ]
}
```

下列範例 JSON 檔案顯示兩份常見問答集文件。其中一個文件只有必要的問題和答案。其他文件也包含其他欄位和使用者內容或存取控制資訊。

```
{
    "SchemaVersion": 1,
    "FaqDocuments": [
        {
            "Question": "How many free clinics are in Spokane WA?",
            "Answer": "13"
        },
        {
            "Question": "How many free clinics are there in Mountain View Missouri?",
            "Answer": "7",
            "Attributes": {
                "_source_uri": "https://s3.region.company.com/bucket-name/directory/faq.csv",
                "_category": "Charitable Clinics"
            },
            "AccessControlList": [
               {
                   "Name": "user@amazon.com",
                   "Type": "USER",
                   "Access": "ALLOW"
               },
               {
                   "Name": "Admin",
                   "Type": "GROUP",
                   "Access": "ALLOW"
               }
            ]
        }
    ]
}
```

以下列出自訂欄位的類型：
+ Date - 具有 ISO 8601 編碼日期和時間值的 JSON 字串值。例如，2012-03-25T12:30:10\$101:00 表示以 ISO 8601 格式記錄的時間：歐洲中部時間 2012 年 3 月 25 日 12:30 (加 10 秒)。
+ 長 - JSON 數字值，例如 `1234`。
+ 字串 - JSON 字串值 （例如 `"custom attribute"`)。
+ 字串清單 - 字串值的 JSON 陣列 （例如，`["item1,item2,item3"]`)。

JSON 檔案可包含使用者存取控制欄位。您可以使用這些欄位，將常見問答集的存取權限制在特定使用者和群組。若要篩選使用者內容，使用者必須在查詢中提供使用者和群組資訊。否則，會傳回所有相關FAQs。如需詳細資訊，請參閱[使用者內容篩選](https://docs.aws.amazon.com/kendra/latest/dg/user-context-filter.html)。

您可以在允許清單或拒絕清單中包含使用者或群組，但不能同時包含個別允許相同使用者但也拒絕群組的使用者。如果您在兩者中都包含使用者或群組，您會收到錯誤。

以下是包含 JSON 常見問答集使用者存取控制的範例。

```
"AccessControlList": [
                {
                    "Name": "group or user name",
                    "Type": "GROUP | USER",
                    "Access": "ALLOW | DENY"
                },
                additional user context
            ]
```

## 使用您的常見問答集檔案
<a name="using-faq-file"></a>

將常見問答集輸入檔案存放在 S3 儲存貯體之後，您可以使用 主控台或 `CreateFaq` API 將問題和答案放入您的索引。如果您想要更新常見問答集，請刪除常見問答集並再次建立。您可以使用 `DeleteFaq` API 來刪除常見問答集。

您必須提供可存取包含來源檔案之 S3 儲存貯體 IAM 的角色。您可以在 主控台或 `RoleArn` 參數中指定角色。以下是將常見問答集檔案新增至索引的範例。

------
#### [ Python ]

```
import boto3

kendra = boto3.client("kendra")

# Provide the index ID
index_id = "index-id"
# Provide the IAM role ARN required to index documents in an S3 bucket
role_arn = "arn:aws:iam::${accountId}:role/${roleName}"

# Provide the S3 bucket path information to the FAQ file
faq_path = {
    "Bucket": "bucket-name",
    "Key": "FreeClinicsUSA.csv"
}

response = kendra.create_faq(
    S3Path =  faq_path,
    Name = "FreeClinicsUSA",
    IndexId = index_id,
    RoleArn = role_arn
)

print(response)
```

------
#### [ Java ]

```
package com.amazonaws.kendra;

import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.CreateFaqRequest;
import software.amazon.awssdk.services.kendra.model.CreateFaqResponse;
import software.amazon.awssdk.services.kendra.model.S3Path;

public class AddFaqExample {
    public static void main(String[] args) {
        KendraClient kendra = KendraClient.builder().build();

        String indexId = "yourIndexId";
        String roleArn = "your role for accessing S3 files";

        CreateFaqRequest createFaqRequest = CreateFaqRequest
            .builder()
            .indexId(indexId)
            .name("FreeClinicsUSA")
            .roleArn(roleArn)
            .s3Path(
                S3Path
                    .builder()
                    .bucket("amzn-s3-demo-bucket")
                    .key("FreeClinicsUSA.csv")
                    .build())
            .build();

        CreateFaqResponse response = kendra.createFaq(createFaqRequest);

        System.out.println(String.format("The result of creating FAQ: %s", response));

    }
}
```

------

## 英文以外語言的常見問答集檔案
<a name="faq-languages"></a>

您可以用支援的語言為常見問答集編製索引。如果您未指定語言，預設會以英文為FAQs編製 Amazon Kendra 索引。您可以在呼叫 [CreateFaq](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateFaq.html) 操作時指定語言代碼，也可以在常見問答集中繼資料中包含常見問答集的語言代碼做為欄位。如果常見問答集在其中繼資料欄位中指定的中繼資料中沒有語言代碼，則常見問答集會使用您呼叫 `CreateFAQ`操作時指定的語言代碼來編製索引。若要在主控台中以支援的語言編製常見問答集文件索引，請前往**FAQs**，然後選取**新增常見問答集**。您可以從下拉式清單中選擇語言****。

# 建立自訂文件欄位
<a name="custom-attributes"></a>

**注意**  
功能支援會因索引類型和正在使用的搜尋 API 而有所不同。若要查看您正在使用的索引類型和搜尋 API 是否支援此功能，請參閱[搜尋索引](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index.html#index-searching)。

您可以在 Amazon Kendra 索引中為文件建立自訂屬性或欄位。例如，您可以建立名為 "Department" 的自訂欄位或屬性，其值為 "HR"、"Sales" 和 "Manufacturing"。如果您將這些自訂欄位或屬性映射到您的 Amazon Kendra 索引，您可以使用它們來篩選搜尋結果，以包含「HR」部門屬性的文件。

您必須先在索引中建立 欄位，才能使用自訂欄位或屬性。使用主控台編輯資料來源欄位映射以新增自訂欄位，或使用 [UpdateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_UpdateIndex.html) API 建立索引欄位。建立欄位後，就無法變更欄位資料類型。

對於大多數資料來源，您可以將外部資料來源中的欄位映射到 中的對應欄位 Amazon Kendra。如需詳細資訊，請參閱[映射資料來源欄位](https://docs.aws.amazon.com/kendra/latest/dg/field-mapping.html)。對於 S3 資料來源，您可以使用 JSON 中繼資料檔案建立自訂欄位或屬性。

您最多可以建立 500 個自訂欄位或屬性。

您也可以使用 Amazon Kendra 預留或通用欄位。如需詳細資訊，請參閱[文件屬性或欄位](https://docs.aws.amazon.com/kendra/latest/dg/hiw-document-attributes.html)。

**Topics**
+ [更新自訂文件欄位](#update-attributes)

## 更新自訂文件欄位
<a name="update-attributes"></a>

使用 `UpdateIndex` API，您可以使用 `DocumentMetadataConfigurationUpdates` 參數新增自訂欄位或屬性。

下列 JSON 範例示範如何使用 `DocumentMetadataConfigurationUpdates` 將名為「部門」的欄位新增至索引。

```
"DocumentmetadataConfigurationUpdates": [
   {
       "Name": "Department",
       "Type": "STRING_VALUE"
   }
]
```

下列各節包含使用 [BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument.html) 為 Amazon S3 資料來源新增自訂屬性或欄位的範例。

**Topics**
+ [使用 BatchPutDocument API 新增自訂屬性或欄位](#custom-attributes-batch)
+ [將自訂屬性或欄位新增至 Amazon S3 資料來源](#custom-attributes-s3)

### 使用 BatchPutDocument API 新增自訂屬性或欄位
<a name="custom-attributes-batch"></a>

當您使用 [BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument.html) API 將文件新增至索引時，您可以指定自訂欄位或屬性做為 的一部分`Attributes`。您可以在呼叫 API 時新增多個欄位或屬性。您最多可以建立 500 個自訂欄位或屬性。下列範例顯示新增「部門」欄位至文件的自訂屬性設定方式。

```
"Attributes": 
    {
        "Department": "HR",
        "_category": "Vacation policy"
    }
```

### 將自訂屬性或欄位新增至 Amazon S3 資料來源
<a name="custom-attributes-s3"></a>

當您使用 S3 儲存貯體做為索引的資料來源時，您可以將中繼資料新增至具有配套中繼資料檔案的文件。中繼資料 JSON 檔案須放置於與文件相對應、層級平行的目錄結構中。如需詳細資訊，請參閱 [S3 文件中繼資料](https://docs.aws.amazon.com/kendra/latest/dg/s3-metadata.html)。

自訂欄位或屬性可在 `Attributes` JSON 結構中進行設定。您最多可以建立 500 個自訂欄位或屬性。例如，下列範例使用 `Attributes` 來定義三個自訂欄位或屬性，以及一個預留欄位。

```
"Attributes": {
        "brand": "Amazon Basics",
        "price": 1595,
        "_category": "sports",
        "subcategories": ["outdoors", "electronics"]
    }
```

下列步驟會逐步引導您將自訂屬性新增至 Amazon S3 資料來源。

**Topics**
+ [步驟 1：建立 Amazon Kendra 索引](#custom-attributes-s3-1)
+ [步驟 2：更新索引以新增自訂文件欄位](#custom-attributes-s3-2)
+ [步驟 3：建立 Amazon S3 資料來源，並將資料來源欄位映射至自訂屬性](#custom-attributes-s3-3)

#### 步驟 1：建立 Amazon Kendra 索引
<a name="custom-attributes-s3-1"></a>

依照中的步驟[建立 索引](create-index.md)建立 Amazon Kendra 索引。

#### 步驟 2：更新索引以新增自訂文件欄位
<a name="custom-attributes-s3-2"></a>

建立索引之後，您可以將欄位新增至索引。下列程序說明如何使用 主控台和 CLI 將欄位新增至索引。

------
#### [ Console ]

**建立索引欄位**

1. 請確定您[已建立索引](https://docs.aws.amazon.com/kendra/latest/dg/create-index.html)。

1. 然後，從左側導覽功能表中，從**資料管理**中選擇**面向定義**。

1. 在**索引欄位設定指南**的**索引欄位中**，選擇**新增欄位**以新增自訂欄位。

1. 在**新增索引欄位**對話方塊中，執行下列動作：
   + **欄位名稱** – 新增欄位名稱。
   + **資料類型** – 選取資料類型，無論是**字串**、**字串清單**或**日期**。
   + **用量類型** – 選取用量類型，無論是 **Facetable**、**Searchable**、**Displayable** 和 **Sortable**。

     然後，選取**新增**。

   針對您要映射的任何其他欄位重複最後一個步驟。

------
#### [ CLI ]

```
aws kendra update-index  \
--region $region \
--endpoint-url $endpoint \
--application-id $applicationId \
--index-id $indexId  \
--document-metadata-configuration-updates \
"[
    {
        "Name": "string",
        "Type": "STRING_VALUE"|"STRING_LIST_VALUE"|"LONG_VALUE"|"DATE_VALUE",
        "Relevance": {
            "Freshness": true|false,
            "Importance": integer,
            "Duration": "string",
            "RankOrder": "ASCENDING"|"DESCENDING",
            "ValueImportanceMap": {"string": integer
            ...}
    },
    "Search": {
        "Facetable": true|false,
        "Searchable": true|false,
        "Displayable": true|false,
        "Sortable": true|false
        }
    }
...
]"
```

------

#### 步驟 3：建立 Amazon S3 資料來源，並將資料來源欄位映射至自訂屬性
<a name="custom-attributes-s3-3"></a>

若要建立 Amazon S3 資料來源並對應欄位，請遵循 中的指示[Amazon S3](data-source-s3.md)。

如果您使用的是 API，請在使用 [CreateDataSource](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateDataSource.html) API `configuration`時使用 下的 `fieldMappings` 屬性。

如需資料來源欄位映射方式的概觀，請參閱 [對應資料來源欄位](field-mapping.md)。

# 使用字符控制使用者對文件的存取
<a name="create-index-access-control"></a>

**注意**  
功能支援會因索引類型和正在使用的搜尋 API 而有所不同。若要查看您正在使用的索引類型和搜尋 API 是否支援此功能，請參閱[索引類型](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html)。

**重要**  
Amazon Kendra GenAI Enterprise Edition 索引不支援字符型使用者存取控制。

您可以控制哪些使用者或群組可以存取索引中的特定文件，或在搜尋結果中查看特定文件。這稱為使用者內容篩選。這是一種個人化搜尋，具有控制文件存取的優點。例如，並非所有搜尋公司入口網站資訊的團隊都應該存取最機密的公司文件，這些文件也與所有使用者無關。只有獲得最高機密文件存取權的特定使用者或團隊群組，才能在其搜尋結果中查看這些文件。

Amazon Kendra 企業和開發人員索引支援使用下列字符類型的字符型使用者存取控制：
+ 開啟 ID
+ 具有共用秘密的 JWT
+ 具有公有金鑰的 JWT
+ JSON

Amazon Kendra 可用於為您的擷取和搜尋應用程式提供安全的企業搜尋。在查詢和擷取期間， 會根據請求中`UserContext`提供的 `AttributeFilters` 和 Amazon Kendra 篩選搜尋結果。 會 Amazon Kendra 讀取其連接器在網路爬取和擷取期間收集的文件存取控制清單 (ACLs)。擷取和搜尋結果會傳回指向原始文件儲存庫加上簡短摘錄URLs。原始儲存庫仍會強制執行完整文件的存取。

**Topics**
+ [使用 OpenID](create-index-access-control-tokens-openid.md)
+ [將 JSON Web Token (JWT) 與共用秘密搭配使用](create-index-access-control-tokens-jwtshared.md)
+ [搭配公有金鑰使用 JSON Web Token (JWT)](create-index-access-control-tokens-jwtpublic.md)
+ [使用 JSON](create-index-access-control-tokens-json.md)

# 使用 OpenID
<a name="create-index-access-control-tokens-openid"></a>

若要設定 Amazon Kendra 索引以使用 OpenID 字符進行存取控制，您需要 OpenID 供應商的 OpenID(JSON Web 金鑰集） URL。在大多數情況下，JWKS URL 的格式如下 （如果遵循 openId 探索）`https://domain-name/.well_known/jwks.json`。

下列範例示範如何在建立索引時使用 OpenID 字符進行使用者存取控制。

------
#### [ Console ]

1. 選擇**建立索引**以開始建立新的索引。

1. 在**指定索引詳細資訊**頁面上，為您的索引指定名稱和描述。

1. 針對**IAM 角色**，選取角色或選取**建立新角色**，並指定角色名稱以建立新的角色。IAM 角色的字首為「AmazonKendra-」。

1. 將所有其他欄位保留為預設值。選擇**下一步**。

1. 在**設定使用者存取控制**頁面的**存取控制設定**下，選擇**是**以使用字符進行存取控制。

1. 在**字符組態**下，選取 **OpenID** 做為**字符類型**。

1. 指定**簽署金鑰 URL**。URL 應指向一組 JSON Web 金鑰。

1. 在**進階組態**下*選用*：

   1. 指定要在 ACL 檢查中使用的**使用者名稱**。

   1. 指定要在 ACL 檢查中使用的一或多個**群組**。

   1. 指定將驗證字符發行**者的發行**者。

   1. 指定**用戶端 ID (s)**。您必須指定符合 JWT 中對象的規則表達式。

1. 在**佈建詳細資訊**頁面中，選擇**開發人員版本**。

1. 選擇**建立**以建立您的索引。

1. 等待您的索引建立。 Amazon Kendra 佈建索引的硬體。此操作可能需要一些時間。

------
#### [ CLI ]

若要 AWS CLI 使用 JSON 輸入檔案使用 建立索引，請先使用所需的參數建立 JSON 檔案：

```
{
    "Name": "user-context",
    "Edition": "ENTERPRISE_EDITION",
    "RoleArn": "arn:aws:iam::account-id:role:/my-role",
    "UserTokenConfigurations": [
        {
            "JwtTokenTypeConfiguration": {
                "KeyLocation": "URL",
                "Issuer": "optional: specify the issuer url",
                "ClaimRegex": "optional: regex to validate claims in the token",
                "UserNameAttributeField": "optional: user",
                "GroupAttributeField": "optional: group",
                "URL": "https://example.com/.well-known/jwks.json"
            }
        }
    ],
    "UserContextPolicy": "USER_TOKEN"
}
```

您可以覆寫預設的使用者和群組欄位名稱。的預設值`UserNameAttributeField`為「使用者」。的預設值`GroupAttributeField`為「群組」。

接著，`create-index`使用輸入檔案呼叫 。例如，如果您的 JSON 檔案名稱為 `create-index-openid.json`，您可以使用下列項目：

```
aws kendra create-index --cli-input-json file://create-index-openid.json
```

------
#### [ Python ]

```
response = kendra.create_index(
    Name='user-context',
    Edition='ENTERPRISE_EDITION',
    RoleArn='arn:aws:iam::account-id:role:/my-role',
    UserTokenConfigurations=[
        {
            "JwtTokenTypeConfiguration": {
                "KeyLocation": "URL",
                "Issuer": "optional: specify the issuer url",
                "ClaimRegex": "optional: regex to validate claims in the token",
                "UserNameAttributeField": "optional: user",
                "GroupAttributeField": "optional: group",
                "URL": "https://example.com/.well-known/jwks.json"
            }
        }
    ],
    UserContextPolicy='USER_TOKEN'
)
```

------

# 將 JSON Web Token (JWT) 與共用秘密搭配使用
<a name="create-index-access-control-tokens-jwtshared"></a>

下列範例示範如何在建立索引時將 JSON Web Token (JWT) 與共用秘密權杖搭配使用，以進行使用者存取控制。

------
#### [ Console ]

1. 選擇**建立索引**以開始建立新的索引。

1. 在**指定索引詳細資訊**頁面上，為您的索引提供名稱和描述。

1. 針對 **IAM 角色**，選取角色或選取**建立新角色**，並指定角色名稱以建立新的角色。 IAM 角色的字首為「AmazonKendra-」。

1. 將所有其他欄位保留為預設值。選擇**下一步**。

1. 在**設定使用者存取控制**頁面的**存取控制設定**下，選擇**是**以使用字符進行存取控制。

1. 在**字符組態**下，選取**具有共用秘密的 JWT** 做為**字符類型**。

1. 在**簽署共用秘密的參數**下，選擇**秘密類型**。您可以使用現有的 AWS Secrets Manager 共用秘密或建立新的共用秘密。

   若要建立新的共用秘密，請選擇**新增**，然後遵循下列步驟：

   1. 在**新 AWS Secrets Manager 秘密**下，指定**秘密名稱**。當您儲存公有金鑰時，`AmazonKendra-`將會新增 字首。

   1. 指定**金鑰 ID**。金鑰 ID 是提示，指出使用哪個金鑰來保護字符的 JSON Web 簽章。

   1. 選擇權杖的簽署**演算法**。這是用來保護 ID 字符的密碼編譯演算法。如需 RSA 的詳細資訊，請參閱 [RSA 加密法](https://tools.ietf.org/html/rfc3447)。

   1. 輸入 base64 URL 編碼**的秘密來指定共用**秘密。您也可以選取**產生秘密**來為您產生秘密。您必須確保秘密是 base64 URL 編碼的秘密。

   1. (*選用*) 指定共用秘密何時有效。您可以指定秘密有效、有效至 或兩者的日期和時間。秘密在指定的間隔內有效。

   1. 選取**儲存秘密**以儲存新秘密。

1. (*選用*) 在**進階組態**下：

   1. 指定要在 ACL 檢查中使用的**使用者名稱**。

   1. 指定要在 ACL 檢查中使用的一或多個**群組**。

   1. 指定將驗證字符發行**者的發行**者。

   1. 指定**宣告 ID (s)**。您必須指定符合 JWT 中對象的規則表達式。

1. 在**佈建詳細資訊**頁面中，選擇**開發人員版本**。

1. 選擇**建立**以建立您的索引。

1. 等待您的索引建立。為您的索引 Amazon Kendra 佈建硬體。此操作可能需要一些時間。

------
#### [ CLI ]

您可以在 中使用 JWT 字符搭配共用秘密 AWS Secrets Manager。秘密必須是 base64 URL 編碼的秘密。您需要 Secrets Manager ARN，而且您的 Amazon Kendra 角色必須能夠存取 Secrets Manager 資源`GetSecretValue`上的 。如果您使用 加密 Secrets Manager 資源 AWS KMS，該角色也必須具有解密動作的存取權。

若要 AWS CLI 使用 JSON 輸入檔案使用 建立索引，請先使用所需的參數建立 JSON 檔案：

```
{
    "Name": "user-context",
    "Edition": "ENTERPRISE_EDITION",
    "RoleArn": "arn:aws:iam::account-id:role:/my-role",
    "UserTokenConfigurations": [
        {
            "JwtTokenTypeConfiguration": {
                "KeyLocation": "SECRET_MANAGER",
                "Issuer": "optional: specify the issuer url",
                "ClaimRegex": "optional: regex to validate claims in the token",
                "UserNameAttributeField": "optional: user",
                "GroupAttributeField": "optional: group",
                "SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret
            }
        }
    ],    
    "UserContextPolicy": "USER_TOKEN"
}
```

您可以覆寫預設的使用者和群組欄位名稱。的預設值`UserNameAttributeField`為「使用者」。的預設值`GroupAttributeField`為「groups」。

接著，`create-index`使用輸入檔案呼叫 。例如，如果您的 JSON 檔案名稱為 `create-index-openid.json`，您可以使用下列項目：

```
aws kendra create-index --cli-input-json file://create-index-openid.json
```

秘密的格式必須如下 AWS Secrets Manager：

```
{
  "keys": [
    {
      "kid": "key_id",
      "alg": "HS256|HS384|HS512",
      "kty": "OCT", 
      "use": "sig", //this value can be sig only for now
      "k": "secret",
      "nbf":"ISO1806 date format"
      "exp":"ISO1806 date format"
    }
  ]
}
```

如需 JWT 的詳細資訊，請參閱 https：//[jwt.io](http://jwt.io)。

------
#### [ Python ]

您可以在 中使用 JWT 字符搭配共用秘密 AWS Secrets Manager。秘密必須是 base64 URL 編碼的秘密。您需要 Secrets Manager ARN，而且您的 Amazon Kendra 角色必須能夠存取 Secrets Manager 資源`GetSecretValue`上的 。如果您使用 加密 Secrets Manager 資源 AWS KMS，該角色也必須具有解密動作的存取權。

```
response = kendra.create_index(
    Name='user-context',
    Edition='ENTERPRISE_EDITION',
    RoleArn='arn:aws:iam::account-id:role:/my-role',
    UserTokenConfigurations=[
        {
            "JwtTokenTypeConfiguration": {
                "KeyLocation": "URL",
                "Issuer": "optional: specify the issuer url",
                "ClaimRegex": "optional: regex to validate claims in the token",
                "UserNameAttributeField": "optional: user",
                "GroupAttributeField": "optional: group",
                "SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret"
            }
        }
    ],
    UserContextPolicy='USER_TOKEN'
)
```

------

# 搭配公有金鑰使用 JSON Web Token (JWT)
<a name="create-index-access-control-tokens-jwtpublic"></a>

下列範例示範如何在建立索引時將 JSON Web Token (JWT) 與公有金鑰搭配使用，以進行使用者存取控制。如需 JWT 的詳細資訊，請參閱 https：//[jwt.io](http://jwt.io)。

------
#### [ Console ]

1. 選擇**建立索引**以開始建立新的索引。

1. 在**指定索引詳細資訊**頁面上，為您的索引指定名稱和描述。

1. 針對 **IAM 角色**，選取角色或選取**建立新角色**，並指定角色名稱以建立新的角色。 IAM 角色的字首為「AmazonKendra-」。

1. 將所有其他欄位保留為預設值。選擇**下一步**。

1. 在**設定使用者存取控制**頁面的**存取控制設定**下，選擇**是**以使用字符進行存取控制。

1. 在**字符組態**下，選取 **JWT 搭配公有金鑰**做為**字符類型**。

1. 在**簽署公有金鑰的參數**下，選擇**秘密類型**。您可以使用現有的 AWS Secrets Manager 秘密或建立新的秘密。

   若要建立新的秘密，請選擇**新增**，然後遵循下列步驟：

   1. 在**新 AWS Secrets Manager 秘密**下，指定**秘密名稱**。當您儲存公有金鑰時，`AmazonKendra-`將會新增 字首。

   1. 指定**金鑰 ID**。金鑰 ID 是提示，指出使用哪個金鑰來保護字符的 JSON Web 簽章。

   1. 選擇權杖的簽署**演算法**。這是用來保護 ID 字符的密碼編譯演算法。如需 RSA 的詳細資訊，請參閱 [RSA 加密法](https://tools.ietf.org/html/rfc3447)。

   1. 在**憑證屬性**下，指定*選用*的**憑證鏈**。憑證鏈是由憑證清單組成。它以伺服器的憑證開頭，並以根憑證終止。

   1. *選用* 指定**指紋或指紋**。它應該是憑證的雜湊，計算所有憑證資料及其簽章。

   1. 指定**指數**。這是 RSA 公有金鑰的指數值。它以 Base64urlUInt 編碼值表示。

   1. 指定**模數**。這是 RSA 公有金鑰的指數值。它以 Base64urlUInt 編碼值表示。

   1. 選取**儲存金鑰**以儲存新金鑰。

1. 在**進階組態**下*選用*：

   1. 指定要在 ACL 檢查中使用的**使用者名稱**。

   1. 指定要在 ACL 檢查中使用的一或多個**群組**。

   1. 指定將驗證字符發行**者的發行**者。

   1. 指定**用戶端 ID (s)**。您必須指定符合 JWT 中對象的規則表達式。

1. 在**佈建詳細資訊**頁面中，選擇**開發人員版本**。

1. 選擇**建立**以建立您的索引。

1. 等待您的索引建立。為您的索引 Amazon Kendra 佈建硬體。此操作可能需要一些時間。

------
#### [ CLI ]

您可以使用 JWT 搭配 內的公有金鑰 AWS Secrets Manager。您需要 Secrets Manager ARN，而且您的 Amazon Kendra 角色必須能夠存取 Secrets Manager 資源`GetSecretValue`上的 。如果您使用 加密 Secrets Manager 資源 AWS KMS，該角色也必須具有解密動作的存取權。

若要 AWS CLI 使用 JSON 輸入檔案使用 建立索引，請先使用所需的參數建立 JSON 檔案：

```
{
    "Name": "user-context",
    "Edition": "ENTERPRISE_EDITION",
    "RoleArn": "arn:aws:iam::account id:role:/my-role",
    "UserTokenConfigurationList": [
        {
            "JwtTokenTypeConfiguration": {
                "KeyLocation": "SECRET_MANAGER",
                "Issuer": "optional: specify the issuer url",
                "ClaimRegex": "optional: regex to validate claims in the token",
                "UserNameAttributeField": "optional: user",
                "GroupAttributeField": "optional: group",
                "SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret
            }
        }
    ],    "UserContextPolicy": "USER_TOKEN"
}
```

您可以覆寫預設的使用者和群組欄位名稱。的預設值`UserNameAttributeField`為「使用者」。的預設值`GroupAttributeField`為「groups」。

接著，`create-index`使用輸入檔案呼叫 。例如，如果您的 JSON 檔案名稱為 `create-index-openid.json`，您可以使用下列項目：

```
aws kendra create-index --cli-input-json file://create-index-openid.json
```

秘密的格式必須如下 Secrets Manager：

```
{
  "keys": [
    {
      "alg": "RS256|RS384|RS512",
      "kty": "RSA", //this can be RSA only for now
      "use": "sig", //this value can be sig only for now
      "n": "modulus of standard pem",
      "e": "exponent of standard pem",
      "kid": "key_id",
      "x5t": "certificate thumprint for x.509 cert",
      "x5c": [
        "certificate chain"
      ]
    }
  ]
}
```

如需 JWT 的詳細資訊，請參閱 https：//[jwt.io](http://jwt.io)。

------
#### [ Python ]

```
response = kendra.create_index(
    Name='user-context',
    Edition='ENTERPRISE_EDITION',
    RoleArn='arn:aws:iam::account id:role:/my-role',
    UserTokenConfigurationList=[
        {
            "JwtTokenTypeConfiguration": {
                "KeyLocation": "URL",
                "Issuer": "optional: specify the issuer url",
                "ClaimRegex": "optional: regex to validate claims in the token",
                "UserNameAttributeField": "optional: user",
                "GroupAttributeField": "optional: group",
                "SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret"
            }
        }
    ],
    UserContextPolicy='USER_TOKEN'
)
```

------

# 使用 JSON
<a name="create-index-access-control-tokens-json"></a>

下列範例示範如何在建立索引時使用 JSON 進行使用者存取控制。

**警告**  
JSON 字符是未經驗證的承載。只有在請求 Amazon Kendra 來自信任的伺服器且從未來自瀏覽器時，才應使用此選項。

------
#### [ Console ]

1. 選擇**建立索引**以開始建立新的索引。

1. 在**指定索引詳細資訊**頁面上，為您的索引指定名稱和描述。

1. 針對**IAM 角色**，選取角色或選取**建立新角色**，並指定角色名稱以建立新的角色。 IAM 角色的字首為「AmazonKendra-」。

1. 將所有其他欄位保留為預設值。選擇**下一步**。

1. 在**設定使用者存取控制**頁面的**存取控制設定**下，選擇**是**以使用字符進行存取控制。

1. 在**字符組態**下，選取 **JSON** 做為**字符類型**。

1. 指定要在 ACL 檢查中使用的**使用者名稱**。

1. 指定要在 ACL 檢查中使用的一或多個**群組**。

1. 選擇**下一步**。

1. 在**佈建詳細資訊**頁面中，選擇**開發人員版本**。

1. 選擇**建立**以建立您的索引。

1. 等待您的索引建立。 Amazon Kendra 佈建索引的硬體。此操作可能需要一些時間。

------
#### [ CLI ]

若要 AWS CLI 使用 JSON 輸入檔案使用 建立索引，請先使用所需的參數建立 JSON 檔案：

```
{
    "Name": "user-context",
    "Edition": "ENTERPRISE_EDITION",
    "RoleArn": "arn:aws:iam::account-id:role:/my-role",
    "UserTokenConfigurations": [
        {
            "JsonTokenTypeConfiguration": {
                "UserNameAttributeField": "user",
                "GroupAttributeField": "group"
            }
        }
    ],
    "UserContextPolicy": "USER_TOKEN"
}
```

接著，`create-index`使用輸入檔案呼叫 。例如，如果您的 JSON 檔案名稱為 `create-index-openid.json`，您可以使用下列項目：

```
aws kendra create-index --cli-input-json file://create-index-openid.json
```

如果您不是針對 使用 Open ID AWS IAM Identity Center，則可以將 JSON 格式的字符傳送給我們。如果您這麼做，則必須指定 JSON 權杖中的哪個欄位包含使用者名稱，以及哪個欄位包含群組。群組欄位值必須是 JSON 字串陣列。例如，如果您使用的是 SAML，您的字符會與下列類似：

```
{
     "username" : "user1", 
     "groups": [
        "group1", 
        "group2"
     ]
}
```

`TokenConfiguration` 會指定使用者名稱和群組欄位名稱：

```
{
    "UserNameAttributeField":"username",
    "GroupAttributeField":"groups"
}
```

------
#### [ Python ]

```
response = kendra.create_index(
    Name='user-context',
    Edition='ENTERPRISE_EDITION',
    RoleArn='arn:aws:iam::account-id:role:/my-role',
    UserTokenConfigurations=[
        {
            "JwtTokenTypeConfiguration": {
                "UserNameAttributeField": "user",
                "GroupAttributeField": "group",
            }
        }
    ],
    UserContextPolicy='USER_TOKEN'
)
```

------