本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
AWS::DynamoDB::Table
AWS::DynamoDB::Table
資源會建立 DynamoDB 資料表。如需詳細資訊,請參閱 Amazon DynamoDB API 參考CreateTable中的。
使用 DynamoDB 資料表時,您應該注意下列行為:
-
AWS CloudFormation 通常會以 parallel 方式建立 DynamoDB 表。但是,如果您的範本包含多個具備索引的 DynamoDB 資料表,則必須宣告依存項目才能循序建立資料表。Amazon DynamoDB 處於建立狀態時,會限制具備輔助索引的資料表數量。若您同時建立多個具備索引的資料表,DynamoDB 將傳回錯誤且堆疊操作會失敗。如需範例,請參閱具有屬性的 DynamoDB 資料表。 DependsOn
重要
我們的指導是使用此處記錄的最新模式為您的 AWS CloudFormation 模板。此結構描述支援下列所有資料表設定的佈建。在 AWS CloudFormation 範本中使用此結構描述時,請確定您的 Identity and Access Management (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
} }
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
屬性
AttributeDefinitions
-
屬性清單,這些屬性會說明表格與索引的索引鍵結構描述;
此屬性是建立 DynamoDB 資料表的必要屬性。
更新需求:部分中斷。如果您編輯現有的,則取代 AttributeDefinition。
必要:有條件
類型:陣列 AttributeDefinition
更新要求:不中斷
BillingMode
-
指定如何向您收取讀取與寫入傳輸量的費用,以及您如何管理容量。
有效值包含:
若沒有指定,則預設為
PROVISIONED
。必要:否
類型:字串
允許值:
PROVISIONED | PAY_PER_REQUEST
更新要求:不中斷
ContributorInsightsSpecification
-
用來啟用或停用指定資料表的 CloudWatch 參與者深入解析的設定。
必要:否
更新要求:不中斷
DeletionProtectionEnabled
-
判斷資料表是否受到保護,避免刪除。啟用時,任何使用者或程序都無法刪除表格。根據預設,停用此設定。如需詳細資訊,請參閱 Amazon DynamoDB 開發人員指南中的使用刪除保護。
必要:否
類型:布林值
更新要求:不中斷
GlobalSecondaryIndexes
-
資料表上待建立的全域次要索引;您最多可以建立 20 個全域輔助索引。
重要
如果您更新資料表以包含新的全域次要索引,則 AWS CloudFormation 會起始建立索引,然後繼續進行堆疊更新。 AWS CloudFormation 不等待索引完成創建,因為回填階段可能需要很長時間,具體取決於表的大小。您必須等到索引的狀態顯示為
ACTIVE
,才能使用該索引或更新資料表。您可以使用 DynamoDB DescribeTable命令來追蹤其狀態。如果您在更新期間新增或刪除索引,我們建議不要更新任何其他資源。若您的堆疊更新失敗並在新增新索引時復原,您必須手動刪除索引。
不支援更新。以下為例外:
-
如果您更新 Contributor Insights 規格或全域輔助索引的佈建輸送量值,便可以在不發生中斷的情況下更新資料表。
-
您可以刪除或新增一個全域輔助索引,而不會發生中斷。若您在相同的更新中同時進行兩個動作 (例如變更索引的邏輯 ID),則更新會失敗。
必要:否
更新要求:不中斷
-
ImportSourceSpecification
-
指定從 S3 儲存貯體來源匯入資料表的資料屬性。
重要
如果您指定
ImportSourceSpecification
屬性,並指定StreamSpecification
、屬性或TableClass
屬性,則 IAM 實體建立/更新堆疊必須具有權限。DeletionProtectionEnabled
UpdateTable
必要:否
更新要求:替換
KeySchema
-
可藉由此屬性來指定資料表所含的主要索引鍵屬性。
AttributeDefinitions
屬性中也必須定義KeySchema
屬性中的屬性。必要:是
類型:陣列 KeySchema
更新要求:不中斷
KinesisStreamSpecification
-
指定資料表的 Kinesis Data Streams 組態。
必要:否
更新要求:不中斷
LocalSecondaryIndexes
-
資料表上待建立的本機次要索引;最多可以建立 5 個本機次要索引。每個索引的範圍不得超過指定的雜湊索引鍵值,而每個雜湊索引鍵的大小最高可達 10 GB。
必要:否
更新要求:不中斷
OnDemandThroughput
-
為指定的隨選資料表設定讀取和寫入單位的最大數目。如果您使用此屬性,則必須指定
MaxReadRequestUnits
MaxWriteRequestUnits
、或兩者。必要:否
類型:OnDemand吞吐量
更新要求:不中斷
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 中的限制。
必要:否
更新要求:不中斷
傳回值
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"
具有屬性的 DynamoDB 資料表 DependsOn
如果單一範本中包含多個具備索引的 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