本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
AWS::DynamoDB::Table
AWS::DynamoDB::Table
资源将创建 DynamoDB 表。有关更多信息,请参阅CreateTable《亚马逊 DynamoDB API 参考》。
在使用 DynamoDB 表时,您应注意以下行为:
-
AWS CloudFormation 通常并行创建 DynamoDB 表。但是,如果模板包含多个带索引的 DynamoDB 表,则必须声明依赖关系,才能按顺序创建表。Amazon DynamoDB 对二级索引处于创建状态的表的数量有限制。如果同时创建多个带索引的表,则 DynamoDB 会返回错误,并且堆栈操作将失败。有关示例,请参阅带有属性的 DynamoDB 表。 DependsOn
重要
我们的指导是使用 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 贡献者见解” 的设置。
必需:否
类型:ContributorInsightsSpecification
更新要求:没有中断
DeletionProtectionEnabled
-
确定表是否受到保护以免被删除。启用后,任何用户或进程都无法删除该表。默认情况下,该设置处于禁用状态。有关更多信息,请参阅 Amazon Dynamo DBDeveloper 指南中的使用删除保护。
必需:否
类型:布尔值
更新要求:没有中断
GlobalSecondaryIndexes
-
要对表创建的全局二级索引。可以创建最多 20 个全局二级索引。
重要
如果您更新表以包含新的全局二级索引,则 AWS CloudFormation 会启动索引创建,然后继续更新堆栈。 AWS CloudFormation 不会等待索引完成创建,因为回填阶段可能需要很长时间,具体取决于表的大小。在索引状态变成
ACTIVE
之前,您无法使用此索引或更新此表。您可以使用 DynamoDB DescribeTable命令跟踪其状态。如果您在更新期间添加或删除索引,我们建议您不要更新任何其他资源。如果在添加新索引期间堆栈更新失败并回滚,则必须手动删除此索引。
不支持更新。存在以下例外:
-
如果更新全局二级索引的 Contributor Insights 规范或预置吞吐量值,则可以在不中断的情况下更新表。
-
您可以在不中断的情况下删除或添加一个全局二级索引。如果您在一次更新中同时执行删除和添加操作(例如:更改索引的逻辑 ID),则更新将失败。
必需:否
类型:数组 GlobalSecondaryIndex
更新要求:没有中断
-
ImportSourceSpecification
-
指定从 S3 存储桶源导入到” 表的数据的属性。
重要
如果您指定了
ImportSourceSpecification
属性,同时还指定了属性StreamSpecification
、TableClass
属性或属性,则创建/更新堆栈的 IAM 实体必须拥有UpdateTable
权限。DeletionProtectionEnabled
WarmThroughput
必需:否
更新要求:替换
KeySchema
-
指定组成表主键的属性。
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
-
表示创建表的热吞吐量(以每秒读取单位和每秒写入单位为单位)。
必需:否
更新要求:没有中断
返回值
Ref
在将此资源的逻辑 ID 传递给内部 Ref
函数时,Ref
将返回资源名称。例如:
{ "Ref": "myDynamoDBTable" }
对于逻辑 ID 为 myDynamoDBTable
的资源,Ref
将返回 DynamoDB 表名称。
有关使用 Ref
函数的更多信息,请参阅 Ref
。
Fn:: GetAtt
Fn::GetAtt
内部函数返回此类型的一个指定属性的值。以下为可用属性和示例返回值。
有关使用 Fn::GetAtt
内部函数的更多信息,请参阅 Fn::GetAtt
。
Arn
-
DynamoDB 表的 Amazon 资源名称(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 表
以下示例创建一个包含 Album
、Artist
、Sales
、NumberOfSongs
作为属性的 DynamoDB 表。主键包含 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
具有 Application Auto Scaling 的 DynamoDB 表
此示例为 AWS::DynamoDB::Table
资源设置 Application 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