本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

您可以使用控制台或通过调用 [CreateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateIndex.html)API 来创建索引。您可以将 AWS Command Line Interface (AWS CLI) 或 SDK 与 API 配合使用。创建索引后，您可以直接向索引中添加文档，也可以从数据来源添加文档。

要创建索引，您必须提供 () 角色的 Amazon 资源名称 AWS Identity and Access Management (ARN IAM) 以供索引访问。 CloudWatch有关更多信息，请参阅[索引的IAM 角色](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html#iam-roles-index)。

以下选项卡提供了使用创建索引的过程，以及使用 AWS 管理控制台、Python 和 Java 的 AWS CLI代码示例 SDKs。

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

**创建索引**

1. 登录 AWS 管理控制台并打开控制 Amazon Kendra 台，网址为[https://console.aws.amazon.com/kendra/](https://console.aws.amazon.com/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 资源名称 (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. 索引可能需要一些时间才能创建完成。要检查索引的状态，请在以下命令中使用 `create-index` 返回的索引 ID。当索引的状态为 `ACTIVE` 时，说明您的索引就已经准备就绪。

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

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

**创建索引**
+ ‌为以下代码示例中的变量提供值：
  + `description` - 正在创建的索引的描述。这是可选的。
  + `index_name` - 正在创建的索引的名称。
  + `role_arn`— 可以运行的角色的亚马逊资源名称 (ARN)。 Amazon Kendra APIs有关更多信息，请参阅 [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`— 可以运行的角色的亚马逊资源名称 (ARN)。 Amazon Kendra APIs有关更多信息，请参阅 [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 来监控为文档编制索引的进度。当您使用文档列表调用 `BatchGetDocumentStatus` API 时 IDs，它会返回文档的状态。当文档状态为 `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)将文本块添加到索引中。您可以使用 `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 文件 fields/attributes ，可用于对常见问题答复进行分解、显示或排序。您还可以定义访问权限控制字段，将常见问题解答响应限制为仅允许特定用户和组查看。
+ JSON-包含问题、答案和自定义的 JSON 文件 fields/attributes ，可用于对常见问题解答进行分解、显示或排序。您还可以定义访问权限控制字段，将常见问题解答响应限制为仅允许特定用户和组查看。

例如，下面是一个基本 CSV 文件，它提供了有关美国华盛顿州斯波坎和美国密苏里州山景城免费诊所的问题的答案。

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

**注意**  
FAQ 文件必须是 UTF-8 编码的文件。

**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) 文件进行输入时，您可以为常见问题声明自定义字段。例如，您可以创建一个自定义字段，将每个常见问题解答的问题分配一个业务部门。例如，在响应中返回常见问题解答时，您可以使用部门作为一个分面，将搜索范围缩小到“人力资源”或“财务”部门。

自定义字段必须映射到索引字段。在控制台中，您可以使用**分面定义**页面来创建索引字段。使用 API 时，必须先使用 [UpdateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_UpdateIndex.html)API 创建索引字段。

FAQ 文件中的 field/attribute 类型必须与关联索引字段的类型相匹配。例如，“部门”字段是一个 `STRING_LIST` 类型字段。因此，您必须在常见问题解答文件中以字符串列表的形式提供部门字段的值。您可以使用控制台中的 **Facet 定义**页面或使用 [DescribeIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_DescribeIndex.html)API 来检查索引字段的类型。

创建映射到自定义属性的索引字段时，您可以将其标记为可显示、可分面或可排序。无法将自定义属性设置为可搜索。

除了自定义属性外，您还可以在自定义 CSV 或 JSON 文件中使用 Amazon Kendra 保留或常用的字段。有关更多信息，请参阅[文档属性或字段](https://docs.aws.amazon.com/kendra/latest/dg/hiw-document-attributes.html)。

## 基本 CSV 文件
<a name="faq-basic-csv"></a>

当您想使用简单的结构时，请使用基本的 CSV 文件 FAQs。在基本 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>

当您想为常见问题解答问题添加自定义内容时， fields/attributes 请使用自定义 CSV 文件。对于自定义 CSV 文件，您可以使用 CSV 文件中的标头行来定义其他属性。

CSV 文件必须包含以下两个必需字段：
+ `_question` - 常见问题
+ `_answer` - 常见问题的答案

您的自定义 CSV 文件可以同时包含 Amazon Kendra 保留字段（`_faq_id`、`_data_source_id``_document_title`、和除外`_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)。

下面列出了自定义字段的类型：
+ Date - ISO 8601 编码的日期和时间值。

  例如，2012-03-25T12:30:10\$101:00 是中部欧洲时间 2012 年 3 月 25 日中午 12:30（10 秒）的 ISO 8601 日期-时间格式。
+ Long - 数字，例如，`1234`。
+ String - 字符串值。如果字符串包含逗号，请用双引号（"）将整个值括起来（例如，`"custom attribute, and more"`）。
+ String list - 字符串值的列表。列出使用引号（"）括起来的逗号分隔值列表（例如，`"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 是中部欧洲时间 2012 年 3 月 25 日中午 12:30（10 秒）的 ISO 8601 日期-时间格式。
+ Long - JSON 数值，例如，`1234`。
+ String - JSON 字符串值（例如，`"custom attribute"`）。
+ String list - 字符串值的 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>

您可以使用支持的语言为常见问题解答编制索引。 Amazon Kendra 如果您未指定语言，则默认使用英语进行索引 FAQs 。您可以在调用[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` 来向索引添加名为“Department”的字段。

```
"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 个自定义字段或属性。以下示例是将“Department”添加到文档中的自定义字段或属性。

```
"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. 在**添加索引字段**对话框中，执行以下操作：
   + **字段名** - 添加字段名称。
   + **数据类型** - 选择数据类型，可以是**字符串**、**字符串列表**或**日期**。
   + **使用类型** - 选择使用类型，可以是**可分面**、**可搜索**、**可显示**和**可排序**。

     然后，选择**添加**。

   对要映射的任何其他字段重复最后一步。

------
#### [ 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，请在使用 AP [CreateDataSource](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateDataSource.html)I `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 企业版索引不支持基于令牌的用户访问控制。

您可以控制哪些用户或组可以访问索引中的某些文档或在搜索结果中查看某些文档。这称为用户上下文筛选。这是一种个性化搜索，其优点是可以控制对文档的访问权限。例如，并非所有在公司门户网站上搜索信息的团队都应该访问绝密的公司文档，这些文档也不应与所有用户相关。只有获得绝密文档访问权限的特定用户或团队组才能在搜索结果中看到这些文档。

Amazon Kendra 企业和开发者索引支持使用以下令牌类型进行基于令牌的用户访问控制：
+ Open ID
+ 带有共享密钥的 JWT
+ 带有公有密钥的 JWT
+ JSON

Amazon Kendra 可用于为您的检索和搜索应用程序提供安全的企业搜索。在查询和检索期间，根据`AttributeFilters`请求中`UserContext`提供的 Amazon Kendra 内容筛选搜索结果。 Amazon Kendra 读取其连接器在抓取和摄取期间收集的文档访问控制列表 (ACLs)。检索和搜索结果返回时 URLs 指向原始文档存储库以及简短的摘录。对完整文档的访问仍由原始存储库强制执行。

**Topics**
+ [使用 OpenID](create-index-access-control-tokens-openid.md)
+ [使用带有共享密钥的 JSON Web 令牌（JWT）](create-index-access-control-tokens-jwtshared.md)
+ [使用带有公有密钥的 JSON Web 令牌（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 提供程序的 JWKS（JSON Web 密钥集）URL。在大多数情况下，JWKS URL 采用以下格式：`https://domain-name/.well_known/jwks.json`（如果他们关注的是 OpenID 发现）。

以下示例说明在创建索引时如何使用 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**。您必须指定与 JWT 中的受众相匹配的正则表达式。

1. 在**配置详细信息**页面中，选择**开发者版本**。

1. 选择**创建**以创建索引。

1. 等待索引创建完成。Amazon Kendra 会为索引预配硬件。此操作可能需要一些时间。

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

要使用 JSON 输入文件通过 AWS CLI 创建索引，请先使用所需参数创建一个 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` 的默认值为“user”。`GroupAttributeField` 的默认值为“groups”。

接下来，使用输入文件调用 `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 令牌（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**。您必须指定与 JWT 中的受众相匹配的正则表达式。

1. 在**配置详细信息**页面中，选择**开发者版本**。

1. 选择**创建**以创建索引。

1. 等待您的索引创建完成。 Amazon Kendra 为您的索引配置硬件。此操作可能需要一些时间。

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

您可以将 JWT 令牌与内部共享密钥一起使用。 AWS Secrets Manager该密钥必须是 base64 URL 编码的密钥。你需要 Secrets Manager ARN，而且你的 Amazon Kendra 角色必须有权访问该`GetSecretValue`资源。 Secrets Manager 如果您使用加密 Secrets Manager 资源 AWS KMS，则该角色还必须有权访问解密操作。

要使用 JSON 输入文件创建索引，请先 AWS CLI 使用所需参数创建一个 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` 的默认值为“user”。`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 的更多信息，请参阅 [jwt.io](http://jwt.io)。

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

您可以将 JWT 令牌与内部共享密钥一起使用。 AWS Secrets Manager该密钥必须是 base64 URL 编码的密钥。你需要 Secrets Manager ARN，而且你的 Amazon Kendra 角色必须有权访问该`GetSecretValue`资源。 Secrets Manager 如果您使用加密 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 令牌（JWT）
<a name="create-index-access-control-tokens-jwtpublic"></a>

以下示例说明在创建索引时如何使用带有公有密钥的 JSON Web Token（JWT）进行用户访问控制。有关 JWT 的更多信息，请参阅 [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 公有密钥的指数值。它以 base64URL UInt 编码的值表示。

   1. 指定**模数**。这是 RSA 公有密钥的指数值。它以 base64URL UInt 编码的值表示。

   1. 选择**保存密钥**以保存新密钥。

1. （*可选*）在**高级配置**下：

   1. 指定要在 ACL 检查中使用的**用户名**。

   1. 指定要在 ACL 检查中使用的一个或多个**组**。

   1. 指定将验证颁发机构的**颁发机构**。

   1. 指定**客户端 ID**。您必须指定与 JWT 中的受众相匹配的正则表达式。

1. 在**配置详细信息**页面中，选择**开发者版本**。

1. 选择**创建**以创建索引。

1. 等待您的索引创建完成。 Amazon Kendra 为您的索引配置硬件。此操作可能需要一些时间。

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

您可以将 JWT 与 AWS Secrets Manager内部的公有密钥一起使用。你需要 Secrets Manager ARN，而且你的 Amazon Kendra 角色必须有权访问该`GetSecretValue`资源。 Secrets Manager 如果您使用加密 Secrets Manager 资源 AWS KMS，则该角色还必须有权访问解密操作。

要使用 JSON 输入文件创建索引，请先 AWS CLI 使用所需参数创建一个 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` 的默认值为“user”。`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 的更多信息，请参阅 [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 ]

要使用 JSON 输入文件通过 AWS CLI 创建索引，请先使用所需参数创建一个 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
```

如果您未使用适用于 AWS IAM Identity Center 的 Open ID，则可以将 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'
)
```

------