AWS::DynamoDB::Table - AWS CloudFormation

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

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 模板中声明此实体,请使用以下语法:

属性

AttributeDefinitions

用于描述表和索引的键架构的属性的列表。

此属性是创建 DynamoDB 表必需的。

更新要求:时而中断。如果您编辑现有的 AttributeDefinition,则为替换。

必需:条件

类型:数组 AttributeDefinition

更新要求没有中断

BillingMode

指定如何对读取和写入吞吐量收费以及如何管理容量。

有效值包括:

  • PROVISIONED – 对于可预测工作负载,建议使用 PROVISIONEDPROVISIONED 将计账模式设置为预置模式

  • PAY_PER_REQUEST – 对于不可预测的工作负载,建议使用 PAY_PER_REQUESTPAY_PER_REQUEST 将计账模式设置为按需模式

如果未指定,则默认值为 PROVISIONED

必需:否

类型:字符串

允许的值PROVISIONED | PAY_PER_REQUEST

更新要求没有中断

ContributorInsightsSpecification

用于为指定表格启用或禁用 “ CloudWatch 贡献者见解” 的设置。

必需:否

类型:ContributorInsightsSpecification

更新要求没有中断

DeletionProtectionEnabled

确定表是否受到保护以免被删除。启用后,任何用户或进程都无法删除该表。默认情况下,该设置处于禁用状态。有关更多信息,请参阅 Amazon DynamoDebDevelop er 指南中的使用删除保护

必需:否

类型:布尔值

更新要求没有中断

GlobalSecondaryIndexes

要对表创建的全局二级索引。可以创建最多 20 个全局二级索引。

重要

如果您更新表以包含新的全局二级索引,则 AWS CloudFormation 会启动索引创建,然后继续更新堆栈。 AWS CloudFormation 不会等待索引完成创建,因为回填阶段可能需要很长时间,具体取决于表的大小。在索引状态变成 ACTIVE 之前,您无法使用此索引或更新此表。您可以使用 DynamoDB DescribeTable命令跟踪其状态。

如果您在更新期间添加或删除索引,我们建议您不要更新任何其他资源。如果在添加新索引期间堆栈更新失败并回滚,则必须手动删除此索引。

不支持更新。存在以下例外:

  • 如果更新全局二级索引的 Contributor Insights 规范或预置吞吐量值,则可以在不中断的情况下更新表。

  • 您可以在不中断的情况下删除或添加一个全局二级索引。如果您在一次更新中同时执行删除和添加操作(例如:更改索引的逻辑 ID),则更新将失败。

必需:否

类型:数组 GlobalSecondaryIndex

更新要求没有中断

ImportSourceSpecification

指定从 S3 桶源导入到表的数据的属性。

重要

如果您指定了ImportSourceSpecification属性,同时还指定了StreamSpecificationTableClass属性或属性,则创建/更新堆栈的 IAM 实体必须拥有UpdateTable权限。DeletionProtectionEnabled

必需:否

类型:ImportSourceSpecification

更新要求替换

KeySchema

指定组成表主键的属性。KeySchema 属性中的属性还必须在 AttributeDefinitions 属性中定义。

必需:是

类型数组 KeySchema

更新要求没有中断

KinesisStreamSpecification

针对指定表的 Kinesis Data Streams 配置。

必需:否

类型:KinesisStreamSpecification

更新要求没有中断

LocalSecondaryIndexes

要对表创建的本地二级索引。可以创建最多 5 个本地二级索引。每个索引的范围都限定到给定哈希键值。每个哈希键的大小最大可以为 10 GB。

必需:否

类型:数组 LocalSecondaryIndex

更新要求没有中断

PointInTimeRecoverySpecification

用于启用时间点恢复的设置。

必需:否

类型:PointInTimeRecoverySpecification

更新要求没有中断

ProvisionedThroughput

指定的表的吞吐量,由 ReadCapacityUnitsWriteCapacityUnits 的值组成。有关预配置吞吐量结构内容的更多信息,请参阅 Amazon DynamoDB 表。 ProvisionedThroughput

如果将 BillingMode 设置为 PROVISIONED,您必须指定该属性。如果将 BillingMode 设置为 PAY_PER_REQUEST,您无法指定该属性。

必需:条件

类型:ProvisionedThroughput

更新要求没有中断

ResourcePolicy

基于资源的策略文档,其中包含添加到指定表的权限。在 CloudFormation 模板中,您可以以 JSON 或 YAML 格式提供策略,因为在将 YAML 提交到之前会将其 CloudFormation 转换为 JSON。 DynamoDB有关基于资源的策略的更多信息,请参阅使用基于资源的策略 DynamoDB和基于资源的策略

当您在创建表时附加基于资源的策略时,策略的创建是高度一致的。有关附加基于资源的策略时应记住的注意事项的信息,请参阅基于资源的策略注意事项。

必需:否

类型:ResourcePolicy

更新要求没有中断

SSESpecification

指定用于启用服务器端加密的设置。

必需:否

类型SSESpecification

更新要求时而中断

StreamSpecification

DynamoDB 表流的设置,用于捕获对存储在表中的项目的变更。

必需:否

类型:StreamSpecification

更新要求没有中断

TableClass

新表的表类。有效值为 STANDARDSTANDARD_INFREQUENT_ACCESS

必需:否

类型:字符串

允许的值STANDARD | STANDARD_INFREQUENT_ACCESS

更新要求没有中断

TableName

表的名称。如果您不指定名称,则 AWS CloudFormation 会生成一个唯一的物理 ID 并将该 ID 用作表名。有关更多信息,请参阅名称类型

重要

如果指定一个名称,您将无法执行需要替换该资源的更新。您可以执行不需要或者只需要部分中断的更新。如果必须替换资源,请指定新名称。

必需:否

类型:字符串

最小值1

最大值1024

更新要求替换

Tags

要应用于此资源的键值对的数组。

有关更多信息,请参阅标签

必需:否

类型标签数组

更新要求没有中断

TimeToLiveSpecification

为表指定生存时间 (TTL) 设置。

注意

有关 DynamoDB 中的限制的详细信息,请参阅《Amazon DynamoDB 开发人员指南》中的 Amazon DynamoDB 中的限制

必需:否

类型:TimeToLiveSpecification

更新要求没有中断

返回值

Ref

在将此资源的逻辑 ID 传递给内部 Ref 函数时,Ref 将返回资源名称。例如:

{ "Ref": "MyResource" }

对于逻辑 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 表

以下示例创建一个包含 AlbumArtistSalesNumberOfSongs 作为属性的 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