本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 從 Amazon S3 匯入 DynamoDB 資料：運作方式
若要將資料匯入 DynamoDB，您的資料必須位於 Amazon S3 儲存貯體中，且為 CSV、DynamoDB JSON 或 Amazon Ion 格式。資料可壓縮為 ZSTD 或 GZIP 格式，也可以直接匯入為未壓縮格式。來源資料可以是單一 Amazon S3 物件，或使用相同字首的多個 Amazon S3 物件。
您的資料將匯入到新的 DynamoDB 資料表中，該資料表將在您發起匯入請求時建立。您可以使用次要索引建立此資料表，然後在匯入完成後立即查詢並更新所有主要索引和次要索引的資料。您也可以在匯入完成後新增全域資料表複本。
**注意**
在 Amazon S3 匯入流程期間，DynamoDB 會建立一個新的目標資料表，並將其匯入。此功能目前不支援匯入至現有資料表。
從 Amazon S3 匯入不會耗用新資料表的寫入容量，因此您不需要佈建任何額外容量即可將資料匯入 DynamoDB。資料匯入定價取決於 Amazon S3 中來源資料的未壓縮大小，該資料會在匯入時進行處理。由於格式化或來源資料的不一致，導致無法載入資料表中的項目，也會在匯入流程中計費。如需詳細資訊，請參閱 [Amazon DynamoDB 定價](https://aws.amazon.com/dynamodb/pricing)。
您可以從不同帳戶所擁有的 Amazon S3 儲存貯體匯入資料，前提是您有讀取該儲存貯體的正確許可。新資料表也可能位於與來源 Amazon S3 儲存貯體不同的區域。如需詳細資訊，請參閱 [Amazon Simple Storage Service 設定和許可](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-walkthroughs-managing-access.html)。
匯入時間與 Amazon S3 中的資料特性直接相關。這包括資料大小、資料格式、壓縮方法、資料分佈的一致性、Amazon S3 物件數量以及其他相關變數。具體而言，索引鍵均勻分佈的資料集，匯入速度會比偏斜的資料集更快。例如，若您的次要索引鍵是以月份分割，而您的資料全部來自十二月，那麼匯入資料就會需要更久時間。
與索引鍵相關聯的屬性在基礎資料表中應為唯一。如有任何索引鍵並非唯一，則匯入程序會覆寫相關聯的項目，直到僅留下最後一次覆寫。例如，若主索引鍵是月份，而有多個項目設定為 9 月份，則每個新項目都會覆寫先前寫入的項目，並僅保留一個「月份」主索引鍵設定為 9 月的項目。此情況下，匯入資料表描述中處理的物件數，與目標資料表中的物件數量不相符。
AWS CloudTrail 會記錄資料表匯入的所有主控台和 API 動作。如需詳細資訊，請參閱[使用 記錄 DynamoDB 操作 AWS CloudTrail](logging-using-cloudtrail.md)。
以下影片介紹如何直接從 Amazon S3 匯入到 DynamoDB。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/fqq0CMOnOaI)
**Topics**
+ [
# 請求在 DynamoDB 中匯入資料表
](S3DataImport.Requesting.md)
+ [
# DynamoDB 的 Amazon S3 匯入格式
](S3DataImport.Format.md)
+ [
# 匯入格式配額與驗證
](S3DataImport.Validation.md)
+ [
# 將 Amazon S3 匯入到 DynamoDB 的最佳實務
](S3DataImport.BestPractices.md)
# 請求在 DynamoDB 中匯入資料表
DynamoDB 匯入功能可讓您將 Amazon S3 儲存貯體中的資料匯入至新的 DynamoDB 資料表。您可以使用 [DynamoDB 主控台](https://console.aws.amazon.com/)、[CLI](AccessingDynamoDB.md#Tools.CLI)、[CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dynamodb-table.html) 或 [DynamoDB API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/Welcome.html) 請求資料表匯入。
如果您想要使用 AWS CLI，您必須先進行設定。如需詳細資訊，請參閱[存取 DynamoDB](AccessingDynamoDB.md)。
**注意**
匯入資料表功能會與多個不同的 AWS 服務互動，例如 Amazon S3 和 CloudWatch。在開始匯入之前，請確定調用匯入 API 的使用者或角色具有該功能所依賴之所有服務和資源權限。
請不要在匯入進行時修改 Amazon S3 物件，因為這可能會導致操作失敗或遭到取消。
如需如何處理錯誤和疑難排解的詳細資訊，請參閱 [匯入格式配額與驗證](S3DataImport.Validation.md)。
**Topics**
+ [
## 設定 IAM 許可
](#DataImport.Requesting.Permissions)
+ [
## 使用 請求匯入 AWS 管理主控台
](#S3DataImport.Requesting.Console)
+ [
## 取得 中過去匯入的詳細資訊 AWS 管理主控台
](#S3DataImport.Requesting.Console.Details)
+ [
## 使用 請求匯入 AWS CLI
](#S3DataImport.Requesting.CLI)
+ [
## 取得 中過去匯入的詳細資訊 AWS CLI
](#S3DataImport.Requesting.CLI.Details)
## 設定 IAM 許可
您可以從您擁有讀取許可的任何 Amazon S3 儲存貯體匯入資料。來源儲存貯體無需與來源資料表位於相同區域或擁有相同的擁有者。Your AWS Identity and Access Management (IAM) 必須包含來源 Amazon S3 儲存貯體的相關動作，以及提供偵錯資訊所需的 CloudWatch 許可。以下所示為政策範例。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowDynamoDBImportAction",
"Effect": "Allow",
"Action": [
"dynamodb:ImportTable",
"dynamodb:DescribeImport"
],
"Resource": "arn:aws:dynamodb:us-east-1:111122223333:table/my-table*"
},
{
"Sid": "AllowS3Access",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::your-bucket/*",
"arn:aws:s3:::your-bucket"
]
},
{
"Sid": "AllowCloudwatchAccess",
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:PutLogEvents",
"logs:PutRetentionPolicy"
],
"Resource": "arn:aws:logs:us-east-1:111122223333:log-group/aws-dynamodb/*"
},
{
"Sid": "AllowDynamoDBListImports",
"Effect": "Allow",
"Action": "dynamodb:ListImports",
"Resource": "*"
}
]
}
```
------
### Amazon S3 許可
從另一個帳戶擁有的 Amazon S3 儲存貯體來源上開始匯入時，請確保該角色或使用者可以存取 Amazon S3 物件。您可以執行 Amazon S3 `GetObject` 命令並使用憑證以確認這點。使用 API 時，Amazon S3 儲存貯體擁有者參數會預設為目前使用者的帳戶 ID。對於跨帳戶匯入，請確定此參數已正確填入儲存貯體擁有者的帳戶 ID。下列程式碼為來源帳戶中 Amazon S3 儲存貯體政策的範例。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{"Sid": "ExampleStatement",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::123456789012:user/Dave"
},
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
------
### AWS Key Management Service
建立新資料表進行匯入時，如果您選取非 DynamoDB 擁有的靜態加密金鑰，則必須提供操作使用客戶受管金鑰加密的 DynamoDB 資料表所需的 AWS KMS 許可。如需詳細資訊[，請參閱授權使用您的 AWS KMS 金鑰](encryption.usagenotes.html#dynamodb-kms-authz)。如果 Amazon S3 物件使用伺服器端加密 KMS (SSE-KMS) 加密，請確保啟動匯入的角色或使用者具有使用 AWS KMS 金鑰解密的存取權。此功能不支援客戶提供加密金鑰 (SSE-C) 加密的 Amazon S3 物件。
### CloudWatch 許可
發起匯入的角色或使用者，將需要與匯入相關聯的日誌群組和日誌串流之建立和管理員權限。
## 使用 請求匯入 AWS 管理主控台
以下範例示範如何使用 DynamoDB 主控台將現有資料匯入名為 `MusicCollection` 的新的資料表。
**請求資料表匯入**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 開啟 DynamoDB 主控台。
1. 在主控台左側的導覽窗格中，選擇 **Import from S3** (從 S3 匯入)。
1. 在出現的頁面上，選取 **Import from S3** (從 S3 匯入)。
1. 選擇 **Import from S3** (從 S3 匯入)。
1. 在**來源 S3 URL** 中，輸入 Amazon S3 來源 URL。
如果您擁有來源儲存貯體，請選擇**瀏覽 S3** 進行搜尋。或者，以下列格式輸入儲存貯體的 URL：`s3://bucket/prefix`。`prefix` 是 Amazon S3 金鑰字首。它可以是您要匯入的 Amazon S3 物件名稱，或是包含您想要匯入之所有 Amazon S3 物件共用的金鑰字首。
**注意**
您不能使用與 DynamoDB 匯出請求相同的字首。匯出功能會為所有匯出建立資料夾結構和資訊清單檔案。如果您使用相同的 Amazon S3 路徑，則會導致錯誤。
反之，將匯入指向資料夾，其中包含來自該特定匯出的資料。在此情況下，正確路徑的格式將為 `s3://bucket/prefix/AWSDynamoDB//data/`，其中 `XXXXXXXX-XXXXXX` 是匯出 ID。您可以在匯出 ARN 中找到匯出 ID，其格式如下：`arn:aws:dynamodb:::table//export/`。例如 `arn:aws:dynamodb:us-east-1:123456789012:table/ProductCatalog/export/01234567890123-a1b2c3d4`。
1. 指定您是否為 **S3 bucket owner** (S3 儲存貯體擁有者)。如果來源儲存貯體由不同的帳戶擁有，請選取**不同的 AWS 帳戶**。然後輸入儲存貯體擁有者的帳戶 ID。
1. 在 **Import file compression** (匯入檔案壓縮)，請選取 **No compression** (無壓縮)、**GZIP** (GZIP) 或者 **ZSTD** (ZSTD)，視情況而定。
1. 選取適當的匯入檔案格式。選項包括 **DynamoDB JSON** (DynamoDB JSON)、**Amazon Ion** (Amazon Ion) 或者**CSV** (CSV)。如果您選擇 **CSV** (CSV)，您將有兩個額外的選項：**CSV header** (CSV 標頭) 和 **CSV delimiter character** (CSV 分隔符號)。
針對 **CSV header** (CSV 標頭)，請選擇是否要從檔案的第一行取得標頭或自訂。如果您選擇**Customize your headers** (自訂標頭)，您可以指定您要匯入的標頭值。用此方法指定的 CSV 標頭區分大小寫，且應包含目標資料表的索引鍵。
針對 **CSV delimiter character** (CSV 分隔符號)，您可以設置用以分隔項目的字元。根據預設，會選取逗號。如果您選擇 **Custom delimiter character** (自訂分隔符號字元)，分隔符號必須符合正則表達式模式：`[,;:|\t ]`。
1. 選擇 **Next** (下一步) 按鈕，然後選擇建立以儲存資料的新資料表選項。
**注意**
「主索引鍵」和「排序索引鍵」必須符合檔案中的屬性，否則匯入將會失敗。屬性區分大小寫。
1. 選擇 **Next** (下一步) 以再次檢視您的匯入選項，然後按一下 **Import** (匯入)，以啟動匯入任務。首先，您會看到「資料表」中列出的新資料表狀態為「建立中」。目前無法存取資料表。
1. 匯入完成後，狀態將顯示為「啟用」，您可以開始使用資料表。
## 取得 中過去匯入的詳細資訊 AWS 管理主控台
您可以按一下導覽側列中的 **Import from S3** (從 S3 匯入)，然後選取 **Imports** (匯入) 索引標籤，找到您過去曾執行的匯入任務資訊。匯入面板包含您在過去 90 天內建立的所有匯入清單。選取 Imports (匯入) 索引標籤中所列出任務的 ARN，即可擷取該匯入的相關資訊，包括您選擇的任何進階組態設定。
## 使用 請求匯入 AWS CLI
下列範例會從名為字首儲存貯體的 S3 儲存貯體，將 CSV 格式的資料匯入到名為 target-table 的新資料表。
```
aws dynamodb import-table --s3-bucket-source S3Bucket=bucket,S3KeyPrefix=prefix \
--input-format CSV --table-creation-parameters '{"TableName":"target-table","KeySchema": \
[{"AttributeName":"hk","KeyType":"HASH"}],"AttributeDefinitions":[{"AttributeName":"hk","AttributeType":"S"}],"BillingMode":"PAY_PER_REQUEST"}' \
--input-format-options '{"Csv": {"HeaderList": ["hk", "title", "artist", "year_of_release"], "Delimiter": ";"}}'
```
**注意**
如果您選擇使用受 AWS Key Management Service (AWS KMS) 保護的金鑰加密匯入，則金鑰必須與目的地 Amazon S3 儲存貯體位於相同的區域。
## 取得 中過去匯入的詳細資訊 AWS CLI
您可以使用 `list-imports` 命令尋找過去曾執行的匯入任務資訊。此命令會傳回您在過去 90 天內建立的所有匯入清單。請注意，雖然匯入任務中繼資料會在 90 天後過期，也無法在此清單中找到早於該時間的任務，但 DynamoDB 不會刪除 Amazon S3 儲存貯體或匯入期間建立的任何物件。
```
aws dynamodb list-imports
```
若要擷取特定匯入任務的詳細資訊 (包括任何進階組態設定)，請使用 `describe-import` 命令。
```
aws dynamodb describe-import \
--import-arn arn:aws:dynamodb:us-east-1:123456789012:table/ProductCatalog/exp
```
# DynamoDB 的 Amazon S3 匯入格式
DynamoDB 可以匯入三種格式的資料：CSV、DynamoDB JSON 和 Amazon Ion。
**Topics**
+ [
## CSV
](#S3DataImport.Requesting.Formats.CSV)
+ [
## DynamoDB JSON
](#S3DataImport.Requesting.Formats.DDBJson)
+ [
## Amazon Ion
](#S3DataImport.Requesting.Formats.Ion)
## CSV
CSV 格式的檔案由以換行符分隔的多個項目組成。根據預設，DynamoDB 會將匯入檔案的第一行解讀為標頭，並預期欄會以逗號分隔。只要標頭符合檔案中的欄數，您也可以定義欲套用的標頭。如果標頭定義明確，檔案的第一行將會匯入為值。
**注意**
從 CSV 檔案匯入時，除了基礎資料表的雜湊範圍與索引鍵和次要索引外，所有欄都會匯入為 DynamoDB 字串。
**轉義雙逸出**
CSV 檔案中存在的任何雙引號字元都必須逸出。如果未經逸出 (如下列範例)，則匯入將失敗：
```
id,value
"123",Women's Full "Length" Dress
```
如果使用兩組雙引號逸出，則相同的匯入將成功：
```
id,value
"""123""","Women's Full ""Length"" Dress"
```
當文字經過正確逸出和匯入之後，就會如原始 CSV 檔案中一樣顯示：
```
id,value
"123",Women's Full "Length" Dress
```
**匯入異質項目類型**
您可以使用單一 CSV 檔案，將不同的項目類型匯入一個資料表。定義標頭列，其中包含所有項目類型的屬性，並為不適用於指定項目的屬性將資料欄保留空白。從匯入的項目省略空資料欄，而不是儲存為空字串。
```
PK,SK,EntityType,Name,Email,OrderDate,Amount,ProductName,Quantity
USER#1,PROFILE,User,Alice,alice@example.com,,,,
USER#1,ORDER#2024-01-15,Order,,,2024-01-15,99.99,,
USER#1,ORDER#2024-02-10,Order,,,2024-02-10,149.50,,
PRODUCT#101,METADATA,Product,,,,,Laptop,50
PRODUCT#102,METADATA,Product,,,,,Mouse,200
USER#2,PROFILE,User,Bob,bob@example.com,,,,
USER#2,ORDER#2024-01-20,Order,,,2024-01-20,75.00,,
PRODUCT#103,METADATA,Product,,,,,Keyboard,150
USER#3,PROFILE,User,Charlie,charlie@example.com,,,,
PRODUCT#104,METADATA,Product,,,,,Monitor,30
```
在此範例中，使用者設定檔、訂單和產品共用相同的資料表。每個項目類型只會使用與其相關的資料欄。
## DynamoDB JSON
DynamoDB JSON 格式的檔案可能由多個項目物件組成。每個個別物件均採用 DynamoDB 的標準封送處理 JSON 格式，而新行則用作項目分隔符號。新增功能中，預設支援從時間點的匯出可作為匯入來源。
**注意**
新行用作 DynamoDB JSON 格式檔案的項目分隔符號，不應用於項目物件。
```
{"Item": {"Authors": {"SS": ["Author1", "Author2"]}, "Dimensions": {"S": "8.5 x 11.0 x 1.5"}, "ISBN": {"S": "333-3333333333"}, "Id": {"N": "103"}, "InPublication": {"BOOL": false}, "PageCount": {"N": "600"}, "Price": {"N": "2000"}, "ProductCategory": {"S": "Book"}, "Title": {"S": "Book 103 Title"}}}
{"Item": {"Authors": {"SS": ["Author1", "Author2"]}, "Dimensions": {"S": "8.5 x 11.0 x 1.5"}, "ISBN": {"S": "444-444444444"}, "Id": {"N": "104"}, "InPublication": {"BOOL": false}, "PageCount": {"N": "600"}, "Price": {"N": "2000"}, "ProductCategory": {"S": "Book"}, "Title": {"S": "Book 104 Title"}}}
{"Item": {"Authors": {"SS": ["Author1", "Author2"]}, "Dimensions": {"S": "8.5 x 11.0 x 1.5"}, "ISBN": {"S": "555-5555555555"}, "Id": {"N": "105"}, "InPublication": {"BOOL": false}, "PageCount": {"N": "600"}, "Price": {"N": "2000"}, "ProductCategory": {"S": "Book"}, "Title": {"S": "Book 105 Title"}}}
```
## Amazon Ion
[Amazon Ion](https://amzn.github.io/ion-docs/) 是輸入豐富、自行描述、階層資料序列化格式，旨在處理快速開發、解耦及日常遇到的效率挑戰等問題，同時設計大規模的服務導向架構。
將資料匯入為 Ion 格式時，DynamoDB 資料表中使用的 DynamoDB 資料類型會映射至 Ion 資料類型。
| 序號 | Ion 至 DynamoDB 資料類型轉換 | B |
| --- | --- | --- |
| `1` | `Ion Data Type` | `DynamoDB Representation` |
| `2` | `string` | `String (s)` |
| `3` | `bool` | `Boolean (BOOL)` |
| `4` | `decimal` | `Number (N)` |
| `5` | `blob` | `Binary (B)` |
| `6` | `list (with type annotation $dynamodb_SS, $dynamodb_NS, or $dynamodb_BS)` | `Set (SS, NS, BS)` |
| `7` | `list` | `List` |
| `8` | `struct` | `Map` |
Ion 檔案中的項目以新行分隔。每行都以 Ion 版本標記開頭，後面接著 Ion 格式的項目。
**注意**
下列範例中，為了便於閱讀，Ion 格式檔案的項目採用多行格式。
```
$ion_1_0
[
{
Item:{
Authors:$dynamodb_SS::["Author1","Author2"],
Dimensions:"8.5 x 11.0 x 1.5",
ISBN:"333-3333333333",
Id:103.,
InPublication:false,
PageCount:6d2,
Price:2d3,
ProductCategory:"Book",
Title:"Book 103 Title"
}
},
{
Item:{
Authors:$dynamodb_SS::["Author1","Author2"],
Dimensions:"8.5 x 11.0 x 1.5",
ISBN:"444-4444444444",
Id:104.,
InPublication:false,
PageCount:6d2,
Price:2d3,
ProductCategory:"Book",
Title:"Book 104 Title"
}
},
{
Item:{
Authors:$dynamodb_SS::["Author1","Author2"],
Dimensions:"8.5 x 11.0 x 1.5",
ISBN:"555-5555555555",
Id:105.,
InPublication:false,
PageCount:6d2,
Price:2d3,
ProductCategory:"Book",
Title:"Book 105 Title"
}
}
]
```
# 匯入格式配額與驗證
## 匯入配額
Amazon S3 的 DynamoDB 匯入可支援多達 50 個並行匯入任務，在 us-east-1、us-west-2 和 eu-west-1 區域的匯入來源物件大小總計達 15TB。在所有其他區域中，最多支援 50 個並行匯入任務，大小總計為 1TB。每個匯入任務在所有區域中最多可以使用 50,000 個 Amazon S3 物件。這些預設配額會套用至每個帳戶。如果您認為需要修改這些配額，請聯絡您的客戶團隊，我們會根據個別情況進行考慮。如需 DynamoDB 限制的詳細資訊，請參閱 [Service Quotas](ServiceQuotas.html)。
## 驗證錯誤
在匯入流程期間，DynamoDB 可能會在剖析資料時遇到錯誤。DynamoDB 會針對每個錯誤發出一份 CloudWatch 日誌，並保留遇到的錯誤總數計數。如果 Amazon S3 物件本身格式錯誤或其內容無法形成 DynamoDB 項目，我們可能會略過處理物件的剩餘部分。
**注意**
如果 Amazon S3 資料來源有多個共用相同索引鍵的項目，這些項目將會覆寫，直到僅留下一個項目為止。這看起來像是匯入了 1 個項目而忽略了其他項目。重複的項目將以隨機順序覆寫，不會計為錯誤，也不會發出到 CloudWatch 日誌中。
匯入完成後，您可以查看匯入的項目總數、錯誤總數，以及處理的項目總數。如需進一步的疑難排解，您也可以檢查所匯入項目的總大小與所處理資料的總大小。
匯入錯誤分為三類：API 驗證錯誤、資料驗證錯誤和組態錯誤。
### API 驗證錯誤
API 驗證錯誤是來自同步 API 的項目層級錯誤。常見原因是許可問題、缺少必要參數以及參數驗證失敗。`ImportTable` 請求所擲回的例外狀況中，包含 API 呼叫失敗原因的詳細資訊。
### 驗證錯誤
資料驗證錯誤可能發生在項目層級或檔案層級。匯入期間，會先根據 DynamoDB 規則驗證項目，然後再匯入目標資料表。當項目驗證失敗且未匯入時，匯入任務會略過該項目，並繼續下一個項目。工作結束時，匯入狀態會設定為「失敗」，伴隨 FailureCode、ItemValidationError 以及 FailureMessage：「部分項目驗證檢查失敗且未匯入，如需詳細資訊，請檢查 CloudWatch 錯誤日誌。」
造成資料驗證錯誤的常見原因包括物件無法剖析、物件格式不正確 (輸入指定 DYNAMODB\$1JSON，但物件不在 DYNAMODB\$1JSON 中)，以及結構描述與指定來源資料表的金鑰不相符。
### 組態錯誤
組態錯誤通常是因為權限驗證而導致的工作流程錯誤。匯入工作流程會在接受請求之後檢查某些權限。如果在呼叫 Amazon S3 或 CloudWatch 等任何必要的相依性時發生問題，則流程會將匯入狀態標示為「失敗」。所以 `failureCode` 和 `failureMessage` 指向失敗原因。在適用的情況下，失敗訊息還包含請求 ID，您可以用來調查 CloudTrail 中失敗的原因。
常見的組態錯誤包括 Amazon S3 儲存貯體的 URL 錯誤，而且沒有存取 Amazon S3 儲存貯體、CloudWatch Logs 和用於解密 Amazon S3 物件的 AWS KMS 金鑰的許可。如需詳細資訊，請參閱[使用與資料金鑰](encryption.usagenotes.html#dynamodb-kms)。
### 驗證 Amazon S3 物件
若要驗證來源 S3 物件，請執行下列步驟。
1. 驗證資料格式與壓縮類型
+ 請確認指定字首下的所有相符 Amazon S3 物件都具有相同的格式 (DYNAMODB\$1JSON、DYNAMODB\$1ION、CSV)
+ 請確認指定字首下的所有相符 Amazon S3 物件都以相同的方式壓縮 (GZIP、ZSTD、無)
**注意**
Amazon S3 物件不需要具有對應的副檔名 (.csv / .json / .ion / .gz / .zstd 等)，因為應以 ImportTable 呼叫中指定的輸入格式優先。
1. 驗證匯入資料是否符合所需的資料表結構描述
+ 請確定來源資料中的每個項目都有主索引鍵。匯入的排序索引鍵為選用。
+ 請確定與主索引鍵和排序索引鍵相關聯的屬性類別符合 Table 和 GSI 結構描述中的屬性類別，如資料表建立參數所指定
### 疑難排解
#### CloudWatch 日誌
對於匯入失敗的工作，詳細錯誤訊息會張貼到 CloudWatch 日誌。若要存取這些日誌，請先從輸出擷取 ImportArn，然後使用此命令進行描述匯入：
```
aws dynamodb describe-import --import-arn arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table/import/01658528578619-c4d4e311
}
```
輸出範例：
```
aws dynamodb describe-import --import-arn "arn:aws:dynamodb:us-east-1:531234567890:table/target-table/import/01658528578619-c4d4e311"
{
"ImportTableDescription": {
"ImportArn": "arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table/import/01658528578619-c4d4e311",
"ImportStatus": "FAILED",
"TableArn": "arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table",
"TableId": "7b7ecc22-302f-4039-8ea9-8e7c3eb2bcb8",
"ClientToken": "30f8891c-e478-47f4-af4a-67a5c3b595e3",
"S3BucketSource": {
"S3BucketOwner": "ACCOUNT",
"S3Bucket": "my-import-source",
"S3KeyPrefix": "import-test"
},
"ErrorCount": 1,
"CloudWatchLogGroupArn": "arn:aws:logs:us-east-1:ACCOUNT:log-group:/aws-dynamodb/imports:*",
"InputFormat": "CSV",
"InputCompressionType": "NONE",
"TableCreationParameters": {
"TableName": "target-table",
"AttributeDefinitions": [
{
"AttributeName": "pk",
"AttributeType": "S"
}
],
"KeySchema": [
{
"AttributeName": "pk",
"KeyType": "HASH"
}
],
"BillingMode": "PAY_PER_REQUEST"
},
"StartTime": 1658528578.619,
"EndTime": 1658528750.628,
"ProcessedSizeBytes": 70,
"ProcessedItemCount": 1,
"ImportedItemCount": 0,
"FailureCode": "ItemValidationError",
"FailureMessage": "Some of the items failed validation checks and were not imported. Please check CloudWatch error logs for more details."
}
}
```
從上述回應擷取日誌群組並匯入 ID，並用其擷取錯誤日誌。匯入 ID 是 `ImportArn` 欄位的最後一個路徑元素。日誌群組的名稱為 `/aws-dynamodb/imports`。錯誤日誌串流的名稱為 `import-id/error`。此例子中，為 `01658528578619-c4d4e311/error`。
#### 缺少項目中的金鑰 pk
如果來源 S3 物件不包含作為參數的主索引鍵，匯入將會失敗。例如，當您將匯入的主索引鍵定義為欄名稱「pk」時。
```
aws dynamodb import-table —s3-bucket-source S3Bucket=my-import-source,S3KeyPrefix=import-test.csv \
—input-format CSV --table-creation-parameters '{"TableName":"target-table","KeySchema": \
[{"AttributeName":"pk","KeyType":"HASH"}],"AttributeDefinitions":[{"AttributeName":"pk","AttributeType":"S"}],"BillingMode":"PAY_PER_REQUEST"}'
```
來源物件 `import-test.csv` 中缺少欄「pk」，其中包含下列內容：
```
title,artist,year_of_release
The Dark Side of the Moon,Pink Floyd,1973
```
由於資料來源中缺少主索引鍵，因此這項匯入會因為項目驗證錯誤而失敗。
CloudWatch 錯誤日誌範例：
```
aws logs get-log-events —log-group-name /aws-dynamodb/imports —log-stream-name 01658528578619-c4d4e311/error
{
"events": [
{
"timestamp": 1658528745319,
"message": "{\"itemS3Pointer\":{\"bucket\":\"my-import-source\",\"key\":\"import-test.csv\",\"itemIndex\":0},\"importArn\":\"arn:aws:dynamodb:us-east-1:531234567890:table/target-table/import/01658528578619-c4d4e311\",\"errorMessages\":[\"One or more parameter values were invalid: Missing the key pk in the item\"]}",
"ingestionTime": 1658528745414
}
],
"nextForwardToken": "f/36986426953797707963335499204463414460239026137054642176/s",
"nextBackwardToken": "b/36986426953797707963335499204463414460239026137054642176/s"
}
```
此錯誤日誌表示「一個或多個參數值無效：缺少項目中的金鑰 pk」。由於此匯入工作失敗，現在存在資料表「target-table」但其為空白，因為沒有匯入任何項目。已處理第一個項目，物件的項目驗證失敗。
若要修正此問題，請先將「target-table」刪除 (若不再需要)。然後使用來源物件中存在的主索引鍵欄名稱，或將來源資料更新為：
```
pk,title,artist,year_of_release
Albums::Rock::Classic::1973::AlbumId::ALB25,The Dark Side of the Moon,Pink Floyd,1973
```
#### 目標資料表存在
當您啟動匯入工作並收到回應時，如下所示：
```
An error occurred (ResourceInUseException) when calling the ImportTable operation: Table already exists: target-table
```
若要修正此錯誤，您必須選擇不存在的資料表名稱，然後再一次匯入。
#### 指定的儲存貯體不存在
如果來源儲存貯體不存在，匯入將失敗，並會在 CloudWatch 中記錄錯誤訊息詳細資料。
描述匯入範例：
```
aws dynamodb —endpoint-url $ENDPOINT describe-import —import-arn "arn:aws:dynamodb:us-east-1:531234567890:table/target-table/import/01658530687105-e6035287"
{
"ImportTableDescription": {
"ImportArn": "arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table/import/01658530687105-e6035287",
"ImportStatus": "FAILED",
"TableArn": "arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table",
"TableId": "e1215a82-b8d1-45a8-b2e2-14b9dd8eb99c",
"ClientToken": "3048e16a-069b-47a6-9dfb-9c259fd2fb6f",
"S3BucketSource": {
"S3BucketOwner": "531234567890",
"S3Bucket": "BUCKET_DOES_NOT_EXIST",
"S3KeyPrefix": "import-test"
},
"ErrorCount": 0,
"CloudWatchLogGroupArn": "arn:aws:logs:us-east-1:ACCOUNT:log-group:/aws-dynamodb/imports:*",
"InputFormat": "CSV",
"InputCompressionType": "NONE",
"TableCreationParameters": {
"TableName": "target-table",
"AttributeDefinitions": [
{
"AttributeName": "pk",
"AttributeType": "S"
}
],
"KeySchema": [
{
"AttributeName": "pk",
"KeyType": "HASH"
}
],
"BillingMode": "PAY_PER_REQUEST"
},
"StartTime": 1658530687.105,
"EndTime": 1658530701.873,
"ProcessedSizeBytes": 0,
"ProcessedItemCount": 0,
"ImportedItemCount": 0,
"FailureCode": "S3NoSuchBucket",
"FailureMessage": "The specified bucket does not exist (Service: Amazon S3; Status Code: 404; Error Code: NoSuchBucket; Request ID: Q4W6QYYFDWY6WAKH; S3 Extended Request ID: ObqSlLeIMJpQqHLRX2C5Sy7n+8g6iGPwy7ixg7eEeTuEkg/+chU/JF+RbliWytMlkUlUcuCLTrI=; Proxy: null)"
}
}
```
此 `FailureCode` 為 `S3NoSuchBucket`，其中 `FailureMessage` 包含請求 ID 等詳細資訊以及擲出錯誤服務。由於在將資料匯入資料表之前就已發現錯誤，因此不會建立新的 DynamoDB 資料表。部分情況下，若資料開始匯入後才遇到這些錯誤，就會保留含有部分匯入資料的資料表。
若要修正此錯誤，請確定來源 Amazon S3 儲存貯體存在，然後重新啟動匯入程序。
# 將 Amazon S3 匯入到 DynamoDB 的最佳實務
以下為將資料從 Amazon S3 匯入到 DynamoDB 的最佳實務。
## 保持在 50,000 個 S3 物件的限制以下
每個匯入工作最多支援 50,000 個 S3 物件。如果您的資料集包含超過 50,000 個物件，請考慮將它們合併為較大的物件。
## 避免過大的 S3 物件
S3 物件會平行匯入。擁有眾多中型 S3 物件允許平行執行，而不會產生過大負荷。對於 1 KB 以下的項目，請考慮在每個 S3 物件中放置 400 萬個項目。如果您的平均項目大小較大，請在每個 S3 物件中按比例放置較少的項目。
## 隨機化已排序的資料
如果 S3 物件以排序順序保存資料，它會建立*滾動的經常性分割區*。這種情況是由其中一個分割區接收所有活動，接著是下一個分割區，依此類推。按排序順序的資料的定義是 S3 物件中的循序項目，將在匯入期間寫入相同目標分割區。資料以排序順序排列的一個常見情況是 CSV 檔案，其中項目會依分割區索引鍵排序，以便讓重複的項目共用相同的分割區索引鍵。
若要避免滾動的經常性分割區，我們建議您在這些情況下隨機化順序。這可以透過散佈寫入操作來改善效能。如需詳細資訊，請參閱[在將資料上傳至 DynamoDB 時有效分配寫入活動](bp-partition-key-data-upload.md)。
## 壓縮資料，將 S3 物件總大小保持在區域限制以下
在[從 S3 匯入程序](S3DataImport.Requesting.md)中，要匯入之 S3 物件資料的總大小有限制。us-east-1、us-west-2 和 eu-west-1 區域中，限制為 15 TB，在所有其他區域中為 1 TB。此限制是以原始 S3 物件大小為基礎。
壓縮可讓更多原始資料符合限制。如果單獨壓縮不足以讓匯入符合限制範圍，您也可以聯絡 [AWS Premium Support](https://aws.amazon.com/premiumsupport/) 請求提高配額。
## 注意項目大小如何影響效能
如果您的平均項目大小非常小 (低於 200 位元組)，匯入程序可能會比較大的項目大小更久。
## 請勿在作用中匯入期間修改 S3 物件
確保來源 S3 物件在匯入操作進行時保持不變。如果在匯入期間修改 S3 物件，操作將會失敗，並顯示錯誤碼`ObjectModifiedInS3DuringImport`和訊息「無法匯入 S3 物件，因為它被覆寫。」
如果您遇到此錯誤，請使用 S3 物件的穩定版本重新啟動匯入操作。若要避免此問題，請等待目前的匯入完成，然後再變更來源檔案。
## 考慮在沒有全域次要索引的情形下匯入
匯入任務的持續時間可能取決於是否存在一或多個全域次要索引 (GSI)。如果您計劃使用低基數的分割區索引鍵來建立索引，那麼如果將索引建立延遲到匯入任務完成之後 (而不是包含在匯入工作中)，匯入速度可能會更快。
**注意**
建立 GSI 不會產生寫入費用，無論是在匯入期間或之後建立。