AWS::DynamoDB::Table - AWS CloudFormation

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

AWS::DynamoDB::Table

AWS::DynamoDB::Table 資源會建立 DynamoDB 資料表。如需詳細資訊,請參閱 Amazon DynamoDB CreateTable 參考中的 Word。 DynamoDB API

使用 DynamoDB 資料表時,您應該注意下列行為:

  • AWS CloudFormation 通常會平行建立 DynamoDB 資料表。但是,如果您的範本包含多個具備索引的 DynamoDB 資料表,則必須宣告依存項目才能循序建立資料表。Amazon DynamoDB 處於建立狀態時,會限制具備輔助索引的資料表數量。若您同時建立多個具備索引的資料表,DynamoDB 將傳回錯誤且堆疊操作會失敗。如需範例,請參閱具有 a DependsOn 屬性的 DynamoDB 資料表

重要

我們的指引是使用 AWS CloudFormation 範本記錄的最新結構描述。此結構描述支援下列所有資料表設定的佈建。在 AWS CloudFormation 範本中使用此結構描述時,請確保您的身分和存取管理 (IAM) 政策已更新,並具有適當的許可,以允許授權這些設定變更。

語法

若要在 AWS CloudFormation 範本中宣告此實體,請使用下列語法:

屬性

AttributeDefinitions

屬性清單,這些屬性會說明表格與索引的索引鍵結構描述;

此屬性是建立 DynamoDB 資料表的必要屬性。

更新需求:部分中斷。如果您編輯現有的 AttributeDefinition,請取代 。

必要:有條件

類型AttributeDefinition 陣列

更新要求不中斷

BillingMode

指定如何向您收取讀取與寫入傳輸量的費用,以及您如何管理容量。

有效值包含:

  • PROVISIONED - 我們建議將 PROVISIONED 用於可預測的工作負載。PROVISIONED 會將帳單模式設為佈建模式

  • PAY_PER_REQUEST - 我們建議將 PAY_PER_REQUEST 用於無法預測的工作負載。PAY_PER_REQUEST 會將帳單模式設為隨需模式

若沒有指定,則預設為 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 屬性,並指定 StreamSpecificationTableClass 屬性、 DeletionProtectionEnabled 屬性或 WarmThroughput 屬性,則建立/更新堆疊的 IAM 實體必須具有 UpdateTable 許可。

必要:否

類型ImportSourceSpecification

更新要求替換

KeySchema

可藉由此屬性來指定資料表所含的主要索引鍵屬性。AttributeDefinitions 屬性中也必須定義 KeySchema 屬性中的屬性。

必要:是

類型KeySchema 陣列

更新要求部分中斷

KinesisStreamSpecification

指定資料表的 Kinesis Data Streams 組態。

必要:否

類型KinesisStreamSpecification

更新要求不中斷

LocalSecondaryIndexes

資料表上待建立的本機次要索引;最多可以建立 5 個本機次要索引。每個索引的範圍不得超過指定的雜湊索引鍵值,而每個雜湊索引鍵的大小最高可達 10 GB。

必要:否

類型LocalSecondaryIndex 陣列

更新要求不中斷

OnDemandThroughput

設定指定隨需資料表的讀取和寫入單位數量上限。如果您使用此屬性,則必須指定 MaxReadRequestUnitsMaxWriteRequestUnits或兩者。

必要:否

類型OnDemandThroughput

更新要求不中斷

PointInTimeRecoverySpecification

用於啟用時間點復原恢復的設定。

必要:否

類型PointInTimeRecoverySpecification

更新要求不中斷

ProvisionedThroughput

指定資料表的輸送量,包括 ReadCapacityUnitsWriteCapacityUnits 的值。如需佈建輸送量結構內容的詳細資訊,請參閱 Amazon DynamoDB Table 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

更新要求不中斷

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 資料表,其中包含 AlbumArtistSalesNumberOfSongs 做為屬性。主索引鍵會將 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"

具有 a 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