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

# 使用批次上傳將文件直接新增至索引
<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 行接續字元 (\\) 取代為插入符號 (^)。

```
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));
    }
}
```

------