기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 인덱스 생성
콘솔을 사용하거나 [CreateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateIndex.html) API를 직접 호출하여 인덱스를 생성할 수 있습니다. API에서 AWS Command Line Interface (AWS CLI) 또는 SDK를 사용할 수 있습니다. 인덱스를 만든 후 인덱스에 직접 또는 데이터 소스에서 문서를 추가할 수 있습니다.
인덱스를 생성하려면 인덱스가 액세스할 수 있도록 () 역할의 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 Management Console및 AWS CLI Python 및 Java SDKs를 사용하기 위한 코드 예제를 제공합니다.
------
#### [ Console ]
**인덱스를 생성하려면**
1. AWS Management Console에 로그인하고 [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. 다음 명령을 사용하여 인덱스를 생성합니다. 는 Amazon Kendra 작업을 실행할 수 있는 IAM 역할의 Amazon 리소스 이름(ARN)`role-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`- 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`- 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:::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)
+ [인덱스에 자주 묻는 질문(FAQ) 추가](in-creating-faq.md)
+ [사용자 지정 문서 필드 만들기](custom-attributes.md)
+ [토큰을 사용하여 문서에 대한 사용자 액세스 제어](create-index-access-control.md)
# 일괄 업로드를 사용하여 인덱스에 직접 문서 추가
[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](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를 사용하여 문서 인덱싱 진행 상황을 모니터링합니다. 문서 ID 목록을 사용하여 `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는 인덱스별로 고유해야 합니다. 고유한 ID로 문서를 인덱싱하는 데이터 소스를 만든 다음 `BatchPutDocument` API를 사용하여 동일한 문서를 인덱싱할 수 없으며 그 반대의 경우도 마찬가지입니다. 데이터 소스를 삭제한 다음 `BatchPutDocument` API를 사용하여 동일한 문서를 인덱싱하거나 그 반대로 할 수 있습니다. 동일한 문서 세트에 `BatchPutDocument` 및 `BatchDeleteDocument` API를 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를 사용하여 문서 추가
다음 예제에서는 [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](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](https://docs.aws.amazon.com/kendra/latest/dg/create-index.html) CLI 및 SDK를 설정하려면 [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 버킷에서 문서 추가
[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](https://docs.aws.amazon.com/kendra/latest/dg/create-index.html) CLI 및 SDK를 설정하려면 [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));
}
}
```
------
# 인덱스에 자주 묻는 질문(FAQ) 추가
**참고**
기능 지원은 인덱스 유형 및 사용 중인 검색 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를 사용하여 자주 묻는 질문(FAQ)을 인덱스에 직접 추가할 수 있습니다. FAQ를 인덱스에 추가하는 것은 비동기식 작업입니다. Amazon Simple Storage Service 버킷에 저장하는 파일에 FAQ의 데이터를 넣습니다. CSV 또는 JSON 파일을 FAQ 입력으로 사용할 수 있습니다.
+ 기본 CSV - 각 행에 질문, 답변 및 선택적 소스 URI가 포함된 CSV 파일입니다.
+ 사용자 지정 CSV - FAQ 응답을 패싯, 표시 또는 정렬하는 데 사용할 수 있는 사용자 지정 필드/속성에 대한 질문, 답변 및 헤더가 포함된 CSV 파일입니다. 액세스 제어 필드를 정의하여 FAQ 응답을 볼 수 있는 특정 사용자 및 그룹으로 FAQ 응답을 제한할 수도 있습니다.
+ JSON - 질문, 답변, 사용자 지정 필드/속성을 포함하는 JSON 파일로, FAQ 응답을 패싯, 표시 또는 정렬하는 데 사용할 수 있습니다. 액세스 제어 필드를 정의하여 FAQ 응답을 볼 수 있는 특정 사용자 및 그룹으로 FAQ 응답을 제한할 수도 있습니다.
예를 들어, 다음은 미국 워싱턴주 스포캔과 미국 미주리주 마운틴뷰에 있는 무료 진료소에 대한 질문에 대한 답변을 제공하는 기본 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**
+ [FAQ 파일의 인덱스 필드 생성](#in-custom-fields-faq)
+ [기본 CSV 파일](#faq-basic-csv)
+ [사용자 지정 CSV 파일](#faq-custom-csv)
+ [JSON 파일](#faq-custom-json)
+ [FAQ 파일 사용](#using-faq-file)
+ [영어 이외의 언어로 된 FAQ 파일](#faq-languages)
## FAQ 파일의 인덱스 필드 생성
**참고**
기능 지원은 인덱스 유형 및 사용 중인 검색 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 질문에 대한 사용자 지정 필드를 선언할 수 있습니다. 예를 들어 각 FAQ 질문에 비즈니스 부서를 할당하는 사용자 지정 필드를 만들 수 있습니다. 예를 들어 FAQ가 응답으로 반환되면 부서를 패싯으로 사용하여 검색 범위를 “HR” 또는 “재무”로만 좁힐 수 있습니다.
사용자 지정 필드는 인덱스 필드에 매핑되어야 합니다. 콘솔에서 **패싯 정의** 페이지를 사용하여 인덱스 필드를 만들 수 있습니다. API를 사용하는 경우 먼저 [UpdateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_UpdateIndex.html) API를 사용하여 인덱스 필드를 생성해야 합니다.
FAQ 파일의 필드/속성 유형은 관련 인덱스 필드의 유형과 일치해야 합니다. 예를 들어, “부서” 필드는 `STRING_LIST` 유형 필드입니다. 따라서 FAQ 파일에 부서 필드 값을 문자열 목록으로 제공해야 합니다. 콘솔의 **패싯 정의** 페이지를 사용하거나 [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 파일
FAQ에 간단한 구조를 사용하려는 경우 기본 CSV 파일을 사용하세요. 기본 CSV 파일의 각 행에는 질문, 답변, 추가 정보가 포함된 문서를 가리키는 선택적 소스 URI 등 2개 또는 3개의 필드가 있습니다.
파일의 내용은 [RFC 4180 CSV(쉼표로 구분된 값) 파일의 공통 형식 및 MIME 유형](https://tools.ietf.org/html/rfc4180)을 따라야 합니다.
다음은 기본 CSV 형식의 FAQ 파일입니다.
```
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 파일
FAQ 질문에 사용자 지정 필드/속성을 추가하려면 사용자 지정 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
```
사용자 지정 파일의 내용은 [RFC 4180 CSV(쉼표로 구분된 값) 파일의 공통 형식 및 MIME 유형](https://tools.ietf.org/html/rfc4180)을 따라야 합니다.
다음은 사용자 지정 필드 유형 목록입니다.
+ 날짜 - ISO 8601로 인코딩된 날짜와 시간 값입니다.
예를 들어, 2012-03-25T12:30:10\$101:00은 중부 유럽 시간대로 2012년 3월 25일 오후 12시 30분 10초에 대한 ISO 8601 날짜/시간 형식입니다.
+ Long - 숫자(예: `1234`).
+ 문자열 - 문자열 값. 문자열에 쉼표가 포함된 경우 전체 값을 큰따옴표 (“) 로 묶으세요(예: `"custom attribute, and more"`).
+ 문자열 목록 - 문자열 값의 목록입니다. 따옴표(“)로 묶인 쉼표로 구분된 목록으로 값을 나열합니다(예: `"item1, item2, item3"`). 목록에 항목이 하나뿐인 경우 따옴표를 생략할 수 있습니다(예: `item1`).
사용자 지정 CSV 파일에는 사용자 액세스 제어 필드가 포함될 수 있습니다. 이 필드를 사용하여 FAQ에 대한 액세스를 특정 사용자 및 그룹으로 제한할 수 있습니다. 사용자 컨텍스트를 기준으로 필터링하려면 사용자가 쿼리에 사용자 및 그룹 정보를 제공해야 합니다. 그렇지 않으면 모든 관련 FAQ가 반환됩니다. 자세한 내용은 [사용자 컨텍스트 필터링](https://docs.aws.amazon.com/kendra/latest/dg/user-context-filter.html)을 참조하세요.
다음은 FAQ의 사용자 컨텍스트 필터 목록입니다.
+ `_acl_user_allow` - 허용 목록에 있는 사용자는 쿼리 응답에서 FAQ를 볼 수 있습니다. 이 FAQ는 다른 사용자에게 반환되지 않습니다.
+ `_acl_user_deny` - 거부 목록에 있는 사용자는 쿼리 응답에서 FAQ를 볼 수 없습니다. 이 FAQ는 쿼리와 관련된 경우 다른 모든 사용자에게 반환됩니다.
+ `_acl_group_allow` - 허용된 그룹의 구성원인 사용자는 쿼리 응답에서 FAQ를 볼 수 있습니다. 다른 그룹의 구성원인 사용자에게는 FAQ가 반환되지 않습니다.
+ `_acl_group_deny` - 거부된 그룹의 구성원인 사용자는 쿼리 응답에서 FAQ를 볼 수 없습니다. 이 FAQ는 쿼리와 관련된 경우 다른 그룹들에 반환됩니다.
따옴표로 묶인 쉼표로 구분된 목록으로 허용 및 거부 목록의 값을 제공합니다(예: `"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 파일
JSON 파일을 사용하여 인덱스에 대한 질문, 답변, 필드를 제공할 수 있습니다. Amazon Kendra 예약된 필드 또는 사용자 지정 필드를 FAQ에 추가할 수 있습니다.
다음은 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 파일은 두 개의 FAQ 문서를 보여줍니다. 문서 중 하나에는 필수 질문과 답변만 있습니다. 다른 문서에는 추가 필드 및 사용자 컨텍스트 또는 액세스 제어 정보도 포함되어 있습니다.
```
{
"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"
}
]
}
]
}
```
다음은 사용자 지정 필드 유형 목록입니다.
+ 날짜 - ISO 8601로 인코딩된 날짜와 시간 값이 있는 JSON 문자열 값입니다. 예를 들어, 2012-03-25T12:30:10\$101:00은 중부 유럽 시간대로 2012년 3월 25일 오후 12시 30분 10초에 대한 ISO 8601 날짜/시간 형식입니다.
+ Long - JSON 숫자 값(예: `1234`)입니다.
+ 문자열 - JSON 문자열 값(예: `"custom attribute"`)입니다.
+ 문자열 목록 - 문자열 값의 JSON 배열(예: `["item1,item2,item3"]`)입니다.
JSON 파일에는 사용자 액세스 제어 필드가 포함될 수 있습니다. 이 필드를 사용하여 FAQ에 대한 액세스를 특정 사용자 및 그룹으로 제한할 수 있습니다. 사용자 컨텍스트를 기준으로 필터링하려면 사용자가 쿼리에 사용자 및 그룹 정보를 제공해야 합니다. 그렇지 않으면 모든 관련 FAQ가 반환됩니다. 자세한 내용은 [사용자 컨텍스트 필터링](https://docs.aws.amazon.com/kendra/latest/dg/user-context-filter.html)을 참조하세요.
사용자나 그룹을 허용 목록 또는 거부 목록에 포함할 수 있지만, 동일한 사용자를 둘 모두에 포함할 수는 없습니다(개인은 허용되지만 그룹은 거부되는 경우). 둘 모두에 사용자나 그룹을 포함하면 오류가 발생합니다.
다음은 JSON FAQ에 대한 사용자 액세스 제어를 포함하는 예입니다.
```
"AccessControlList": [
{
"Name": "group or user name",
"Type": "GROUP | USER",
"Access": "ALLOW | DENY"
},
additional user context
]
```
## FAQ 파일 사용
FAQ 입력 파일을 S3 버킷에 저장한 후 콘솔 또는 `CreateFaq` API를 사용하여 질문과 답변을 인덱스에 추가합니다. FAQ를 업데이트하려면 FAQ를 삭제하고 다시 생성하세요. `DeleteFaq` API를 사용하여 FAQ를 삭제합니다.
소스 파일이 포함된 S3 버킷에 액세스할 수 있는 IAM 역할을 제공해야 합니다. 콘솔 또는 `RoleArn` 파라미터에 역할을 지정합니다. 다음은 FAQ 파일을 인덱스에 추가하는 예입니다.
------
#### [ 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));
}
}
```
------
## 영어 이외의 언어로 된 FAQ 파일
지원되는 언어로 FAQ를 인덱싱할 수 있습니다. 언어를 지정하지 않으면 기본적으로 영어로 FAQs를 Amazon Kendra 인덱싱합니다. [CreateFaq](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateFaq.html) 작업을 호출할 때 언어 코드를 지정하거나 FAQ 메타데이터에 FAQ의 언어 코드를 필드로 포함할 수 있습니다. 메타데이터 필드에 지정된 FAQ의 메타데이터에 언어 코드가 없는 경우 `CreateFAQ` 작업을 호출할 때 지정된 언어 코드를 사용하여 FAQ를 인덱싱합니다. 콘솔에서 지원되는 언어로 FAQ 문서를 인덱싱하려면 **FAQ**로 이동하여 **FAQ** 추가를 선택합니다. **언어** 드롭다운에서 언어를 선택합니다.
# 사용자 지정 문서 필드 만들기
**참고**
기능 지원은 인덱스 유형 및 사용 중인 검색 API에 따라 다릅니다. 사용 중인 인덱스 유형 및 검색 API에 대해 이 기능이 지원되는지 확인하려면 [인덱스 검색](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index.html#index-searching)을 참조하세요.
Amazon Kendra 인덱스에서 문서에 대한 사용자 지정 속성 또는 필드를 생성할 수 있습니다. 예를 들어, “HR”, “영업” 및 “제조” 값을 사용하여 “부서”라는 사용자 지정 필드 또는 속성을 만들 수 있습니다. 이러한 사용자 지정 필드나 속성을 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)
## 사용자 지정 문서 필드 업데이트
`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를 사용하여 사용자 지정 속성 또는 필드 추가
[BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument.html) API를 사용하여 인덱스에 문서를 추가할 때는 사용자 지정 필드 또는 속성을 `Attributes`의 일부로 지정합니다. API를 호출할 때 여러 필드 또는 속성을 추가할 수 있습니다. 최대 500개의 사용자 지정 필드 또는 속성을 만들 수 있습니다. 다음 예제는 문서에 “부서”를 추가하는 사용자 지정 필드 또는 속성입니다.
```
"Attributes":
{
"Department": "HR",
"_category": "Vacation policy"
}
```
### Amazon S3 데이터 소스에 사용자 지정 속성 또는 필드 추가
S3 버킷을 인덱스의 데이터 소스로 사용하는 경우, 관련 메타데이터 파일과 함께 문서에 메타데이터를 추가합니다. 문서와 병렬인 디렉터리 구조에 메타데이터 JSON 파일을 배치합니다. 자세한 내용은 [S3 문서 메타데이터](https://docs.aws.amazon.com/kendra/latest/dg/s3-metadata.html)를 참조하세요.
`Attributes` JSON 구조에서 사용자 지정 필드 또는 속성을 지정합니다. 최대 500개의 사용자 지정 필드 또는 속성을 만들 수 있습니다. 예를 들어, 다음 예제에서는 `Attributes`를 사용하여 사용자 지정 필드 또는 속성 3개와 예약된 필드 1개를 정의합니다.
```
"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 인덱스 생성
[인덱스 생성](create-index.md)의 단계에 따라 Amazon Kendra 인덱스를 생성합니다.
#### 2단계: 사용자 지정 문서 필드를 추가하도록 인덱스 업데이트
인덱스를 생성한 후 인덱스에 필드를 추가합니다. 다음 절차에서는 콘솔과 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 데이터 소스 생성 및 데이터 소스 필드를 사용자 지정 속성에 매핑
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) 섹션을 참조하세요.
# 토큰을 사용하여 문서에 대한 사용자 액세스 제어
**참고**
기능 지원은 인덱스 유형 및 사용 중인 검색 API에 따라 다릅니다. 사용 중인 인덱스 유형 및 검색 API에 대해 이 기능이 지원되는지 확인하려면 [인덱스 유형](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html)을 참조하세요.
**중요**
Amazon Kendra GenAI Enterprise Edition 인덱스는 토큰 기반 사용자 액세스 제어를 지원하지 않습니다.
인덱스의 특정 문서에 액세스하거나 검색 결과에서 특정 문서를 볼 수 있는 사용자 또는 그룹을 제어할 수 있습니다. 이를 사용자 컨텍스트 필터링이라고 합니다. 문서에 대한 액세스를 제어할 수 있는 이점이 있는 일종의 개인화된 검색입니다. 예를 들어 회사 포털에서 정보를 검색하는 모든 팀이 일급 기밀 회사 문서에 액세스해야 하는 것은 아니며, 이러한 문서가 모든 사용자에게 관련된 것도 아닙니다. 일급 기밀 문서에 대한 액세스 권한을 받은 특정 사용자 또는 팀 그룹만 검색 결과에서 이러한 문서를 볼 수 있습니다.
Amazon Kendra 엔터프라이즈 및 개발자 인덱스는 다음 토큰 유형을 사용하여 토큰 기반 사용자 액세스 제어를 지원합니다.
+ Open ID
+ 공유 암호가 있는 JWT
+ 퍼블릭 키가 있는 JWT
+ JSON
Amazon Kendra 는 검색 및 검색 애플리케이션에 대한 안전한 엔터프라이즈 검색을 제공하는 데 사용할 수 있습니다. 쿼리 및 검색 중에는 요청에 `UserContext` 제공`AttributeFilters`되고 이를 기반으로 검색 결과를 Amazon Kendra 필터링합니다.는 크롤링 및 수집 중에 커넥터에서 수집한 문서 액세스 제어 목록(ACLs)을 Amazon Kendra 읽습니다. 검색 및 검색 결과에는 원본 문서 리포지토리를 가리키는 URL과 짧은 발췌문이 반환됩니다. 원본 리포지토리에서는 여전히 전체 문서에 대한 액세스를 강제합니다.
**Topics**
+ [OpenID 사용](create-index-access-control-tokens-openid.md)
+ [공유 암호가 있는 JSON 웹 토큰(JWT) 사용](create-index-access-control-tokens-jwtshared.md)
+ [JSON 웹 토큰(JWT)을 퍼블릭 키와 함께 사용](create-index-access-control-tokens-jwtpublic.md)
+ [JSON 사용](create-index-access-control-tokens-json.md)
# OpenID 사용
액세스 제어에 OpenID 토큰을 사용하도록 Amazon Kendra 인덱스를 구성하려면 OpenID 공급자의 JWKS(JSON 웹 키 집합) 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 웹 키 집합을 가리켜야 합니다.
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 웹 토큰(JWT) 사용
다음 예제는 인덱스를 생성할 때 사용자 액세스 제어를 위해 공유 암호 토큰이 있는 JSON 웹 토큰(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 웹 서명을 보호하는 데 어떤 키가 사용되었는지 나타내는 힌트입니다.
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 역할에 Secrets Manager 리소스의 `GetSecretValue`에 대한 액세스 권한이 있어야 합니다. 를 사용하여 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 역할에 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 웹 토큰(JWT)을 퍼블릭 키와 함께 사용
다음 예제는 인덱스를 생성할 때 사용자 액세스 제어를 위해 퍼블릭 키가 있는 JSON 웹 토큰(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 웹 서명을 보호하는 데 어떤 키가 사용되었는지 나타내는 힌트입니다.
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**를 지정합니다. JWT의 대상과 일치하는 정규 표현식을 지정해야 합니다.
1. **프로비저닝 세부 정보** 페이지에서 **개발자 에디션**을 선택합니다.
1. **생성**을 선택하여 인덱스를 생성합니다.
1. 인덱스가 생성될 때까지 기다립니다. Amazon Kendra 는 인덱스의 하드웨어를 프로비저닝합니다. 이 작업에는 다소 시간이 걸릴 수 있습니다.
------
#### [ CLI ]
AWS Secrets Manager내부에 퍼블릭 키가 있는 JWT를 사용할 수 있습니다. Secrets Manager ARN이 필요하며 Amazon Kendra 역할에 Secrets Manager 리소스의 `GetSecretValue`에 대한 액세스 권한이 있어야 합니다. 를 사용하여 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 사용
다음 예제는 인덱스를 생성할 때 사용자 액세스 제어를 위해 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'
)
```
------