本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
AWS::DynamoDB::Table
資源會建立 DynamoDB 資料表。如需詳細資訊,請參閱《Amazon DynamoDB API 參考》中的 CreateTable。
使用 DynamoDB 資料表時,您應該注意下列行為:
-
AWS CloudFormation 通常會平行建立 DynamoDB 資料表。但是,如果您的範本包含多個具備索引的 DynamoDB 資料表,則必須宣告依存項目才能循序建立資料表。Amazon DynamoDB 處於建立狀態時,會限制具備輔助索引的資料表數量。若您同時建立多個具備索引的資料表,DynamoDB 將傳回錯誤且堆疊操作會失敗。如需範例,請參閱具備 DependsOn 屬性的 DynamoDB 資料表。
重要
我們的指引是使用 AWS CloudFormation 範本記錄的最新結構描述。此結構描述支援下列所有資料表設定的佈建。在 AWS CloudFormation 範本中使用此結構描述時,請確保您的身分與存取管理 (IAM) 政策已更新,並具有適當的許可,以允許授權這些設定變更。
語法
若要在 AWS CloudFormation 範本中宣告此實體,請使用下列語法:
JSON
{
"Type" : "AWS::DynamoDB::Table",
"Properties" : {
"AttributeDefinitions" : [ AttributeDefinition, ... ]
,
"BillingMode" : String
,
"ContributorInsightsSpecification" : ContributorInsightsSpecification
,
"DeletionProtectionEnabled" : Boolean
,
"GlobalSecondaryIndexes" : [ GlobalSecondaryIndex, ... ]
,
"ImportSourceSpecification" : ImportSourceSpecification
,
"KeySchema" : [ KeySchema, ... ]
,
"KinesisStreamSpecification" : KinesisStreamSpecification
,
"LocalSecondaryIndexes" : [ LocalSecondaryIndex, ... ]
,
"OnDemandThroughput" : OnDemandThroughput
,
"PointInTimeRecoverySpecification" : PointInTimeRecoverySpecification
,
"ProvisionedThroughput" : ProvisionedThroughput
,
"ResourcePolicy" : ResourcePolicy
,
"SSESpecification" : SSESpecification
,
"StreamSpecification" : StreamSpecification
,
"TableClass" : String
,
"TableName" : String
,
"Tags" : [ Tag, ... ]
,
"TimeToLiveSpecification" : TimeToLiveSpecification
,
"WarmThroughput" : WarmThroughput
}
}
YAML
Type: AWS::DynamoDB::Table
Properties:
AttributeDefinitions:
- AttributeDefinition
BillingMode: String
ContributorInsightsSpecification:
ContributorInsightsSpecification
DeletionProtectionEnabled: Boolean
GlobalSecondaryIndexes:
- GlobalSecondaryIndex
ImportSourceSpecification:
ImportSourceSpecification
KeySchema:
- KeySchema
KinesisStreamSpecification:
KinesisStreamSpecification
LocalSecondaryIndexes:
- LocalSecondaryIndex
OnDemandThroughput:
OnDemandThroughput
PointInTimeRecoverySpecification:
PointInTimeRecoverySpecification
ProvisionedThroughput:
ProvisionedThroughput
ResourcePolicy:
ResourcePolicy
SSESpecification:
SSESpecification
StreamSpecification:
StreamSpecification
TableClass: String
TableName: String
Tags:
- Tag
TimeToLiveSpecification:
TimeToLiveSpecification
WarmThroughput:
WarmThroughput
屬性
AttributeDefinitions
-
屬性清單,這些屬性會說明表格與索引的索引鍵結構描述;
此屬性是建立 DynamoDB 資料表的必要屬性。
更新需求:部分中斷。若您編輯了現有的 AttributeDefinition,則需要進行替換。
必要:有條件
類型:AttributeDefinition 陣列
更新要求:不中斷
BillingMode
-
指定如何向您收取讀取與寫入傳輸量的費用,以及您如何管理容量。
有效值包含:
若沒有指定,則預設為
PROVISIONED
。必要:否
類型:字串
允許值:
PROVISIONED | PAY_PER_REQUEST
更新要求:不中斷
ContributorInsightsSpecification
-
用來啟用或停用指定資料表的 CloudWatch Contributor Insights 的設定。
必要:否
類型:ContributorInsightsSpecification
更新要求:不中斷
DeletionProtectionEnabled
-
判斷資料表是否受到保護,不會遭到刪除。啟用時,任何使用者或程序都無法刪除資料表。根據預設,停用此設定。如需詳細資訊,請參閱《Amazon DynamoDBDeveloper 指南》中的使用刪除保護。
必要:否
類型:布林值
更新要求:不中斷
GlobalSecondaryIndexes
-
資料表上待建立的全域次要索引;您最多可以建立 20 個全域輔助索引。
重要
如果您更新資料表以包含新的全域次要索引, 會 AWS CloudFormation 啟動索引建立,然後繼續堆疊更新。 AWS CloudFormation 不會等待索引建立完成,因為回填階段可能需要很長的時間,取決於資料表的大小。您必須等到索引的狀態顯示為
ACTIVE
,才能使用該索引或更新資料表。您可以使用 DynamoDB DescribeTable 命令來追蹤其狀態。如果您在更新期間新增或刪除索引,我們建議不要更新任何其他資源。若您的堆疊更新失敗並在新增新索引時復原,您必須手動刪除索引。
不支援更新。以下為例外:
-
如果您更新 Contributor Insights 規格或全域輔助索引的佈建輸送量值,便可以在不發生中斷的情況下更新資料表。
-
您可以刪除或新增一個全域輔助索引,而不會發生中斷。若您在相同的更新中同時進行兩個動作 (例如變更索引的邏輯 ID),則更新會失敗。
必要:否
類型:GlobalSecondaryIndex 陣列
更新要求:不中斷
-
ImportSourceSpecification
-
指定要從 S3 儲存貯體來源匯入至「資料表」的資料屬性。
重要
如果您指定
ImportSourceSpecification
屬性,也指定StreamSpecification
、TableClass
屬性、DeletionProtectionEnabled
屬性或WarmThroughput
屬性,則建立/更新堆疊的 IAM 實體必須具有UpdateTable
許可。必要:否
更新要求:替換
KeySchema
-
可藉由此屬性來指定資料表所含的主要索引鍵屬性。
AttributeDefinitions
屬性中也必須定義KeySchema
屬性中的屬性。必要:是
更新要求:部分中斷
KinesisStreamSpecification
-
指定資料表的 Kinesis Data Streams 組態。
必要:否
更新要求:不中斷
LocalSecondaryIndexes
-
資料表上待建立的本機次要索引;最多可以建立 5 個本機次要索引。每個索引的範圍不得超過指定的雜湊索引鍵值,而每個雜湊索引鍵的大小最高可達 10 GB。
必要:否
類型:LocalSecondaryIndex 陣列
更新要求:不中斷
OnDemandThroughput
-
設定指定隨需資料表的讀取和寫入單位數量上限。如果您使用此屬性,則必須指定
MaxReadRequestUnits
、MaxWriteRequestUnits
或兩者。必要:否
更新要求:不中斷
PointInTimeRecoverySpecification
-
用於啟用時間點復原恢復的設定。
必要:否
類型:PointInTimeRecoverySpecification
更新要求:不中斷
ProvisionedThroughput
-
指定資料表的輸送量,包括
ReadCapacityUnits
與WriteCapacityUnits
的值。如需佈建輸送量結構內容的詳細資訊,請參閱 Amazon DynamoDB 資料表 ProvisionedThroughput。若您將
BillingMode
設為PROVISIONED
,您必須指定此屬性。若您將BillingMode
設為PAY_PER_REQUEST
,您便無法指定此屬性。必要:有條件
更新要求:不中斷
ResourcePolicy
-
以資源為基礎的政策文件,其中包含可新增至指定資料表的許可。在 CloudFormation 範本中,您可以提供 JSON 或 YAML 格式的政策,因為 會將 YAML CloudFormation 轉換為 JSON,然後再提交給 DynamoDB。如需資源型政策的詳細資訊,請參閱針對 和 資源型政策範例使用 DynamoDB資源型政策。
當您在建立資料表時連接以資源為基礎的政策時,政策建立會非常一致。如需附加資源型政策時應謹記之考量事項的相關資訊,請參閱資源型政策考量事項。
必要:否
更新要求:不中斷
SSESpecification
-
指定此屬性來啟用伺服器端加密。
必要:否
更新要求:部分中斷
StreamSpecification
-
DynamoDB 資料表串流的設定,可擷取對存放在資料表中項目的變更。
必要:否
更新要求:不中斷
TableClass
-
新資料表的資料表類別。有效值為
STANDARD
和STANDARD_INFREQUENT_ACCESS
。必要:否
類型:字串
允許值:
STANDARD | STANDARD_INFREQUENT_ACCESS
更新要求:不中斷
TableName
-
資料表的名稱。如果您未指定名稱, AWS CloudFormation 會產生唯一的實體 ID,並將該 ID 用於資料表名稱。如需詳細資訊,請參閱名稱類型。
重要
若指定名稱,則無法執行需要替換該資源的更新。可執行不需中斷或僅需部分中斷的更新作業。若一定要替換此資源,請指定一個新名稱。
必要:否
類型:字串
下限:
1
上限:
1024
更新要求:替換
-
要套用到此資源的鍵/值對陣列。
如需詳細資訊,請參閱標籤。
必要:否
類型:標籤陣列
更新要求:不中斷
TimeToLiveSpecification
-
指定資料表的存留時間 (TTL) 設定。
注意
如需 DynamoDB 中限制的詳細資訊,請參閱《Amazon DynamoDB 開發人員指南》中的 Amazon DynamoDB 中的限制。
必要:否
更新要求:不中斷
WarmThroughput
-
代表建立資料表的暖輸送量 (以每秒讀取單位和每秒寫入單位為單位)。
必要:否
類型: WarmThroughput
更新要求:不中斷
傳回值
Ref
當您將此資源的邏輯 ID 傳遞至內部 Ref
函數時,Ref
函數便會傳回資源名稱。例如:
{ "Ref": "myDynamoDBTable" }
針對邏輯 ID 為 myDynamoDBTable
的資源,Ref
會傳回 DynamoDB 資料表名稱。
如需使用 Ref
函數的詳細資訊,請參閱 Ref
。
Fn::GetAtt
Fn::GetAtt
內部函數會傳回此類型之指定屬性的值。以下為可用屬性及傳回值的範例。
如需有關使用 Fn::GetAtt
內部函數的詳細資訊,請參閱 Fn::GetAtt
。
Arn
-
DynamoDB 資料表的 Amazon Resource Name (ARN),例如
arn:aws:dynamodb:us-east-2:123456789012:table/myDynamoDBTable
。 StreamArn
-
DynamoDB 串流的 ARN,例如
arn:aws:dynamodb:us-east-1:123456789012:table/testddbstack-myDynamoDBTable-012A1SL7SMP5Q/stream/2015-11-30T20:10:00.000
。注意
您必須指定
StreamSpecification
屬性,才能使用此屬性。
範例
具備區域與輔助索引的 DynamoDB 資料表
以下範例會建立一個 DynamoDB 資料表,其中包含 Album
、Artist
、Sales
、NumberOfSongs
做為屬性。主索引鍵會將 Album
屬性做為雜湊索引鍵,並將 Artist
屬性做為範圍索引鍵。該資料表亦包含兩個全域索引和一個次要索引。如需查詢指定演出者的銷售數量,全域次要索引會將 Sales
屬性做為雜湊索引鍵,並將 Artist
屬性當成範圍索引鍵。
如需根據歌曲編號查詢銷售數量,全域次要索引會將 NumberOfSongs
屬性做為雜湊索引鍵,並將 Sales
屬性當成範圍索引鍵。
如需查詢專輯的銷售數量,本機次要索引會採用與資料表相同的雜湊索引鍵,但會以 Sales
屬性做為範圍索引鍵。
JSON
{ "AWSTemplateFormatVersion" : "2010-09-09", "Resources" : {
"myDynamoDBTable" : { "Type" : "AWS::DynamoDB::Table", "Properties" : {
"AttributeDefinitions" : [ { "AttributeName" : "Album", "AttributeType" : "S" }, {
"AttributeName" : "Artist", "AttributeType" : "S" }, { "AttributeName" : "Sales",
"AttributeType" : "N" }, { "AttributeName" : "NumberOfSongs", "AttributeType" : "N" } ],
"KeySchema" : [ { "AttributeName" : "Album", "KeyType" : "HASH" }, { "AttributeName" :
"Artist", "KeyType" : "RANGE" } ], "ProvisionedThroughput" : { "ReadCapacityUnits" :
"5", "WriteCapacityUnits" : "5" }, "TableName" : "myTableName", "GlobalSecondaryIndexes"
: [{ "IndexName" : "myGSI", "KeySchema" : [ { "AttributeName" : "Sales", "KeyType" :
"HASH" }, { "AttributeName" : "Artist", "KeyType" : "RANGE" } ], "Projection" : {
"NonKeyAttributes" : ["Album","NumberOfSongs"], "ProjectionType" : "INCLUDE" },
"ProvisionedThroughput" : { "ReadCapacityUnits" : "5", "WriteCapacityUnits" : "5" } }, {
"IndexName" : "myGSI2", "KeySchema" : [ { "AttributeName" : "NumberOfSongs", "KeyType" :
"HASH" }, { "AttributeName" : "Sales", "KeyType" : "RANGE" } ], "Projection" : {
"NonKeyAttributes" : ["Album","Artist"], "ProjectionType" : "INCLUDE" },
"ProvisionedThroughput" : { "ReadCapacityUnits" : "5", "WriteCapacityUnits" : "5" } }],
"LocalSecondaryIndexes" :[{ "IndexName" : "myLSI", "KeySchema" : [ { "AttributeName" :
"Album", "KeyType" : "HASH" }, { "AttributeName" : "Sales", "KeyType" : "RANGE" } ],
"Projection" : { "NonKeyAttributes" : ["Artist","NumberOfSongs"], "ProjectionType" :
"INCLUDE" } }] } } } }
YAML
AWSTemplateFormatVersion: "2010-09-09" Resources: myDynamoDBTable:
Type: AWS::DynamoDB::Table Properties: AttributeDefinitions: - AttributeName: "Album"
AttributeType: "S" - AttributeName: "Artist" AttributeType: "S" - AttributeName: "Sales"
AttributeType: "N" - AttributeName: "NumberOfSongs" AttributeType: "N" KeySchema: -
AttributeName: "Album" KeyType: "HASH" - AttributeName: "Artist" KeyType: "RANGE"
ProvisionedThroughput: ReadCapacityUnits: "5" WriteCapacityUnits: "5" TableName:
"myTableName" GlobalSecondaryIndexes: - IndexName: "myGSI" KeySchema: - AttributeName:
"Sales" KeyType: "HASH" - AttributeName: "Artist" KeyType: "RANGE" Projection:
NonKeyAttributes: - "Album" - "NumberOfSongs" ProjectionType: "INCLUDE"
ProvisionedThroughput: ReadCapacityUnits: "5" WriteCapacityUnits: "5" - IndexName:
"myGSI2" KeySchema: - AttributeName: "NumberOfSongs" KeyType: "HASH" - AttributeName:
"Sales" KeyType: "RANGE" Projection: NonKeyAttributes: - "Album" - "Artist"
ProjectionType: "INCLUDE" ProvisionedThroughput: ReadCapacityUnits: "5"
WriteCapacityUnits: "5" LocalSecondaryIndexes: - IndexName: "myLSI" KeySchema: -
AttributeName: "Album" KeyType: "HASH" - AttributeName: "Sales" KeyType: "RANGE"
Projection: NonKeyAttributes: - "Artist" - "NumberOfSongs" ProjectionType:
"INCLUDE"
具備 DependsOn 屬性的 DynamoDB 資料表
如果單一範本中包含多個具備索引的 DynamoDB 資料表,您必須在其中包含依存性,才能依序建立資料表。DynamoDB 會限制處於建立狀態,具備輔助索引的資料表數量。若您同時建立多個具備索引的資料表,DynamoDB 將傳回錯誤且堆疊操作會失敗。
以下範例會假設 myFirstDDBTable
資料表在相同範本中已宣告為 mySecondDDBTable
資料表,且兩個資料表皆包含輔助索引。mySecondDDBTable
資料表會包含 myFirstDDBTable
資料表上的依存項目,讓 AWS CloudFormation
能夠一次建立一個資料表。
JSON
"mySecondDDBTable" : { "Type" : "AWS::DynamoDB::Table",
"DependsOn" : "myFirstDDBTable" , "Properties" : { "AttributeDefinitions" : [ {
"AttributeName" : "ArtistId", "AttributeType" : "S" }, { "AttributeName" : "Concert",
"AttributeType" : "S" }, { "AttributeName" : "TicketSales", "AttributeType" : "S" } ],
"KeySchema" : [ { "AttributeName" : "ArtistId", "KeyType" : "HASH" }, { "AttributeName"
: "Concert", "KeyType" : "RANGE" } ], "ProvisionedThroughput" : { "ReadCapacityUnits" :
{"Ref" : "ReadCapacityUnits"}, "WriteCapacityUnits" : {"Ref" : "WriteCapacityUnits"} },
"GlobalSecondaryIndexes" : [{ "IndexName" : "myGSI", "KeySchema" : [ { "AttributeName" :
"TicketSales", "KeyType" : "HASH" } ], "Projection" : { "ProjectionType" : "KEYS_ONLY"
}, "ProvisionedThroughput" : { "ReadCapacityUnits" : {"Ref" : "ReadCapacityUnits"},
"WriteCapacityUnits" : {"Ref" : "WriteCapacityUnits"} } }], "Tags": [ { "Key": "foo",
"Value": "bar" } ] } }
YAML
mySecondDDBTable: Type: AWS::DynamoDB::Table DependsOn:
"myFirstDDBTable" Properties: AttributeDefinitions: - AttributeName: "ArtistId"
AttributeType: "S" - AttributeName: "Concert" AttributeType: "S" - AttributeName:
"TicketSales" AttributeType: "S" KeySchema: - AttributeName: "ArtistId" KeyType: "HASH"
- AttributeName: "Concert" KeyType: "RANGE" ProvisionedThroughput: ReadCapacityUnits:
Ref: "ReadCapacityUnits" WriteCapacityUnits: Ref: "WriteCapacityUnits"
GlobalSecondaryIndexes: - IndexName: "myGSI" KeySchema: - AttributeName: "TicketSales"
KeyType: "HASH" Projection: ProjectionType: "KEYS_ONLY" ProvisionedThroughput:
ReadCapacityUnits: Ref: "ReadCapacityUnits" WriteCapacityUnits: Ref:
"WriteCapacityUnits" Tags: - Key: foo Value: bar
具備應用程式 Auto Scaling 的 DynamoDB 資料表
此範例會為 AWS::DynamoDB::Table
資源設定應用程式 Auto Scaling。範本所定義的 TargetTrackingScaling
擴展政策,則可向上擴展資料表的 WriteCapacityUnits
傳輸量。
JSON
{
"Resources": {
"DDBTable": {
"Type": "AWS::DynamoDB::Table",
"Properties": {
"AttributeDefinitions": [
{
"AttributeName": "ArtistId",
"AttributeType": "S"
},
{
"AttributeName": "Concert",
"AttributeType": "S"
},
{
"AttributeName": "TicketSales",
"AttributeType": "S"
}
],
"KeySchema": [
{
"AttributeName": "ArtistId",
"KeyType": "HASH"
},
{
"AttributeName": "Concert",
"KeyType": "RANGE"
}
],
"GlobalSecondaryIndexes": [
{
"IndexName": "GSI",
"KeySchema": [
{
"AttributeName": "TicketSales",
"KeyType": "HASH"
}
],
"Projection": {
"ProjectionType": "KEYS_ONLY"
},
"ProvisionedThroughput": {
"ReadCapacityUnits": 5,
"WriteCapacityUnits": 5
}
}
],
"ProvisionedThroughput": {
"ReadCapacityUnits": 5,
"WriteCapacityUnits": 5
}
}
},
"WriteCapacityScalableTarget": {
"Type": "AWS::ApplicationAutoScaling::ScalableTarget",
"Properties": {
"MaxCapacity": 15,
"MinCapacity": 5,
"ResourceId": { "Fn::Join": [
"/",
[
"table",
{ "Ref": "DDBTable" }
]
] },
"RoleARN": {
"Fn::GetAtt": ["ScalingRole", "Arn"]
},
"ScalableDimension": "dynamodb:table:WriteCapacityUnits",
"ServiceNamespace": "dynamodb"
}
},
"ScalingRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"application-autoscaling.amazonaws.com"
]
},
"Action": [
"sts:AssumeRole"
]
}
]
},
"Path": "/",
"Policies": [
{
"PolicyName": "root",
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DescribeTable",
"dynamodb:UpdateTable",
"cloudwatch:PutMetricAlarm",
"cloudwatch:DescribeAlarms",
"cloudwatch:GetMetricStatistics",
"cloudwatch:SetAlarmState",
"cloudwatch:DeleteAlarms"
],
"Resource": "*"
}
]
}
}
]
}
},
"WriteScalingPolicy": {
"Type": "AWS::ApplicationAutoScaling::ScalingPolicy",
"Properties": {
"PolicyName": "WriteAutoScalingPolicy",
"PolicyType": "TargetTrackingScaling",
"ScalingTargetId": {
"Ref": "WriteCapacityScalableTarget"
},
"TargetTrackingScalingPolicyConfiguration": {
"TargetValue": 50.0,
"ScaleInCooldown": 60,
"ScaleOutCooldown": 60,
"PredefinedMetricSpecification": {
"PredefinedMetricType": "DynamoDBWriteCapacityUtilization"
}
}
}
}
}
}
YAML
Resources:
DDBTable:
Type: AWS::DynamoDB::Table
Properties:
AttributeDefinitions:
-
AttributeName: "ArtistId"
AttributeType: "S"
-
AttributeName: "Concert"
AttributeType: "S"
-
AttributeName: "TicketSales"
AttributeType: "S"
KeySchema:
-
AttributeName: "ArtistId"
KeyType: "HASH"
-
AttributeName: "Concert"
KeyType: "RANGE"
GlobalSecondaryIndexes:
-
IndexName: "GSI"
KeySchema:
-
AttributeName: "TicketSales"
KeyType: "HASH"
Projection:
ProjectionType: "KEYS_ONLY"
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
WriteCapacityScalableTarget:
Type: AWS::ApplicationAutoScaling::ScalableTarget
Properties:
MaxCapacity: 15
MinCapacity: 5
ResourceId: !Join
- /
- - table
- !Ref DDBTable
RoleARN: !GetAtt ScalingRole.Arn
ScalableDimension: dynamodb:table:WriteCapacityUnits
ServiceNamespace: dynamodb
ScalingRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
-
Effect: "Allow"
Principal:
Service:
- application-autoscaling.amazonaws.com
Action:
- "sts:AssumeRole"
Path: "/"
Policies:
-
PolicyName: "root"
PolicyDocument:
Version: "2012-10-17"
Statement:
-
Effect: "Allow"
Action:
- "dynamodb:DescribeTable"
- "dynamodb:UpdateTable"
- "cloudwatch:PutMetricAlarm"
- "cloudwatch:DescribeAlarms"
- "cloudwatch:GetMetricStatistics"
- "cloudwatch:SetAlarmState"
- "cloudwatch:DeleteAlarms"
Resource: "*"
WriteScalingPolicy:
Type: AWS::ApplicationAutoScaling::ScalingPolicy
Properties:
PolicyName: WriteAutoScalingPolicy
PolicyType: TargetTrackingScaling
ScalingTargetId: !Ref WriteCapacityScalableTarget
TargetTrackingScalingPolicyConfiguration:
TargetValue: 50.0
ScaleInCooldown: 60
ScaleOutCooldown: 60
PredefinedMetricSpecification:
PredefinedMetricType: DynamoDBWriteCapacityUtilization