AWS::DynamoDB::Table - AWS CloudFormation

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

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 範本中宣告此實體,請使用下列語法:

屬性

AttributeDefinitions

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

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

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

必要:有條件

類型:陣列 AttributeDefinition

更新要求不中斷

BillingMode

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

有效值包含:

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

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

若沒有指定,則預設為 PROVISIONED

必要:否

類型:字串

允許值PROVISIONED | PAY_PER_REQUEST

更新要求不中斷

ContributorInsightsSpecification

用來啟用或停用指定資料表的 CloudWatch 參與者深入解析的設定。

必要:否

類型ContributorInsights規格

更新要求不中斷

DeletionProtectionEnabled

判斷資料表是否受到保護,避免刪除。啟用時,任何使用者或程序都無法刪除表格。根據預設,停用此設定。如需詳細資訊,請參閱 Amazon DynamoDB 開發人員指南中的使用刪除保護

必要:否

類型:布林值

更新要求不中斷

GlobalSecondaryIndexes

資料表上待建立的全域次要索引;您最多可以建立 20 個全域輔助索引。

重要

如果您更新資料表以包含新的全域次要索引,則 AWS CloudFormation 會起始建立索引,然後繼續進行堆疊更新。 AWS CloudFormation 不等待索引完成創建,因為回填階段可能需要很長時間,具體取決於表的大小。您必須等到索引的狀態顯示為 ACTIVE,才能使用該索引或更新資料表。您可以使用 DynamoDB DescribeTable命令來追蹤其狀態。

如果您在更新期間新增或刪除索引,我們建議不要更新任何其他資源。若您的堆疊更新失敗並在新增新索引時復原,您必須手動刪除索引。

不支援更新。以下為例外:

  • 如果您更新 Contributor Insights 規格或全域輔助索引的佈建輸送量值,便可以在不發生中斷的情況下更新資料表。

  • 您可以刪除或新增一個全域輔助索引,而不會發生中斷。若您在相同的更新中同時進行兩個動作 (例如變更索引的邏輯 ID),則更新會失敗。

必要:否

類型GlobalSecondary索引數

更新要求不中斷

ImportSourceSpecification

指定從 S3 儲存貯體來源匯入資料表的資料屬性。

重要

如果您指定ImportSourceSpecification屬性,並指定StreamSpecification、屬性或TableClass屬性,則 IAM 實體建立/更新堆疊必須具有權限。DeletionProtectionEnabled UpdateTable

必要:否

類型ImportSource規格

更新要求替換

KeySchema

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

必要:是

類型陣列 KeySchema

更新要求不中斷

KinesisStreamSpecification

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

必要:否

類型KinesisStream規格

更新要求不中斷

LocalSecondaryIndexes

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

必要:否

類型LocalSecondary索引數

更新要求不中斷

OnDemandThroughput

為指定的隨選資料表設定讀取和寫入單位的最大數目。如果您使用此屬性,則必須指定MaxReadRequestUnitsMaxWriteRequestUnits、或兩者。

必要:否

類型OnDemand吞吐量

更新要求不中斷

PointInTimeRecoverySpecification

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

必要:否

類型PointInTimeRecovery規格

更新要求不中斷

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": "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"

具有屬性的 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