kvp in attributeList)
{
string attributeName = kvp.Key;
AttributeValue value = kvp.Value;
Console.WriteLine(
attributeName + " " +
(value.S == null ? "" : "S=[" + value.S + "]") +
(value.N == null ? "" : "N=[" + value.N + "]") +
(value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") +
(value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]") +
(value.B == null ? "" : "B=[" + FromGzipMemoryStream(value.B) + "]")
);
}
Console.WriteLine("************************************************");
}
private static MemoryStream ToGzipMemoryStream(string value)
{
MemoryStream output = new MemoryStream();
using (GZipStream zipStream = new GZipStream(output, CompressionMode.Compress, true))
using (StreamWriter writer = new StreamWriter(zipStream))
{
writer.Write(value);
}
return output;
}
private static string FromGzipMemoryStream(MemoryStream stream)
{
using (GZipStream zipStream = new GZipStream(stream, CompressionMode.Decompress))
using (StreamReader reader = new StreamReader(zipStream))
{
return reader.ReadToEnd();
}
}
}
}
```
# 在 DynamoDB 中使用次要索引來改善資料存取
Amazon DynamoDB 透過指定主索引鍵值來提供資料表中項目的快速存取。不過，許多應用程式都會受益於下列情況：有一或多個次要 (或替代) 索引鍵可用，允許使用主索引鍵以外的屬性來有效存取資料。若要解決此問題，您可以在資料表上建立一或多個次要索引，並針對這些索引發出 `Query` 或 `Scan` 請求。
*次要索引*是一種資料結構，包含資料表中的屬性子集，以及可支援 `Query` 操作的替代索引鍵。您可以使用 `Query` 從索引擷取資料，方式與您搭配使用 `Query` 與資料表相同。一份資料表可以有多個次要索引，讓您的應用程式能夠存取許多不同的查詢模式。
**注意**
您也可以對索引進行 `Scan`，方式與您對資料表進行 `Scan` 相同。
[資源型政策](access-control-resource-based.md)目前不支援次要索引掃描操作的跨帳戶存取。
每個次要索引都只能與一個資料表建立關聯，次要索引可從資料表中取得其資料。這稱為索引的*基礎資料表*。當您建立索引時，請定義索引的替代索引鍵 (分割區索引鍵和排序索引鍵)。您還可以定義要從基礎資料表*投影*或複製到索引中的屬性。DynamoDB 會將這些屬性以及基礎資料表中的主索引鍵屬性複製到索引。您接著可以查詢或掃描索引，就像查詢或掃描資料表一樣。
DynamoDB 會自動維護每個次要索引。當您新增、修改或刪除基礎資料表中的項目時，也會更新該資料表上的任何索引，以反映這些變更。
DynamoDB 支援兩種次要索引：
+ **[全域次要索引](GSI.html)：**一種含分割區索引鍵或排序索引鍵的索引，這些索引鍵可與基礎資料表上的索引鍵不同。全域次要索引之所以視為全域，是因為索引上的查詢可以跨越所有分割區之間基礎資料表中的所有資料。全域次要索引會儲存在基礎資料表以外的專屬分割區空間，且會和基礎資料表分開調整。
+ **[本機次要索引](LSI.html)：**是一種與基礎資料表擁有相同分割區索引鍵但不同排序索引鍵的索引。本機次要索引的「本機」概念是指，本機次要索引的每個分割區都會列入基礎資料表分割區的範圍，其中分割區索引鍵的值皆相同。
如需全域次要索引與本機次要索引的比較，請觀看此影片。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/BkEu7zBWge8)
**Topics**
+ [在 DynamoDB 中使用全域次要索引](GSI.md)
+ [本機次要索引](LSI.md)
當您判斷要使用的索引類型時，應該考量應用程式需求。下列資料表會顯示全域次要索引和本機次要索引之間的主要差異。
****
| 特性 | 全域次要索引 | 本機次要索引 |
| --- | --- | --- |
| 索引鍵結構描述 | 全域次要索引的主索引鍵可以是簡單 (分割區索引鍵) 或複合 (分割區索引鍵和排序索引鍵)。 | 本機次要索引的主索引鍵必須是複合形式 (分割區索引鍵和排序索引鍵)。 |
| 索引鍵屬性 | 索引的分割區索引鍵和排序索引鍵 (若存在) 可以是字串、數字或二進位類型的任何基礎資料表屬性。 | 索引的分割區索引鍵與基礎資料表的分割區索引鍵具有相同的屬性。排序索引鍵可以是字串、數字或二進位類型的任何基礎資料表屬性。 |
| 每個分割區索引鍵值的大小限制 | 全域次要索引沒有大小限制。 | 針對每個分割區索引鍵值，所有已索引項目的大小總計必須是 10 GB 或以下。 |
| 線上索引操作 | 您可在建立資料表的同時建立全域次要索引。您也可以將新的全域次要索引新增至現有的資料表，或刪除現有的全域次要索引。如需詳細資訊，請參閱 [在 DynamoDB 中管理全域次要索引](GSI.OnlineOps.md)。 | 本機次要索引是在建立資料表的同時建立的。您無法對現有資料表新增本機次要索引，也無法刪除現有的任何本機次要索引。 |
| 查詢和分割區 | 全域次要索引可讓您跨所有分割區查詢整個資料表。 | 本機次要索引可讓您查詢單一分割區 (由查詢中的分割區索引鍵值所指定)。 |
| 讀取一致性 | 全域次要索引上的查詢僅支援最終一致性。 | 當您查詢本機次要索引時，可以選擇最終一致性或強烈一致性。 |
| 佈建輸送量耗用 | 針對讀取和寫入活動，每個全域次要索引都有自己的佈建輸送量設定。對全域次要索引的查詢或掃描會使用來自索引的容量單位，而不是來自基礎資料表。這適用於資料表寫入引發的全域次要索引更新。與全域資料表相關聯的全域次要索引會耗用寫入容量單位。 | 對本機次要索引的查詢或掃描會使用來自基礎資料表的讀取容量單位。當您寫入至資料表時，也會一併更新其本機次要索引，且這些更新會使用來自基礎資料表的寫入容量單位。與全域資料表相關聯的本機次要索引會耗用複寫的寫入容量單位。 |
| 投影屬性 | 您可以使用全域次要索引查詢或掃描來僅請求投影至索引的屬性。DynamoDB 不會從資料表中擷取任何屬性。 | 若要查詢或掃描本機次要索引，您可以請求未投影至索引的屬性。DynamoDB 會自動從資料表中擷取這些屬性。 |
如果您想要建立具有次要索引的多個資料表，則必須循序進行這項操作。例如，您建立第一個資料表並等待它變成 `ACTIVE`、建立下一個資料表並等待其變成 `ACTIVE`，以此類推。如果您嘗試並行建立具有次要索引的多份資料表，則 DynamoDB 會傳回 `LimitExceededException`。
每個次要索引使用的[資料表類別](HowItWorks.TableClasses.html)和[容量模式](capacity-mode.md)皆與其相關聯的基礎資料表相同。針對每個次要索引，您必須指定下列項目：
+ 要建立的索引類型：全域次要索引或本機次要索引。
+ 索引的名稱。索引的命名規則與資料表的命名規則相同，如「[Amazon DynamoDB 中的配額](ServiceQuotas.md)」中所列。名稱對與其建立關聯的基礎資料表而言必須是唯一的，但您可以將相同的名稱用於與其不同基礎資料表建立關聯的索引。
+ 索引的索引鍵結構描述。索引鍵結構描述中的每個屬性都必須是 `String`、`Number` 或 `Binary` 類型的最上層屬性。不允許其他資料類型 (包含文件和集合)。索引鍵結構描述的其他需求取決於索引類型：
+ 針對全域次要索引，分割區索引鍵可以是基礎資料表的任何純量屬性。排序索引鍵是選用項目，它也可以是基礎資料表的任何純量屬性。
+ 針對本機次要索引，分割區索引鍵必須與基礎資料表的分割區索引鍵相同，而排序索引鍵必須是非索引鍵基礎資料表屬性。
+ 從基礎資料表投影至索引的其他屬性 (如果有的話)。這些是自動投影至每個索引之資料表索引鍵屬性以外的屬性。您可以投影任何資料類型的屬性 (包含純量、文件和集合)。
+ 索引的佈建輸送量設定 (必要時)：
+ 針對全域次要索引，您必須指定讀取和寫入容量單位設定。這些佈建輸送量設定與基礎資料表設定無關。
+ 針對本機次要索引，您不需要指定讀取和寫入容量單位設定。本機次要索引的任何讀取和寫入操作都是取自其基礎資料表的佈建輸送量設定。
為獲得最大的查詢靈活性，您最多可以為每份資料表建立 20 個全域次要索引 (預設配額) 和 5 個本機次要索引。
若要取得資料表次要索引的詳細清單，請使用 `DescribeTable` 操作。`DescribeTable` 會傳回資料表中每個次要索引的名稱、儲存大小和項目計數。這些值不會即時更新，但大約每六小時會重新整理一次。
您可以使用 `Query` 或 `Scan` 操作來存取次要索引中的資料。您必須指定基礎資料表名稱以及您要使用的索引名稱、要在結果中傳回的屬性，以及您要套用的任何條件表達式或篩選條件。DynamoDB 可以依遞增或遞減順序傳回結果。
當您刪除資料表時，也會刪除與該資料表建立關聯的所有索引。
如需最佳實務做法，請參閱「[使用 DynamoDB 中次要索引的最佳實務](bp-indexes.md)」。
# 在 DynamoDB 中使用全域次要索引
某些應用程式可能需要執行多種查詢，並使用各種不同的屬性做為查詢條件。若要支援這些需求，您可以建立一或多個*全域次要索引*，並在 Amazon DynamoDB 中對這些索引發出 `Query` 請求。
**Topics**
+ [藍本：使用全域次要索引](#GSI.scenario)
+ [屬性投影](#GSI.Projections)
+ [多屬性金鑰結構描述](#GSI.MultiAttributeKeys)
+ [從全域次要索引讀取資料](#GSI.Reading)
+ [資料表與全域次要索引之間的資料同步](#GSI.Writes)
+ [具有全域次要索引的資料表類別](#GSI.tableclasses)
+ [全域次要索引的佈建輸送量考量](#GSI.ThroughputConsiderations)
+ [全域次要索引的儲存考量](#GSI.StorageConsiderations)
+ [設計模式](GSI.DesignPatterns.md)
+ [在 DynamoDB 中管理全域次要索引](GSI.OnlineOps.md)
+ [偵測和修正 DynamoDB 中的索引鍵違規情況](GSI.OnlineOps.ViolationDetection.md)
+ [使用全域次要索引：Java](GSIJavaDocumentAPI.md)
+ [使用全域次要索引：.NET](GSILowLevelDotNet.md)
+ [在 DynamoDB 中搭配使用 AWS CLI 與全域次要索引](GCICli.md)
## 藍本：使用全域次要索引
為了示範，假設有一份名為 `GameScores` 的資料表，會追蹤手機遊戲應用程式的使用者與分數。`GameScores` 中的每個項目都是按分割區索引鍵 (`UserId`) 和排序索引鍵 (`GameTitle`) 識別。下圖顯示這些項目在資料表中的組織方式。(並未顯示所有屬性。)
![\[包含使用者 ID、遊戲名稱、分數、日期和勝/敗清單的 GameScores 表。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/GSI_01.png)
現在假設您想要撰寫排行榜應用程式來顯示每個遊戲的最高分。已指定索引鍵屬性 (`UserId` 和 `GameTitle`) 的查詢會很有效率。但若應用程式僅能根據 `GameTitle` 從 `GameScores` 擷取資料，就需要使用 `Scan` 操作。當愈來愈多項目新增至資料表時，掃描所有資料會變得很慢且效率不彰。這會讓回答問題變得很困難，例如下列問題：
+ Meteor Blasters 遊戲曾記錄到的最高分為何？
+ 哪位使用者在 Galaxy Invaders 中得到最高分？
+ 最高的勝負比為何？
若要加速非索引鍵屬性的查詢，您可以建立全域次要索引。全域次要索引包含基礎資料表中的一系列屬性，但這些屬性會依與該資料表不同的主索引鍵組織。索引鍵不需要有任何來自資料表的索引鍵屬性。甚至不需要有和資料表相同的索引鍵結構描述。
例如，您可以建立名為 `GameTitleIndex` 的全域次要索引，其中分割區索引鍵為 `GameTitle`，排序索引鍵為 `TopScore`。因為基礎資料表的主索引鍵屬性一律會投影到索引，所以也會顯示 `UserId` 屬性。下圖說明 `GameTitleIndex` 索引可能的樣子。
![\[包含遊戲名稱、分數和使用者 ID 清單的 GameTitleIndex 資料表。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/GSI_02.png)
您現在可以查詢 `GameTitleIndex` 並輕鬆取得 Meteor Blasters 的分數。結果會依排序索引鍵值 `TopScore` 排序。如果您將 `ScanIndexForward` 參數設定為 false，結果會依遞減順序傳回，因此最高分優先傳回。
每個全域次要索引都必須有分割區索引鍵，並可以有一個選用的排序索引鍵。索引鍵結構描述可以和基礎資料表結構描述不同。您可以擁有一個具有簡易主索引鍵 (分割區索引鍵) 的資料表，並使用複合主鍵 (分割區索引鍵和排序索引鍵) 建立全域次要索引，反之亦然。索引鍵屬性可包含來自基礎資料表的任何最上層 `String`、`Number` 或 `Binary` 屬性。不允許其他純量類型、文件類型和集合類型。
您可以視需要將其他基礎資料表屬性投影到索引。當您查詢索引時，DynamoDB 可有效率地擷取這些投影屬性。但是，全域次要索引查詢無法自基礎資料表擷取屬性。例如，如果您依上圖所示查詢 `GameTitleIndex`，則除 `TopScore` 外，此查詢不能存取任何非索引鍵屬性 (雖然會自動投影索引鍵屬性 `GameTitle` 和 `UserId`)。
在 DynamoDB 資料表中，每個索引鍵值必須是唯一的。不過，全域次要索引中的索引鍵值不需要是唯一的。為了示範，假設有一款名為 Comet Quest 的遊戲特別難，許多新的使用者試過後均無法突破零分的成績。以下為可代表此遊戲的一些資料。
****
| UserId | GameTitle | TopScore |
| --- | --- | --- |
| 123 | Comet Quest | 0 |
| 201 | Comet Quest | 0 |
| 301 | Comet Quest | 0 |
當此資料新增至 `GameScores` 資料表時，DynamoDB 會將其傳播至 `GameTitleIndex`。如果我們接著使用 `GameTitle` Comet Quest 與 `TopScore` 0 來查詢索引，即會傳回下列資料。
![\[包含遊戲名稱、最高分和使用者 ID 清單的資料表。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/GSI_05.png)
回應中只會顯示具有指定索引鍵值的項目。在此資料集合中，項目未依特定順序排列。
全域次要索引只會追蹤索引鍵屬性確實存在的資料項目。例如，假設您在 `GameScores` 表中新增另一個新項目，但只提供必要的主索引鍵屬性。
****
| UserId | GameTitle |
| --- | --- |
| 400 | Comet Quest |
因為您未指定 `TopScore` 屬性，所以 DynamoDB 不會將此項目傳播至 `GameTitleIndex`。因此，如已針對 `GameScores` 查詢所有 Comet Quest 項目，可能會取得下列四個項目。
![\[包含 4 個遊戲名稱、最高分和使用者 ID 清單的資料表。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/GSI_04.png)
針對 `GameTitleIndex` 的類似查詢仍只會傳回三個項目，而不是四個。這是因為具有不存在 `TopScore` 的項目不會傳播至索引。
![\[包含 3 個遊戲名稱、最高分和使用者 ID 清單的資料表。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/GSI_05.png)
## 屬性投影
*投影*是指從資料表複製到次要索引的屬性集合。資料表的分割區索引鍵和排序索引鍵一律會投影到索引中；您可以投影其他屬性來支援應用程式的查詢需求。查詢索引時，Amazon DynamoDB 可以存取投影中的任何屬性，就好像這些屬性在它們自己的資料表中一樣。
在建立次要索引時，您需要指定要投影到索引中的屬性。DynamoDB 為此提供三種不同的選項：
+ *KEYS\$1ONLY*：索引中的每個項目都只包含資料表分割索引鍵和排序索引鍵值，以及索引鍵值。`KEYS_ONLY` 選項會產生最小的可行次要索引。
+ *INCLUDE*：除了 `KEYS_ONLY` 中描述的屬性外，次要索引還包含您指定的其他非索引鍵屬性。
+ *ALL*：次要索引包含來源資料表中的所有屬性。因為索引中的所有資料表資料都會重複，所以 `ALL` 投影會產生最大的可行次要索引。
在上圖中，`GameTitleIndex` 只有一個投影的屬性：`UserId`。因此，雖然應用程式可以在查詢中使用 `GameTitle` 和 `TopScore` 有效率地判斷每個遊戲最高分得主的 `UserId`，卻無法有效率地判斷最高分得主的最高勝負比。若要這樣做，應用程式必須在基礎資料表上執行額外的查詢，以擷取每個最高評分者的優缺點。支援查詢此資料更有效率的方法，便是將這些屬性從基礎資料表投影到全域次要索引，如下圖所示。
![\[描述如何將非索引鍵屬性投射到 GSI 以支援高效查詢。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/GSI_06.png)
由於非索引鍵屬性 `Wins` 與 `Losses` 會投影到索引，因此應用程式可以判斷任何遊戲或任何遊戲與使用者 ID 組合的勝負比。
在選擇要投影到全域次要索引的屬性時，您必須權衡佈建輸送量成本和儲存成本：
+ 若您只需要存取少量的屬性，並且希望盡可能地降低延遲，建議您考慮只將那些屬性投影到全域次要索引。索引愈小，存放成本就愈低，您的寫入成本也愈低。
+ 如果應用程式會頻繁存取某些非索引鍵屬性，您應該考慮將這些屬性投影到全域次要索引。全域次要索引的額外儲存成本會抵銷頻繁執行資料表掃描的成本。
+ 如果需要頻繁存取大多數的非索引鍵屬性，您可以將這些屬性 (或整個基礎資料表) 投影到全域次要索引。這能讓您掌握最大的靈活性。但儲存成本可能會增加，甚至翻倍。
+ 如果您的應用程式不需頻繁查詢資料表，但必須對資料表中的資料執行許多寫入或更新，請考慮投影 `KEYS_ONLY`。全域次要索引的大小將會最小，但仍能在需要的時候進行查詢活動。
## 多屬性金鑰結構描述
全域次要索引支援多屬性索引鍵，可讓您從多個屬性編寫分割區索引鍵和排序索引鍵。使用多屬性索引鍵，您可以從最多四個屬性建立分割區索引鍵，以及從最多四個屬性建立排序索引鍵，每個索引鍵結構描述總計最多八個屬性。
多屬性索引鍵可簡化資料模型，無需手動將屬性串連至合成索引鍵。您可以直接使用網域模型中的自然屬性`TOURNAMENT#WINTER2024#REGION#NA-EAST`，而不是像 一樣建立複合字串。DynamoDB 會自動處理複合索引鍵邏輯、針對資料分佈將多個分割區索引鍵屬性雜湊在一起，並跨多個排序索引鍵屬性維護階層排序順序。
例如，假設您想依賽事和區域組織配對的遊戲競賽系統。使用多屬性索引鍵，您可以將分割區索引鍵定義為兩個不同的屬性： `tournamentId`和 `region`。同樣地，您可以使用 `round`、 和 等多個屬性來定義排序索引鍵`bracket`，`matchId`以建立自然階層。此方法可讓您的資料類型和程式碼保持乾淨，無需處理或剖析字串。
當您使用多屬性索引鍵查詢全域次要索引時，您必須使用等式條件指定所有分割區索引鍵屬性。對於排序索引鍵屬性，您可以依索引鍵結構描述中定義的順序left-to-right查詢它們。這表示您可以單獨查詢第一個排序索引鍵屬性、同時查詢前兩個屬性，或同時查詢所有屬性，但您無法略過中間的屬性。`>`、`BETWEEN`、 `<`或 等不等式條件`begins_with()`必須是查詢中的最後一個條件。
在現有資料表上建立全域次要索引時，多屬性索引鍵的效果特別好。您可以使用資料表中已存在的屬性，而無需在資料中回填合成索引鍵。這可讓您直接將新的查詢模式新增至應用程式，方法是建立索引，使用不同的屬性組合來重組您的資料。
多屬性索引鍵中的每個屬性可以有自己的資料類型：`String`(S)、`Number`(N) 或 `Binary`(B)。選擇資料類型時，請考慮`Number`屬性會按數字排序，而不需要零填補，而`String`屬性則會按詞典排序。例如，如果您對分數屬性使用 `Number`類型，則值 5、50、500 和 1000 會依自然數字順序排序。與 `String`類型相同的值會排序為 "1000"、"5"、"50"、"500"，除非您以前導零填補它們。
設計多屬性索引鍵時，請排序從最一般到最具體的屬性。對於分割區索引鍵，將一律一起查詢並提供良好資料分佈的屬性合併在一起。對於排序索引鍵，請先在階層中放置經常查詢的屬性，以最大化查詢彈性。此排序可讓您以任何符合您存取模式的精細程度進行查詢。
如需實作範例[多屬性索引鍵](GSI.DesignPattern.MultiAttributeKeys.md)，請參閱 。
## 從全域次要索引讀取資料
您可以使用 `Query` 和 `Scan` 操作從全域次要索引擷取項目。`GetItem` 和 `BatchGetItem` 操作不能用於全域次要索引。
### 查詢全域次要索引
您可以使用 `Query` 操作存取全域次要索引中一或多個項目。詢必須指定基礎資料表名稱以及您要使用的索引名稱、要在查詢結果中傳回的屬性，以及您要套用的任何查詢條件。DynamoDB 可以依遞增或遞減順序傳回結果。
假設下列資料從請求排行榜應用程式遊戲資料的 `Query` 傳回。
```
{
"TableName": "GameScores",
"IndexName": "GameTitleIndex",
"KeyConditionExpression": "GameTitle = :v_title",
"ExpressionAttributeValues": {
":v_title": {"S": "Meteor Blasters"}
},
"ProjectionExpression": "UserId, TopScore",
"ScanIndexForward": false
}
```
在此查詢中：
+ DynamoDB 會存取 *GameTitleIndex*，並使用 *GameTitle* 分割區索引鍵尋找 Meteor Blasters 的索引項目。所有具有此索引鍵的索引項目都會相鄰存放，以利快速擷取。
+ 在此遊戲中，DynamoDB 使用索引存取此遊戲的所有使用者 ID 與最高分。
+ 結果會傳回並遞減排序，因為 `ScanIndexForward` 參數設定為 false。
### 掃描全域次要索引
您可以使用 `Scan` 操作從全域次要索引檢索所有資料。您必須在請求中提供基礎資料表名稱及索引名稱。使用 `Scan`，DynamoDB 會讀取索引中的所有資料，並將其傳回應用程式。您也可以請求只傳回一部分的資料，並捨棄其他剩餘的資料。若要執行此作業，請使用 `FilterExpression` 操作的 `Scan` 參數。如需詳細資訊，請參閱 [掃描的篩選條件表達式](Scan.md#Scan.FilterExpression)。
## 資料表與全域次要索引之間的資料同步
DynamoDB 會自動將每個全域次要索引與其基礎資料表同步。當應用程式寫入或刪除資料表中的項目時，該資料表的任何全域次要索引都會使用最終一致模型非同步更新。應用程式永遠不會直接寫入索引。然而，了解 DynamoDB 維持這些索引之方式的含義很重要。
全域次要索引會從基礎資料表繼承讀取/寫入容量模式。如需詳細資訊，請參閱[切換 DynamoDB 容量模式時的注意事項](bp-switching-capacity-modes.md)。
在建立全域次要索引時，您要指定一或多個索引鍵屬性及其資料類型。這表示每次您將項目寫入基礎資料表時，這些屬性的資料類型都必須符合索引鍵結構描述的資料類型。在 `GameTitleIndex` 案例中，索引的 `GameTitle` 分割區索引鍵是定義為 `String` 資料類型。索引的 `TopScore` 排序索引鍵類型為 `Number`。如果您嘗試在 `GameScores` 表中新增項目，並為 `GameTitle` 或 `TopScore` 指定不同的資料類型，DynamoDB 會因資料類型不符而傳回 `ValidationException`。
當您在資料表中放置或刪除項目時，該資料表的全域次要索引會以最終一致的方式更新。在正常的情況下，資料表的資料變更會在瞬間傳播至全域次要索引。不過，在某些不太可能發生的失敗情況下，可能發生較久的傳播延遲。因此，您的應用程式必須能夠預期及處理針對全域次要索引查詢，卻傳回非最新結果的情況。
如果將項目寫入資料表，您不需指定任何全域次要索引排序索引鍵的屬性。以 `GameTitleIndex` 為例，您不需指定 `TopScore` 屬性的值，也能將新的項目寫入 `GameScores` 表。在此案例中，DynamoDB 不會將任何資料寫入此特定項目的索引。
相較於索引較少的資料表，全域次要索引較多的資料表會有較高的寫入活動成本。如需詳細資訊，請參閱[全域次要索引的佈建輸送量考量](#GSI.ThroughputConsiderations)。
## 具有全域次要索引的資料表類別
全域次要索引永遠會使用相同的資料表類別做為其基礎資料表。每當新增資料表的全域次要索引時，新索引都會使用與其基礎資料表相同的資料表類別。更新資料表的資料表類別時，也會更新所有相關聯的全域次要索引。
## 全域次要索引的佈建輸送量考量
當您對佈建模式資料表建立全域次要索引時，必須為該索引的預期工作負載指定讀取與寫入容量單位。全域次要索引的佈建輸送量設定與其基礎資料表的佈建輸送量設定無關。對全域次要索引執行 `Query` 操作會使用索引 (而不是基礎資料表) 的讀取容量單位。當您在資料表中放置、更新或刪除項目時，也會更新該資料表中的全域次要索引。這些索引更新會使用來自索引的寫入容量單位，而不是基礎資料表的單位。
例如，如果對全域次要索引執行 `Query` 操作，並超出其佈建讀取容量，您的請求就會經過限流。如果您對資料表執行大量寫入活動，但該資料表全域次要索引的寫入容量不足，即會限流該資料表的寫入活動。
**重要**
若要避免限流問題產生，全域次要索引的佈建寫入容量必須大於等於基礎資料表的寫入容量，因為新的更新會同時寫入基礎資料表及全域次要索引。
若要檢視全域次要索引的佈建輸送量設定，請使用 `DescribeTable` 操作。會傳回所有資料表全域次要索引的詳細資訊。
### 讀取容量單位
全域次要索引支援最終一致讀取，每個讀取均使用一半的讀取容量單位。這表示單一全域次要索引查詢每個讀取容量單位最多可擷取 2 × 4 KB = 8 KB。
在全域次要索引查詢方面，DynamoDB 會使用為資料表查詢計算佈建讀取活動相同的方式，計算佈建讀取活動。唯一的差別在於計算方式是以索引項目的大小為基礎，而非基礎資料表中項目的大小。讀取容量單位數為所有傳回項目中，所有投影屬性大小的總和。然後，結果四捨五入至下一個 4 KB 界限。如需 DynamoDB 如何計算佈建輸送用量的詳細資訊，請參閱 [DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。
`Query` 操作傳回的結果大小上限是 1 MB。這包含所有傳回項目之所有屬性名稱與值的大小。
例如，假設有一個全域次要索引，其每個項目均包含 2,000 個位元組的資料。現在假設您 `Query` 此索引，而此查詢的 `KeyConditionExpression` 會傳回 8 個項目。相符項目的總大小為 2,000 位元組 × 8 個項目 = 16,000 位元組。然後，此結果四捨五入至最近的 4 KB 界限。因為全域次要索引查詢為最終一致，所以總成本為 0.5 × (16 KB/4 KB) 或 2 個讀取容量單位。
### 寫入容量單位
當新增、更新或刪除資料表項目，並影響到全域次要索引時，全域次要索引會使用該操作的佈建寫入容量單位。寫入的總佈建輸送量成本包含寫入基礎資料表使用的寫入容量單位加上更新全域次要索引使用的寫入容量單位。如果資料表的寫入作業不需更新全域次要索引，就不會使用該索引的寫入容量。
為成功寫入資料表，資料表及其所有全域次要索引的佈建輸送量設定皆必須具有足以容納寫入的寫入容量。否則資料表的寫入會受到限流。
**重要**
建立全域次要索引 (GSI) 時，如果因寫入基礎資料表所產生的 GSI 活動超過 GSI 的佈建寫入容量，則會對基礎資料表的寫入操作限流。此限流會影響所有寫入操作，包括編製索引程序，甚至可能中斷生產工作負載。如需詳細資訊，請參閱[對 Amazon DynamoDB 中的限流問題進行疑難排解](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TroubleshootingThrottling.html)。
將項目寫入全域次要索引的成本取決於幾個因素：
+ 若您將項目寫入定義索引屬性的資料表，或是您將現有的項目更新為先前未定義的索引屬性，則將該項目寫入索引需要進行一次寫入操作。
+ 若資料表的更新會變更索引鍵屬性的值 (從 A 到 B)，則需要兩次寫入：一次是從索引刪除先前的項目，第二次則是將新的項目寫入索引。
+ 若項目存在於索引中，但寫入資料表致使索引屬性遭到刪除，則需要進行一次寫入，從索引刪除舊項目的投影。
+ 若項目在更新之前或之後並不存在於索引中，則該索引將不會有任何額外的寫入成本。
+ 如果資料表的更新只變更索引鍵結構描述中投影屬性的值，但並不變更任何索引鍵屬性的值，則需執行一個寫入將投影屬性的值更新至索引中。
所有這些因素都假設索引中每個項目的大小都小於或等於 1 KB 項目大小 (用於計算寫入容量單位)。較大的索引項目需要額外的寫入容量單位。您可以考慮您的查詢所需要傳回的屬性，並只將那些屬性投影到索引中，來將寫入成本降至最小。
## 全域次要索引的儲存考量
當應用程式將項目寫入資料表時，DynamoDB 會自動將正確的部分屬性複製到應顯示這些屬性的任何全域次要索引中。 AWS 您的帳戶會支付基本資料表中項目的儲存費用，以及該資料表上任何全域次要索引中屬性的儲存費用。
索引項目使用的空間數為下列項目的總和：
+ 基礎資料表主索引鍵 (分割區索引鍵和排序索引鍵) 的大小 (位元組)
+ 索引鍵屬性的大小 (位元組)
+ 投影屬性 (若有的話) 的大小 (位元組)
+ 每個索引項目 100 位元組的額外負荷
若要估算全域次要索引的儲存需求，您可以估算索引中項目的平均大小，再乘以基礎資料表中具有全域次要索引鍵屬性的項目數。
如果資料表包含未定義特定屬性的項目，但該屬性定義為索引分割區索引鍵或排序索引鍵，則 DynamoDB 不會將該項目的任何資料寫入索引。
# 設計模式
設計模式為使用全域次要索引時的常見挑戰提供經過驗證的解決方案。這些模式會示範如何針對特定使用案例建構索引，協助您建置有效率、可擴展的應用程式。
每個模式都包含完整的實作指南，其中包含程式碼範例、最佳實務和實際使用案例，協助您將模式套用至自己的應用程式。
**Topics**
+ [多屬性索引鍵](GSI.DesignPattern.MultiAttributeKeys.md)
# 多屬性索引鍵模式
## 概觀
多屬性索引鍵可讓您建立全域次要索引 (GSI) 分割區，並排序每個分割區最多包含四個屬性的索引鍵。這可減少用戶端程式碼，並可讓您更輕鬆地對資料進行初始建模，並在稍後新增新的存取模式。
考慮常見的案例：若要建立依多個階層屬性查詢項目的 GSI，傳統上您需要透過串連值來建立合成索引鍵。例如，在遊戲應用程式中，若要依競賽、區域和回合查詢競賽配對，您可以建立合成 GSI 分割區索引鍵，例如 TOURNAMENT\$1WINTER2024\$1REGION\$1NA-EAST，以及合成排序索引鍵，例如 ROUND\$1SEMIFINALS\$1BRACKET\$1UPPER。此方法有效，但如果您要將 GSI 新增至現有資料表，則在寫入資料、讀取時剖析和在所有現有項目中回填合成索引鍵時，需要字串串連。這使得程式碼更雜亂且具有挑戰性，以在個別關鍵元件上維持類型安全。
多屬性索引鍵可解決 GSIs此問題。您可以使用多個現有屬性來定義 GSI 分割區索引鍵，例如 tournamentId 和 region。DynamoDB 會自動處理複合索引鍵邏輯，將它們雜湊在一起以進行資料分佈。您可以使用網域模型中的自然屬性撰寫項目，GSI 會自動為其編製索引。不串連、不剖析、不回填。您的程式碼會保持乾淨，您的資料會保持輸入狀態，而您的查詢會保持簡單。當您擁有具有自然屬性分組的階層式資料 （例如競賽 → 區域 → 回合或組織 → 部門 → 團隊） 時，此方法特別有用。
## 應用程式範例
本指南會逐步解說如何為 電競平台建置競賽配對追蹤系統。平台需要有效率地查詢多個維度的配對：依賽事和區域進行括號管理、依玩家進行配對歷史記錄，以及依排程日期進行查詢。
## 資料模型
在此演練中，競賽配對追蹤系統支援三種主要存取模式，每個模式都需要不同的金鑰結構：
**存取模式 1：**依其唯一 ID 查詢特定相符項目
+ **解決方案：**使用 `matchId`做為分割區索引鍵的基礎資料表
**存取模式 2：**查詢特定賽事和區域的所有配對，選擇性地依四捨五入、括號或配對進行篩選
+ **解決方案：**具有多屬性分割區索引鍵 (`tournamentId` \$1 `region`) 和多屬性排序索引鍵 (`round` \$1 `bracket` \$1 `matchId`) 的全域次要索引
+ **範例查詢：**「NA-EAST 區域中的所有 WINTER2024 相符項目」或「WINTER2024/NA-EAST 上括號中的所有 SEMIFINALS 相符項目」
**存取模式 3：**查詢玩家的配對歷史記錄，選擇性地依日期範圍或競賽四捨五入進行篩選
+ **解決方案：**具有單一分割區索引鍵 (`player1Id`) 和多屬性排序索引鍵 (`matchDate` \$1 `round`) 的全域次要索引
+ **範例查詢：**「玩家 101 的所有配對」或「Player 101 在 2024 年 1 月的配對」
檢查項目結構時，傳統和多屬性方法之間的主要差異會變得明確：
**傳統全域次要索引方法 （串連索引鍵）：**
```
// Manual concatenation required for GSI keys
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
// Synthetic keys needed for GSI
GSI_PK: `TOURNAMENT#${tournamentId}#REGION#${region}`, // Must concatenate
GSI_SK: `${round}#${bracket}#${matchId}`, // Must concatenate
// ... other attributes
};
```
**多屬性全域次要索引方法 （原生索引鍵）：**
```
// Use existing attributes directly - no concatenation needed
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
matchDate: '2024-01-18',
// No synthetic keys needed - GSI uses existing attributes directly
// ... other attributes
};
```
使用多屬性索引鍵，您可以使用自然網域屬性寫入項目一次。DynamoDB 會自動跨多個 GSIs 編製索引，而不需要合成串連金鑰。
**基礎資料表結構描述：**
+ 分割區索引鍵：`matchId`(1 屬性）
**全域次要索引結構描述 （具有多屬性索引鍵的 TournamentRegionIndex)：**
+ 分割區索引鍵：`tournamentId`、 `region` (2 個屬性）
+ 排序索引鍵：`round`、`bracket`、 `matchId` (3 個屬性）
**全域次要索引結構描述 (PlayerMatchHistoryIndex 與多屬性索引鍵）：**
+ 分割區索引鍵：`player1Id`(1 屬性）
+ 排序索引鍵：`matchDate`、 `round` (2 個屬性）
### 基礎資料表：TournamentMatches
| matchId (PK) | tournamentId | region | round | 括號 | player1Id | player2Id | matchDate | 優勝者 | 分數 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| match-001 | WINTER2024 | NA-EAST | 最終 | CHAMPIONSHIP | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| match-002 | WINTER2024 | NA-EAST | SEMIFINALS | UPPER | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| match-003 | WINTER2024 | NA-EAST | SEMIFINALS | UPPER | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| match-004 | WINTER2024 | NA-EAST | QUARTERFINALS | UPPER | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| match-005 | WINTER2024 | NA-WEST | 最終 | CHAMPIONSHIP | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| match-006 | WINTER2024 | NA-WEST | SEMIFINALS | UPPER | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| match-007 | SPRING2024 | NA-EAST | QUARTERFINALS | UPPER | 101 | 108 | 2024-03-15 | 101 | 3-0 |
| match-008 | SPRING2024 | NA-EAST | QUARTERFINALS | LOWER | 103 | 110 | 2024-03-15 | 103 | 3-2 |
### GSI：TournamentRegionIndex （多屬性索引鍵）
| tournamentId (PK) | 區域 (PK) | round (SK) | 括號 (SK) | matchId (SK) | player1Id | player2Id | matchDate | 優勝者 | 分數 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| WINTER2024 | NA-EAST | 最終 | CHAMPIONSHIP | match-001 | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| WINTER2024 | NA-EAST | QUARTERFINALS | UPPER | match-004 | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| WINTER2024 | NA-EAST | SEMIFINALS | UPPER | match-002 | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| WINTER2024 | NA-EAST | SEMIFINALS | UPPER | match-003 | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| WINTER2024 | NA-WEST | 最終 | CHAMPIONSHIP | match-005 | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| WINTER2024 | NA-WEST | SEMIFINALS | UPPER | match-006 | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| SPRING2024 | NA-EAST | QUARTERFINALS | LOWER | match-008 | 103 | 110 | 2024-03-15 | 103 | 3-2 |
| SPRING2024 | NA-EAST | QUARTERFINALS | UPPER | match-007 | 101 | 108 | 2024-03-15 | 101 | 3-0 |
### GSI： PlayerMatchHistoryIndex （多屬性索引鍵）
| player1Id (PK) | matchDate (SK) | round (SK) | tournamentId | region | 括號 | matchId | player2Id | 優勝者 | 分數 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 101 | 2024-01-15 | QUARTERFINALS | WINTER2024 | NA-EAST | UPPER | match-004 | 109 | 101 | 3-1 |
| 101 | 2024-01-18 | SEMIFINALS | WINTER2024 | NA-EAST | UPPER | match-002 | 105 | 101 | 3-2 |
| 101 | 2024-01-20 | 最終 | WINTER2024 | NA-EAST | CHAMPIONSHIP | match-001 | 103 | 101 | 3-1 |
| 101 | 2024-03-15 | QUARTERFINALS | SPRING2024 | NA-EAST | UPPER | match-007 | 108 | 101 | 3-0 |
| 102 | 2024-01-18 | SEMIFINALS | WINTER2024 | NA-WEST | UPPER | match-006 | 106 | 102 | 3-1 |
| 102 | 2024-01-20 | 最終 | WINTER2024 | NA-WEST | CHAMPIONSHIP | match-005 | 104 | 102 | 3-2 |
| 103 | 2024-01-18 | SEMIFINALS | WINTER2024 | NA-EAST | UPPER | match-003 | 107 | 103 | 3-0 |
| 103 | 2024-03-15 | QUARTERFINALS | SPRING2024 | NA-EAST | LOWER | match-008 | 110 | 103 | 3-2 |
## 先決條件
開始前，請確保您具備以下條件：
### 帳戶和許可
+ 作用中 AWS 帳戶 （視需要[在此處建立一個](https://aws.amazon.com/free/))
+ DynamoDB 操作的 IAM 許可：
+ `dynamodb:CreateTable`
+ `dynamodb:DeleteTable`
+ `dynamodb:DescribeTable`
+ `dynamodb:PutItem`
+ `dynamodb:Query`
+ `dynamodb:BatchWriteItem`
**注意**
**安全備註：**針對生產用途，建立僅具有所需許可的自訂 IAM 政策。在本教學課程中，您可以使用 AWS 受管政策 `AmazonDynamoDBFullAccessV2`。
### 開發環境
+ 安裝在機器上的 Node.js
+ AWS 使用下列其中一種方法設定的登入資料：
**選項 1： AWS CLI**
```
aws configure
```
**選項 2：環境變數**
```
export AWS_ACCESS_KEY_ID=your_access_key_here
export AWS_SECRET_ACCESS_KEY=your_secret_key_here
export AWS_DEFAULT_REGION=us-east-1
```
### 安裝必要的套件
```
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```
## 實作
### 步驟 1：使用多屬性索引鍵建立具有 GSIs資料表
使用簡單的基本金鑰結構和使用多屬性金鑰GSIs 建立資料表。
#### 程式碼範例
```
import { DynamoDBClient, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const response = await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' } // Simple PK
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
// GSIs with multi-attribute keys
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'region', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'round', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'bracket', KeyType: 'RANGE' }, // GSI SK attribute 2
{ AttributeName: 'matchId', KeyType: 'RANGE' } // GSI SK attribute 3
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' }, // GSI PK
{ AttributeName: 'matchDate', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'round', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
console.log("Table with multi-attribute GSI keys created successfully");
```
**關鍵設計決策：**
**基礎資料表：**基礎資料表使用簡單的`matchId`分割區索引鍵進行直接比對查詢，讓基礎資料表結構保持直接，同時 GSIs 提供複雜的查詢模式。
**TournamentRegionIndex 全域次要索引：**`TournamentRegionIndex`全域次要索引使用 `tournamentId` \$1 `region`作為多屬性分割區索引鍵，建立競爭區域隔離，其中資料會依兩個屬性的雜湊合併分佈，在特定競爭區域內容中啟用有效的查詢。多屬性排序索引鍵 (`round` \$1 `bracket` \$1 `matchId`) 提供階層排序，支援階層任何層級的查詢，自然排序從一般 （圓形） 到特定 （相符 ID)。
**PlayerMatchHistoryIndex 全域次要索引：**`PlayerMatchHistoryIndex`全域次要索引使用 `player1Id`做為分割區索引鍵，依玩家重新組織資料，為特定玩家啟用跨旅程查詢。多屬性排序索引鍵 (`matchDate` \$1 `round`) 提供依時間順序排序的功能，可依日期範圍或特定競賽回合進行篩選。
### 步驟 2：插入具有原生屬性的資料
使用自然屬性新增競賽配對資料。GSI 會自動為這些屬性編製索引，而不需要合成索引鍵。
#### 程式碼範例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Tournament match data - no synthetic keys needed for GSIs
const matches = [
// Winter 2024 Tournament, NA-EAST region
{
matchId: 'match-001',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '101',
player2Id: '103',
matchDate: '2024-01-20',
winner: '101',
score: '3-1'
},
{
matchId: 'match-002',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '105',
matchDate: '2024-01-18',
winner: '101',
score: '3-2'
},
{
matchId: 'match-003',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '103',
player2Id: '107',
matchDate: '2024-01-18',
winner: '103',
score: '3-0'
},
{
matchId: 'match-004',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '109',
matchDate: '2024-01-15',
winner: '101',
score: '3-1'
},
// Winter 2024 Tournament, NA-WEST region
{
matchId: 'match-005',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '102',
player2Id: '104',
matchDate: '2024-01-20',
winner: '102',
score: '3-2'
},
{
matchId: 'match-006',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '102',
player2Id: '106',
matchDate: '2024-01-18',
winner: '102',
score: '3-1'
},
// Spring 2024 Tournament, NA-EAST region
{
matchId: 'match-007',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '108',
matchDate: '2024-03-15',
winner: '101',
score: '3-0'
},
{
matchId: 'match-008',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'LOWER',
player1Id: '103',
player2Id: '110',
matchDate: '2024-03-15',
winner: '103',
score: '3-2'
}
];
// Insert all matches
for (const match of matches) {
await docClient.send(new PutCommand({
TableName: 'TournamentMatches',
Item: match
}));
console.log(`Added: ${match.matchId} - ${match.tournamentId}/${match.region} - ${match.round} ${match.bracket}`);
}
console.log(`\nInserted ${matches.length} tournament matches`);
console.log("No synthetic keys created - GSIs use native attributes automatically");
```
**資料結構說明：**
**自然屬性用量：**每個屬性代表一個真正的競賽概念，不需要字串串連或剖析，提供直接映射到網域模型。
**自動全域次要索引索引：**GSIs 會使用現有屬性 (`tournamentId`、`region``round``bracket`、、 `matchId`代表 TournamentRegionIndex，以及 `player1Id`、 `round`代表 PlayerMatchHistoryIndex) 自動索引項目`matchDate`，而不需要合成串連索引鍵。
**不需要回填：**當您將具有多屬性索引鍵的新全域次要索引新增至現有資料表時，DynamoDB 會使用其自然屬性自動為所有現有項目編製索引，而不需要使用合成索引鍵更新項目。
### 步驟 3：查詢具有所有分割區索引鍵屬性的 TournamentRegionIndex 全域次要索引
此範例會查詢具有多屬性分割區索引鍵 (`tournamentId` \$1 ) 的 TournamentRegionIndex 全域次要索引`region`。所有分割區索引鍵屬性都必須在查詢中指定等式條件 - 您無法`tournamentId`單獨使用 查詢，或在分割區索引鍵屬性上使用不等式運算子。
#### 程式碼範例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query GSI: All matches for WINTER2024 tournament in NA-EAST region
const response = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: {
'#region': 'region', // 'region' is a reserved keyword
'#tournament': 'tournament'
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST'
}
}));
console.log(`Found ${response.Items.length} matches for WINTER2024/NA-EAST:\n`);
response.Items.forEach(match => {
console.log(` ${match.round} | ${match.bracket} | ${match.matchId}`);
console.log(` Players: ${match.player1Id} vs ${match.player2Id}`);
console.log(` Winner: ${match.winner}, Score: ${match.score}\n`);
});
```
**預期的輸出：**
```
Found 4 matches for WINTER2024/NA-EAST:
FINALS | CHAMPIONSHIP | match-001
Players: 101 vs 103
Winner: 101, Score: 3-1
QUARTERFINALS | UPPER | match-004
Players: 101 vs 109
Winner: 101, Score: 3-1
SEMIFINALS | UPPER | match-002
Players: 101 vs 105
Winner: 101, Score: 3-2
SEMIFINALS | UPPER | match-003
Players: 103 vs 107
Winner: 103, Score: 3-0
```
**無效查詢：**
```
// Missing region attribute
KeyConditionExpression: 'tournamentId = :tournament'
// Using inequality on partition key attribute
KeyConditionExpression: 'tournamentId = :tournament AND #region > :region'
```
**效能：**多屬性分割區索引鍵會雜湊在一起，提供與單一屬性索引鍵相同的 O(1) 查詢效能。
### 步驟 4：從left-to-right查詢全域次要索引排序索引鍵
排序索引鍵屬性必須依全域次要索引中定義的順序left-to-right查詢。此範例示範在不同階層層級查詢 TournamentRegionIndex：僅依 `round`篩選、依 `round` \$1 篩選`bracket`，或依所有三個排序索引鍵屬性篩選。您無法略過中間的屬性，例如，您無法在略過 `matchId`時透過 `round`和 查詢`bracket`。
#### 程式碼範例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Filter by first sort key attribute (round)
console.log("Query 1: All SEMIFINALS matches");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Filter by first two sort key attributes (round + bracket)
console.log("Query 2: SEMIFINALS UPPER bracket matches");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Filter by all three sort key attributes (round + bracket + matchId)
console.log("Query 3: Specific match in SEMIFINALS UPPER bracket");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket AND matchId = :matchId',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER',
':matchId': 'match-002'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - skipping round
console.log("Query 4: Attempting to skip first sort key attribute (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot skip sort key attributes - must query left-to-right\n`);
}
```
**預期的輸出：**
```
Query 1: All SEMIFINALS matches
Found 2 matches
Query 2: SEMIFINALS UPPER bracket matches
Found 2 matches
Query 3: Specific match in SEMIFINALS UPPER bracket
Found 1 matches
Query 4: Attempting to skip first sort key attribute (WILL FAIL)
Error: Query key condition not supported
Cannot skip sort key attributes - must query left-to-right
```
**Left-to-right查詢規則：**您必須從左至右依序查詢屬性，而不略過任何屬性。
**有效模式：**
+ 僅限第一個屬性： `round = 'SEMIFINALS'`
+ 前兩個屬性： `round = 'SEMIFINALS' AND bracket = 'UPPER'`
+ 全部三個屬性： `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId = 'match-002'`
**無效的模式：**
+ 略過第一個屬性： `bracket = 'UPPER'`（略過四捨五入）
+ 查詢順序不正確： `matchId = 'match-002' AND round = 'SEMIFINALS'`
+ 離開間隙： `round = 'SEMIFINALS' AND matchId = 'match-002'` （略過括號）
**注意**
**設計秘訣：**從最一般到最具體的排序索引鍵屬性，以最大化查詢彈性。
### 步驟 5：在全域次要索引排序索引鍵上使用不等式條件
不等式條件必須是查詢中的最後一個條件。此範例示範在排序索引鍵屬性上使用比較運算子 (`>=`、`BETWEEN`) 和字首比對 (`begins_with()`)。使用不等式運算子之後，就無法再新增任何其他排序索引鍵條件，不等式必須是索引鍵條件表達式中的最終條件。
#### 程式碼範例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Round comparison (inequality on first sort key attribute)
console.log("Query 1: Matches from QUARTERFINALS onwards");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round >= :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Round range with BETWEEN
console.log("Query 2: Matches between QUARTERFINALS and SEMIFINALS");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round BETWEEN :start AND :end',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':start': 'QUARTERFINALS',
':end': 'SEMIFINALS'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Prefix matching with begins_with (treated as inequality)
console.log("Query 3: Matches in brackets starting with 'U'");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND begins_with(bracket, :prefix)',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':prefix': 'U'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - condition after inequality
console.log("Query 4: Attempting condition after inequality (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round > :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot add conditions after inequality - it must be last\n`);
}
```
**不等式運算子規則：**您可以將比較運算子 (`>`、`>=``<`、、`<=`)、 `BETWEEN`用於範圍查詢，以及 `begins_with()`用於字首比對。不等式必須是查詢中的最後一個條件。
**有效模式：**
+ 等式條件後接不等式： `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId > 'match-001'`
+ 第一個屬性上的不等式： `round BETWEEN 'QUARTERFINALS' AND 'SEMIFINALS'`
+ 字首比對為最終條件： `round = 'SEMIFINALS' AND begins_with(bracket, 'U')`
**無效的模式：**
+ 在不等式之後新增條件： `round > 'QUARTERFINALS' AND bracket = 'UPPER'`
+ 使用多個不等式： `round > 'QUARTERFINALS' AND bracket > 'L'`
**重要**
`begins_with()` 會被視為不等式條件，因此沒有任何額外的排序索引鍵條件可以遵循它。
### 步驟 6：使用多屬性排序索引鍵查詢 PlayerMatchHistoryIndex 全域次要索引
此範例會查詢具有單一分割區索引鍵 (`player1Id`) 和多屬性排序索引鍵 (`matchDate` \$1 ) 的 PlayerMatchHistoryIndex`round`。這可透過查詢特定玩家的所有配對而不了解賽事 IDs，而基礎資料表則需要每個賽事區域組合個別的查詢。
#### 程式碼範例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: All matches for Player 101 across all tournaments
console.log("Query 1: All matches for Player 101");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: {
':player': '101'
}
}));
console.log(` Found ${query1.Items.length} matches for Player 101:`);
query1.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log();
// Query 2: Player 101 matches on specific date
console.log("Query 2: Player 101 matches on 2024-01-18");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Player 101 SEMIFINALS matches on specific date
console.log("Query 3: Player 101 SEMIFINALS matches on 2024-01-18");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date AND round = :round',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: Player 101 matches in date range
console.log("Query 4: Player 101 matches in January 2024");
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate BETWEEN :start AND :end',
ExpressionAttributeValues: {
':player': '101',
':start': '2024-01-01',
':end': '2024-01-31'
}
}));
console.log(` Found ${query4.Items.length} matches\n`);
```
## 模式變化
### 具有多屬性索引鍵的時間序列資料
使用階層式時間屬性最佳化時間序列查詢
#### 程式碼範例
```
{
TableName: 'IoTReadings',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'readingId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'readingId', AttributeType: 'S' },
{ AttributeName: 'deviceId', AttributeType: 'S' },
{ AttributeName: 'locationId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'timestamp', AttributeType: 'S' }
],
// GSI with multi-attribute keys for time-series queries
GlobalSecondaryIndexes: [{
IndexName: 'DeviceLocationTimeIndex',
KeySchema: [
{ AttributeName: 'deviceId', KeyType: 'HASH' },
{ AttributeName: 'locationId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'timestamp', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query patterns enabled via GSI:
// - All readings for device in location
// - Readings for specific year
// - Readings for specific month in year
// - Readings for specific day
// - Readings in time range
```
**優點：**自然時間階層 （年 → 月 → 日 → 時間戳記） 可隨時啟用有效率的查詢，而無需日期剖析或操作。全域次要索引會使用其自然時間屬性自動為所有讀數編製索引。
### 具有多屬性索引鍵的電子商務訂單
追蹤具有多個維度的訂單
#### 程式碼範例
```
{
TableName: 'Orders',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'orderId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'orderId', AttributeType: 'S' },
{ AttributeName: 'sellerId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'orderDate', AttributeType: 'S' },
{ AttributeName: 'category', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'orderStatus', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'SellerRegionIndex',
KeySchema: [
{ AttributeName: 'sellerId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'category', KeyType: 'RANGE' },
{ AttributeName: 'orderId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'CustomerOrdersIndex',
KeySchema: [
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'orderStatus', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// SellerRegionIndex GSI queries:
// - Orders by seller and region
// - Orders by seller, region, and date
// - Orders by seller, region, date, and category
// CustomerOrdersIndex GSI queries:
// - Customer's orders
// - Customer's orders by date
// - Customer's orders by date and status
```
### 階層組織資料
模型組織階層
#### 程式碼範例
```
{
TableName: 'Employees',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'employeeId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'employeeId', AttributeType: 'S' },
{ AttributeName: 'companyId', AttributeType: 'S' },
{ AttributeName: 'divisionId', AttributeType: 'S' },
{ AttributeName: 'departmentId', AttributeType: 'S' },
{ AttributeName: 'teamId', AttributeType: 'S' },
{ AttributeName: 'skillCategory', AttributeType: 'S' },
{ AttributeName: 'skillLevel', AttributeType: 'S' },
{ AttributeName: 'yearsExperience', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'OrganizationIndex',
KeySchema: [
{ AttributeName: 'companyId', KeyType: 'HASH' },
{ AttributeName: 'divisionId', KeyType: 'HASH' },
{ AttributeName: 'departmentId', KeyType: 'RANGE' },
{ AttributeName: 'teamId', KeyType: 'RANGE' },
{ AttributeName: 'employeeId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'SkillsIndex',
KeySchema: [
{ AttributeName: 'skillCategory', KeyType: 'HASH' },
{ AttributeName: 'skillLevel', KeyType: 'RANGE' },
{ AttributeName: 'yearsExperience', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'INCLUDE', NonKeyAttributes: ['employeeId', 'name'] }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// OrganizationIndex GSI query patterns:
// - All employees in company/division
// - Employees in specific department
// - Employees in specific team
// SkillsIndex GSI query patterns:
// - Employees by skill and experience level
```
### 稀疏多屬性索引鍵
結合多屬性索引鍵來製作稀疏的 GSI
#### 程式碼範例
```
{
TableName: 'Products',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'productId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'productId', AttributeType: 'S' },
{ AttributeName: 'categoryId', AttributeType: 'S' },
{ AttributeName: 'subcategoryId', AttributeType: 'S' },
{ AttributeName: 'averageRating', AttributeType: 'N' },
{ AttributeName: 'reviewCount', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'CategoryIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'subcategoryId', KeyType: 'HASH' },
{ AttributeName: 'productId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'ReviewedProductsIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'averageRating', KeyType: 'RANGE' }, // Optional attribute
{ AttributeName: 'reviewCount', KeyType: 'RANGE' } // Optional attribute
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Only products with reviews appear in ReviewedProductsIndex GSI
// Automatic filtering without application logic
// Multi-attribute sort key enables rating and count queries
```
### SaaS 多租戶
具有客戶隔離的多租戶 SaaS 平台
#### 程式碼範例
```
// Table design
{
TableName: 'SaasData',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'resourceId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'resourceId', AttributeType: 'S' },
{ AttributeName: 'tenantId', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'resourceType', AttributeType: 'S' }
],
// GSI with multi-attribute keys for tenant-customer isolation
GlobalSecondaryIndexes: [{
IndexName: 'TenantCustomerIndex',
KeySchema: [
{ AttributeName: 'tenantId', KeyType: 'HASH' },
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'resourceType', KeyType: 'RANGE' },
{ AttributeName: 'resourceId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query GSI: All resources for tenant T001, customer C001
const resources = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001'
}
}));
// Query GSI: Specific resource type for tenant/customer
const documents = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer AND resourceType = :type',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001',
':type': 'document'
}
}));
```
**優點：**租戶-客戶內容和自然資料組織內的高效率查詢。
### 金融交易
銀行系統使用 GSIs追蹤帳戶交易
#### 程式碼範例
```
// Table design
{
TableName: 'BankTransactions',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'transactionId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'transactionId', AttributeType: 'S' },
{ AttributeName: 'accountId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'transactionType', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'AccountTimeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'transactionId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'TransactionTypeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'transactionType', KeyType: 'RANGE' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Query AccountTimeIndex GSI: All transactions for account in 2023
const yearTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023'
}
}));
// Query AccountTimeIndex GSI: Transactions in specific month
const monthTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year AND #month = :month',
ExpressionAttributeNames: { '#year': 'year', '#month': 'month' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023',
':month': '11'
}
}));
// Query TransactionTypeIndex GSI: Deposits in 2023
const deposits = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'TransactionTypeIndex',
KeyConditionExpression: 'accountId = :account AND transactionType = :type AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':type': 'deposit',
':year': '2023'
}
}));
```
## 完成範例
下列範例示範從設定到清除的多屬性金鑰：
### 程式碼範例
```
import {
DynamoDBClient,
CreateTableCommand,
DeleteTableCommand,
waitUntilTableExists
} from "@aws-sdk/client-dynamodb";
import {
DynamoDBDocumentClient,
PutCommand,
QueryCommand
} from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
async function multiAttributeKeysDemo() {
console.log("Starting Multi-Attribute GSI Keys Demo\n");
// Step 1: Create table with GSIs using multi-attribute keys
console.log("1. Creating table with multi-attribute GSI keys...");
await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'round', KeyType: 'RANGE' },
{ AttributeName: 'bracket', KeyType: 'RANGE' },
{ AttributeName: 'matchId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' },
{ AttributeName: 'matchDate', KeyType: 'RANGE' },
{ AttributeName: 'round', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
await waitUntilTableExists({ client, maxWaitTime: 120 }, { TableName: 'TournamentMatches' });
console.log("Table created\n");
// Step 2: Insert tournament matches
console.log("2. Inserting tournament matches...");
const matches = [
{ matchId: 'match-001', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '101', player2Id: '103', matchDate: '2024-01-20', winner: '101', score: '3-1' },
{ matchId: 'match-002', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'SEMIFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '105', matchDate: '2024-01-18', winner: '101', score: '3-2' },
{ matchId: 'match-003', tournamentId: 'WINTER2024', region: 'NA-WEST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '102', player2Id: '104', matchDate: '2024-01-20', winner: '102', score: '3-2' },
{ matchId: 'match-004', tournamentId: 'SPRING2024', region: 'NA-EAST', round: 'QUARTERFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '108', matchDate: '2024-03-15', winner: '101', score: '3-0' }
];
for (const match of matches) {
await docClient.send(new PutCommand({ TableName: 'TournamentMatches', Item: match }));
}
console.log(`Inserted ${matches.length} tournament matches\n`);
// Step 3: Query GSI with multi-attribute partition key
console.log("3. Query TournamentRegionIndex GSI: WINTER2024/NA-EAST matches");
const gsiQuery1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: { '#region': 'region' },
ExpressionAttributeValues: { ':tournament': 'WINTER2024', ':region': 'NA-EAST' }
}));
console.log(` Found ${gsiQuery1.Items.length} matches:`);
gsiQuery1.Items.forEach(match => {
console.log(` ${match.round} - ${match.bracket} - ${match.winner} won`);
});
// Step 4: Query GSI with multi-attribute sort key
console.log("\n4. Query PlayerMatchHistoryIndex GSI: All matches for Player 101");
const gsiQuery2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: { ':player': '101' }
}));
console.log(` Found ${gsiQuery2.Items.length} matches for Player 101:`);
gsiQuery2.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log("\nDemo complete");
console.log("No synthetic keys needed - GSIs use native attributes automatically");
}
async function cleanup() {
console.log("Deleting table...");
await client.send(new DeleteTableCommand({ TableName: 'TournamentMatches' }));
console.log("Table deleted");
}
// Run demo
multiAttributeKeysDemo().catch(console.error);
// Uncomment to cleanup:
// cleanup().catch(console.error);
```
**最小程式碼 scaffold**
### 程式碼範例
```
// 1. Create table with GSI using multi-attribute keys
await client.send(new CreateTableCommand({
TableName: 'MyTable',
KeySchema: [
{ AttributeName: 'id', KeyType: 'HASH' } // Simple base table PK
],
AttributeDefinitions: [
{ AttributeName: 'id', AttributeType: 'S' },
{ AttributeName: 'attr1', AttributeType: 'S' },
{ AttributeName: 'attr2', AttributeType: 'S' },
{ AttributeName: 'attr3', AttributeType: 'S' },
{ AttributeName: 'attr4', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [{
IndexName: 'MyGSI',
KeySchema: [
{ AttributeName: 'attr1', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'attr2', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'attr3', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'attr4', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}));
// 2. Insert items with native attributes (no concatenation needed for GSI)
await docClient.send(new PutCommand({
TableName: 'MyTable',
Item: {
id: 'item-001',
attr1: 'value1',
attr2: 'value2',
attr3: 'value3',
attr4: 'value4',
// ... other attributes
}
}));
// 3. Query GSI with all partition key attributes
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2'
}
}));
// 4. Query GSI with sort key attributes (left-to-right)
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2 AND attr3 = :v3',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2',
':v3': 'value3'
}
}));
// Note: If any attribute name is a DynamoDB reserved keyword, use ExpressionAttributeNames:
// KeyConditionExpression: 'attr1 = :v1 AND #attr2 = :v2'
// ExpressionAttributeNames: { '#attr2': 'attr2' }
```
## 其他資源
+ [DynamoDB 最佳實務](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html)
+ [使用資料表和資料](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.html)
+ [全域次要索引](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html)
+ [查詢和掃描操作](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html)
# 在 DynamoDB 中管理全域次要索引
本節說明如何在 Amazon DynamoDB 中建立、修改和刪除全域次要索引。
**Topics**
+ [建立具有全域次要索引的資料表](#GSI.Creating)
+ [描述資料表上的全域次要索引](#GSI.Describing)
+ [將全域次要索引新增至現有資料表](#GSI.OnlineOps.Creating)
+ [刪除全域次要索引](#GSI.OnlineOps.Deleting)
+ [建立期間修改全域次要索引](#GSI.OnlineOps.Creating.Modify)
## 建立具有全域次要索引的資料表
若要建立具有一或多個全域次要索引的資料表，請搭配 `CreateTable` 參數使用 `GlobalSecondaryIndexes` 操作。為達最大的查詢靈活性，您最多可以為每個資料表建立 20 個全域次要索引 (預設配額)。
您必須指定一個屬性做為分割區索引鍵。您可以選擇為排序索引鍵指定另一個屬性。上述任一索引鍵屬性皆不需與資料表的索引鍵屬性相同。例如，在 *GameScores* 表中 (請參閱 [在 DynamoDB 中使用全域次要索引](GSI.md))，`TopScore` 和 `TopScoreDateTime` 都不是索引鍵屬性。您可以建立分割區索引鍵為 `TopScore`、排序索引鍵為 `TopScoreDateTime` 的全域次要索引。您可能會使用這類索引來判斷高分與一天中玩遊戲的時間之間是否有相互關聯性。
每個索引鍵屬性都必須是類型為 `String`、`Number` 或 `Binary` 的純量。(而不可以是文件或集合)。您可以將任何資料類型的屬性投影到全域次要索引。這包括純量、文件和集合。如需資料類型的完整清單，請參閱 [資料類型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)。
如果使用的是佈建模式，您必須為索引提供 `ProvisionedThroughput` 設定，包含 `ReadCapacityUnits` 和 `WriteCapacityUnits`。這些佈建輸送量設定與資料表的佈建輸送量設定無關，但運作方式類似。如需詳細資訊，請參閱 [全域次要索引的佈建輸送量考量](GSI.md#GSI.ThroughputConsiderations)。
全域次要索引會從基礎資料表繼承讀取/寫入容量模式。如需詳細資訊，請參閱[切換 DynamoDB 容量模式時的注意事項](bp-switching-capacity-modes.md)。
**注意**
建立新 GSI 時，檢查您選擇的分割區索引鍵是否會在新索引的分割區索引鍵值之間產生資料或流量的不均勻分佈或小範圍分佈，這一點非常重要。如果發生這種情況，您可能會看到回填和寫入操作同時發生，並限流對基礎資料表的寫入。該服務會採取措施以將此情況的可能性降至最低，但沒有與索引分割區索引鍵、所選擇的投射或主索引鍵稀疏程度有關的客戶資料形狀的洞察。
如果您懷疑新的全域次要索引在分割區索引鍵值上可能具有小範圍或偏斜的資料或流量分佈，請在將新索引新增到對操作而言重要的資料表之前，考慮以下項目。
在應用程式驅動的流量為最少時新增索引可能是最安全的做法。
考慮在基礎資料表和索引上啟用 CloudWatch Contributor Insights。這將為您的流量分佈提供有價值的洞察。
在整個過程中觀看 `ThrottledRequests`、 `WriteThrottleEvents`和 `OnlineIndexPercentageProgress` CloudWatch 指標。視需要調整佈建的寫入容量，以便在合理的時間內完成回填，而不會對進行中的操作造成任何重大限流影響。 `OnlineIndexConsumedWriteCapacity`和 `OnlineThrottleEvents` 預期在索引回填期間會顯示 0。
如果您因為寫入限流而發生操作影響，請準備好取消索引建立。
## 描述資料表上的全域次要索引
若要檢視資料表上所有全域次要索引的狀態，請使用 `DescribeTable` 操作。回應的 `GlobalSecondaryIndexes` 部分會顯示資料表上的所有索引，以及每個索引的目前狀態 (`IndexStatus`)。
全域次要索引的 `IndexStatus` 會是下列其中一項：
+ `CREATING`：正在建立索引，尚無法使用。
+ `ACTIVE`：索引已可供使用，應用程式可以在索引上執行 `Query` 操作。
+ `UPDATING`：正在變更索引的佈建輸送量設定。
+ `DELETING`：正在刪除索引，無法再使用。
當 DynamoDB 建置完全域次要索引時，索引狀態會從 `CREATING` 變更為 `ACTIVE`。
## 將全域次要索引新增至現有資料表
若要將全域次要索引新增至現有資料表，請搭配 `GlobalSecondaryIndexUpdates` 參數使用 `UpdateTable` 操作。您必須提供下列項目：
+ 索引名稱。該名稱在資料表的所有索引中必須是唯一的。
+ 索引的索引鍵結構描述。您必須指定一個屬性做為索引的分割區索引鍵，並可以選擇性地指定另一個屬性做為索引的排序索引鍵。上述任一索引鍵屬性皆不需與資料表的索引鍵屬性相同。每個結構描述屬性的資料類型都必須是純量：`String`、`Number` 或 `Binary`。
+ 要從資料表投影到索引的屬性：
+ `KEYS_ONLY`：索引中的每個項目都只包含資料表分割索引鍵和排序索引鍵值，以及索引鍵值。
+ `INCLUDE`：除了 `KEYS_ONLY` 中描述的屬性外，次要索引會包含您指定的其他非索引鍵屬性。
+ `ALL`：索引包含來源資料表中的所有屬性。
+ 索引的佈建輸送量設定，包含 `ReadCapacityUnits` 和 `WriteCapacityUnits`。這些佈建輸送量設定與資料表的佈建輸送量設定無關。
每個 `UpdateTable` 操作只能建立一個全域次要索引。
### 索引建立階段
當您將新的全域次要索引新增至現有資料表時，資料表在索引建置時仍可繼續使用。但新的索引在其狀態從 `CREATING` 變更為 `ACTIVE` 前，都不可進行 Query 操作。
**注意**
全域次要索引建立不使用 Application Auto Scaling。提高 `MIN` Application Auto Scaling 容量不會減少全域次要索引的建立時間。
DynamoDB 幕後的索引建置分為兩個階段：
**資源配置**
DynamoDB 會配置建立索引所需的運算和儲存資源。
在資源配置階段，`IndexStatus` 屬性是 `CREATING`，而 `Backfilling` 屬性是 false。您可使用 `DescribeTable` 操作擷取資料表的狀態和其所有次要索引。
當索引處於資源配置階段時，您無法刪除索引或刪除其父資料表。您也無法修改索引或資料表的佈建輸送量。您無法新增或刪除資料表上的其他索引。不過，您可以修改這些其他索引的佈建輸送量。
**回填**
對於資料表中的每個項目，DynamoDB 會根據屬性的投影，判斷將哪一組屬性寫入索引 (`KEYS_ONLY`、`INCLUDE` 或 `ALL`)。然後它會將這些屬性寫入索引。在回填階段期間，DynamoDB 會追蹤正在資料表中新增、刪除或更新的項目。也會適當地在索引中新增、刪除或更新這些項目的屬性。
在回填階段，`IndexStatus` 屬性會設為 `CREATING`，而 `Backfilling` 屬性是 true。您可使用 `DescribeTable` 操作擷取資料表的狀態和其所有次要索引。
當索引正在回填時，您無法刪除其父資料表。但您仍然可以刪除索引，或修改資料表及其任何全域次要索引的佈建輸送量。
在回填階段，違規項目的寫入可能一部分成功，而一部分則遭到拒絕。回填後，所有違反新索引鍵結構描述的項目寫入都會遭到拒絕。建議您在回填階段完成後執行 Violation Detector 工具，以偵測和解決任何可能已發生的索引鍵違規情況。如需詳細資訊，請參閱 [偵測和修正 DynamoDB 中的索引鍵違規情況](GSI.OnlineOps.ViolationDetection.md)。
進行資源配置和回填階段時，索引的狀態為 `CREATING`。在這期間，DynamoDB 會對資料表執行讀取操作。從基礎資料表填入全域次要索引的讀取操作不需支付費用。
當索引建置完成時，其狀態會變更為 `ACTIVE`。您無法 `Query` 或 `Scan` 索引，直到其 `ACTIVE` 為止。
**注意**
在部分情況下，DynamoDB 會因索引鍵違規情況而無法將資料表中的資料寫入索引。如果發生下列情況，就會發生此情形：
屬性值的資料類型與索引鍵結構描述資料類型的資料類型不相符。
屬性的大小超過索引鍵屬性的最大長度。
索引鍵屬性具有空字串或空的二進制屬性值。
索引鍵違規情況不會影響全域次要索引建立。不過，當索引變成 `ACTIVE` 時，索引中不會出現違規索引鍵。
DynamoDB 提供獨立工具來尋找和解決這些問題。如需詳細資訊，請參閱 [偵測和修正 DynamoDB 中的索引鍵違規情況](GSI.OnlineOps.ViolationDetection.md)。
### 將全域次要索引新增至大型資料表
建置全域次要索引所需的時間取決於幾個因素，例如：
+ 資料表的大小
+ 資料表中符合納入索引資格的項目數目
+ 投影到索引的屬性數目
+ 索引建置期間主要資料表上的寫入活動
如果您要將全域次要索引新增至極大的資料表，建立程序可能需要很久才能完成。若要監控進度並判斷索引是否有足夠的寫入容量，請參閱下列 Amazon CloudWatch 指標：
+ `OnlineIndexPercentageProgress`
如需與 DynamoDB 相關的 CloudWatch 指標的詳細資訊，請參閱 [DynamoDB 指標](metrics-dimensions.md#dynamodb-metrics)。
**重要**
在建立或更新全域次要索引之前，您可能需要允許提列非常大的資料表。請聯絡 AWS Support 以允許列出您的資料表。
回填索引時，DynamoDB 會使用內部系統容量從資料表讀取。這是要將索引建立的影響降到最小，並確保資料表的讀取容量不會用盡。
## 刪除全域次要索引
如果您不再需要全域次要索引，可以使用 `UpdateTable` 操作將其刪除。
每個 `UpdateTable` 操作只能刪除一個全域次要索引。
刪除全域次要索引時，父資料表中所有讀取和寫入活動皆不受影響。當刪除正在進行時，仍可修改其他索引上的佈建輸送量。
**注意**
當您使用 `DeleteTable` 動作刪除資料表時，也會刪除該資料表中所有全域次要索引。
您的帳戶將不會因全域次要索引的刪除操作而被收取費用。
## 建立期間修改全域次要索引
當索引建置時，您可以使用 `DescribeTable` 操作來判斷它所處的階段。索引的描述包含布林值屬性 `Backfilling`，指出 DynamoDB 目前是否正在將資料表中的項目載入索引。如果 `Backfilling` 為 true，則資源配置階段已完成，且正在回填索引。
在回填階段，您可以刪除正在建立的索引。在這段階段，您無法新增或刪除資料表上的其他索引。
**注意**
針對已在 `CreateTable` 操作中建立的索引，`Backfilling` 屬性不會出現在 `DescribeTable` 輸出中。如需詳細資訊，請參閱[索引建立階段](#GSI.OnlineOps.Creating.Phases)。
# 偵測和修正 DynamoDB 中的索引鍵違規情況
在建立全域次要索引的回填階段，Amazon DynamoDB 會檢查資料表中的每個項目，判斷是否符合納入索引中的資格。某些項目可能不符合資格，因為這些項目會導致索引鍵違規情況。在這些情況下，項目會保留在資料表中，但索引沒有該項目的對應項目。
出現以下狀況時會發生*索引鍵違規情況*：
+ 屬性值與索引鍵結構描述資料類型之間存在資料類型不相符的問題。例如，假設其中一個項目在 `GameScores` 資料表中有一個類型為 `String` 的值 `TopScore`。如果新增分割區索引鍵為 `TopScore`、類型為 `Number` 的全域次要索引，資料表中的項目會違反索引鍵。
+ 來自資料表的屬性數值超過索引鍵屬性的最大長度。分割區索引鍵的最大長度是 2048 個位元組，而排序索引鍵的最大長度是 1024 個位元組。如果資料表中的任何對應屬性值超過這些限制，資料表中的項目將違反索引鍵。
**注意**
如果為用作索引鍵的屬性設定了「字串」或「二進制」屬性值，則屬性值的長度必須大於零；否則，資料表中的項目將違反索引鍵。
這個工具此時不會標記此索引鍵違規情況。
如果發生索引鍵違規情況，回填階段會繼續，而不會中斷。但是，索引中不會包含任何違規項目。回填階段完成後，所有違反新索引鍵結構描述的項目寫入都會遭到拒絕。
若要識別並修正資料表中違反索引鍵的屬性值，請使用 Violation Detector 工具。若要執行 Violation Detector，請建立組態檔案，指定要掃描的資料表名稱、全域次要索引分割區索引鍵及排序索引鍵的名稱和資料類型，以及發現任何索引鍵違規情況時要採取的動作。Violation Detector 可以在以下兩種不同模式之一執行：
+ **偵測模式**：偵測索引鍵違規情況。使用偵測模式報告資料表中會導致全域次要索引中發生索引鍵違規情況的項目。(您可以選擇請求在找到這些違規的資料表項目時立即將其刪除。) 偵測模式的輸出會寫入檔案，可供您用其進行進一步分析。
+ **校正模式**：校正索引鍵違規情況。在校正模式下，Violation Detector 會從偵測模式讀取與輸出檔案格式相同的輸入檔案。校正模式會從輸入檔案讀取紀錄，並且會針對每個紀錄刪除或更新資料表中的對應項目。(請注意，如果您選擇更新項目，則必須編輯輸入檔案並為這些更新設定適當的值。)
## 下載並執行 Violation Detector
Violation Detector 可以作為可執行的 Java 封存檔 (`.jar` 檔案)，並在 Windows、macOS 或 Linux 電腦上執行。Violation Detector 需要 Java 1.7 (或更新版本) 和 Apache Maven。
+ [從 GitHub 下載 Violation Detector](https://github.com/awslabs/dynamodb-online-index-violation-detector)
請遵循 `README.md` 檔案中的說明使用 Maven 下載並安裝 Violation Detector。
若要啟動 Violation Detector，請移至您已建立 `ViolationDetector.java` 的目錄，然後輸入下列命令。
```
java -jar ViolationDetector.jar [options]
```
Violation Detector 命令列接受下列選項：
+ `-h | --help`：列印 Violation Detector 的使用摘要和選項。
+ `-p | --configFilePath` `value`：Violation Detector 組態檔案的完全合格名稱。如需詳細資訊，請參閱 [Violation Detector 組態檔案](#GSI.OnlineOps.ViolationDetection.ConfigFile)。
+ `-t | --detect` `value`：偵測資料表中的索引鍵違規情況，並將其寫入 Violation Detector 輸出檔案。如果此參數的值設定為 `keep`，則不會修改具有索引鍵違規情況的項目。如果值設為 `delete`，則會從資料表中刪除具有索引鍵違規情況的項目。
+ `-c | --correct` `value`：從輸入檔案讀取索引鍵違規情況，並對資料表中的項目採取更正動作。如果此參數的值設定為 `update`，則會使用新的非違規值來更新具有索引鍵違規情況的項目。如果值設為 `delete`，則會從資料表中刪除具有索引鍵違規情況的項目。
## Violation Detector 組態檔案
在執行時期，Violation Detector 工具需要組態檔案。此檔案中的參數決定 Violation Detector 可以存取哪些 DynamoDB 資源，以及其可以消耗多少佈建的輸送量。下表描述了這些參數。
****
| 參數名稱 | Description | 是否為必要？ |
| --- | --- | --- |
| `awsCredentialsFile` | 包含您 AWS 憑證的檔案的完全合格名稱。憑證檔案必須採用下列格式： accessKey = access_key_id_goes_here
secretKey = secret_key_goes_here
| 是 |
| `dynamoDBRegion` | 資料表所在的 AWS 區域。例如：`us-west-2`。 | 是 |
| `tableName` | 所要掃描 DynamoDB 資料表的名稱。 | 是 |
| `gsiHashKeyName` | 索引分割區索引鍵的名稱。 | 是 |
| `gsiHashKeyType` | 索引分割區索引鍵的資料類型：`String`、`Number` 或 `Binary`： `S \| N \| B` | 是 |
| `gsiRangeKeyName` | 索引排序索引鍵的名稱。如果索引只有簡易的主索引鍵 (分割區索引鍵)，請勿指定此參數。 | 否 |
| `gsiRangeKeyType` | 索引排序索引鍵的資料類型：`String`、`Number` 或 `Binary`： `S \| N \| B` 如果索引只有簡易的主索引鍵 (分割區索引鍵)，請勿指定此參數。 | 否 |
| `recordDetails` | 是否將索引鍵違規情況的完整詳細資訊寫入輸出檔案。如果設定為 `true` (預設值)，則會報告違規項目的完整資訊。如果設定為 `false`，則只會報告違規情況的數量。 | 否 |
| `recordGsiValueInViolationRecord` | 是否將違反索引鍵的數值寫入輸出檔案。如果設定為 `true` (預設值)，則會報告索引鍵值。如果設定為 `false`，則不會報告索引鍵值。 | 否 |
| `detectionOutputPath` | Violation Detector 輸出檔案的完整路徑。此參數支援寫入本機目錄或 Amazon Simple Storage Service (Amazon S3)。範例如下： `detectionOutputPath = ``//local/path/filename.csv` `detectionOutputPath = ``s3://bucket/filename.csv` 輸出檔案中的資訊會以逗號分隔值 (CSV) 格式顯示。如果您未設定 `detectionOutputPath`，則輸出檔案會命名為 `violation_detection.csv` 並寫入目前的工作目錄。 | 否 |
| `numOfSegments` | 當 Violation Detector 掃描資料表時，要使用的平行掃描區段數目。預設值為 1，表示會以連續方式掃描資料表。如果數值為 2 或更高，則 Violation Detector 會將資料表分割為許多邏輯區段和相同數量的掃描執行緒。`numOfSegments` 的最高設定為 4096。對於較大的資料表，平行掃描通常比循序掃描更快。此外，如果資料表大小足以跨越多個分割區，則平行掃描會將讀取活動平均分配到多個分割區。如需在 DynamoDB 中執行平行掃描的詳細資訊，請參閱 [平行掃描](Scan.md#Scan.ParallelScan)。 | 否 |
| `numOfViolations` | 索引鍵違規情況寫入輸出檔案的上限。如果設定為 `-1` (預設值)，則會掃描整個資料表。如果設定為正整數，則 Violation Detector 會在偵測到該數量的違規情況後停止。 | 否 |
| `numOfRecords` | 要掃描的資料表中的項目數。如果設定為 -1 (預設值)，則會掃描整個資料表。如果設定為正整數，則 Violation Detector 會在掃描到資料表中該數量的項目後停止。 | 否 |
| `readWriteIOPSPercent` | 規範資料表掃描期間耗用的已佈建讀取容量單位百分比。有效值範圍從 `1` 到 `100`。預設值 (`25`) 表示 Violation Detector 將消耗不超過資料表佈建的讀取輸送量的 25%。 | 否 |
| `correctionInputPath` | Violation Detector 修正輸入檔案的完整路徑。如果您在校正模式下執行 Violation Detector，則會使用此檔案的內容來修改或刪除資料表中違反全域次要索引的資料項目。 `correctionInputPath` 檔案的格式與 `detectionOutputPath` 檔案的格式相同。這可讓您在校正模式下將偵測模式的輸出作為輸入處理。 | 否 |
| `correctionOutputPath` | Violation Detector 修正輸出檔案的完整路徑。只有在發生更新錯誤時，才會建立此檔案。 此參數支援寫入本機目錄或 Amazon S3。範例如下： `correctionOutputPath = ``//local/path/filename.csv` `correctionOutputPath = ``s3://bucket/filename.csv` 輸出檔案中的資訊會以 CSV 格式顯示。如果您未設定 `correctionOutputPath`，則輸出檔案會命名為 `violation_update_errors.csv` 並寫入目前的工作目錄。 | 否 |
## 偵測
若要偵測索引鍵違規情況，請將 Violation Detector 與 `--detect` 命令列選項搭配使用。若要顯示此選項的運作方式，請考慮 `ProductCatalog` 資料表。以下是資料表中的項目清單。僅顯示主索引鍵 (`Id`) 以及 `Price` 屬性。
****
| ID (主索引鍵) | Price |
| --- | --- |
| 101 | 5 |
| 102 | 20 |
| 103 | 200 |
| 201 | 100 |
| 202 | 200 |
| 203 | 300 |
| 204 | 400 |
| 205 | 500 |
所有 `Price` 的數值均為類型 `Number`。不過，因為 DynamoDB 不具結構描述，所以可以新增具有非數字 `Price` 的項目。例如，假設您將另一個項目新增至 `ProductCatalog` 資料表。
****
| ID (主索引鍵) | Price |
| --- | --- |
| 999 | "Hello" |
資料表現在共有九個項目。
現在，您將新的全域次要索引新增至資料表 `PriceIndex`。此索引的主索引鍵是分割區索引鍵 `Price`，其類型是 `Number`。建置索引後，將會包含八個項目，但 `ProductCatalog` 資料表含有九個項目。造成此差異的原因是數值 `"Hello"` 的類型為 `String`，但 `PriceIndex` 的主索引鍵為類型 `Number`。此 `String` 值違反全域次要索引鍵，因此不會出現在索引中。
若要在此情況中使用 Violation Detector，請先建立如下的組態檔案。
```
# Properties file for violation detection tool configuration.
# Parameters that are not specified will use default values.
awsCredentialsFile = /home/alice/credentials.txt
dynamoDBRegion = us-west-2
tableName = ProductCatalog
gsiHashKeyName = Price
gsiHashKeyType = N
recordDetails = true
recordGsiValueInViolationRecord = true
detectionOutputPath = ./gsi_violation_check.csv
correctionInputPath = ./gsi_violation_check.csv
numOfSegments = 1
readWriteIOPSPercent = 40
```
接著，您可以執行 Violation Detector，如下列範例所示。
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --detect keep
Violation detection started: sequential scan, Table name: ProductCatalog, GSI name: PriceIndex
Progress: Items scanned in total: 9, Items scanned by this thread: 9, Violations found by this thread: 1, Violations deleted by this thread: 0
Violation detection finished: Records scanned: 9, Violations found: 1, Violations deleted: 0, see results at: ./gsi_violation_check.csv
```
如果 `recordDetails` 組態參數設為 `true`，Violation Detector 會將每個違規情況的詳細資訊寫入輸出檔案，如下列範例所示。
```
Table Hash Key,GSI Hash Key Value,GSI Hash Key Violation Type,GSI Hash Key Violation Description,GSI Hash Key Update Value(FOR USER),Delete Blank Attributes When Updating?(Y/N)
999,"{""S"":""Hello""}",Type Violation,Expected: N Found: S,,
```
輸出檔案採用 CSV 格式。檔案中的第一行是標頭，後接每個違反索引鍵的項目的一筆紀錄。這些違規情況紀錄的欄位如下所示：
+ **資料表雜湊索引鍵** - 資料表中項目的分割區索引鍵值。
+ **資料表範圍索引鍵** - 資料表中項目的排序索引鍵值。
+ **GSI 雜湊索引鍵值** - 全域次要索引的分割區索引鍵值。
+ **GSI 雜湊索引鍵違規情況類型** - `Type Violation` 或 `Size Violation`。
+ **GSI 雜湊索引鍵違規情況說明** - 違反的原因。
+ **GSI 雜湊索引鍵更新值 (針對使用者)** - 在校正模式下，屬性的新使用者提供的數值。
+ **GSI 範圍索引鍵值** - 全域次要索引的排序索引鍵值。
+ **GSI 範圍索引鍵違規情況類型** - `Type Violation` 或 `Size Violation`。
+ **GSI 範圍索引鍵違規情況說明** - 違反的原因。
+ **GSI 範圍索引鍵更新值 (針對使用者)** - 在校正模式下，屬性的新使用者提供的數值。
+ **更新時刪除空白屬性 (是/否)** - 在校正模式下，決定要刪除 (是) 或保留 (否) 資料表中的違規情況，但只有在下列其中一個欄位為空白時：
+ `GSI Hash Key Update Value(FOR USER)`
+ `GSI Range Key Update Value(FOR USER)`
如果這些欄位中的任何一個並非空白，則 `Delete Blank Attribute When Updating(Y/N)` 不起作用。
**注意**
輸出格式可能會因組態檔案和命令列選項而有所不同。例如，如果資料表有簡單的主索引鍵 (沒有排序索引鍵)，則輸出中不會出現任何排序索引鍵欄位。
檔案中的違規情況紀錄可能不會以排序順序顯示。
## 更正
若要校正索引鍵違規情況，請將 Violation Detector 與 `--correct` 命令列選項搭配使用。在校正模式下，Violation Detector 會讀取 `correctionInputPath` 參數指定的輸入檔案。此檔案具有與 `detectionOutputPath` 檔案相同的格式，以便您可以使用來自偵測的輸出作為校正的輸入。
Violation Detector 提供兩種不同的方法來校正索引鍵違規情況：
+ **刪除違規情況**：刪除具有違反屬性值的資料表項目。
+ **更新違規情況**：更新資料表項目，以非違規值取代違規屬性。
在任何一種情況下，您都可以使用偵測模式的輸出檔案作為校正模式的輸入。
繼續進行 `ProductCatalog` 範例，假設您想要從資料表刪除違規情況。若要執行此操作，請使用以下命令列。
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --correct delete
```
此時，系統會要求您確認是否要刪除違規項目。
```
Are you sure to delete all violations on the table?y/n
y
Confirmed, will delete violations on the table...
Violation correction from file started: Reading records from file: ./gsi_violation_check.csv, will delete these records from table.
Violation correction from file finished: Violations delete: 1, Violations Update: 0
```
現在 `ProductCatalog` 和 `PriceIndex` 都具有相同數量的項目。
# 使用全域次要索引：Java
您可以使用 適用於 Java 的 AWS SDK 文件 API 建立具有一或多個全域次要索引的 Amazon DynamoDB 資料表、描述資料表上的索引，並使用索引執行查詢。
下列是資料表操作的常用步驟。
1. 建立 `DynamoDB` 類別的執行個體。
1. 透過建立對應的請求物件，為操作提供必要及選用的參數。
1. 呼叫您在前一步驟中建立之用戶端所提供的適當方法。
**Topics**
+ [建立具有全域次要索引的資料表](#GSIJavaDocumentAPI.CreateTableWithIndex)
+ [使用全域次要索引描述資料表](#GSIJavaDocumentAPI.DescribeTableWithIndex)
+ [查詢全域次要索引](#GSIJavaDocumentAPI.QueryAnIndex)
+ [範例：使用 適用於 Java 的 AWS SDK 文件 API 的全域次要索引](GSIJavaDocumentAPI.Example.md)
## 建立具有全域次要索引的資料表
您可在建立資料表的同時建立全域次要索引。若要執行這項操作，請使用 `CreateTable`，並提供一或多個全域次要索引的規格。以下 Java 程式碼範例會建立資料表來保存天氣資料的相關資訊。分割區索引鍵為 `Location`，而排序索引鍵為 `Date`。名為 `PrecipIndex` 的全域次要索引允許快速存取各個地點的降水資料。
以下是使用 DynamoDB Document API 建立具有全域次要索引的資料表的步驟。
1. 建立 `DynamoDB` 類別的執行個體。
1. 建立 `CreateTableRequest` 類別的執行個體，以提供請求資訊。
您必須提供資料表名稱、其主索引鍵，以及佈建的輸送量數值。對於全域次要索引，您必須提供索引名稱、其佈建的輸送量設定值、索引排序索引鍵的屬性定義、索引的索引鍵結構描述以及屬性投影。
1. 以參數形式提供請求物件，以便呼叫 `createTable` 方法。
下列 Java 程式碼範例示範上述步驟。程式碼會建立具有全域次要索引 (`PrecipIndex`) 的資料表 (`WeatherData`)。索引分割區索引鍵是 `Date`，而其排序索引鍵是 `Precipitation`。所有的資料表屬性都會投影到索引。使用者可以查詢此索引以取得特定日期的天氣資料，可選擇依降水量排序資料。
因為 `Precipitation` 不是資料表的索引鍵屬性，所以其並非必要項目。不過，沒有 `Precipitation` 的 `WeatherData` 項目不會在 `PrecipIndex` 中顯示。
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Location")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Date")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Precipitation")
.withAttributeType("N"));
// Table key schema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Location")
.withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.RANGE)); //Sort key
// PrecipIndex
GlobalSecondaryIndex precipIndex = new GlobalSecondaryIndex()
.withIndexName("PrecipIndex")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 10)
.withWriteCapacityUnits((long) 1))
.withProjection(new Projection().withProjectionType(ProjectionType.ALL));
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Precipitation")
.withKeyType(KeyType.RANGE)); //Sort key
precipIndex.setKeySchema(indexKeySchema);
CreateTableRequest createTableRequest = new CreateTableRequest()
.withTableName("WeatherData")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 5)
.withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions)
.withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(precipIndex);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
您必須等到 DynamoDB 建立資料表，並將資料表狀態設定為 `ACTIVE`。之後，您可以開始將資料項目放入資料表中。
## 使用全域次要索引描述資料表
若要取得資料表上全域次要索引的資訊，請使用 `DescribeTable`。對於每個索引，您可以存取其名稱、索引鍵結構描述和投影屬性。
以下是存取資料表的全域次要索引資訊的步驟。
1. 建立 `DynamoDB` 類別的執行個體。
1. 建立 `Table` 類別的執行個體，代表您要進行作業的索引。
1. 在 `Table` 物件上呼叫 `describe` 方法。
下列 Java 程式碼範例示範上述步驟。
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
TableDescription tableDesc = table.describe();
Iterator gsiIter = tableDesc.getGlobalSecondaryIndexes().iterator();
while (gsiIter.hasNext()) {
GlobalSecondaryIndexDescription gsiDesc = gsiIter.next();
System.out.println("Info for index "
+ gsiDesc.getIndexName() + ":");
Iterator kseIter = gsiDesc.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = gsiDesc.getProjection();
System.out.println("\tThe projection type is: "
+ projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: "
+ projection.getNonKeyAttributes());
}
}
```
## 查詢全域次要索引
您可以在全域次要索引上使用 `Query`，與 `Query` 資料表的方式相同。您需要指定索引名稱、索引分割區索引鍵和排序索引鍵的查詢條件 (如存在)，以及要傳回的屬性。在本例中，索引為 `PrecipIndex`，其分割區索引鍵為 `Date`，排序索引鍵為 `Precipitation`。索引查詢會傳回特定日期的所有天氣資料，其中降水量大於零。
以下是使用 適用於 Java 的 AWS SDK 文件 API 查詢全域次要索引的步驟。
1. 建立 `DynamoDB` 類別的執行個體。
1. 建立 `Table` 類別的執行個體，代表您要進行作業的索引。
1. 針對您想要查詢的索引建立 `Index` 類別的執行個體。
1. 在 `Index` 物件上呼叫 `query` 方法。
屬性名稱 `Date` 是 DynamoDB 保留字。因此，您必須使用表達式屬性名稱作為 `KeyConditionExpression` 中的預留位置。
下列 Java 程式碼範例示範上述步驟。
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
Index index = table.getIndex("PrecipIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("#d = :v_date and Precipitation = :v_precip")
.withNameMap(new NameMap()
.with("#d", "Date"))
.withValueMap(new ValueMap()
.withString(":v_date","2013-08-10")
.withNumber(":v_precip",0));
ItemCollection items = index.query(spec);
Iterator- iter = items.iterator();
while (iter.hasNext()) {
System.out.println(iter.next().toJSONPretty());
}
```
# 範例：使用 適用於 Java 的 AWS SDK 文件 API 的全域次要索引
下列 Java 程式碼範例示範如何使用全域次要索引。此範例會建立名為 `Issues` 的資料表，可用於軟體開發的簡單錯誤追蹤系統。分割區索引鍵為 `IssueId`，而排序索引鍵為 `Title`。此資料表上有三個全域次要索引：
+ `CreateDateIndex`：分割區索引鍵為 `CreateDate`，而排序索引鍵為 `IssueId`。除了資料表索引鍵之外，屬性 `Description` 和 `Status` 都會投影到索引中。
+ `TitleIndex`：分割區索引鍵為 `Title`，而排序索引鍵為 `IssueId`。除了資料表索引鍵之外，其他屬性均不會投影到索引中。
+ `DueDateIndex`：分割區索引鍵為 `DueDate`，沒有排序索引鍵。所有的資料表屬性都會投影到索引。
建立 `Issues` 資料表後，程式會載入所含資料表示軟體錯誤報告的資料表。然後，便會使用全域次要索引查詢資料。最後，程式會刪除 `Issues` 資料表。
如需測試下列範例的逐步說明，請參閱 [Java 程式碼範例](CodeSamples.Java.md)。
**Example**
```
package com.amazonaws.codesamples.document;
import java.util.ArrayList;
import java.util.Iterator;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.document.DynamoDB;
import com.amazonaws.services.dynamodbv2.document.Index;
import com.amazonaws.services.dynamodbv2.document.Item;
import com.amazonaws.services.dynamodbv2.document.ItemCollection;
import com.amazonaws.services.dynamodbv2.document.QueryOutcome;
import com.amazonaws.services.dynamodbv2.document.Table;
import com.amazonaws.services.dynamodbv2.document.spec.QuerySpec;
import com.amazonaws.services.dynamodbv2.document.utils.ValueMap;
import com.amazonaws.services.dynamodbv2.model.AttributeDefinition;
import com.amazonaws.services.dynamodbv2.model.CreateTableRequest;
import com.amazonaws.services.dynamodbv2.model.GlobalSecondaryIndex;
import com.amazonaws.services.dynamodbv2.model.KeySchemaElement;
import com.amazonaws.services.dynamodbv2.model.KeyType;
import com.amazonaws.services.dynamodbv2.model.Projection;
import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput;
public class DocumentAPIGlobalSecondaryIndexExample {
static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
static DynamoDB dynamoDB = new DynamoDB(client);
public static String tableName = "Issues";
public static void main(String[] args) throws Exception {
createTable();
loadData();
queryIndex("CreateDateIndex");
queryIndex("TitleIndex");
queryIndex("DueDateIndex");
deleteTable(tableName);
}
public static void createTable() {
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("IssueId").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Title").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("CreateDate").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("DueDate").withAttributeType("S"));
// Key schema for table
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.HASH)); // Partition
// key
tableKeySchema.add(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.RANGE)); // Sort
// key
// Initial provisioned throughput settings for the indexes
ProvisionedThroughput ptIndex = new ProvisionedThroughput().withReadCapacityUnits(1L)
.withWriteCapacityUnits(1L);
// CreateDateIndex
GlobalSecondaryIndex createDateIndex = new GlobalSecondaryIndex().withIndexName("CreateDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("CreateDate").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(
new Projection().withProjectionType("INCLUDE").withNonKeyAttributes("Description", "Status"));
// TitleIndex
GlobalSecondaryIndex titleIndex = new GlobalSecondaryIndex().withIndexName("TitleIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(new Projection().withProjectionType("KEYS_ONLY"));
// DueDateIndex
GlobalSecondaryIndex dueDateIndex = new GlobalSecondaryIndex().withIndexName("DueDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("DueDate").withKeyType(KeyType.HASH)) // Partition
// key
.withProjection(new Projection().withProjectionType("ALL"));
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName)
.withProvisionedThroughput(
new ProvisionedThroughput().withReadCapacityUnits((long) 1).withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions).withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(createDateIndex, titleIndex, dueDateIndex);
System.out.println("Creating table " + tableName + "...");
dynamoDB.createTable(createTableRequest);
// Wait for table to become active
System.out.println("Waiting for " + tableName + " to become ACTIVE...");
try {
Table table = dynamoDB.getTable(tableName);
table.waitForActive();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void queryIndex(String indexName) {
Table table = dynamoDB.getTable(tableName);
System.out.println("\n***********************************************************\n");
System.out.print("Querying index " + indexName + "...");
Index index = table.getIndex(indexName);
ItemCollection items = null;
QuerySpec querySpec = new QuerySpec();
if (indexName == "CreateDateIndex") {
System.out.println("Issues filed on 2013-11-01");
querySpec.withKeyConditionExpression("CreateDate = :v_date and begins_with(IssueId, :v_issue)")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-01").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "TitleIndex") {
System.out.println("Compilation errors");
querySpec.withKeyConditionExpression("Title = :v_title and begins_with(IssueId, :v_issue)")
.withValueMap(
new ValueMap().withString(":v_title", "Compilation error").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "DueDateIndex") {
System.out.println("Items that are due on 2013-11-30");
querySpec.withKeyConditionExpression("DueDate = :v_date")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-30"));
items = index.query(querySpec);
} else {
System.out.println("\nNo valid index name provided");
return;
}
Iterator
- iterator = items.iterator();
System.out.println("Query: printing results...");
while (iterator.hasNext()) {
System.out.println(iterator.next().toJSONPretty());
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
Table table = dynamoDB.getTable(tableName);
table.delete();
// Wait for table to be deleted
System.out.println("Waiting for " + tableName + " to be deleted...");
try {
table.waitForDelete();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error", "Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10", 1, "Assigned");
putItem("A-102", "Can't read data file", "The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30", 2, "In progress");
putItem("A-103", "Test failure", "Functional test of Project X produces errors", "2013-11-01", "2013-11-02",
"2013-11-10", 1, "In progress");
putItem("A-104", "Compilation error", "Variable 'messageCount' was not initialized.", "2013-11-15",
"2013-11-16", "2013-11-30", 3, "Assigned");
putItem("A-105", "Network issue", "Can't ping IP address 127.0.0.1. Please fix this.", "2013-11-15",
"2013-11-16", "2013-11-19", 5, "Assigned");
}
public static void putItem(
String issueId, String title, String description, String createDate, String lastUpdateDate, String dueDate,
Integer priority, String status) {
Table table = dynamoDB.getTable(tableName);
Item item = new Item().withPrimaryKey("IssueId", issueId).withString("Title", title)
.withString("Description", description).withString("CreateDate", createDate)
.withString("LastUpdateDate", lastUpdateDate).withString("DueDate", dueDate)
.withNumber("Priority", priority).withString("Status", status);
table.putItem(item);
}
}
```
# 使用全域次要索引：.NET
您可以使用 適用於 .NET 的 AWS SDK 低階 API 來建立具有一或多個全域次要索引的 Amazon DynamoDB 資料表、描述資料表上的索引，以及使用索引執行查詢。這些操作會映射至對應的 DynamoDB 操作。如需詳細資訊，請參閱《[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)》。
下列是使用 .NET 低階 API 執行資料表操作的一般步驟。
1. 建立 `AmazonDynamoDBClient` 類別的執行個體。
1. 透過建立對應的請求物件，為操作提供必要及選用的參數。
例如，建立 `CreateTableRequest` 物件來建立資料表，以及建立 `QueryRequest` 物件來查詢資料表或索引。
1. 執行您在前一步驟中建立之用戶端所提供的適當方法。
**Topics**
+ [建立具有全域次要索引的資料表](#GSILowLevelDotNet.CreateTableWithIndex)
+ [使用全域次要索引描述資料表](#GSILowLevelDotNet.DescribeTableWithIndex)
+ [查詢全域次要索引](#GSILowLevelDotNet.QueryAnIndex)
+ [範例：使用 適用於 .NET 的 AWS SDK 低階 API 的全域次要索引](GSILowLevelDotNet.Example.md)
## 建立具有全域次要索引的資料表
您可在建立資料表的同時建立全域次要索引。若要執行這項操作，請使用 `CreateTable`，並提供一或多個全域次要索引的規格。以下 C\$1 程式碼範例會建立資料表來保存天氣資料的相關資訊。分割區索引鍵為 `Location`，而排序索引鍵為 `Date`。名為 `PrecipIndex` 的全域次要索引允許快速存取各個地點的降水資料。
以下是使用 .NET 低階 API 建立具有全域次要索引之資料表的步驟。
1. 建立 `AmazonDynamoDBClient` 類別的執行個體。
1. 建立 `CreateTableRequest` 類別的執行個體，以提供請求資訊。
您必須提供資料表名稱、其主索引鍵，以及佈建的輸送量數值。對於全域次要索引，您必須提供索引名稱、其佈建的輸送量設定值、索引排序索引鍵的屬性定義、索引的索引鍵結構描述以及屬性投影。
1. 以參數形式提供請求物件，以便執行 `CreateTable` 方法。
下列 C\$1 程式碼範例示範前述步驟。程式碼會建立具有全域次要索引 (`PrecipIndex`) 的資料表 (`WeatherData`)。索引分割區索引鍵是 `Date`，而其排序索引鍵是 `Precipitation`。所有的資料表屬性都會投影到索引。使用者可以查詢此索引以取得特定日期的天氣資料，可選擇依降水量排序資料。
因為 `Precipitation` 不是資料表的索引鍵屬性，所以其並非必要項目。不過，沒有 `Precipitation` 的 `WeatherData` 項目不會在 `PrecipIndex` 中顯示。
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition{
AttributeName = "Location",
AttributeType = "S"}},
{new AttributeDefinition{
AttributeName = "Date",
AttributeType = "S"}},
{new AttributeDefinition(){
AttributeName = "Precipitation",
AttributeType = "N"}
}
};
// Table key schema
var tableKeySchema = new List()
{
{new KeySchemaElement {
AttributeName = "Location",
KeyType = "HASH"}}, //Partition key
{new KeySchemaElement {
AttributeName = "Date",
KeyType = "RANGE"} //Sort key
}
};
// PrecipIndex
var precipIndex = new GlobalSecondaryIndex
{
IndexName = "PrecipIndex",
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)10,
WriteCapacityUnits = (long)1
},
Projection = new Projection { ProjectionType = "ALL" }
};
var indexKeySchema = new List {
{new KeySchemaElement { AttributeName = "Date", KeyType = "HASH"}}, //Partition key
{new KeySchemaElement{AttributeName = "Precipitation",KeyType = "RANGE"}} //Sort key
};
precipIndex.KeySchema = indexKeySchema;
CreateTableRequest createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = { precipIndex }
};
CreateTableResponse response = client.CreateTable(createTableRequest);
Console.WriteLine(response.CreateTableResult.TableDescription.TableName);
Console.WriteLine(response.CreateTableResult.TableDescription.TableStatus);
```
您必須等到 DynamoDB 建立資料表，並將資料表狀態設定為 `ACTIVE`。之後，您可以開始將資料項目放入資料表中。
## 使用全域次要索引描述資料表
若要取得資料表上全域次要索引的資訊，請使用 `DescribeTable`。對於每個索引，您可以存取其名稱、索引鍵結構描述和投影屬性。
以下是使用 .NET 低階 API 存取資料表的全域次要索引資訊的步驟。
1. 建立 `AmazonDynamoDBClient` 類別的執行個體。
1. 以參數形式提供請求物件，以便執行 `describeTable` 方法。
建立 `DescribeTableRequest` 類別的執行個體，以提供請求資訊。您必須提供資料表名稱。
下列 C\$1 程式碼範例示範前述步驟。
**Example**
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest { TableName = tableName});
List globalSecondaryIndexes =
response.DescribeTableResult.Table.GlobalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (GlobalSecondaryIndexDescription gsiDescription in globalSecondaryIndexes) {
Console.WriteLine("Info for index " + gsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in gsiDescription.KeySchema) {
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = gsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE")) {
Console.WriteLine("\t\tThe non-key projected attributes are: "
+ projection.NonKeyAttributes);
}
}
```
## 查詢全域次要索引
您可以在全域次要索引上使用 `Query`，與 `Query` 資料表的方式相同。您需要指定索引名稱、索引分割區索引鍵和排序索引鍵的查詢條件 (如存在)，以及要傳回的屬性。在本例中，索引為 `PrecipIndex`，其分割區索引鍵為 `Date`，排序索引鍵為 `Precipitation`。索引查詢會傳回特定日期的所有天氣資料，其中降水量大於零。
以下是使用 .NET 低階 API 查詢全域次要索引的步驟。
1. 建立 `AmazonDynamoDBClient` 類別的執行個體。
1. 建立 `QueryRequest` 類別的執行個體，以提供請求資訊。
1. 以參數形式提供請求物件，以便執行 `query` 方法。
屬性名稱 `Date` 是 DynamoDB 保留字。因此，您必須使用表達式屬性名稱作為 `KeyConditionExpression` 中的預留位置。
下列 C\$1 程式碼範例示範前述步驟。
**Example**
```
client = new AmazonDynamoDBClient();
QueryRequest queryRequest = new QueryRequest
{
TableName = "WeatherData",
IndexName = "PrecipIndex",
KeyConditionExpression = "#dt = :v_date and Precipitation > :v_precip",
ExpressionAttributeNames = new Dictionary {
{"#dt", "Date"}
},
ExpressionAttributeValues = new Dictionary {
{":v_date", new AttributeValue { S = "2013-08-01" }},
{":v_precip", new AttributeValue { N = "0" }}
},
ScanIndexForward = true
};
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
Console.Write(attr + "---> ");
if (attr == "Precipitation")
{
Console.WriteLine(currentItem[attr].N);
}
else
{
Console.WriteLine(currentItem[attr].S);
}
}
Console.WriteLine();
}
```
# 範例：使用 適用於 .NET 的 AWS SDK 低階 API 的全域次要索引
下列 C\$1 程式碼範例示範如何使用全域次要索引。此範例會建立名為 `Issues` 的資料表，可用於軟體開發的簡單錯誤追蹤系統。分割區索引鍵為 `IssueId`，而排序索引鍵為 `Title`。此資料表上有三個全域次要索引：
+ `CreateDateIndex`：分割區索引鍵為 `CreateDate`，而排序索引鍵為 `IssueId`。除了資料表索引鍵之外，屬性 `Description` 和 `Status` 都會投影到索引中。
+ `TitleIndex`：分割區索引鍵為 `Title`，而排序索引鍵為 `IssueId`。除了資料表索引鍵之外，其他屬性均不會投影到索引中。
+ `DueDateIndex`：分割區索引鍵為 `DueDate`，沒有排序索引鍵。所有的資料表屬性都會投影到索引。
建立 `Issues` 資料表後，程式會載入所含資料表示軟體錯誤報告的資料表。然後，便會使用全域次要索引查詢資料。最後，程式會刪除 `Issues` 資料表。
如需測試下列範例的逐步說明，請參閱 [.NET 程式碼範例](CodeSamples.DotNet.md)。
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelGlobalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
public static String tableName = "Issues";
public static void Main(string[] args)
{
CreateTable();
LoadData();
QueryIndex("CreateDateIndex");
QueryIndex("TitleIndex");
QueryIndex("DueDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press enter");
Console.Read();
}
private static void CreateTable()
{
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition {
AttributeName = "IssueId", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "Title", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "CreateDate", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "DueDate", AttributeType = "S"
}}
};
// Key schema for table
var tableKeySchema = new List() {
{
new KeySchemaElement {
AttributeName= "IssueId",
KeyType = "HASH" //Partition key
}
},
{
new KeySchemaElement {
AttributeName = "Title",
KeyType = "RANGE" //Sort key
}
}
};
// Initial provisioned throughput settings for the indexes
var ptIndex = new ProvisionedThroughput
{
ReadCapacityUnits = 1L,
WriteCapacityUnits = 1L
};
// CreateDateIndex
var createDateIndex = new GlobalSecondaryIndex()
{
IndexName = "CreateDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "CreateDate", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "INCLUDE",
NonKeyAttributes = {
"Description", "Status"
}
}
};
// TitleIndex
var titleIndex = new GlobalSecondaryIndex()
{
IndexName = "TitleIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "Title", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "KEYS_ONLY"
}
};
// DueDateIndex
var dueDateIndex = new GlobalSecondaryIndex()
{
IndexName = "DueDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "DueDate",
KeyType = "HASH" //Partition key
}
},
Projection = new Projection
{
ProjectionType = "ALL"
}
};
var createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = {
createDateIndex, titleIndex, dueDateIndex
}
};
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
private static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error",
"Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "Assigned");
putItem("A-102", "Can't read data file",
"The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30",
2, "In progress");
putItem("A-103", "Test failure",
"Functional test of Project X produces errors",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "In progress");
putItem("A-104", "Compilation error",
"Variable 'messageCount' was not initialized.",
"2013-11-15", "2013-11-16", "2013-11-30",
3, "Assigned");
putItem("A-105", "Network issue",
"Can't ping IP address 127.0.0.1. Please fix this.",
"2013-11-15", "2013-11-16", "2013-11-19",
5, "Assigned");
}
private static void putItem(
String issueId, String title,
String description,
String createDate, String lastUpdateDate, String dueDate,
Int32 priority, String status)
{
Dictionary item = new Dictionary();
item.Add("IssueId", new AttributeValue
{
S = issueId
});
item.Add("Title", new AttributeValue
{
S = title
});
item.Add("Description", new AttributeValue
{
S = description
});
item.Add("CreateDate", new AttributeValue
{
S = createDate
});
item.Add("LastUpdateDate", new AttributeValue
{
S = lastUpdateDate
});
item.Add("DueDate", new AttributeValue
{
S = dueDate
});
item.Add("Priority", new AttributeValue
{
N = priority.ToString()
});
item.Add("Status", new AttributeValue
{
S = status
});
try
{
client.PutItem(new PutItemRequest
{
TableName = tableName,
Item = item
});
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
}
private static void QueryIndex(string indexName)
{
Console.WriteLine
("\n***********************************************************\n");
Console.WriteLine("Querying index " + indexName + "...");
QueryRequest queryRequest = new QueryRequest
{
TableName = tableName,
IndexName = indexName,
ScanIndexForward = true
};
String keyConditionExpression;
Dictionary expressionAttributeValues = new Dictionary();
if (indexName == "CreateDateIndex")
{
Console.WriteLine("Issues filed on 2013-11-01\n");
keyConditionExpression = "CreateDate = :v_date and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-01"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
}
else if (indexName == "TitleIndex")
{
Console.WriteLine("Compilation errors\n");
keyConditionExpression = "Title = :v_title and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_title", new AttributeValue
{
S = "Compilation error"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else if (indexName == "DueDateIndex")
{
Console.WriteLine("Items that are due on 2013-11-30\n");
keyConditionExpression = "DueDate = :v_date";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-30"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo valid index name provided");
return;
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "Priority")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# 在 DynamoDB 中搭配使用 AWS CLI 與全域次要索引
您可以使用 AWS CLI 建立含有一或多個全域次要索引的 Amazon DynamoDB 資料表、描述資料表上的索引，以及使用索引執行查詢。
**Topics**
+ [建立具有全域次要索引的資料表](#GCICli.CreateTableWithIndex)
+ [將全域次要索引新增至現有資料表](#GCICli.CreateIndexAfterTable)
+ [使用全域次要索引描述資料表](#GCICli.DescribeTableWithIndex)
+ [查詢全域次要索引](#GCICli.QueryAnIndex)
## 建立具有全域次要索引的資料表
您可在建立資料表的同時建立全域次要索引。若要執行這項操作，請使用 `create-table` 參數，並提供一或多個全域次要索引的規格。以下範例會建立名為 `GameScores` 的資料表，以及名為 `GameTitleIndex` 的全域次要索引。基礎資料表具有分割區索引鍵 `UserId` 和排序索引鍵 `GameTitle`，可讓您有效率地找到個別使用者在特定遊戲中的最佳分數，而 GSI 具有分割區索引鍵 `GameTitle` 和排序索引鍵 `TopScore`，可讓您快速找到特定遊戲的整體最高分數。
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S \
AttributeName=GameTitle,AttributeType=S \
AttributeName=TopScore,AttributeType=N \
--key-schema AttributeName=UserId,KeyType=HASH \
AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--global-secondary-indexes \
"[
{
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
},
\"ProvisionedThroughput\": {
\"ReadCapacityUnits\": 10,
\"WriteCapacityUnits\": 5
}
}
]"
```
您必須等到 DynamoDB 建立資料表，並將資料表狀態設定為 `ACTIVE`。之後，您可以開始將資料項目放入資料表中。您可以使用 [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) 來判斷資料表建立的狀態。
## 將全域次要索引新增至現有資料表
全域次要索引也可以在建立資料表之後新增或修改。若要執行這項操作，請使用 `update-table` 參數，並提供一或多個全域次要索引的規格。下列範例使用與上一個範例相同的結構描述，但假設資料表已經建立，我們稍後會新增 GSI。
```
aws dynamodb update-table \
--table-name GameScores \
--attribute-definitions AttributeName=TopScore,AttributeType=N \
--global-secondary-index-updates \
"[
{
\"Create\": {
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
}
}
}
]"
```
## 使用全域次要索引描述資料表
若要取得資料表上全域次要索引的資訊，請使用 `describe-table` 參數。對於每個索引，您可以存取其名稱、索引鍵結構描述和投影屬性。
```
aws dynamodb describe-table --table-name GameScores
```
## 查詢全域次要索引
您可以依照與 `query` 資料表大致相同的方式在全域次要索引上使用 `query` 操作。您必須指定索引名稱、索引排序索引鍵的查詢準則，以及您要傳回的屬性。在本例中，索引是 `GameTitleIndex`，而索引排序索引鍵為 `GameTitle`。
傳回的唯一屬性是已投影到索引的屬性。您也可以修改此查詢來選擇非索引鍵屬性，但這需要相對昂貴的資料表擷取活動。如需資料表擷取的詳細資訊，請參閱 [屬性投影](GSI.md#GSI.Projections)。
```
aws dynamodb query --table-name GameScores\
--index-name GameTitleIndex \
--key-condition-expression "GameTitle = :v_game" \
--expression-attribute-values '{":v_game":{"S":"Alien Adventure"} }'
```
# 本機次要索引
某些應用程式只需要使用基礎資料表的主索引鍵查詢資料。但是，在某些情況下，替代排序索引鍵會有所幫助。為了給應用程式提供排序索引鍵選擇，您可以在 Amazon DynamoDB 資料表上建立一或多個本機次要索引，並針對這些索引發出 `Query` 或 `Scan` 請求。
**Topics**
+ [案例：使用本機次要索引](#LSI.Scenario)
+ [屬性投影](#LSI.Projections)
+ [建立本機次要索引](#LSI.Creating)
+ [從本機次要索引讀取資料](#LSI.Reading)
+ [項目寫入和本機次要索引](#LSI.Writes)
+ [本機次要索引的佈建輸送量考量](#LSI.ThroughputConsiderations)
+ [本機次要索引的儲存考量](#LSI.StorageConsiderations)
+ [本機次要索引中的項目集合](#LSI.ItemCollections)
+ [使用本機次要索引：Java](LSIJavaDocumentAPI.md)
+ [使用本機次要索引：.NET](LSILowLevelDotNet.md)
+ [在 DynamoDB AWS CLI 中使用本機次要索引](LCICli.md)
## 案例：使用本機次要索引
例如，請考慮 `Thread` 資料表。此資料表適用於應用程式，例如 [AWS 開發論壇](https://forums.aws.amazon.com/)。下圖顯示這些項目在資料表中的組織方式。(並未顯示所有屬性。)
![\[主題資料表包含論壇名稱、話題、上次貼文時間和回覆次數的清單。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/LSI_01.png)
DynamoDB 會連續儲存具有相同分割區索引鍵值的所有項目。在本例中，給定一個特定的 `ForumName`，`Query` 操作就可以立即找到該論壇的所有主題。在具有相同分割區索引鍵值的項目群組中，項目會依排序索引鍵值排序。如果查詢中還提供了排序索引鍵 (`Subject`)，DynamoDB 可以縮小傳回的結果範圍，例如傳回「S3」論壇中以字母「a」開頭的 `Subject` 的所有主題。
某些請求可能需要更複雜的資料存取模式。例如：
+ 哪些論壇主題獲得最多的觀看次數和回覆？
+ 特定論壇中哪個主題的訊息數量最多？
+ 在特定時段內，有多少個主題發布在特定論壇？
若要回答這些問題，`Query` 動作並不足夠。您還必須 `Scan` 整個資料表。對於包含數百萬個項目的資料表，這會消耗大量佈建的讀取輸送量，而且需要很長的時間才能完成。
不過，您可以在非索引鍵屬性上指定一或多個本機次要索引，例如 `Replies` 或 `LastPostDateTime`。
*本機次要索引*會針對指定分割區索引鍵值維護替代排序索引鍵。本機次要索引也包含基礎資料表中部分或全部屬性的複本。您可以指定在建立資料表時要投影到本機次要索引中的屬性。本機次要索引中的資料由與基礎資料表相同的分割區索引鍵組織，但具有不同的排序索引鍵。這可讓您在此不同維度之間有效地存取資料項目。為獲得更大的查詢或掃描靈活性，您最多可以為每個資料表建立五個本機次要索引。
假設應用程式需要尋找在最近三個月內張貼於特定論壇中的所有主題。如果沒有本機次要索引，應用程式必須 `Scan` 整個 `Thread` 資料表，並捨棄任何不在指定時間範圍內的貼文。使用本機次要索引，`Query` 操作可以使用 `LastPostDateTime` 作為排序索引鍵，並快速找到資料。
下圖顯示名為 `LastPostIndex` 的本機次要索引。請注意，分割區索引鍵與 `Thread` 資料表的分割區索引鍵相同，但排序索引鍵是 `LastPostDateTime`。
![\[包含論壇名稱、主題和上次貼文時間的 LastPostIndex 資料表。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/LSI_02.png)
每個本機次要索引均須符合下列條件：
+ 分割區索引鍵與其基礎資料表的分割區索引鍵相同。
+ 排序索引鍵只包含一個純量屬性。
+ 基礎資料表的排序索引鍵會投影到索引中，在索引中充當非索引鍵屬性。
在本例中，分割區索引鍵是 `ForumName`，而本機次要索引的排序索引鍵是 `LastPostDateTime`。此外，基礎資料表中的排序索引鍵值 (在本例中為 `Subject`) 會投影到索引中，但不是索引鍵的一部分。如果應用程式需要以 `ForumName` 和 `LastPostDateTime` 為基礎的清單，則可針對 `LastPostIndex` 發出 `Query` 請求。查詢結果會依 `LastPostDateTime` 排序，並且可以依升序或降序排列傳回。查詢也可以套用索引鍵條件，例如僅傳回在特定的時間範圍內具有 `LastPostDateTime` 的項目。
每個本機次要索引會自動包含來自其基礎資料表的分割區索引鍵和排序索引鍵；您可以選擇將非索引鍵屬性投影到索引中。當您查詢索引時，DynamoDB 可有效率地擷取這些投影屬性。在查詢本機次要索引時，查詢還可以檢索*未*投影到索引中的屬性。DynamoDB 會自動從基礎資料表擷取這些屬性，但延遲較大，且佈建的輸送量成本也較高。
對於任何本機次要索引，每個不同的分割區索引鍵值最多可存放 10 GB 的資料。此圖包含基礎資料表中的所有項目，以及索引中具有相同分割區索引鍵值的所有項目。如需詳細資訊，請參閱 [本機次要索引中的項目集合](#LSI.ItemCollections)。
## 屬性投影
應用程式可以借助 `LastPostIndex` 將 `ForumName` 和 `LastPostDateTime` 用作查詢條件。不過，若要擷取任何其他屬性，DynamoDB 必須對 `Thread` 資料表執行額外的讀取操作。這些額外讀取稱為*擷取*，可以增加查詢所需的佈建輸送量總量。
假設您想要填入一個網頁，其中包含「S3」中所有主題的清單，以及每個主題的回覆次數 (依上次回覆日期/時間，從最近回覆開始排序)。若要填入此清單，您需要下列屬性：
+ `Subject`
+ `Replies`
+ `LastPostDateTime`
查詢這些資料並避免擷取操作的最有效方法是將 `Replies` 屬性從資料表投影至本機次要索引，如此圖所示。
![\[包含論壇名稱、上次貼文時間、主題和回覆的清單的 LastPostIndex 資料表。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/LSI_03.png)
*投影*是指從資料表複製到次要索引的屬性集合。資料表的分割區索引鍵和排序索引鍵一律會投影到索引中；您可以投影其他屬性來支援應用程式的查詢需求。查詢索引時，Amazon DynamoDB 可以存取投影中的任何屬性，就好像這些屬性在它們自己的資料表中一樣。
在建立次要索引時，您需要指定要投影到索引中的屬性。DynamoDB 為此提供三種不同的選項：
+ *KEYS\$1ONLY*：索引中的每個項目都只包含資料表分割索引鍵和排序索引鍵值，以及索引鍵值。`KEYS_ONLY` 選項會產生最小的可行次要索引。
+ *INCLUDE*：除了 `KEYS_ONLY` 中描述的屬性外，次要索引還包含您指定的其他非索引鍵屬性。
+ *ALL*：次要索引包含來源資料表中的所有屬性。因為索引中的所有資料表資料都會重複，所以 `ALL` 投影會產生最大的可行次要索引。
在上圖中，非索引鍵屬性 `Replies` 投影到 `LastPostIndex`。應用程式可以查詢 `LastPostIndex`，而不是完整的 `Thread` 資料表，以便使用 `Subject`、`Replies` 和 `LastPostDateTime` 來填充網頁。如果請求任何其他非索引鍵屬性，DynamoDB 需要從 `Thread` 資料表擷取這些屬性。
從應用程式的角度來看，從基礎資料表擷取其他屬性是自動且透明的程序，因此不需要重寫任何應用程式邏輯。不過，此類擷取會大幅降低使用本機次要索引的效能優勢。
在選擇要投影到本機次要索引的屬性時，您必須權衡佈建輸送量成本和儲存成本：
+ 若您只需要存取少量的屬性，並且希望盡可能的降低延遲，建議您考慮只將那些屬性投影到本機次要索引。索引愈小，存放成本就愈低，您的寫入成本也愈低。如果您偶爾需要擷取屬性，佈建輸送量的成本可能會超過儲存這些屬性的長期成本。
+ 如果應用程式會頻繁存取某些非索引鍵屬性，您應該考慮將這些屬性投影到本機次要索引。本機次要索引的額外儲存成本會抵銷頻繁執行資料表掃描的成本。
+ 如果需要頻繁存取大多數的非索引鍵屬性，您可以將這些屬性 (或整個基礎資料表) 投影到本機次要索引。這可為您提供最大的靈活性和最低的佈建輸送量耗用量，因為不需要擷取。但是，如果投影所有屬性，您的儲存成本將會增加，甚至翻倍。
+ 如果您的應用程式不需頻繁查詢資料表，但必須對資料表中的資料執行許多寫入或更新，請考慮投影 *KEYS\$1ONLY*。本機次要索引的大小將會最小，但仍能在需要的時候進行查詢活動。
## 建立本機次要索引
若要在資料表上建立具有一或多個本機次要索引，請使用 `CreateTable` 操作的 `LocalSecondaryIndexes` 參數。建立資料表時，會建立資料表上的本機次要索引。當您使用刪除資料表時，也會刪除該資料表上的任何本機次要索引。
您必須指定一個非索引鍵屬性作為本機次要索引的排序索引鍵。您選擇的屬性必須是純量 `String`、`Number` 或 `Binary`。不允許其他純量類型、文件類型和集合類型。如需資料類型的完整清單，請參閱 [資料類型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)。
**重要**
對於具有本機次要索引的資料表，每個分割區索引鍵值都有 10 GB 的大小限制。具有本機次要索引的資料表可以存放任何數量的項目，只要任何一個分割區索引鍵值的總大小不超過 10 GB 即可。如需詳細資訊，請參閱 [項目集合大小限制](#LSI.ItemCollections.SizeLimit)。
您可以將任何資料類型的屬性投影到本機次要索引。這包括純量、文件和集合。如需資料類型的完整清單，請參閱 [資料類型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)。
## 從本機次要索引讀取資料
您可以使用 `Query` 和 `Scan` 操作從本機次要索引擷取項目。`GetItem` 和 `BatchGetItem` 操作不能用於本機次要索引。
### 查詢本機次要索引
在 DynamoDB 資料表中，每個項目的組合分割區索引鍵值和排序索引鍵值必須是唯一的值。不過，在本機次要索引中，排序索引鍵值對於指定的分割區索引鍵值不一定是唯一的值。如果本機次要索引中有多個項目具有相同的排序索引鍵值，`Query` 操作會傳回具有相同分割區索引鍵值的所有項目。在回應中，符合的項目不會以任何特定的順序傳回。
您可以使用最終一致或高度一致性讀取來查詢本機次要索引。若要指定您想要的一致性類型，請使用 `Query` 操作的 `ConsistentRead` 參數。來自本機次要索引的高度一致性讀取一律會傳回最新的更新值。如果查詢需要從基礎資料表中取得其他屬性，這些屬性將與索引保持一致。
**Example**
請考慮從 `Query` (請求來自特定論壇主題的資料) 傳回的下列資料。
```
{
"TableName": "Thread",
"IndexName": "LastPostIndex",
"ConsistentRead": false,
"ProjectionExpression": "Subject, LastPostDateTime, Replies, Tags",
"KeyConditionExpression":
"ForumName = :v_forum and LastPostDateTime between :v_start and :v_end",
"ExpressionAttributeValues": {
":v_start": {"S": "2015-08-31T00:00:00.000Z"},
":v_end": {"S": "2015-11-31T00:00:00.000Z"},
":v_forum": {"S": "EC2"}
}
}
```
在此查詢中：
+ DynamoDB 存取 `LastPostIndex`，使用 `ForumName` 分割區索引鍵尋找「EC2」的索引項目。所有具有此索引鍵的索引項目都會相鄰存放，以利快速擷取。
+ 在此論壇中，DynamoDB 使用索引來尋找符合指定 `LastPostDateTime` 條件的索引鍵。
+ 由於 `Replies` 屬性投影到索引中時，DynamoDB 可以檢索此屬性，而不會耗用任何額外的佈建輸送量。
+ 此 `Tags` 屬性不會投影到索引中，因此 DynamoDB 必須存取 `Thread` 資料表並擷取此屬性。
+ 結果會傳回，並依 `LastPostDateTime` 排序。索引項目依分割區索引鍵值排序，再依排序索引鍵值排序，然後由 `Query` 依儲存的順序將其傳回。(您可以使用 `ScanIndexForward` 參數，以遞減順序傳回結果。)
由於 `Tags` 屬性未投影到本機次要索引中，DynamoDB 必須消耗額外的讀取容量單位，才能從基礎資料表擷取此屬性。如果需要經常執行此查詢，您應將 `Tags` 投影至 `LastPostIndex`，避免從基礎資料表擷取。不過，如果您僅偶爾需要存取 `Tags`，則將 `Tags` 投影至索引中的額外儲存成本便可能不值得。
### 掃描本機次要索引
您可以使用 `Scan` 從本機次要索引檢索所有資料。您必須在請求中提供基礎資料表名稱及索引名稱。使用 `Scan`，DynamoDB 會讀取索引中的所有資料，並將其傳回應用程式。您也可以請求只傳回一部分的資料，並捨棄其他剩餘的資料。若要執行此作業，請使用 `Scan` API 的 `FilterExpression` 參數。如需詳細資訊，請參閱 [掃描的篩選條件表達式](Scan.md#Scan.FilterExpression)。
## 項目寫入和本機次要索引
DynamoDB 會自動讓所有本機次要索引與各自的基礎資料表同步。應用程式永遠不會直接寫入索引。然而，了解 DynamoDB 維持這些索引之方式的含義很重要。
在建立本機次要索引時，您可以指定一個屬性作為索引的排序索引鍵。您也可以為該屬性指定資料類型。這表示每次您將項目寫入基礎資料表時，如果項目定義了索引鍵屬性，則其類型必須與索引鍵結構描述的資料類型相符。在 `LastPostIndex` 案例中，索引的 `LastPostDateTime` 排序索引鍵是定義為 `String` 資料類型。如果您嘗試在 `Thread` 資料表中新增項目，並為 `LastPostDateTime` (如 `Number`) 指定不同的資料類型，DynamoDB 會因資料類型不符而傳回 `ValidationException`。
基礎資料表中的項目與本機次要索引中的項目之間沒有一對一的關係要求。事實上，這種行為對許多應用程式來說可能是有利的。
相較於索引較少的資料表，本機次要索引較多的資料表會有較高的寫入活動成本。如需詳細資訊，請參閱 [本機次要索引的佈建輸送量考量](#LSI.ThroughputConsiderations)。
**重要**
對於具有本機次要索引的資料表，每個分割區索引鍵值都有 10 GB 的大小限制。具有本機次要索引的資料表可以存放任何數量的項目，只要任何一個分割區索引鍵值的總大小不超過 10 GB 即可。如需詳細資訊，請參閱 [項目集合大小限制](#LSI.ItemCollections.SizeLimit)。
## 本機次要索引的佈建輸送量考量
在 DynamoDB 中建立資料表時，您可以為資料表的預期工作負載佈建讀取和寫入容量單位。該工作負載包括在資料表本機次要索引上的讀取和寫入活動。
若要檢視佈建的輸送容量的目前費率，請參閱 [Amazon DynamoDB 定價](https://aws.amazon.com/dynamodb/pricing)。
### 讀取容量單位
在查詢本機次要索引時，消耗的讀取容量單位數目取決於資料的存取方式。
與資料表查詢一樣，索引查詢可以使用最終一致性或高度一致性讀取，取決於 `ConsistentRead` 的值。一個高度一致性讀取會消耗一個讀取容量單位；最終一致讀取則只會消耗一半的讀取容量單位。因此，透過選擇最終一致讀取，您可以減少讀取容量單位的費用。
對於僅請求索引鍵和投影屬性的索引查詢，DynamoDB 會使用為資料表查詢計算佈建讀取活動相同的方式，計算佈建讀取活動。唯一的差別在於計算方式是以索引項目的大小為基礎，而非基礎資料表中項目的大小。讀取容量單位數為所有傳回項目中，所有投影屬性大小的總和；結果會四捨五入至下一個 4 KB 界限。如需 DynamoDB 如何計算佈建輸送用量的詳細資訊，請參閱 [DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。
對於讀取未投影到本機次要索引的屬性的索引查詢，除了從索引讀取投影的屬性之外，DynamoDB 還需要從基礎資料表擷取這些屬性。當您在 `Query` 操作的 `Select` 或 `ProjectionExpression` 參數中包含任何非投影屬性，即會發生這些擷取。擷取會在查詢回應中造成額外的延遲，也會產生較高的佈建輸送量成本：除了從先前描述的本機次要索引讀取之外，您還需要針對每個擷取的基礎資料表項目支付讀取容量單位費用。此費用是用於讀取資料表中的每個項目，而不僅僅是請求的屬性。
`Query` 操作傳回的結果大小上限是 1 MB。這包含所有傳回項目之所有屬性名稱與值的大小。不過，如果針對本機次要索引進行查詢導致 DynamoDB 從基礎資料表擷取項目屬性，則結果中資料的大小上限可能會降低。在這種情況下，結果大小是以下各項的總和：
+ 索引中相符項目的大小，且項目大小會四捨五入至下一個 4 KB。
+ 基礎資料表中每個相符項目的大小，且每個項目的大小會四捨五入至下一個 4 KB。
若使用此公式，查詢操作傳回的結果的大小上限仍為 1 MB。
例如，假設有一個資料表，其中每個項目的大小均為 300 個位元組。該資料表上有本機次要索引，但每個項目只有 200 個位元組投影到索引中。現在假設您 `Query` 此索引，查詢將需為每個項目擷取資料表，且查詢會傳回 4 個項目。DynamoDB 會計算以下總數：
+ 索引中相符項目的大小：200 個位元組 × 4 個項目 = 800 個位元組；接著會四捨五入至 4 KB。
+ 基礎資料表中每個相符項目的大小：(300 個位元組，四捨五入至 4 KB) × 4 個項目 = 16 KB。
因此，結果中的資料總大小為 20 KB。
### 寫入容量單位
當新增、更新或刪除資料表中的項目時，更新本機次要索引會耗用資料表的佈建寫入容量單位。寫入的總佈建輸送量成本為寫入資料表使用的寫入容量單位，加上更新本機次要索引使用的寫入容量單位。
將項目寫入本機次要索引的成本取決於幾個因素：
+ 若您將項目寫入定義索引屬性的資料表，或是您將現有的項目更新為先前未定義的索引屬性，則將該項目寫入索引需要進行一次寫入操作。
+ 若資料表的更新會變更索引鍵屬性的值 (從 A 到 B)，則需要兩次寫入：一次是從索引刪除先前的項目，第二次則是將新的項目寫入索引。
+ 若項目存在於索引中，但寫入資料表致使索引屬性遭到刪除，則需要進行一次寫入，從索引刪除舊項目的投影。
+ 若項目在更新之前或之後並不存在於索引中，則該索引將不會有任何額外的寫入成本。
所有這些因素都假設索引中每個項目的大小都小於或等於 1 KB 項目大小 (用於計算寫入容量單位)。較大的索引項目需要額外的寫入容量單位。您可以考慮查詢需要傳回的屬性，並只將那些屬性投影到索引中，從而將寫入成本降至最小。
## 本機次要索引的儲存考量
當應用程式將項目寫入資料表時，DynamoDB 會自動將正確的部分屬性複製到應顯示這些屬性的任何本機次要索引中。 AWS 您的帳戶需要支付基本資料表中項目的儲存費用，以及該資料表上任何本機次要索引中屬性的儲存費用。
索引項目使用的空間數為下列項目的總和：
+ 基礎資料表主索引鍵 (分割區索引鍵和排序索引鍵) 的大小 (位元組)
+ 索引鍵屬性的大小 (位元組)
+ 投影屬性 (若有的話) 的大小 (位元組)
+ 每個索引項目 100 位元組的額外負荷
若要估算本機次要索引的儲存需求，您可以估算索引中項目的平均大小，再乘以索引中的項目數量。
如果資料表包含特定屬性未經定義的項目，但該屬性卻已定義為索引的排序索引鍵時，DynamoDB 不會將該項目的任何資料寫入索引。
## 本機次要索引中的項目集合
**注意**
此節僅適用於具有本機次要索引的資料表。
在 DynamoDB 中，*項目集合*是資料表及其所有本機次要索引中具有相同分割區索引鍵值的任何項目群組。在本節所使用的範例中，`Thread` 資料表的分割區索引鍵為 `ForumName`，`LastPostIndex` 的分割區索引鍵也為 `ForumName`。所有具有相同 `ForumName` 的資料表和索引項目均屬於相同的項目集合。例如，在 `Thread` 資料表與 `LastPostIndex` 本機次要索引中，論壇 `EC2` 有一個項目集合，論壇 `RDS` 則有一個不同的項目集合。
下圖顯示論壇 `S3` 的項目集合。
![\[DynamoDB 項目集合，其中的資料表及本機次要索引項目均具有相同分割區索引鍵值 S3。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/LSI_04.png)
在此圖表中，項目集合由 `Thread` 和 `LastPostIndex` 中的所有項目組成，其中 `ForumName` 分割區索引鍵值為「S3」。如果資料表上有其他本機次要索引，則這些索引中 `ForumName` 等於「S3」的任何項目也將成為項目集合的一部分。
您可以在 DynamoDB 中使用下列任何操作來傳回項目集合的相關資訊：
+ `BatchWriteItem`
+ `DeleteItem`
+ `PutItem`
+ `UpdateItem`
+ `TransactWriteItems`
這些操作中的每一個都支援 `ReturnItemCollectionMetrics` 參數。在將此參數設定為 `SIZE`，您可以檢視索引中每個項目集合大小的相關資訊。
**Example**
以下是 `Thread` 資料表上 `UpdateItem` 操作的輸出範例，其中 `ReturnItemCollectionMetrics` 設定為 `SIZE`。更新的項目的 `ForumName` 值為「EC2」，因此輸出包含有關該項目集合的資訊。
```
{
ItemCollectionMetrics: {
ItemCollectionKey: {
ForumName: "EC2"
},
SizeEstimateRangeGB: [0.0, 1.0]
}
}
```
`SizeEstimateRangeGB` 物件會顯示此項目集合的大小介於 0 到 1 GB 之間。DynamoDB 會定期更新此大小估計值，因此下次修改項目時，數字可能會有所不同。
### 項目集合大小限制
包含一或多個本機次要索引之資料表，其任何項目集合的大小上限為 10GB。這不適用於沒有本機次要索引之資料表的項目集合，也不適用於全域次要索引中的項目集合。僅具有一或多個本機次要索引的資料表才會受到影響。
如果項目集合超過 10 GB 的限制，DynamoDB 可能會傳回 `ItemCollectionSizeLimitExceededException`，而且您可能無法將更多項目新增至項目集合，或增加項目集合中項目的大小。(仍允許會縮小項目集合大小的讀取和寫入操作。) 您仍可將項目新增至其他項目集合。
若要減少項目集合的大小，您可以執行下列操作之一：
+ 刪除有問題的分割區索引鍵值的任何不必要項目。在從基礎資料表中刪除這些項目時，DynamoDB 也會移除具有相同分割區索引鍵值的任何索引項目。
+ 透過移除屬性或減少屬性大小來更新項目。如果這些屬性投影到任何本機次要索引中，DynamoDB 也會減少對應索引項目的大小。
+ 使用相同的分割區索引鍵和排序索引鍵來建立新資料表，然後將項目從舊資料表移至新資料表。如果資料表具有不常存取的歷史資料，這可能是一個很好的方法。您也可以考慮將此歷史資料封存至 Amazon Simple Storage Service (Amazon S3)。
當項目集合的總大小降到 10 GB 以下時，您可以再次新增具有相同分割區索引鍵值的項目。
作為最佳實務，我們建議您檢測應用程式以監控項目集合的大小。方法之一是在使用 `BatchWriteItem`、`DeleteItem`、`PutItem` 或 `UpdateItem` 時將 `ReturnItemCollectionMetrics` 參數設定為 `SIZE`。您的應用程式應該檢查輸出中的 `ReturnItemCollectionMetrics` 物件，並在項目集合超過使用者定義的限制 (例如 8 GB) 時記錄錯誤訊息。設定小於 10 GB 的限制會提供一個預警系統，讓您及時掌握項目集合正接近限制，以便採取相關措施。
### 項目集合和分割區
在包含一或多個本機次要索引的資料表中，每個項目集合會儲存在一個分割區中。此項目集合的總大小僅限於該分割區的容量：10GB。應用程式中，若資料模型包含大小無上限的項目集合，或您可能合理預期某些項目集合日後會超過 10GB，您應考慮改用全域次要索引。
您應將應用程式設計為讓資料表資料均勻分佈在不同的分割區索引鍵值之間。對於具有本機次要索引的資料表，您的應用程式不應在單一分割區上的單一項目集合內建立讀取和寫入活動的「熱點」。
# 使用本機次要索引：Java
您可以使用 適用於 Java 的 AWS SDK 文件 API 建立具有一或多個本機次要索引的 Amazon DynamoDB 資料表、描述資料表上的索引，並使用索引執行查詢。
以下是使用 適用於 Java 的 AWS SDK 文件 API 進行資料表操作的常見步驟。
1. 建立 `DynamoDB` 類別的執行個體。
1. 透過建立對應的請求物件，為操作提供必要及選用的參數。
1. 呼叫您在前一步驟中建立之用戶端所提供的適當方法。
**Topics**
+ [使用本機次要索引建立資料表](#LSIJavaDocumentAPI.CreateTableWithIndex)
+ [使用本機次要索引描述資料表](#LSIJavaDocumentAPI.DescribeTableWithIndex)
+ [查詢本機次要索引](#LSIJavaDocumentAPI.QueryAnIndex)
+ [範例：使用 Java Document API 的本機次要索引](LSIJavaDocumentAPI.Example.md)
## 使用本機次要索引建立資料表
您必須同時建立資料表和本機次要索引。若要執行這項操作，請使用 `createTable` 方法，並提供一或多個本機次要索引的規格。以下 Java 程式碼範例會建立資料表來保存音樂收藏中歌曲的相關資訊。分割區索引鍵為 `Artist`，而排序索引鍵為 `SongTitle`。次要索引 `AlbumTitleIndex` 有助於依照專輯標題查詢。
以下是使用 DynamoDB Document API 建立具有本機次要索引的資料表的步驟。
1. 建立 `DynamoDB` 類別的執行個體。
1. 建立 `CreateTableRequest` 類別的執行個體，以提供請求資訊。
您必須提供資料表名稱、其主索引鍵，以及佈建的輸送量數值。對於本機次要索引，您必須提供索引名稱、索引排序索引鍵的名稱和資料類型、索引的索引鍵結構描述以及屬性投影。
1. 以參數形式提供請求物件，以便呼叫 `createTable` 方法。
下列 Java 程式碼範例示範上述步驟。程式碼會建立一個資料表 (`Music`) 與次要索引 `AlbumTitle` 屬性。資料表分割區索引鍵和排序索引鍵以及索引排序索引鍵，是唯一投影到索引的屬性。
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName);
//ProvisionedThroughput
createTableRequest.setProvisionedThroughput(new ProvisionedThroughput().withReadCapacityUnits((long)5).withWriteCapacityUnits((long)5));
//AttributeDefinitions
ArrayList attributeDefinitions= new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Artist").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("SongTitle").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("AlbumTitle").withAttributeType("S"));
createTableRequest.setAttributeDefinitions(attributeDefinitions);
//KeySchema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement().withAttributeName("SongTitle").withKeyType(KeyType.RANGE)); //Sort key
createTableRequest.setKeySchema(tableKeySchema);
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement().withAttributeName("AlbumTitle").withKeyType(KeyType.RANGE)); //Sort key
Projection projection = new Projection().withProjectionType(ProjectionType.INCLUDE);
ArrayList nonKeyAttributes = new ArrayList();
nonKeyAttributes.add("Genre");
nonKeyAttributes.add("Year");
projection.setNonKeyAttributes(nonKeyAttributes);
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
.withIndexName("AlbumTitleIndex").withKeySchema(indexKeySchema).withProjection(projection);
ArrayList localSecondaryIndexes = new ArrayList();
localSecondaryIndexes.add(localSecondaryIndex);
createTableRequest.setLocalSecondaryIndexes(localSecondaryIndexes);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
您必須等到 DynamoDB 建立資料表，並將資料表狀態設定為 `ACTIVE`。之後，您可以開始將資料項目放入資料表中。
## 使用本機次要索引描述資料表
若要取得資料表上本機次要索引的資訊，請使用 `describeTable` 方法。對於每個索引，您可以存取其名稱、索引鍵結構描述和投影屬性。
以下是使用 適用於 Java 的 AWS SDK Document API 存取資料表的本機次要索引資訊的步驟。
1. 建立 `DynamoDB` 類別的執行個體。
1. 建立 `Table` 類別的執行個體。您必須提供資料表名稱。
1. 在 `Table` 物件上呼叫 `describeTable` 方法。
下列 Java 程式碼範例示範上述步驟。
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
TableDescription tableDescription = table.describe();
List localSecondaryIndexes
= tableDescription.getLocalSecondaryIndexes();
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
Iterator lsiIter = localSecondaryIndexes.iterator();
while (lsiIter.hasNext()) {
LocalSecondaryIndexDescription lsiDescription = lsiIter.next();
System.out.println("Info for index " + lsiDescription.getIndexName() + ":");
Iterator kseIter = lsiDescription.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = lsiDescription.getProjection();
System.out.println("\tThe projection type is: " + projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: " + projection.getNonKeyAttributes());
}
}
```
## 查詢本機次要索引
您可以依照與 `Query` 資料表大致相同的方式在本機次要索引上使用 `Query` 操作。您必須指定索引名稱、索引排序索引鍵的查詢準則，以及您要傳回的屬性。在本例中，索引是 `AlbumTitleIndex`，而索引排序索引鍵為 `AlbumTitle`。
傳回的唯一屬性是已投影到索引的屬性。您也可以修改此查詢來選擇非索引鍵屬性，但這需要相對昂貴的資料表擷取活動。如需資料表擷取的詳細資訊，請參閱 [屬性投影](LSI.md#LSI.Projections)。
以下是使用 適用於 Java 的 AWS SDK 文件 API 查詢本機次要索引的步驟。
1. 建立 `DynamoDB` 類別的執行個體。
1. 建立 `Table` 類別的執行個體。您必須提供資料表名稱。
1. 建立 `Index` 類別的執行個體。您必須提供索引名稱。
1. 呼叫 `Index` 類別的 `query` 方法。
下列 Java 程式碼範例示範上述步驟。
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
Index index = table.getIndex("AlbumTitleIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"));
ItemCollection items = index.query(spec);
Iterator
- itemsIter = items.iterator();
while (itemsIter.hasNext()) {
Item item = itemsIter.next();
System.out.println(item.toJSONPretty());
}
```
### 本機次要索引上的一致讀取
與僅支援最終一致讀取的全域次要索引不同，本機次要索引支援最終一致和強烈一致讀取。來自本機次要索引的高度一致性讀取一律會傳回最新的更新值。如果查詢需要從基礎資料表擷取其他屬性，則這些擷取的屬性也與索引一致。
根據預設， `Query`會使用最終一致讀取。若要請求強式一致讀取，請在 `true`中將 `ConsistentRead`設定為 `QuerySpec`。下列範例查詢`AlbumTitleIndex`使用強式一致讀取：
**Example**
```
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"))
.withConsistentRead(true);
```
**注意**
強式一致讀取每傳回 4 KB 的資料會耗用一個讀取容量單位 （四捨五入），而最終一致讀取則會耗用一半。例如，傳回 9 KB 資料的強式一致讀取耗用 3 個讀取容量單位 (9 KB/4 KB = 2.25，四捨五入至 3)，而使用最終一致讀取的相同查詢耗用 1.5 個讀取容量單位。如果您的應用程式可以容忍讀取可能稍微過時的資料，請使用最終一致讀取來減少讀取容量用量。如需詳細資訊，請參閱[讀取容量單位](LSI.md#LSI.ThroughputConsiderations.Reads)。
# 範例：使用 Java Document API 的本機次要索引
下列 Java 程式碼範例示範如何使用 Amazon DynamoDB 中的本機次要索引。例如，您可以建立名為 `CustomerOrders` 的資料表，其中分割區索引鍵為 `CustomerId`，排序索引鍵為 `OrderId`。此資料表上有兩個本機次要索引：
+ `OrderCreationDateIndex`：排序索引鍵為 `OrderCreationDate`，並且以下屬性會投影到索引：
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex`：排序索引鍵為 `IsOpen`，並且所有的資料表屬性都會投影到索引。
建立 `CustomerOrders` 資料表後，程式會載入所含資料表示客戶訂單的資料表。然後，其便會使用本機次要索引查詢資料。最後，程式會刪除 `CustomerOrders` 資料表。
如需測試下列範例的逐步說明，請參閱 [Java 程式碼範例](CodeSamples.Java.md)。
**Example**
```
package com.example.dynamodb;
import software.amazon.awssdk.core.waiters.WaiterResponse;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
import java.util.HashMap;
import java.util.Map;
public class DocumentAPILocalSecondaryIndexExample {
static DynamoDbClient client = DynamoDbClient.create();
public static String tableName = "CustomerOrders";
public static void main(String[] args) {
createTable();
loadData();
query(null);
query("IsOpenIndex");
query("OrderCreationDateIndex");
deleteTable(tableName);
}
public static void createTable() {
CreateTableRequest request = CreateTableRequest.builder()
.tableName(tableName)
.provisionedThroughput(ProvisionedThroughput.builder()
.readCapacityUnits(1L)
.writeCapacityUnits(1L)
.build())
.attributeDefinitions(
AttributeDefinition.builder().attributeName("CustomerId").attributeType(ScalarAttributeType.S).build(),
AttributeDefinition.builder().attributeName("OrderId").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("OrderCreationDate").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("IsOpen").attributeType(ScalarAttributeType.N).build())
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderId").keyType(KeyType.RANGE).build())
.localSecondaryIndexes(
LocalSecondaryIndex.builder()
.indexName("OrderCreationDateIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderCreationDate").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.INCLUDE)
.nonKeyAttributes("ProductCategory", "ProductName")
.build())
.build(),
LocalSecondaryIndex.builder()
.indexName("IsOpenIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("IsOpen").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.ALL)
.build())
.build())
.build();
System.out.println("Creating table " + tableName + "...");
client.createTable(request);
try (DynamoDbWaiter waiter = client.waiter()) {
WaiterResponse response = waiter.waitUntilTableExists(r -> r.tableName(tableName));
response.matched().response().ifPresent(System.out::println);
}
}
public static void query(String indexName) {
System.out.println("\n***********************************************************\n");
System.out.println("Querying table " + tableName + "...");
if ("IsOpenIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that are open.");
System.out.println("Only a user-specified list of attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_isopen", AttributeValue.builder().n("1").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and IsOpen = :v_isopen")
.expressionAttributeValues(values)
.projectionExpression("OrderCreationDate, ProductCategory, ProductName, OrderStatus")
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else if ("OrderCreationDateIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that were placed after 01/31/2015.");
System.out.println("Only the projected attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_orddate", AttributeValue.builder().n("20150131").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and OrderCreationDate >= :v_orddate")
.expressionAttributeValues(values)
.select(Select.ALL_PROJECTED_ATTRIBUTES)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else {
System.out.println("\nNo index: All of Bob's orders, by OrderId:\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression("CustomerId = :v_custid")
.expressionAttributeValues(values)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
client.deleteTable(DeleteTableRequest.builder().tableName(tableName).build());
try (DynamoDbWaiter waiter = client.waiter()) {
waiter.waitUntilTableNotExists(r -> r.tableName(tableName));
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150101").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("The Great Outdoors").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Bike").build(),
"ProductName", AttributeValue.builder().s("Super Mountain").build(),
"OrderStatus", AttributeValue.builder().s("ORDER RECEIVED").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150304").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("A Quiet Interlude").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("176493").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150111").build(),
"ProductCategory", AttributeValue.builder().s("Movie").build(),
"ProductName", AttributeValue.builder().s("Calm Before The Storm").build(),
"OrderStatus", AttributeValue.builder().s("SHIPPING DELAY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("859323").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"OrderCreationDate", AttributeValue.builder().n("20150124").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("E-Z Listening").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("756943").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("Symphony 9").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("645193").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("4").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150222").build(),
"ProductCategory", AttributeValue.builder().s("Hardware").build(),
"ProductName", AttributeValue.builder().s("Extra Heavy Hammer").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("5").build(),
"OrderCreationDate", AttributeValue.builder().n("20150309").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("How To Cook").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("440185").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("6").build(),
"OrderCreationDate", AttributeValue.builder().n("20150318").build(),
"ProductCategory", AttributeValue.builder().s("Luggage").build(),
"ProductName", AttributeValue.builder().s("Really Big Suitcase").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("893927").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("7").build(),
"OrderCreationDate", AttributeValue.builder().n("20150324").build(),
"ProductCategory", AttributeValue.builder().s("Golf").build(),
"ProductName", AttributeValue.builder().s("PGA Pro II").build(),
"OrderStatus", AttributeValue.builder().s("OUT FOR DELIVERY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("383283").build()));
}
private static void putItem(Map item) {
client.putItem(PutItemRequest.builder().tableName(tableName).item(item).build());
}
}
```
# 使用本機次要索引：.NET
**Topics**
+ [使用本機次要索引建立資料表](#LSILowLevelDotNet.CreateTableWithIndex)
+ [使用本機次要索引描述資料表](#LSILowLevelDotNet.DescribeTableWithIndex)
+ [查詢本機次要索引](#LSILowLevelDotNet.QueryAnIndex)
+ [範例：使用 適用於 .NET 的 AWS SDK 低階 API 的本機次要索引](LSILowLevelDotNet.Example.md)
您可以使用 適用於 .NET 的 AWS SDK 低階 API 來建立具有一或多個本機次要索引的 Amazon DynamoDB 資料表、描述資料表上的索引，並使用索引執行查詢。這些操作會映射至對應的低階 DynamoDB API 動作。如需詳細資訊，請參閱 [.NET 程式碼範例](CodeSamples.DotNet.md)。
下列是使用 .NET 低階 API 執行資料表操作的一般步驟。
1. 建立 `AmazonDynamoDBClient` 類別的執行個體。
1. 透過建立對應的請求物件，為操作提供必要及選用的參數。
例如，建立 `CreateTableRequest` 物件來建立資料表，以及建立 `QueryRequest` 物件來查詢資料表或索引。
1. 執行您在前一步驟中建立之用戶端所提供的適當方法。
## 使用本機次要索引建立資料表
您必須同時建立資料表和本機次要索引。若要執行這項操作，請使用 `CreateTable`，並提供一或多個本機次要索引的規格。以下 C\$1 程式碼範例會建立資料表來保存音樂收藏中歌曲的相關資訊。分割區索引鍵為 `Artist`，而排序索引鍵為 `SongTitle`。次要索引 `AlbumTitleIndex` 有助於依照專輯標題查詢。
以下是使用 .NET 低階 API 建立具有本機次要索引之資料表的步驟。
1. 建立 `AmazonDynamoDBClient` 類別的執行個體。
1. 建立 `CreateTableRequest` 類別的執行個體，以提供請求資訊。
您必須提供資料表名稱、其主索引鍵，以及佈建的輸送量數值。對於本機次要索引，您必須提供索引名稱、索引排序索引鍵的名稱和資料類型、索引的索引鍵結構描述以及屬性投影。
1. 以參數形式提供請求物件，以便執行 `CreateTable` 方法。
下列 C\$1 程式碼範例示範前述步驟。程式碼會建立一個資料表 (`Music`) 與次要索引 `AlbumTitle` 屬性。資料表分割區索引鍵和排序索引鍵以及索引排序索引鍵，是唯一投影到索引的屬性。
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest()
{
TableName = tableName
};
//ProvisionedThroughput
createTableRequest.ProvisionedThroughput = new ProvisionedThroughput()
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)5
};
//AttributeDefinitions
List attributeDefinitions = new List();
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "Artist",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "SongTitle",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "AlbumTitle",
AttributeType = "S"
});
createTableRequest.AttributeDefinitions = attributeDefinitions;
//KeySchema
List tableKeySchema = new List();
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "SongTitle", KeyType = "RANGE" }); //Sort key
createTableRequest.KeySchema = tableKeySchema;
List indexKeySchema = new List();
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "AlbumTitle", KeyType = "RANGE" }); //Sort key
Projection projection = new Projection() { ProjectionType = "INCLUDE" };
List nonKeyAttributes = new List();
nonKeyAttributes.Add("Genre");
nonKeyAttributes.Add("Year");
projection.NonKeyAttributes = nonKeyAttributes;
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
{
IndexName = "AlbumTitleIndex",
KeySchema = indexKeySchema,
Projection = projection
};
List localSecondaryIndexes = new List();
localSecondaryIndexes.Add(localSecondaryIndex);
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
CreateTableResponse result = client.CreateTable(createTableRequest);
Console.WriteLine(result.CreateTableResult.TableDescription.TableName);
Console.WriteLine(result.CreateTableResult.TableDescription.TableStatus);
```
您必須等到 DynamoDB 建立資料表，並將資料表狀態設定為 `ACTIVE`。之後，您可以開始將資料項目放入資料表中。
## 使用本機次要索引描述資料表
若要取得資料表上本機次要索引的資訊，請使用 `DescribeTable` API。對於每個索引，您可以存取其名稱、索引鍵結構描述和投影屬性。
以下是使用 .NET 低階 API 存取資料表的本機次要索引資訊的步驟。
1. 建立 `AmazonDynamoDBClient` 類別的執行個體。
1. 建立 `DescribeTableRequest` 類別的執行個體，以提供請求資訊。您必須提供資料表名稱。
1. 以參數形式提供請求物件，以便執行 `describeTable` 方法。
下列 C\$1 程式碼範例示範前述步驟。
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest() { TableName = tableName });
List localSecondaryIndexes =
response.DescribeTableResult.Table.LocalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (LocalSecondaryIndexDescription lsiDescription in localSecondaryIndexes)
{
Console.WriteLine("Info for index " + lsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in lsiDescription.KeySchema)
{
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = lsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE"))
{
Console.WriteLine("\t\tThe non-key projected attributes are:");
foreach (String s in projection.NonKeyAttributes)
{
Console.WriteLine("\t\t" + s);
}
}
}
```
## 查詢本機次要索引
您可以依照與 `Query` 資料表大致相同的方式在本機次要索引上使用 `Query`。您必須指定索引名稱、索引排序索引鍵的查詢準則，以及您要傳回的屬性。在本例中，索引是 `AlbumTitleIndex`，而索引排序索引鍵為 `AlbumTitle`。
傳回的唯一屬性是已投影到索引的屬性。您也可以修改此查詢來選擇非索引鍵屬性，但這需要相對昂貴的資料表擷取活動。如需資料表擷取的詳細資訊，請參閱 [屬性投影](LSI.md#LSI.Projections)
以下是使用 .NET 低階 API 查詢本機次要索引的步驟。
1. 建立 `AmazonDynamoDBClient` 類別的執行個體。
1. 建立 `QueryRequest` 類別的執行個體，以提供請求資訊。
1. 以參數形式提供請求物件，以便執行 `query` 方法。
下列 C\$1 程式碼範例示範前述步驟。
**Example**
```
QueryRequest queryRequest = new QueryRequest
{
TableName = "Music",
IndexName = "AlbumTitleIndex",
Select = "ALL_ATTRIBUTES",
ScanIndexForward = true,
KeyConditionExpression = "Artist = :v_artist and AlbumTitle = :v_title",
ExpressionAttributeValues = new Dictionary()
{
{":v_artist",new AttributeValue {S = "Acme Band"}},
{":v_title",new AttributeValue {S = "Songs About Life"}}
},
};
QueryResponse response = client.Query(queryRequest);
foreach (var attribs in response.Items)
{
foreach (var attrib in attribs)
{
Console.WriteLine(attrib.Key + " ---> " + attrib.Value.S);
}
Console.WriteLine();
}
```
# 範例：使用 適用於 .NET 的 AWS SDK 低階 API 的本機次要索引
下列 C\$1 程式碼範例示範如何在 Amazon DynamoDB 中使用本機次要索引。例如，您可以建立名為 `CustomerOrders` 的資料表，其中分割區索引鍵為 `CustomerId`，排序索引鍵為 `OrderId`。此資料表上有兩個本機次要索引：
+ `OrderCreationDateIndex`：排序索引鍵為 `OrderCreationDate`，並且以下屬性會投影到索引：
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex`：排序索引鍵為 `IsOpen`，並且所有的資料表屬性都會投影到索引。
建立 `CustomerOrders` 資料表後，程式會載入所含資料表示客戶訂單的資料表。然後，其便會使用本機次要索引查詢資料。最後，程式會刪除 `CustomerOrders` 資料表。
如需測試下列範例的逐步說明，請參閱 [.NET 程式碼範例](CodeSamples.DotNet.md)。
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelLocalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
private static string tableName = "CustomerOrders";
static void Main(string[] args)
{
try
{
CreateTable();
LoadData();
Query(null);
Query("IsOpenIndex");
Query("OrderCreationDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
private static void CreateTable()
{
var createTableRequest =
new CreateTableRequest()
{
TableName = tableName,
ProvisionedThroughput =
new ProvisionedThroughput()
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
}
};
var attributeDefinitions = new List()
{
// Attribute definitions for table primary key
{ new AttributeDefinition() {
AttributeName = "CustomerId", AttributeType = "S"
} },
{ new AttributeDefinition() {
AttributeName = "OrderId", AttributeType = "N"
} },
// Attribute definitions for index primary key
{ new AttributeDefinition() {
AttributeName = "OrderCreationDate", AttributeType = "N"
} },
{ new AttributeDefinition() {
AttributeName = "IsOpen", AttributeType = "N"
}}
};
createTableRequest.AttributeDefinitions = attributeDefinitions;
// Key schema for table
var tableKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderId", KeyType = "RANGE"
} } //Sort key
};
createTableRequest.KeySchema = tableKeySchema;
var localSecondaryIndexes = new List();
// OrderCreationDateIndex
LocalSecondaryIndex orderCreationDateIndex = new LocalSecondaryIndex()
{
IndexName = "OrderCreationDateIndex"
};
// Key schema for OrderCreationDateIndex
var indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderCreationDate", KeyType = "RANGE"
} } //Sort key
};
orderCreationDateIndex.KeySchema = indexKeySchema;
// Projection (with list of projected attributes) for
// OrderCreationDateIndex
var projection = new Projection()
{
ProjectionType = "INCLUDE"
};
var nonKeyAttributes = new List()
{
"ProductCategory",
"ProductName"
};
projection.NonKeyAttributes = nonKeyAttributes;
orderCreationDateIndex.Projection = projection;
localSecondaryIndexes.Add(orderCreationDateIndex);
// IsOpenIndex
LocalSecondaryIndex isOpenIndex
= new LocalSecondaryIndex()
{
IndexName = "IsOpenIndex"
};
// Key schema for IsOpenIndex
indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
}}, //Partition key
{ new KeySchemaElement() {
AttributeName = "IsOpen", KeyType = "RANGE"
}} //Sort key
};
// Projection (all attributes) for IsOpenIndex
projection = new Projection()
{
ProjectionType = "ALL"
};
isOpenIndex.KeySchema = indexKeySchema;
isOpenIndex.Projection = projection;
localSecondaryIndexes.Add(isOpenIndex);
// Add index definitions to CreateTable request
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
public static void Query(string indexName)
{
Console.WriteLine("\n***********************************************************\n");
Console.WriteLine("Querying table " + tableName + "...");
QueryRequest queryRequest = new QueryRequest()
{
TableName = tableName,
ConsistentRead = true,
ScanIndexForward = true,
ReturnConsumedCapacity = "TOTAL"
};
String keyConditionExpression = "CustomerId = :v_customerId";
Dictionary expressionAttributeValues = new Dictionary {
{":v_customerId", new AttributeValue {
S = "bob@example.com"
}}
};
if (indexName == "IsOpenIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that are open.");
Console.WriteLine("Only a user-specified list of attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and IsOpen = :v_isOpen";
expressionAttributeValues.Add(":v_isOpen", new AttributeValue
{
N = "1"
});
// ProjectionExpression
queryRequest.ProjectionExpression = "OrderCreationDate, ProductCategory, ProductName, OrderStatus";
}
else if (indexName == "OrderCreationDateIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that were placed after 01/31/2013.");
Console.WriteLine("Only the projected attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and OrderCreationDate > :v_Date";
expressionAttributeValues.Add(":v_Date", new AttributeValue
{
N = "20130131"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo index: All of Bob's orders, by OrderId:\n");
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "OrderId" || attr == "IsOpen"
|| attr == "OrderCreationDate")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
Console.WriteLine("\nConsumed capacity: " + result.ConsumedCapacity.CapacityUnits + "\n");
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest()
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
public static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
Dictionary item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130101"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "The Great Outdoors"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
PutItemRequest putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Bike"
};
item["ProductName"] = new AttributeValue
{
S = "Super Mountain"
};
item["OrderStatus"] = new AttributeValue
{
S = "ORDER RECEIVED"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130304"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "A Quiet Interlude"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "176493"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130111"
};
item["ProductCategory"] = new AttributeValue
{
S = "Movie"
};
item["ProductName"] = new AttributeValue
{
S = "Calm Before The Storm"
};
item["OrderStatus"] = new AttributeValue
{
S = "SHIPPING DELAY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "859323"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130124"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "E-Z Listening"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "756943"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "Symphony 9"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "645193"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "4"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130222"
};
item["ProductCategory"] = new AttributeValue
{
S = "Hardware"
};
item["ProductName"] = new AttributeValue
{
S = "Extra Heavy Hammer"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "5"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130309"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "How To Cook"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "440185"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "6"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130318"
};
item["ProductCategory"] = new AttributeValue
{
S = "Luggage"
};
item["ProductName"] = new AttributeValue
{
S = "Really Big Suitcase"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "893927"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "7"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130324"
};
item["ProductCategory"] = new AttributeValue
{
S = "Golf"
};
item["ProductName"] = new AttributeValue
{
S = "PGA Pro II"
};
item["OrderStatus"] = new AttributeValue
{
S = "OUT FOR DELIVERY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "383283"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# 在 DynamoDB AWS CLI 中使用本機次要索引
您可以使用 AWS CLI 建立含有一或多個本機次要索引的 Amazon DynamoDB 資料表、描述資料表上的索引，以及使用索引執行查詢。
**Topics**
+ [使用本機次要索引建立資料表](#LCICli.CreateTableWithIndex)
+ [使用本機次要索引描述資料表](#LCICli.DescribeTableWithIndex)
+ [查詢本機次要索引](#LCICli.QueryAnIndex)
## 使用本機次要索引建立資料表
您必須同時建立資料表和本機次要索引。若要執行這項操作，請使用 `create-table` 參數，並提供一或多個本機次要索引的規格。以下範例會建立資料表 (`Music`) 來保存音樂收藏中歌曲的相關資訊。分割區索引鍵為 `Artist`，而排序索引鍵為 `SongTitle`。`AlbumTitle` 屬性上的次要索引 `AlbumTitleIndex` 有助於依照專輯標題查詢。
```
aws dynamodb create-table \
--table-name Music \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S \
AttributeName=AlbumTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--provisioned-throughput \
ReadCapacityUnits=10,WriteCapacityUnits=5 \
--local-secondary-indexes \
"[{\"IndexName\": \"AlbumTitleIndex\",
\"KeySchema\":[{\"AttributeName\":\"Artist\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"AlbumTitle\",\"KeyType\":\"RANGE\"}],
\"Projection\":{\"ProjectionType\":\"INCLUDE\", \"NonKeyAttributes\":[\"Genre\", \"Year\"]}}]"
```
您必須等到 DynamoDB 建立資料表，並將資料表狀態設定為 `ACTIVE`。之後，您可以開始將資料項目放入資料表中。您可以使用 [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) 來判斷資料表建立的狀態。
## 使用本機次要索引描述資料表
若要取得資料表上本機次要索引的資訊，請使用 `describe-table` 參數。對於每個索引，您可以存取其名稱、索引鍵結構描述和投影屬性。
```
aws dynamodb describe-table --table-name Music
```
## 查詢本機次要索引
您可以依照與 `query` 資料表大致相同的方式在本機次要索引上使用 `query` 操作。您必須指定索引名稱、索引排序索引鍵的查詢準則，以及您要傳回的屬性。在本例中，索引是 `AlbumTitleIndex`，而索引排序索引鍵為 `AlbumTitle`。
傳回的唯一屬性是已投影到索引的屬性。您也可以修改此查詢來選擇非索引鍵屬性，但這需要相對昂貴的資料表擷取活動。如需資料表擷取的詳細資訊，請參閱 [屬性投影](LSI.md#LSI.Projections)。
```
aws dynamodb query \
--table-name Music \
--index-name AlbumTitleIndex \
--key-condition-expression "Artist = :v_artist and AlbumTitle = :v_title" \
--expression-attribute-values '{":v_artist":{"S":"Acme Band"},":v_title":{"S":"Songs About Life"} }'
```
# 管理 DynamoDB 交易的複雜工作流程
Amazon DynamoDB Transactions 可簡化開發人員的使用體驗，讓這些人員同時對資料表內和跨資料表的多個項目，進行統籌協調式、全有或全無的變更。交易在 DynamoDB 中提供了不可分割性、一致性、隔離性和耐久性 (ACID)，讓您能夠輕鬆地維持應用程式的資料正確性。
您可以利用 DynamoDB 的交易讀取和寫入 API，來管理複雜的業務工作流程，這些流程需要將新增、更新或刪除多個項目的動作，當做全有或全無的單一操作來執行。例如，當玩家在電玩遊戲中交換物品或在遊戲中購買物品時，遊戲開發人員可以確保玩家的資料正確更新。
使用交易寫入 API，您可分組多個 `Put`、`Update`、`Delete` 和 `ConditionCheck` 動作。然後，將動作提交為單一 `TransactWriteItems` 操作，以單位形式成功或失敗。多項 `Get` 動作也可以相同的方式處理，在將這些動作分組後，當做單一 `TransactGetItems` 操作提交。
在您的 DynamoDB 資料表中啟用交易功能，不需額外付費。您只需針對交易中所進行的讀取和寫入付費即可。DynamoDB 會對交易中的每個項目進行兩項基本的讀取和寫入動作：一項是用來準備交易，一項是用來遞交交易。這兩項基本的讀取/寫入操作，會顯示在您的 Amazon CloudWatch 指標中。
若要開始使用 DynamoDB 交易，請下載最新的 AWS SDK 或 AWS Command Line Interface (AWS CLI)。然後遵循 [DynamoDB 交易範例](transaction-example.md)。
下列各節提供交易 API 的詳細概觀，並說明如何在 DynamoDB 中使用這些 API。
**Topics**
+ [運作方式](transaction-apis.md)
+ [將 IAM 搭配交易使用](transaction-apis-iam.md)
+ [範例程式碼](transaction-example.md)
# Amazon DynamoDB Transactions：運作方式
使用 Amazon DynamoDB Transactions 時，您可以將多項動作歸為一組，然後將這些動作以全有或全無的單一 `TransactWriteItems` 或 `TransactGetItems` 操作提交。下列各節說明 API 操作、容量管理、最佳實務，以及關於在 DynamoDB 中使用交易操作的其他詳細資訊。
**Topics**
+ [TransactWriteItems API](#transaction-apis-txwriteitems)
+ [TransactGetItems API](#transaction-apis-txgetitems)
+ [DynamoDB 交易的隔離層級](#transaction-isolation)
+ [DynamoDB 中的交易衝突處理](#transaction-conflict-handling)
+ [使用 DynamoDB Accelerator (DAX) 中的交易 API](#transaction-apis-dax)
+ [交易的容量管理](#transaction-capacity-handling)
+ [交易的最佳實務](#transaction-best-practices)
+ [將交易 API 與全域資料表搭配使用](#transaction-integration)
+ [DynamoDB 交易與 AWSLabs 用戶端程式庫的比較](#transaction-vs-library)
## TransactWriteItems API
`TransactWriteItems` 是一項冪等性的同步寫入操作，可將最多 100 個寫入動作分組成為全有或全無的單一操作。這些動作最多可將相同 AWS 帳戶和相同區域中一或多個 DynamoDB 資料表中的 100 個不同項目設為目標。交易中項目的彙總大小不能超過 4 MB。這些動作的完成具有不可分割性，也就是全部成功或全部失敗。
**注意**
`TransactWriteItems` 操作與 `BatchWriteItem` 操作的不同之處，在於前者所包含的全部動作，都必須順利地完成，否則就完全不會進行變更。如果是使用 `BatchWriteItem` 操作，即可允許批次中只有某些動作順利完成 (其他的動作失敗)。
無法使用索引執行交易。
在同一筆交易中，您無法針對同一個項目進行多項操作。例如，您不能對同一筆交易中的同一個項目既執行 `ConditionCheck` 又執行 `Update` 動作。
您可以將下列類型的動作新增到交易中：
+ `Put`：發起 `PutItem` 操作，來建立新的項目，或是用新的項目取代舊的項目 (具有條件或不指定任何條件)。
+ `Update`：發起 `UpdateItem` 操作，來編輯現有項目的屬性，或是在新項目尚未存在時，將新項目加入到資料表。利用此項動作，來新增、刪除或更新現有項目的屬性 (具有條件或無條件)。
+ `Delete`：發起 `DeleteItem` 操作，透過指定資料表中某項目的主索引鍵，來刪除該單一項目。
+ `ConditionCheck`：查看某項目是否存在，或是查看某項目特定屬性的條件。
交易在 DynamoDB 中完成時，其變更會開始傳播至全域次要索引 (GSI)、串流和備份。此傳播會逐步發生：來自相同交易的串流記錄，可能會在不同時間出現，且可能與其他交易的記錄交錯。串流取用者不應假設交易具有原子性或排序保證。
為了確保交易中修改項目的原子快照，請使用 TransactGetItems 操作，以同時讀取所有相關項目。此操作提供一致的資料檢視，確保您所見內容為已完成交易的所有變更，或完全不顯示任何變更。
因為傳播不是立即或瞬時完成，所以如果資料表是從備份還原 ([RestoreTableFromBackup](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_RestoreTableFromBackup.html)) 或匯出到中途傳播的某個時間點 ([ExportTableToPointInTime](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ExportTableToPointInTime.html))，可能只包含最近交易期間完成的部分變更。
### 冪等性
在進行 `TransactWriteItems` 呼叫時，您可以選擇性地加入用戶端符記，以確保請求具有*冪等性*。如果讓交易具有冪等性，則在因為連線逾時或其他連線問題，而多次提交同一項操作時，有助於防止應用程式發生錯誤。
如果原始的 `TransactWriteItems` 呼叫順利完成，便會成功傳回後續具有相同用戶端字符的 `TransactWriteItems` 呼叫，不建立任何變更。如果設定了 `ReturnConsumedCapacity` 參數，則初始的 `TransactWriteItems` 呼叫會傳回在建立變更時所使用的寫入容量單位數量。後續具有相同用戶端符記的 `TransactWriteItems` 呼叫，會傳回在讀取項目時所用掉的讀取容量單位數量。
**關於冪等性的重點**
+ 用戶端符記在使用該符記的請求完成後 10 分鐘內為有效。10 分鐘過後，使用同一個用戶端符記的任何請求，會被視為新的請求。在經過 10 分鐘之後，您就不應該針對相同的請求，重複使用同一個用戶端符記。
+ 如果您在 10 分鐘的冪等性有效期間內，使用相同的用戶端符記來重複請求，但變更了其他的某些請求參數，則 DynamoDB 會傳回 `IdempotentParameterMismatch` 例外。
### 寫入的錯誤處理
在下列的情況中，寫入交易不會成功：
+ 當其中一個條件表達式中的條件不符時。
+ 因為在同一個 `TransactWriteItems` 操作中，有超過一個以上的動作鎖定相同的項目，而造成交易驗證錯誤時。
+ 如果 `TransactWriteItems` 請求與 `TransactWriteItems` 請求中一或多個項目持續執行的 `TransactWriteItems` 操作相互衝突時。在這種情況中，請求會失敗，並且丟出 `TransactionCanceledException` 例外。
+ 佈建的容量不足，而使交易無法完成時。
+ 當項目的大小過大 (超過 400 KB)、本機次要索引 (LSI) 變得過大，或是因為交易所進行的變更造成類似的驗證錯誤時。
+ 發生使用者錯誤時，例如無效的資料格式。
如需如何處理 `TransactWriteItems` 操作衝突的詳細資訊，請參閱 [DynamoDB 中的交易衝突處理](#transaction-conflict-handling)。
## TransactGetItems API
`TransactGetItems` 是一項同步讀取操作，可將最多 100 個 `Get` 動作歸成一組。這些動作最多可將相同 AWS 帳戶和區域中一或多個 DynamoDB 資料表中的 100 個不同項目設為目標。交易中項目的彙總大小不能超過 4 MB。
`Get` 動作的執行具有不可分割性，也就是全部成功或全部失敗：
+ `Get`：發起 `GetItem` 操作，針對具有指定主索引鍵的項目，擷取該項目的一組屬性。如果找不到符合的項目，則 `Get` 不會傳回任何資料。
### 讀取的錯誤處理
在下列的情況中，讀取交易不會成功：
+ 如果 `TransactGetItems` 請求與 `TransactGetItems` 請求中一或多個項目持續執行的 `TransactWriteItems` 操作相互衝突時。在這種情況中，請求會失敗，並且丟出 `TransactionCanceledException` 例外。
+ 佈建的容量不足，而使交易無法完成時。
+ 發生使用者錯誤時，例如無效的資料格式。
如需如何處理 `TransactGetItems` 操作衝突的詳細資訊，請參閱 [DynamoDB 中的交易衝突處理](#transaction-conflict-handling)。
## DynamoDB 交易的隔離層級
交易操作 (`TransactWriteItems` 或 `TransactGetItems`) 和其他操作的隔離層級如下。
### 可序列化
如果在前一項操作完成之前，沒有任何操作開始執行，則*可序列化*隔離可確保多個同時並行操作的結果會相同。
在下列的操作類型之間，具有可序列化的隔離層級：
+ 在任何交易操作和任何標準寫入操作 (`PutItem`、`UpdateItem` 或 `DeleteItem`) 之間。
+ 在任何交易操作和任何標準讀取操作 (`GetItem`) 之間。
+ 在 `TransactWriteItems` 操作和 `TransactGetItems` 操作之間。
雖然在交易操作之間具有可序列化隔離層級，而且每個個別的標準會在 `BatchWriteItem` 操作中寫入，但是在交易和做為單位的 `BatchWriteItem` 操作之間，不具有可序列化隔離層級。
同樣地，交易操作與 `BatchGetItem` 操作中個別 `GetItems` 之間的隔離層是可以序列化。但是交易與當作一個單位的 `BatchGetItem` 操作之間的隔離層是*專供讀取*。
單一 `GetItem` 請求是兩種可序列化的 `TransactWriteItems` 請求方式之一，可以發生在 `TransactWriteItems` 請求之前或之後。與 `TransactWriteItems` 請求同時發出的多個 `GetItem` 請求，能夠以任何順序執行，因此結果會是*專供讀取*。
例如，如果項目 A 和項目 B 的 `GetItem` 請求與修改項目 A 和項目 B 的 `TransactWriteItems` 請求同時執行，則會有四種可能性：
+ 兩個 `GetItem` 請求皆會在 `TransactWriteItems` 請求之前執行。
+ 兩個 `GetItem` 請求皆會在 `TransactWriteItems` 請求之後執行。
+ 項目 A 的 `GetItem` 請求會在 `TransactWriteItems` 請求之前執行。針對項目 B，`GetItem` 會在 `TransactWriteItems` 之後執行。
+ 項目 B 的 `GetItem` 請求會在 `TransactWriteItems` 請求之前執行。針對項目 A，`GetItem` 會在 `TransactWriteItems` 之後執行。
如果您偏好適用於執行多個 `GetItem` 請求的可序列化隔離等級，應使用 `TransactGetItems`。
如果針對多個項目執行非交易式讀取，而這些項目原本屬於同一筆傳輸中的交易寫入請求，可能會出現部分項目可讀取到新狀態，而其他項目仍顯示舊狀態的情況。唯有在交易成功寫入並收到回應，表示該交易已完成時，您才能讀取原屬於該交易寫入請求之所有項目的新狀態。
交易成功完成並收到回應後，後續的*最終一致*讀取操作在短時間內仍可能傳回舊狀態，這是由於 DynamoDB 的最終一致性模式所致。為了確保在交易後立即讀取最新狀態資料，您應該將 `ConsistentRead` 設定為 true，使用[*高度一致性*](HowItWorks.ReadConsistency.md#HowItWorks.ReadConsistency.Strongly)讀取。
### 專供讀取
*專供讀取*隔離可確保讀取操作對特定項目一律傳回已確認的值 - 如果交易寫入最終未成功，則讀取操作一律不向該項目呈現此寫入狀態的檢視。專供讀取隔離不會防止在讀取操作後立即修改項目。
在任何交易操作和牽涉到多次標準讀取 (`BatchGetItem`、`Query` 或 `Scan`) 的任何讀取操作之間，其隔離層級為專供讀取。如果交易寫入在 `BatchGetItem`、`Query` 或 `Scan` 操作期間更新項目，則讀取操作的後續部分會傳回新確認的值 (含有 `ConsistentRead)` 或可能是先前已確認的值(最終一致讀取)。
### 操作摘要
做為總結，下表顯示了交易操作 (`TransactWriteItems` 或 `TransactGetItems`) 和其他操作之間的隔離層級。
| 作業 | 隔離層級 |
| --- | --- |
| `DeleteItem` | *可序列化* |
| `PutItem` | *可序列化* |
| `UpdateItem` | *可序列化* |
| `GetItem` | *可序列化* |
| `BatchGetItem` | *專供讀取*\$1 |
| `BatchWriteItem` | *不可序列化*\$1 |
| `Query` | *專供讀取* |
| `Scan` | *專供讀取* |
| 其他交易操作 | *可序列化* |
標有星號的層級 (\$1) 適用於單位式操作。不過，這些操作內的個別動作具有*可序列化*的隔離層級。
## DynamoDB 中的交易衝突處理
在交易內的項目上進行並行項目層級請求期間，可能會發生交易衝突。下列情境可能發生交易衝突：
+ 項目的 `PutItem`、`UpdateItem` 或 `DeleteItem` 請求與包括相同項目的持續 `TransactWriteItems` 請求發生衝突。
+ `TransactWriteItems` 請求內的項目是另一個持續 `TransactWriteItems` 請求的一部分。
+ `TransactGetItems` 請求的項目是持續 `TransactWriteItems`、`BatchWriteItem`、`PutItem`、`UpdateItem` 或 `DeleteItem` 請求的一部分。
**注意**
當 `PutItem`、`UpdateItem` 或 `DeleteItem` 請求遭到拒絕時，請求失敗並顯示 `TransactionConflictException`。
如果 `TransactWriteItems` 或 `TransactGetItems` 內的項目層級請求遭到拒絕，則請求失敗並顯示 `TransactionCanceledException`。如果請求失敗， AWS SDKs不會重試請求。
如果您使用的是 適用於 Java 的 AWS SDK，則例外狀況會包含 [CancellationReasons](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CancellationReason.html) 的清單，並根據`TransactItems`請求參數中的項目清單排序。對於其他語言，清單的字串表示法會併入異常的錯誤訊息中。
不過，如果有持續執行的 `TransactWriteItems` 和 `TransactGetItems` 操作，與同時並行的 `GetItem` 請求相互衝突時，這兩項操作都可以順利完成。
對於每個失敗的項目層級請求，[TransactionConflict CloudWatch 指標](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html)會遞增。
## 使用 DynamoDB Accelerator (DAX) 中的交易 API
DynamoDB Accelerator (DAX) 中支援 `TransactWriteItems` 和 `TransactGetItems`，且隔離層級與在 DynamoDB 中相同。
`TransactWriteItems` 會透過 DAX 寫入。DAX 會將 `TransactWriteItems` 呼叫傳送給 DynamoDB，然後傳回回應。為在寫入後填入快取，對於 `TransactWriteItems` 操作中的每個項目，DAX 會在背景呼叫 `TransactGetItems`，並耗用更多讀取容量單位。(如需詳細資訊，請參閱 [交易的容量管理](#transaction-capacity-handling)。) 此功能可讓您保持簡單的應用程式邏輯，並使用 DAX 執行交易及非交易操作。
`TransactGetItems` 呼叫透過 DAX 傳遞，項目不在本機進行快取。這個行為與 DAX 中的高度一致性讀取 API 相同。
## 交易的容量管理
在您的 DynamoDB 資料表中啟用交易功能，不需額外付費。您只需針對交易中所進行的讀取和寫入付費即可。DynamoDB 會對交易中的每個項目進行兩項基本的讀取和寫入動作：一項是用來準備交易，一項是用來遞交交易。這兩項基本的讀取/寫入操作，會顯示在您的 Amazon CloudWatch 指標中。
在為資料表佈建容量時，請規劃交易 API 所需的額外讀取與寫入容量。例如，假設您的應用程式每秒執行一項交易，而每項交易會在您的資料表中寫入三個 500 位元組的項目。每個項目需要兩個寫入容量單位 (WCU)：一個單位用來準備交易，另一個單位用來遞交交易。因此，您會需要佈建六個 WCU 給該資料表。
如果您在前一個範例中使用 DynamoDB Accelerator (DAX)，則也會針對 `TransactWriteItems` 呼叫中的每個項目使用兩個讀取容量單位 (RCU)。因此，您會需要佈建六個額外 RCU 給資料表。
同樣地，如果您的應用程式每秒執行一次讀取交易，而每項交易會在您的資料表中讀取三個 500 位元組的項目，則您會需要佈建六個讀取容量單位 (RCU) 給該資料表。讀取每個項目需要兩個 RCU：一個用來準備交易，另一個用來遞交交易。
此外，在出現 `TransactionInProgressException` 例外時，預設的 SDK 動作是重試交易。請規劃這些重試動作會使用的額外讀取容量單位 (RCU)。如果用您自己的程式碼，使用 `ClientRequestToken` 來重試交易時，也請進行同樣的規劃。
## 交易的最佳實務
在使用 DynamoDB 交易時，請考慮採用下列建議的做法。
+ 啟用資料表的自動擴展功能，或是確定您已佈建足夠的輸送容量，來針對您交易中的每個項目，進行兩項讀取或寫入操作。
+ 如果您不是使用 AWS 提供的 SDK，請在`TransactWriteItems`呼叫時包含 `ClientRequestToken` 屬性，以確保請求是等冪的。
+ 如非必要，請勿在交易中將操作歸為一組。例如，如果包含 10 項操作的單一交易，可以分成多項交易執行，而不會影響到應用程式的正確度，則我們建議拆分該項交易。簡化的交易可提升輸送量，而且成功的機率更高。
+ 更新同一個項目的多項交易如果同時執行，可能會造成衝突而導致交易取消。我們建議採用下列的 DynamoDB 資料建模最佳實務，來將此等衝突減到最少。
+ 如果在單一交易中，經常更新跨多個項目的一組屬性，請考慮將這些屬性分組成為單一項目，來縮小交易的範圍。
+ 避免使用大量擷取資料的交易。如果是大量寫入作業，較理想的做法是使用 `BatchWriteItem`。
## 將交易 API 與全域資料表搭配使用
交易操作僅在呼叫寫入 API 的 AWS 區域內提供原子性、一致性、隔離性和耐久性 (ACID) 保證。全域資料表不支援跨區域交易。舉例來說，假設您在美國東部 (俄亥俄) 與美國西部 (奧勒岡) 區域中有具有複本的全域資料表，並且在美國東部 (維吉尼亞北部) 區域中執行 `TransactWriteItems` 操作。由於變更受到複寫，所以您可能會在美國西部 (奧勒岡) 區域中看到部分已完成交易。當變更已在來源區域遞交後，這些變更才會複寫至其他區域。
## DynamoDB 交易與 AWSLabs 用戶端程式庫的比較
DynamoDB 交易針對 [AWSLabs](https://github.com/awslabs) 交易用戶端程式庫，提供了更具成本效益、更強大和更高效能的替代方法。我們建議您更新應用程式，以使用原生的伺服器端交易 API。
# 將 IAM 與 DynamoDB 交易搭配使用
您可以使用 AWS Identity and Access Management (IAM) 來限制交易操作可在 Amazon DynamoDB 中執行的動作。如需在 DynamoDB 中使用 IAM 政策的詳細資訊，請參閱 [適用於 DynamoDB 的以身分為基礎的政策](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies)。
`Put`、`Update`、`Delete` 和 `Get` 動作的許可，受到底層 `PutItem`、`UpdateItem`、`DeleteItem` 和 `GetItem` 操作使用的許可所管理。如果是 `ConditionCheck` 動作，您可以使用 IAM 政策中的 `dynamodb:ConditionCheckItem` 許可。
您可以使用下列的 IAM 政策範例，來設定 DynamoDB 交易。
## 範例 1：允許交易操作
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## 範例 2：只允許交易操作
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
}
]
}
```
------
## 範例 3：允許非交易讀取與寫入，並且封鎖交易讀取與寫入
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:UpdateItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## 範例 4：防止在 ConditionCheck 失敗時傳回資訊
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": "arn:aws:dynamodb:*:*:table/table01",
"Condition": {
"StringEqualsIfExists": {
"dynamodb:ReturnValues": "NONE"
}
}
}
]
}
```
------
# DynamoDB 交易範例
以 Amazon DynamoDB Transactions 十分實用的情況作為範例，請考慮此線上市場的 Java 應用程式範例。
應用程式在其後端有三個 DynamoDB 資料表：
+ `Customers`：此資料表儲存有關市場客戶的詳細資訊。其主索引鍵為 `CustomerId` 唯一識別符。
+ `ProductCatalog`：此資料表儲存的詳細資訊包括關於市場上銷售之產品的價格和供貨情況。其主索引鍵為 `ProductId` 唯一識別符。
+ `Orders`：此資料表儲存有關市場訂單的詳細資訊。其主索引鍵為 `OrderId` 唯一識別符。
## 下訂單
下列程式碼片段說明如何使用 DynamoDB 交易來協調建立和處理訂單所需的多個步驟。使用單一「全有或全無」操作，可確保如果交易的任何部分失敗，便不會執行交易中的任何動作，也不會進行任何變更。
在此範例中，您可以為 `customerId` 為 `09e8e9c8-ec48` 的客戶設定訂單。然後，您可以使用下列簡單的訂單處理工作流程，將其當作單一交易執行：
1. 判斷客戶 ID 有效。
1. 確定產品為 `IN_STOCK`，並將產品狀態更新為 `SOLD`。
1. 請確定訂單不存在，並建立訂單。
### 驗證客戶
首先，請定義一個動作，以便驗證客戶資料表中是否存在 `customerId` 等於 `09e8e9c8-ec48` 的客戶。
```
final String CUSTOMER_TABLE_NAME = "Customers";
final String CUSTOMER_PARTITION_KEY = "CustomerId";
final String customerId = "09e8e9c8-ec48";
final HashMap customerItemKey = new HashMap<>();
customerItemKey.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
ConditionCheck checkCustomerValid = new ConditionCheck()
.withTableName(CUSTOMER_TABLE_NAME)
.withKey(customerItemKey)
.withConditionExpression("attribute_exists(" + CUSTOMER_PARTITION_KEY + ")");
```
### 更新產品狀態
接下來，如果產品狀態目前是將 `IN_STOCK` 設定為 `true`，請定義要將產品狀態更新至 `SOLD` 的動作。如果項目的產品狀態屬性不等於 `IN_STOCK`，則設定 `ReturnValuesOnConditionCheckFailure` 參數會傳回項目。
```
final String PRODUCT_TABLE_NAME = "ProductCatalog";
final String PRODUCT_PARTITION_KEY = "ProductId";
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
Map expressionAttributeValues = new HashMap<>();
expressionAttributeValues.put(":new_status", new AttributeValue("SOLD"));
expressionAttributeValues.put(":expected_status", new AttributeValue("IN_STOCK"));
Update markItemSold = new Update()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey)
.withUpdateExpression("SET ProductStatus = :new_status")
.withExpressionAttributeValues(expressionAttributeValues)
.withConditionExpression("ProductStatus = :expected_status")
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD);
```
### 建立訂單
最後，只要具有 `OrderId` 的訂單尚不存在，便可建立訂單。
```
final String ORDER_PARTITION_KEY = "OrderId";
final String ORDER_TABLE_NAME = "Orders";
HashMap orderItem = new HashMap<>();
orderItem.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
orderItem.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
orderItem.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
orderItem.put("OrderStatus", new AttributeValue("CONFIRMED"));
orderItem.put("OrderTotal", new AttributeValue("100"));
Put createOrder = new Put()
.withTableName(ORDER_TABLE_NAME)
.withItem(orderItem)
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)
.withConditionExpression("attribute_not_exists(" + ORDER_PARTITION_KEY + ")");
```
### 執行交易
下列範例說明如何執行先前定義為「全有或全無」的單一操作動作。
```
Collection actions = Arrays.asList(
new TransactWriteItem().withConditionCheck(checkCustomerValid),
new TransactWriteItem().withUpdate(markItemSold),
new TransactWriteItem().withPut(createOrder));
TransactWriteItemsRequest placeOrderTransaction = new TransactWriteItemsRequest()
.withTransactItems(actions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
client.transactWriteItems(placeOrderTransaction);
System.out.println("Transaction Successful");
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.out.println("Transaction Canceled " + tce.getMessage());
}
```
## 讀取訂單詳細資訊
下列範例示範如何以交易方式讀取 `Orders` 和 `ProductCatalog` 資料表中的已完成訂單。
```
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
HashMap orderKey = new HashMap<>();
orderKey.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
Get readProductSold = new Get()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey);
Get readCreatedOrder = new Get()
.withTableName(ORDER_TABLE_NAME)
.withKey(orderKey);
Collection getActions = Arrays.asList(
new TransactGetItem().withGet(readProductSold),
new TransactGetItem().withGet(readCreatedOrder));
TransactGetItemsRequest readCompletedOrder = new TransactGetItemsRequest()
.withTransactItems(getActions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
TransactGetItemsResult result = client.transactGetItems(readCompletedOrder);
System.out.println(result.getResponses());
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.err.println("Transaction Canceled" + tce.getMessage());
}
```
# 使用 Amazon DynamoDB 變更資料擷取
當存放在 DynamoDB 資料表中的項目發生變更時，擷取這類變更的功能可為許多應用程式提供好處。下列是一些範例使用案例：
+ 熱門行動應用程式以每秒數千筆更新的速率修改 DynamoDB 資料表中的資料。另一個應用程式擷取及存放這些更新的相關資料，為行動應用程式提供近乎即時的用量指標。
+ 財務應用程式會修改 DynamoDB 資料表中的股票市場資料。平行執行的不同應用程式會即時追蹤這些變更，計算風險價值，並根據股票價格變動自動重新平衡投資組合。
+ 運輸車輛和工業設備中的感應器會將資料傳送至 DynamoDB 資料表。不同的應用程式會監控效能並在偵測到問題時傳送簡訊提醒，透過應用機器學習演算法預測任何潛在缺陷，以及將資料壓縮和封存到 Amazon Simple Storage Service (Amazon S3)。
+ 應用程式在某位朋友上傳新圖片時，立即自動傳送通知給群組中所有朋友的行動裝置。
+ 新客戶將資料新增至 DynamoDB 資料表。此事件調用另一個應用程式，該應用程式會將歡迎電子郵件傳送給新客戶。
DynamoDB 支援近乎即時的項目層級變更資料擷取紀錄串流。您可以建立使用這些串流並根據內容採取動作的應用程式。
**注意**
新增標籤至 DynamoDB Streams 與透過 DynamoDB Streams 使用[屬性型存取控制 (ABAC)](access-control-resource-based.md)，目前未提供支援。
以下影片將為您介紹變更資料擷取概念。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/VVv_-mZ5Ge8)
**Topics**
+ [變更資料擷取的串流選項](#streamsmain.choose)
+ [使用 Kinesis Data Streams 來擷取 DynamoDB 的變更](kds.md)
+ [DynamoDB Streams 的變更資料擷取](Streams.md)
## 變更資料擷取的串流選項
DynamoDB 提供兩種用於變更資料擷取的串流模型：DynamoDB 專用 Kinesis Data Streams 和 DynamoDB Streams。
為了協助您為應用程式選擇合適的解決方案，下表摘要說明每種串流模型的特色。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/streamsmain.html)
您可以在同一個 DynamoDB 資料表上啟用這兩種串流模型。
下面這段影片將進一步說明這兩個選項之間的差異。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/UgG17Wh2y0g)
# 使用 Kinesis Data Streams 來擷取 DynamoDB 的變更
您可以使用 Amazon Kinesis Data Streams 來擷取 Amazon DynamoDB 的變更。
Kinesis Data Streams 會擷取任何 DynamoDB 資料表中的項目層級修改，並將其複製到您選擇的 [Kinesis 資料串流](https://docs.aws.amazon.com/streams/latest/dev/introduction.html)。您的應用程式可以存取此串流，並以近乎即時的速度檢視項目層級的變更。您每小時可以持續擷取和儲存 TB 級的資料。您可以利用較長的資料保留時間，並透過增強的廣發功能，您可以同時觸及兩個以上的下游應用程式。其他優點包括額外的稽核和安全透明度。
Kinesis Data Streams 也可讓您存取 [Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) 和 [Amazon Managed Service for Apache Flink](https://docs.aws.amazon.com/kinesisanalytics/latest/dev/what-is.html)。這可讓您建置應用程式來啟動即時儀表板、產生提醒、實作動態定價和廣告，以及執行複雜的資料分析及機器學習演算法。
**注意**
為 DynamoDB 使用 Kinesis 資料串流同時受到資料串流的 [Kinesis Data Streams 定價](https://aws.amazon.com/kinesis/data-streams/pricing/)和來源資料表的 [DynamoDB 定價](https://aws.amazon.com/dynamodb/pricing/)的約束。
若要使用主控台 AWS CLI或 Java SDK 在 DynamoDB 資料表上啟用 Kinesis 串流，請參閱 [Amazon DynamoDB 專用 Kinesis Data Streams 入門](kds_gettingstarted.md)。
**Topics**
+ [Kinesis Data Streams 如何與 DynamoDB 搭配運作](#kds_howitworks)
+ [Amazon DynamoDB 專用 Kinesis Data Streams 入門](kds_gettingstarted.md)
+ [以 DynamoDB Streams 和 Kinesis Data Streams 使用碎片和指標](kds_using-shards-and-metrics.md)
+ [使用 Amazon Kinesis Data Streams 和 Amazon DynamoDB 專用的 IAM 政策](kds_iam.md)
## Kinesis Data Streams 如何與 DynamoDB 搭配運作
當 DynamoDB 資料表啟用 Kinesis 資料串流時，資料表會傳送資料記錄，以擷取該資料表資料的任何變更。此資料記錄包括：
+ 最近建立、更新或刪除之任何項目的具體時間
+ 該項目的主索引鍵
+ 修改前記錄的快照
+ 修改後記錄的快照
這些資料記錄會以接近即時的速度擷取和發布，並予以發布。將其寫入 Kinesis 資料串流後，就可以像其他記錄一樣讀取。您可以使用 Kinesis Client Library、使用 AWS Lambda、呼叫 Kinesis Data Streams API，以及使用其他連線的服務。如需詳細資訊，請參閱《Amazon Kinesis Data Streams 開發人員指南》中的[從 Amazon Kinesis Data Streams 讀取資料](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)。
這些對資料的變更也會以非同步方式擷取。Kinesis 對其串流來源的資料表沒有效能影響。存放在 Kinesis 資料串流中的串流紀錄會採用靜態加密。如需詳細資訊，請參閱 [Amazon Kinesis Data Streams 中的資料保護](https://docs.aws.amazon.com/streams/latest/dev/server-side-encryption.html)。
Kinesis 資料串流記錄的顯示順序，可能與項目變更發生的順序不同。相同的項目通知也可能會在串流中多次出現。您可以檢查 `ApproximateCreationDateTime` 屬性來識別項目修改發生的順序，並識別重複的記錄。
當您啟用 Kinesis 資料串流做為 DynamoDB 資料表串流目的地時，您可以毫秒或微秒為單位，設定 `ApproximateCreationDateTime` 值的精確度。根據預設，`ApproximateCreationDateTime` 會以毫秒為單位指出變更的時間。此外，您可以在作用中的串流目的地上變更此值。更新後，寫入 Kinesis 的串流記錄會以所需的精確度記錄 `ApproximateCreationDateTime` 值。
寫入 DynamoDB 的二進位值必須使用 [base64 編碼格式](HowItWorks.NamingRulesDataTypes.md)進行編碼。然而，當資料記錄寫入 Kinesis 資料串流時，這些編碼的二進位值會使用 base64 編碼再次編碼。從 Kinesis 資料串流讀取這些記錄時，為了擷取原始二進位值，應用程式必須將這些值解碼兩次。
使用 Kinesis Data Streams 時，DynamoDB 會根據變更資料擷取單位收取費用。每個單一項目的 1 KB 變更會計為一個變更資料擷取單位。使用與[寫入作業的容量單位耗用量](read-write-operations.md#write-operation-consumption)相同的邏輯，以寫入串流之項目的「之前」和「之後」映像中較大者，計算每個項目的 KB 變化量。運作方式與 DynamoDB [隨需](capacity-mode.md#capacity-mode-on-demand)模式類似，您不需要為變更資料擷取單位佈建容量輸送量。
### 為 DynamoDB 資料表開啟 Kinesis 資料串流
您可以使用 、 AWS 管理主控台 AWS SDK 或 AWS Command Line Interface ()，從現有的 DynamoDB 資料表啟用或停用串流至 Kinesis AWS CLI。
+ 您只能在與資料表相同的 AWS 帳戶和 AWS 區域中，將資料從 DynamoDB 串流到 Kinesis Data Streams。
+ 您只能將 DynamoDB 資料表中的資料串流至一個 Kinesis 資料串流。
### 在 DynamoDB 資料表上變更 Kinesis Data Streams 目的地
根據預設，所有 Kinesis 資料串流記錄都包含 `ApproximateCreationDateTime` 屬性。此屬性代表每個記錄建立當下約略的時間戳記，以毫秒為單位。您可以使用 [https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis)、 SDK 或 來變更這些值的精確度 AWS CLI
# Amazon DynamoDB 專用 Kinesis Data Streams 入門
本節說明如何搭配 Amazon DynamoDB 主控台、 AWS Command Line Interface (AWS CLI) 和 API 使用 Amazon DynamoDB 資料表的 Kinesis Data Streams。
## 建立作用中的 Amazon Kinesis 資料串流
所有這些範例都使用 `Music` DynamoDB 資料表，該資料表是在 [DynamoDB 入門](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)教學課程中建立的。
若要進一步了解如何建置取用者並將 Kinesis 資料串流連線至其他 AWS 服務，請參閱《Amazon Kinesis Data Streams 開發人員指南》**中的[從 Kinesis Data Streams 讀取資料](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)。
**注意**
第一次使用 KDS 碎片時，建議您將碎片設定為隨著使用模式向上擴展和縮減。累積更多使用模式的相關資料後，您可以調整串流中的碎片以進行配對。
------
#### [ Console ]
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/kinesis/](https://console.aws.amazon.com/kinesis/) 的 Kinesis 主控台。
1. 選擇 **Create data stream** (建立資料串流)，並依照說明來建立名為 `samplestream` 的串流。
1. 請在 [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 開啟 DynamoDB 主控台。
1. 在主控台左側的導覽窗格中，選擇 **Tables** (資料表)。
1. 選擇 **Music** (音樂) 資料表。
1. 選擇 **Exports and streams** (匯出與串流) 索引標籤。
1. (選用) 您可以在 **Amazon Kinesis 資料串流詳細資訊**下，將記錄時間戳記精確度從微秒 (預設) 變更為毫秒。
1. 從下拉式清單選擇 **samplestream** (範例串流)。
1. 選擇 **Turn On** (開啟) 按鈕。
------
#### [ AWS CLI ]
1. 使用 [create-stream 命令](https://docs.aws.amazon.com/cli/latest/reference/kinesis/create-stream.html)建立名為 `samplestream` 的 Kinesis 資料串流。
```
aws kinesis create-stream --stream-name samplestream --shard-count 3
```
請先參閱 [Kinesis Data Streams 的碎片管理考量事項](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment)，再為 Kinesis 資料串流設定碎片數量。
1. 使用 [describe-stream 命令](https://docs.aws.amazon.com/cli/latest/reference/kinesis/describe-stream.html)確認 Kinesis 串流是否處於作用中狀態且可供使用。
```
aws kinesis describe-stream --stream-name samplestream
```
1. 使用 DynamoDB `enable-kinesis-streaming-destination` 命令在 DynamoDB 資料表上啟用 Kinesis 串流功能。將 `stream-arn` 值替換為上一個步驟中傳回的值 `describe-stream`。可選擇性啟用時間戳記值精確度更精細 (微秒級) 的串流，傳回至每筆記錄上。
啟用微秒級時間戳記精確度串流：
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
--enable-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
或啟用預設時間戳記精確度串流 (毫秒級)：
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
```
1. 使用 DynamoDB `describe-kinesis-streaming-destination` 命令確認資料表上的 Kinesis 串流是否處於作用中狀態。
```
aws dynamodb describe-kinesis-streaming-destination --table-name Music
```
1. 使用 `put-item` 命令將資料寫入 DynamoDB 資料表，如《[DynamoDB 開發人員指南](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-2.html)》中所述。
```
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Call Me Today"}, "AlbumTitle": {"S": "Somewhat Famous"}, "Awards": {"N": "1"}}'
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"}, "AlbumTitle": {"S": "Songs About Life"}, "Awards": {"N": "10"} }'
```
1. 使用 Kinesis [get-records](https://docs.aws.amazon.com/cli/latest/reference/kinesis/get-records.html) CLI 命令來擷取 Kinesis 串流內容。然後使用下面的程式碼片段來將串流內容還原序列化。
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we want to fetch the value
* of this attribute from the new item image. The following code fetches this value.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
#### [ Java ]
1. 遵循《Kinesis Data Streams 開發人員指南》中的說明，使用 Java [建立](https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-create-stream.html)名為 `samplestream` 的 Kinesis 資料串流。
請先參閱 [Kinesis Data Streams 的碎片管理考量事項](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment)，再為 Kinesis 資料串流設定碎片數量。
1. 使用以下程式碼片段來啟用 DynamoDB 資料表上的 Kinesis 串流。可選擇性啟用時間戳記值精確度更精細 (微秒級) 的串流，傳回至每筆記錄上。
啟用微秒級時間戳記精確度串流：
```
EnableKinesisStreamingConfiguration enableKdsConfig = EnableKinesisStreamingConfiguration.builder()
.approximateCreationDateTimePrecision(ApproximateCreationDateTimePrecision.MICROSECOND)
.build();
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.enableKinesisStreamingConfiguration(enableKdsConfig)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
或啟用預設時間戳記精確度串流 (毫秒級)：
```
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
1. 遵循《Kinesis Data Streams 開發人員指南》中的說明，從建立的資料串流中進行[讀取](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)。
1. 然後使用下面的程式碼片段將串流內容還原序列化
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we wanted to fetch the value
* of this attribute from the new item image, the below code would fetch this.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
## 變更作用中的 Amazon Kinesis 資料串流
本節說明如何使用 主控台 AWS CLI 和 API 來變更作用中的 Kinesis Data Streams for DynamoDB 設定。
**AWS 管理主控台**
1. 請在 [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 開啟 DynamoDB 主控台。
1. 前往您的資料表。
1. 選擇**匯出與串流**。
**AWS CLI**
1. 呼叫 `describe-kinesis-streaming-destination` 以確認串流為 `ACTIVE`。
1. 呼叫 `UpdateKinesisStreamingDestination`，例如在此範例中：
```
aws dynamodb update-kinesis-streaming-destination --table-name enable_test_table --stream-arn arn:aws:kinesis:us-east-1:12345678901:stream/enable_test_stream --update-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
1. 呼叫 `describe-kinesis-streaming-destination` 以確認串流為 `UPDATING`。
1. 定期呼叫 `describe-kinesis-streaming-destination`，直到串流狀態再次變成 `ACTIVE` 為止。時間戳記精確度更新通常需要 5 分鐘才會生效。一旦此狀態更新，表示更新已完成，且新的精確度值將套用至未來的記錄。
1. 使用 `putItem` 寫入資料表。
1. 使用 Kinesis `get-records` 命令來取得串流內容。
1. 確認寫入的 `ApproximateCreationDateTime` 具有所需的精確度。
**Java API**
1. 提供可建構 `UpdateKinesisStreamingDestination` 請求和 `UpdateKinesisStreamingDestination` 回應的程式碼片段。
1. 提供可建構 `DescribeKinesisStreamingDestination` 請求和 `DescribeKinesisStreamingDestination response` 回應的程式碼片段。
1. 定期呼叫 `describe-kinesis-streaming-destination`，直到串流狀態再次變成 `ACTIVE`，表示更新已完成，且新的精確度值將套用至未來的記錄。
1. 執行對資料表的寫入。
1. 從串流讀取並還原序列化串流內容。
1. 確認寫入的 `ApproximateCreationDateTime` 具有所需的精確度。
# 以 DynamoDB Streams 和 Kinesis Data Streams 使用碎片和指標
## Kinesis Data Streams 的碎片管理考量事項
Kinesis 資料串流會計算其在[碎片](https://docs.aws.amazon.com/streams/latest/dev/key-concepts.html)中的輸送量。在 Amazon Kinesis Data Streams 中，您可為資料串流選擇**隨需**模式或**佈建**模式。
如果您的 DynamoDB 寫入工作負載高度可變且無法預測，我們建議您使用 Kinesis Data Streams 的隨需模式。使用隨需模式時，無需容量規劃，因為 Kinesis Data Streams 會自動管理碎片，提供必要的輸送量。
對於可預測的工作負載，您可以針對 Kinesis Data Stream 使用佈建模式。採用佈建模式，必須指定資料串流的碎片數目，以容納來自 DynamoDB 的變更資料擷取紀錄。若要判斷 Kinesis 資料串流支援 DynamoDB 資料表所需的碎片數目，您需要以下輸入值：
+ DynamoDB 資料表紀錄的平均大小 (以位元組為單位) (`average_record_size_in_bytes`)。
+ 您的 DynamoDB 資料表上將執行的每秒寫入操作數目上限。這包括應用程式執行的建立、刪除和更新操作，以及自動產生的操作，例如「存留時間」產生的刪除操作 (`write_throughput`)。
+ 與建立或刪除操作相比，您在資料表上執行的更新和覆寫操作的百分比 (`percentage_of_updates`)。請注意，更新和覆寫操作會將已修改項目的舊映像和新映像複製到串流。因此產生兩倍大小的 DynamoDB 項目。
您可使用以下公式帶入輸入值，計算 Kinesis 資料串流所需的碎片數目 (`number_of_shards`)：
```
number_of_shards = ceiling( max( ((write_throughput * (4+percentage_of_updates) * average_record_size_in_bytes) / 1024 / 1024), (write_throughput/1000)), 1)
```
例如，您可能有每秒 1040 個寫入操作 (`write_throughput`) 的最大輸送量，平均記錄大小為 800 位元組 (`average_record_size_in_bytes)`。如果其中 25% 的寫入操作為更新操作 (`percentage_of_updates`)，您需要兩個碎片 (`number_of_shards`) 以容納 DynamoDB 串流輸送量：
```
ceiling( max( ((1040 * (4+25/100) * 800)/ 1024 / 1024), (1040/1000)), 1).
```
使用公式計算 Kinesis 資料串流佈建模式所需的碎片數量之前，請考慮下列事項：
+ 此公式有助於預估容納 DynamoDB 變更資料記錄所需的碎片數量。其不代表 Kinesis 資料串流中所需的碎片總數，例如支援額外 Kinesis 資料串流取用者所需的碎片數量。
+ 如果您未設定處理尖峰輸送量的資料串流，則可能仍會在佈建模式中遇到讀取和寫入輸送量例外狀況。在這種情形下，您必須手動擴展資料串流以適應資料流量。
+ 此公式會考量 DynamoDB 將變更日誌資料記錄串流至 Kinesis Data Stream 之前，所產生的額外膨脹。
如需進一步了解 Kinesis Data Stream 上的容量模式，請參閱[選擇資料串流容量模式](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-size-a-stream.html)。如需進一步了解不同容量模式之間的定價差異，請參閱 [Amazon Kinesis Data Streams 定價](https://aws.amazon.com/kinesis/data-streams/pricing/)。
## 使用 Kinesis Data Streams 監控變更資料擷取
DynamoDB 提供數個 Amazon CloudWatch 指標，可協助您監控將變更資料擷取到 Kinesis 的複寫。如需 CloudWatch 指標的完整清單，請參閱 [DynamoDB 指標和維度](metrics-dimensions.md)。
為判斷串流是否有足夠的容量，建議您在啟用串流期間和生產環境期間監控下列項目：
+ `ThrottledPutRecordCount`：因為 Kinesis 資料串流容量不足而受到 Kinesis Data Streams 限流的記錄數量。儘管在特殊使用峰值期間，您可能會遇到限流的情況，仍應盡可能降低 `ThrottledPutRecordCount`。DynamoDB 會重試將限流記錄傳送到 Kinesis 資料串流，但這可能會導致較高的複寫延遲。
如果遇到過多且規律的限流，您可能需要按照觀察到的資料表寫入輸送量按比例增加 Kinesis 串流碎片的數量。若要進一步了解如何判斷 Kinesis 資料串流的大小，請參閱[判斷 Kinesis Data Stream 的初始大小](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html#how-do-i-size-a-stream)。
+ `AgeOfOldestUnreplicatedRecord`：自 DynamoDB 資料表中出現尚未複寫到 Kinesis 資料串流的最舊項目層級變更以來經過的時間。在正常的操作下，`AgeOfOldestUnreplicatedRecord` 應該以毫秒為單位。當不成功的複寫嘗試是因客戶控制的組態選擇所引起時，此數字會隨著不成功複寫嘗試的增加而增加。
如果 `AgeOfOldestUnreplicatedRecord` 指標超過 168 小時，從 DynamoDB 資料表到 Kinesis 資料串流的項目層級變更複寫將自動停用。
可能導致複寫嘗試失敗的客戶控制組態示例包括，佈建的 Kinesis 資料串流容量不足導致過度限流，或是手動更新 Kinesis 資料串流的存取政策因而拒絕 DynamoDB 新增資料至您的資料串流。為盡可能降低此指標，您可能需要確保妥善佈建您的 Kinesis 資料串流容量，並確保 DynamoDB 的許可保持不變。
+ `FailedToReplicateRecordCount`：DynamoDB 無法複寫到您的 Kinesis 資料串流的記錄數目。大於 34KB 的某些項目可能會擴充大小，以變更大於 Kinesis Data Streams 1MB 項目大小限制的資料記錄。當這些大於 34KB 的項目包含大量的布林值或空白屬性值時，就會發生此大小擴充。布林值和空白屬性值會以 1 位元組形式儲存在 DynamoDB 中，但是在使用用於 Kinesis Data Streams 複寫的標準 JSON 將其序列化時，最多可擴充至 5 個位元組。DynamoDB 無法將這類變更記錄複寫到您的 Kinesis 資料串流。DynamoDB 會略過這些變更資料記錄，並自動繼續複寫後續記錄。
您可以建立 Amazon CloudWatch 警示，以便在上述任何指標超過特定閾值時，傳送 Amazon Simple Notification Service (Amazon SNS) 通知訊息。
# 使用 Amazon Kinesis Data Streams 和 Amazon DynamoDB 專用的 IAM 政策
第一次為 Amazon DynamoDB 啟用 Amazon Kinesis Data Streams 時，DynamoDB 會自動為您建立 AWS Identity and Access Management (IAM) 服務連結角色。 DynamoDB 這個角色 (`AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`) 可讓 DynamoDB 代表您管理對 Kinesis Data Streams 的項目層級變更的複寫。請勿刪除此服務連結角色。
如需服務連結角色的詳細資訊，請參閱《*IAM 使用者指南*》中的[使用服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)。
**注意**
DynamoDB 不支援 IAM 政策的標籤型條件。
若要啟用 Amazon DynamoDB 專用 Amazon Kinesis Data Streams，您必須擁有下列資料表許可：
+ `dynamodb:EnableKinesisStreamingDestination`
+ `kinesis:ListStreams`
+ `kinesis:PutRecords`
+ `kinesis:DescribeStream`
若要為指定的 DynamoDB 資料表描述 Amazon DynamoDB 專用 Amazon Kinesis Data Streams，您必須擁有下列資料表許可。
+ `dynamodb:DescribeKinesisStreamingDestination`
+ `kinesis:DescribeStreamSummary`
+ `kinesis:DescribeStream`
若要停用 Amazon DynamoDB 專用 Amazon Kinesis Data Streams，您必須擁有下列資料表許可。
+ `dynamodb:DisableKinesisStreamingDestination`
若要更新 Amazon DynamoDB 專用 Amazon Kinesis Data Streams，您必須擁有下列資料表許可。
+ `dynamodb:UpdateKinesisStreamingDestination`
下列範例顯示如何使用 IAM 政策授予 Amazon DynamoDB 專用 Amazon Kinesis Data Streams 的許可。
## 範例：啟用 Amazon DynamoDB 專用 Amazon Kinesis Data Streams
以下 IAM 政策會授予 `Music` 資料表啟用 Amazon DynamoDB 專用 Amazon Kinesis Data Streams 的許可。其不會授予 `Music` 資料表停用、更新或描述 DynamoDB 專用 Kinesis Data Streams 的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/kinesisreplication.dynamodb.amazonaws.com/AWSServiceRoleForDynamoDBKinesisDataStreamsReplication",
"Condition": {
"StringLike": {
"iam:AWSServiceName": "kinesisreplication.dynamodb.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## 範例：更新 Amazon DynamoDB 專用 Amazon Kinesis Data Streams
以下 IAM 政策會授予 `Music` 資料表更新 Amazon DynamoDB 專用 Amazon Kinesis Data Streams 的許可。其不會授予 `Music` 資料表啟用、停用或描述 Amazon DynamoDB 專用 Amazon Kinesis Data Streams 的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:UpdateKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## 範例：停用 Amazon DynamoDB 專用 Amazon Kinesis Data Streams
以下 IAM 政策會授予 `Music` 資料表停用 Amazon DynamoDB 專用 Amazon Kinesis Data Streams 的許可。其不會授予 `Music` 資料表啟用、更新或描述 Amazon DynamoDB 專用 Amazon Kinesis Data Streams 的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## 範例：根據資源選擇性地為 Amazon DynamoDB 專用 Amazon Kinesis Data Streams 套用許可
下列 IAM 政策會授予 `Music` 資料表啟用及描述 Amazon DynamoDB 專用 Amazon Kinesis Data Streams 的許可，但不會授予 `Orders` 資料表停用 Amazon DynamoDB 專用 Amazon Kinesis Data Streams 的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination",
"dynamodb:DescribeKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
},
{
"Effect": "Deny",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Orders"
}
]
}
```
------
## 為 DynamoDB 專用 Kinesis Data Streams 使用服務連結角色
Amazon DynamoDB 的 Amazon Kinesis Data Streams 使用 AWS Identity and Access Management (IAM)[ 服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role)。 DynamoDB 服務連結角色是特殊類型的 IAM 角色，此角色可直接連結到 DynamoDB 專用 Kinesis Data Streams。服務連結角色由適用於 DynamoDB 的 Kinesis Data Streams 預先定義，並包含該服務代表您呼叫其他 AWS 服務所需的所有許可。
服務連結角色可讓 DynamoDB 專用 Kinesis Data Streams 的設定更為簡單，因為您不必手動新增必要的許可。DynamoDB 專用 Kinesis Data Streams 會定義其服務連結角色的許可，除非另有定義，否則僅有 DynamoDB 專用 Kinesis Data Streams 可以擔任其角色。定義的許可包括信任政策和許可政策，並且該許可政策不能連接到任何其他 IAM 實體。
如需關於支援服務連結角色的其他服務的資訊，請參閱[可搭配 IAM 運作的AWS 服務](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)，並尋找 **Service-Linked Role** (服務連結角色) 欄顯示為 **Yes** (是) 的服務。選擇具有連結的 **Yes** (是)，以檢視該服務的服務連結角色文件。
### DynamoDB 專用 Kinesis Data Streams 的服務連結角色許可
DynamoDB 專用 Kinesis Data Streams 會使用名為 **AWSServiceRoleForDynamoDBKinesisDataStreamsReplication** 的服務連結角色。服務連結角色的目的是讓 Amazon DynamoDB 代表您管理對 Kinesis Data Streams 項目層級變更的複寫。
`AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` 服務連結角色信任下列服務以擔任角色：
+ `kinesisreplication.dynamodb.amazonaws.com`
此角色許可政策允許 DynamoDB 專用 Kinesis Data Streams 對指定資源完成下列動作：
+ 動作：`Kinesis stream` 上的 `Put records and describe`
+ 動作：`Generate data keys`開啟 `AWS KMS` 以將資料放置在使用使用者產生 AWS KMS 金鑰加密的 Kinesis 串流上。
如需政策文件的確切內容，請參閱 [DynamoDBKinesisReplicationServiceRolePolicy](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/aws-service-role/DynamoDBKinesisReplicationServiceRolePolicy)。
您必須設定許可，IAM 實體 (如使用者、群組或角色) 才可建立、編輯或刪除服務連結角色。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[服務連結角色許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#service-linked-role-permissions)。
### 為 DynamoDB 專用 Kinesis Data Streams 建立服務連結角色
您不需要手動建立服務連結角色，當您在 AWS 管理主控台、 AWS CLI或 AWS API 中啟用 DynamoDB 的 Kinesis Data Streams 時，DynamoDB 的 Kinesis Data Streams 會為您建立服務連結角色。
若您刪除此服務連結角色，之後需要再次建立，您可以在帳戶中使用相同程序重新建立角色。在啟用 DynamoDB 專用 Kinesis Data Streams 時，DynamoDB 專用 Kinesis Data Streams 會再次為您建立服務連結角色。
### 為 DynamoDB 專用 Kinesis Data Streams 編輯服務連結角色
DynamoDB 專用 Kinesis Data Streams 不允許您編輯 `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` 服務連結角色。因為有各種實體可能會參考服務連結角色，所以您無法在建立角色之後變更角色名稱。然而，您可使用 IAM 來編輯角色描述。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[編輯服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#edit-service-linked-role)。
### 為 DynamoDB 專用 Kinesis Data Streams 刪除服務連結角色
您也可以使用 IAM 主控台、 AWS CLI 或 AWS API 手動刪除服務連結角色。若要執行此操作，您必須先手動清除服務連結角色的資源，然後才能手動刪除它。
**注意**
若 DynamoDB 專用 Kinesis Data Streams 服務在您試圖刪除資源時正在使用該角色，刪除可能會失敗。若此情況發生，請等待數分鐘後並再次嘗試操作。
**使用 IAM 手動刪除服務連結角色**
使用 IAM 主控台 AWS CLI、 或 AWS API 來刪除`AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`服務連結角色。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[刪除服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)。
# DynamoDB Streams 的變更資料擷取
DynamoDB Streams 可擷取任何 DynamoDB 資料表中依時間順序排序的項目層級修改，並將此資訊存放於日誌中長達 24 小時。應用程式可以存取此日誌，並近乎即時地檢視資料項目修改前後的顯示內容。
靜態加密功能會加密 DynamoDB Streams 中的資料。如需詳細資訊，請參閱 [DynamoDB 靜態加密](EncryptionAtRest.md)。
*DynamoDB 串流*是 DynamoDB 資料表中項目變更資訊的排序流程。當您在資料表啟用串流時，DynamoDB 會擷取資料表中資料項目的每項修改資訊。
應用程式每次建立、更新或刪除資料表中的項目時，DynamoDB Streams 都會使用已修改項目的主索引鍵屬性寫入串流紀錄。*串流紀錄*包含 DynamoDB 資料表中單一項目資料修改的相關資訊。您可以設定串流，讓串流紀錄擷取其他資訊，例如修改項目的「之前」與「之後」影像。
DynamoDB Streams 可協助確保下列事項：
+ 每個串流紀錄只在串流中出現一次。
+ 對於 DynamoDB 資料表中的每個修改項目，串流紀錄的出現順序與項目的實際修改順序相同。
DynamoDB Streams 會近乎即時地寫入串流紀錄，讓您可以建立使用這些串流並根據內容採取動作的應用程式。
**Topics**
+ [DynamoDB Streams 的端點](#Streams.Endpoints)
+ [啟用串流](#Streams.Enabling)
+ [讀取及處理串流](#Streams.Processing)
+ [DynamoDB Streams 和存留時間](time-to-live-ttl-streams.md)
+ [使用 DynamoDB Streams Kinesis 轉接器處理串流記錄](Streams.KCLAdapter.md)
+ [DynamoDB Streams 低階 API：Java 範例](Streams.LowLevel.Walkthrough.md)
+ [DynamoDB 串流和 AWS Lambda 觸發](Streams.Lambda.md)
+ [DynamoDB Streams 和 Apache Flink](StreamsApacheFlink.xml.md)
## DynamoDB Streams 的端點
AWS 會維護 DynamoDB 和 DynamoDB Streams 的個別端點。為了使用資料庫資料表與索引，應用程式必須能存取 DynamoDB 端點。為了讀取及處理 DynamoDB Streams 紀錄，應用程式必須能存取同一區域中的 DynamoDB Streams 端點。
DynamoDB Streams 提供兩組端點。這些類別為：
+ **IPv4-only 端點**：具有命名慣例的端點。 `streams.dynamodb..amazonaws.com`
+ **雙堆疊端點**：與 IPv4 和 IPv6 相容並遵循`streams-dynamodb..api.aws`命名慣例的新端點。
**注意**
如需 DynamoDB 和 DynamoDB Streams 區域與端點的完整清單，請參閱 *AWS 一般參考* 中的[區域與端點](https://docs.aws.amazon.com/general/latest/gr/rande.html)。
AWS SDKs 為 DynamoDB 和 DynamoDB Streams 提供單獨的用戶端。視您需求的不同，應用程式可以存取 DynamoDB 端點、DynamoDB Streams 端點，或同時存取這兩種端點。若要連線到這兩種端點，您的應用程式必須具體化兩個用戶端：一個用於 DynamoDB，另一個用於 DynamoDB Streams。
## 啟用串流
您可以使用 AWS CLI 或其中一個 AWS SDKs 在新資料表上啟用串流。您也可以在現有的資料表上啟用或停用串流，或變更串流的設定。DynamoDB Streams 會以非同步方式運作，因此若您啟用串流，也不會影響資料表的效能。
管理 DynamoDB Streams 最簡單的方式就是使用 AWS 管理主控台。
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 開啟 DynamoDB 主控台。
1. 在 DynamoDB 主控台儀表板上，選擇 **Tables** (資料表)，然後選取現有的資料表。
1. 選擇 **Exports and streams** (匯出與串流) 索引標籤。
1. 在 **DynamoDB 串流詳細資訊**區段中，選擇**開啟**。
1. 在**開啟 DynamoDB 串流**頁面中，選擇每次修改資料表資料時會寫入串流的資訊：
+ **僅限金鑰屬性**：僅已修改項目的金鑰屬性。
+ **新映像**：在修改後出現的整個項目。
+ **舊映像**：在修改前出現的整個項目。
+ **新舊映像**：項目的新舊映像。
當您滿意設定後，請選擇**開啟串流**。
1. (選用) 若要停用現有的串流，請選擇 **DynamoDB 串流詳細資訊**下的**關閉**。
您也可以使用 `CreateTable` 或 `UpdateTable` API 操作來啟用或修改串流。`StreamSpecification` 參數可決定串流的設定方式：
+ `StreamEnabled`：指定是否啟用 (`true`) 或停用 (`false`) 資料表的串流。
+ `StreamViewType`：指定每次修改資料表資料時，將會寫入串流的資訊：
+ `KEYS_ONLY`：僅已修改項目的索引鍵屬性。
+ `NEW_IMAGE`：在修改後出現的整個項目。
+ `OLD_IMAGE`：在修改前出現的整個項目。
+ `NEW_AND_OLD_IMAGES`：項目的新舊映像。
您可以隨時啟用或停用串流。但若嘗試在已有串流的資料表中啟用串流，就會收到 `ValidationException`。若嘗試在沒有串流的資料表中停用串流，也會收到 `ValidationException`。
當您將 `StreamEnabled` 設定為 `true` 時，DynamoDB 會建立新的串流，並對其指派唯一的串流描述項。如果您停用再重新啟用資料表串流，則會使用不同的串流描述項建立新的串流。
每個串流都可依 Amazon Resource Name (ARN) 唯一識別。以下是名為 `TestTable` 的 DynamoDB 資料表上串流的 ARN 範例。
```
arn:aws:dynamodb:us-west-2:111122223333:table/TestTable/stream/2015-05-11T21:21:33.291
```
若要判斷資料表的最新串流描述項，請發出 DynamoDB `DescribeTable` 請求，並尋找回應中的 `LatestStreamArn` 元素。
**注意**
一旦串流設定完畢，就無法再編輯 `StreamViewType`。若您需要變更已設定完畢的串流，就必須停用目前的串流並建立一個新的串流。
## 讀取及處理串流
若要讀取及處理串流，您的應用程式必須連線到 DynamoDB Streams 端點，並發出 API 請求。
串流由*串流紀錄*所組成。每個串流紀錄均代表串流所屬之 DynamoDB 資料表中的一項資料修改。每個串流紀錄會獲派一個序號，其反映出紀錄發布至串流的順序。
串流紀錄會整理成群組，即*碎片*。每個碎片皆代表多個串流紀錄的容器，並含有存取及重複處理這些紀錄所需的資訊。碎片內的串流紀錄會在 24 小時後自動移除。
碎片為暫時性：系統會視需要自動建立及刪除這些碎片。任何碎片還可分割成多個新的碎片，這也會自動發生。(父碎片也可能只有一個子碎片。) 碎片可能會為了回應其父資料表上的上層寫入活動而分割，讓應用程式可同時處理多個碎片中的紀錄。
如果您停用串流，所有開啟的碎片都會關閉。串流中的資料在 24 小時內仍可供讀取。
由於碎片具有系屬關係 (父系與子系)，因此應用程式一律必須先處理父碎片，再處理子碎片。這有利於確保串流紀錄也按照正確順序處理。(如果您使用的是 DynamoDB Streams Kinesis 轉接器，則系統會為您處理這個問題。應用程式會依正確順序處理碎片和串流紀錄。除了當應用程式正在執行時分割的碎片，其還會自動處理新的或過期碎片。如需詳細資訊，請參閱 [使用 DynamoDB Streams Kinesis 轉接器處理串流記錄](Streams.KCLAdapter.md)。)
下圖說明串流、串流中的碎片及碎片中的串流紀錄之間的關係。
![\[DynamoDB Streams 結構。代表資料修改的串流記錄，會以碎片的形式組織。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/streams-terminology.png)
**注意**
如果您執行的 `PutItem` 或 `UpdateItem` 操作不會變更項目中的任何資料，則 DynamoDB Streams *不會*寫入該操作的串流紀錄。
若要存取串流及處理其中的串流紀錄，您必須執行下列操作：
+ 判斷您要存取之串流的唯一 ARN。
+ 判斷串流中包含您感興趣之串流紀錄的碎片。
+ 存取碎片及擷取您要的串流紀錄。
**注意**
最多不得同時從同一個串流碎片讀取 2 個以上的處理程序。每個碎片具有 2 個以上的讀取器會導致限流。
DynamoDB Streams API 提供下列可讓應用程式使用的動作：
+ `[ListStreams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_ListStreams.html)`：傳回目前帳戶及端點的串流描述項清單。您可以只選擇性地請求特定資料表名稱的串流描述項。
+ `[DescribeStream](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_DescribeStream.html)` – 傳回串流相關資訊，包含目前串流狀態，其 Amazon Resource Name (ARN)、構成的碎片數量，以及其對應的 DynamoDB 資料表。您可以選擇性使用 `ShardFilter` 欄位擷取與父碎片相關的現有子碎片。
+ `[GetShardIterator](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetShardIterator.html)`：傳回*碎片疊代運算*，其描述了碎片內的位置。您可以請求疊代運算提供串流中最舊點、最新點或特定點的存取權。
+ `[GetRecords](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetRecords.html)`：傳回指定碎片內的串流紀錄。您必須提供從 `GetShardIterator` 請求傳回的碎片疊代運算。
如需這些 API 操作的完整說明 (包括範例請求與回應)，請參閱《[Amazon DynamoDB Streams API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations_Amazon_DynamoDB_Streams.html)》。
### 碎片探索
使用兩項強大的方法來探索 DynamoDB 串流中的新碎片。Amazon DynamoDB Streams 使用者可以透過兩種有效的方式追蹤並識別新的碎片：
**輪詢整個串流拓撲**
使用 `DescribeStream` API 定期輪詢串流。此步驟會傳回串流中的所有碎片，包括任何已建立的新碎片。您可以透過比較結果，偵測新增的碎片。
**探索子碎片**
使用 `DescribeStream` API 搭配 `ShardFilter` 參數以尋找碎片的子集。透過在請求中指定父碎片，DynamoDB Streams 會傳回其直屬子碎片。此方法適用於僅追蹤碎片譜系，而不掃描整個串流的情況。
從 DynamoDB Streams 取用資料的應用程式，可使用 `ShardFilter` 參數，有效地從讀取封閉碎片，轉換為讀取其子碎片，避免重複呼叫 `DescribeStream` API，以擷取和周遊所有封閉及開啟碎片的碎片對應。這有助於在父碎片關閉後快速探索子碎片，提高串流處理應用程式的回應性並更符合成本效益。
這兩項方法都有助於您掌握 DynamoDB Streams 不斷變化的結構，確保您不會錯過重要的資料更新或碎片修改。
### DynamoDB Streams 的資料保留限制
DynamoDB Streams 中所有資料的生命週期皆為 24 小時。您可以擷取並分析任何指定資料表過去 24 小時的活動。但超過 24 小時的資料容易隨時受到裁剪 (移除) 的影響。
如果您停用資料表的串流，則串流中的資料在 24 小時內仍可供讀取。過了這段時間後，資料就會過期，且串流紀錄也會自動刪除。沒有手動刪除現有串流的機制。您必須等到保留限制過期 (24 小時)，所有串流紀錄才會被刪除。
# DynamoDB Streams 和存留時間
您可以備份或處理[存留時間](TTL.md) (TTL) 刪除的項目，方法是在資料表上啟用 Amazon DynamoDB Streams 並處理過期項目的串流紀錄。如需詳細資訊，請參閱[讀取及處理串流](Streams.md#Streams.Processing)。
串流紀錄包含使用者身分欄位 `Records[].userIdentity`。
存留時間程序在過期後刪除的項目具有下列欄位：
+ `Records[].userIdentity.type`
`"Service"`
+ `Records[