本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
DynamoDB 解析程序映射模板参考
这些区域有:Amazon AppSync DynamoDB 解析器允许您使用GraphQL
主题
GetItem
这些区域有:GetItem
请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个GetItem
请求发送到 DynamoDB,并使您能够指定:
-
DynamoDB 中项目的键
-
是否使用一致性读取
GetItem
映射文档具有以下结构:
{ "version" : "2017-02-28", "operation" : "GetItem", "key" : { "foo" : ... typed value, "bar" : ... typed value }, "consistentRead" : true }
字段定义如下:
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
GetItem
DynamoDB 操作,此字段必须设置为GetItem
。此值为必填项。 -
key
-
中项目的键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
consistentRead
-
是否对 DynamoDB 执行强一致性读取。这是可选的,默认值为
false
。
从 DynamoDB 返回的项目自动转换为 GraphQL 和 JSON 基元类型,并且可用于映射上下文 ($context.result
)。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射).
有关响应映射模板的更多信息,请参阅解析程序映射模板概述。
示例
下面是 GraphQL 查询 getThing(foo: String!, bar:
String!)
的一个映射模板:
{ "version" : "2017-02-28", "operation" : "GetItem", "key" : { "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo), "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar) }, "consistentRead" : true }
有关 DynamoDB GetItem
API 的更多信息,请参阅 DynamoDB API 文档。
PutItem
这些区域有:PutItem
请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个PutItem
请求发送到 DynamoDB,并使您能够指定以下各项:
-
DynamoDB 中项目的键
-
项目的完整内容(包括
key
和attributeValues
) -
操作成功执行的条件
PutItem
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "PutItem", "key": { "foo" : ... typed value, "bar" : ... typed value }, "attributeValues" : { "baz" : ... typed value }, "condition" : { ... }, "_version" : 1 }
字段定义如下:
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
PutItem
DynamoDB 操作,此字段必须设置为PutItem
。此值为必填项。 -
key
-
中项目的键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
attributeValues
-
要放入 DynamoDB 中的项目的其余属性。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此字段为可选项。
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
PutItem
请求将覆盖该项目的任何现有条目。有关条件的更多信息,请参阅条件表达式。该值为可选项。 -
_version
-
表示项目的最新已知版本的数值。该值为可选项。此字段用于冲突检测 ,仅受版本化数据源支持。
写入 DynamoDB 的项目自动转换为 GraphQL 和 JSON 基元类型,并且可用于映射上下文 ($context.result
)。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射).
有关响应映射模板的更多信息,请参阅解析程序映射模板概述。
示例 1
下面是 GraphQL 更改 updateThing(foo:
String!, bar: String!, name: String!, version: Int!)
的一个映射模板:
如果带指定键的项目不存在,则会创建它。如果带指定键的项已存在,则会覆盖它。
{ "version" : "2017-02-28", "operation" : "PutItem", "key": { "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo), "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar) }, "attributeValues" : { "name" : $util.dynamodb.toDynamoDBJson($ctx.args.name), "version" : $util.dynamodb.toDynamoDBJson($ctx.args.version) } }
示例 2
下面是 GraphQL 更改 updateThing(foo:
String!, bar: String!, name: String!, expectedVersion: Int!)
的一个映射模板:
此示例进行检查,以确保当前在 DynamoDB 中的项目具有version
字段设置为expectedVersion
.
{ "version" : "2017-02-28", "operation" : "PutItem", "key": { "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo), "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar) }, "attributeValues" : { "name" : $util.dynamodb.toDynamoDBJson($ctx.args.name), #set( $newVersion = $context.arguments.expectedVersion + 1 ) "version" : $util.dynamodb.toDynamoDBJson($newVersion) }, "condition" : { "expression" : "version = :expectedVersion", "expressionValues" : { ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion) } } }
有关 DynamoDB PutItem
API 的更多信息,请参阅 DynamoDB API 文档。
UpdateItem
这些区域有:UpdateItem
请求映射文档使你能够告诉Amazon AppSync DynamoDB 解析器创建一个UpdateItem
请求发送到 DynamoDB,并允许您指定以下各项:
-
DynamoDB 中项目的键
-
描述如何更新 DynamoDB 中项目的更新表达式
-
操作成功执行的条件
UpdateItem
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "UpdateItem", "key": { "foo" : ... typed value, "bar" : ... typed value }, "update" : { "expression" : "someExpression", "expressionNames" : { "#foo" : "foo" }, "expressionValues" : { ":bar" : ... typed value } }, "condition" : { ... }, "_version" : 1 }
字段定义如下:
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
UpdateItem
DynamoDB 操作,此字段必须设置为UpdateItem
。此值为必填项。 -
key
-
中项目的键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
update
-
这些区域有:
update
部分让您指定一个更新表达式,该表达式描述如何更新 DynamoDB 中的项目。有关如何编写更新表达式的更多信息,请参阅DynamoDB UpdateExpressions 文档. 此部分是必需的。update
部分有三个组成部分:-
expression
-
更新表达式。此值为必填项。
-
expressionNames
-
用于替代表达式属性名称 占位符,格式为键值对。键对应于中使用的名称占位符
expression
,而值必须是与 DynamoDB 中项目的属性名称相对应的字符串。此字段是可选的,应只填充expression
中使用的表达式属性名称占位符的替代内容。 -
expressionValues
-
用于替代表达式属性值 占位符,格式为键/值对。键对应于
expression
中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。必须指定此值。此字段是可选的,应只填充expression
中使用的表达式属性值占位符的替代内容。
-
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
UpdateItem
请求将更新现有条目,而不考虑其当前状态。有关条件的更多信息,请参阅条件表达式。该值为可选项。 -
_version
-
表示项目的最新已知版本的数值。该值为可选项。此字段用于冲突检测 ,仅受版本化数据源支持。
在 DynamoDB 中更新的项目自动转换为 GraphQL 和 JSON 基元类型,并且可用于映射上下文 ($context.result
)。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射).
有关响应映射模板的更多信息,请参阅解析程序映射模板概述。
示例 1
下面是 GraphQL 更改 upvote(id:
ID!)
的一个映射模板:
在本示例中,DynamoDB 中的一个项目如下所示upvotes
和version
字段增加 1。
{ "version" : "2017-02-28", "operation" : "UpdateItem", "key" : { "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id) }, "update" : { "expression" : "ADD #votefield :plusOne, version :plusOne", "expressionNames" : { "#votefield" : "upvotes" }, "expressionValues" : { ":plusOne" : { "N" : 1 } } } }
示例 2
下面是 GraphQL 更改 updateItem(id: ID!,
title: String, author: String, expectedVersion: Int!)
的一个映射模板:
这是一个复杂的示例,用于检查参数并动态生成更新表达式,此表达式仅包含由客户端提供的参数。例如,如果省略了 title
和 author
,则不会更新它们。如果指定了参数但其值为null
,则会从 DynamoDB 中的对象删除该字段。最后,操作具有一个条件,此条件验证当前在 DynamoDB 中的项目是否有version
字段设置为expectedVersion
:
{ "version" : "2017-02-28", "operation" : "UpdateItem", "key" : { "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id) }, ## Set up some space to keep track of things we're updating ** #set( $expNames = {} ) #set( $expValues = {} ) #set( $expSet = {} ) #set( $expAdd = {} ) #set( $expRemove = [] ) ## Increment "version" by 1 ** $!{expAdd.put("version", ":newVersion")} $!{expValues.put(":newVersion", { "N" : 1 })} ## Iterate through each argument, skipping "id" and "expectedVersion" ** #foreach( $entry in $context.arguments.entrySet() ) #if( $entry.key != "id" && $entry.key != "expectedVersion" ) #if( (!$entry.value) && ("$!{entry.value}" == "") ) ## If the argument is set to "null", then remove that attribute from the item in DynamoDB ** #set( $discard = ${expRemove.add("#${entry.key}")} ) $!{expNames.put("#${entry.key}", "$entry.key")} #else ## Otherwise set (or update) the attribute on the item in DynamoDB ** $!{expSet.put("#${entry.key}", ":${entry.key}")} $!{expNames.put("#${entry.key}", "$entry.key")} #if( $entry.key == "ups" || $entry.key == "downs" ) $!{expValues.put(":${entry.key}", { "N" : $entry.value })} #else $!{expValues.put(":${entry.key}", { "S" : "${entry.value}" })} #end #end #end #end ## Start building the update expression, starting with attributes we're going to SET ** #set( $expression = "" ) #if( !${expSet.isEmpty()} ) #set( $expression = "SET" ) #foreach( $entry in $expSet.entrySet() ) #set( $expression = "${expression} ${entry.key} = ${entry.value}" ) #if ( $foreach.hasNext ) #set( $expression = "${expression}," ) #end #end #end ## Continue building the update expression, adding attributes we're going to ADD ** #if( !${expAdd.isEmpty()} ) #set( $expression = "${expression} ADD" ) #foreach( $entry in $expAdd.entrySet() ) #set( $expression = "${expression} ${entry.key} ${entry.value}" ) #if ( $foreach.hasNext ) #set( $expression = "${expression}," ) #end #end #end ## Continue building the update expression, adding attributes we're going to REMOVE ** #if( !${expRemove.isEmpty()} ) #set( $expression = "${expression} REMOVE" ) #foreach( $entry in $expRemove ) #set( $expression = "${expression} ${entry}" ) #if ( $foreach.hasNext ) #set( $expression = "${expression}," ) #end #end #end ## Finally, write the update expression into the document, along with any expressionNames and expressionValues ** "update" : { "expression" : "${expression}" #if( !${expNames.isEmpty()} ) ,"expressionNames" : $utils.toJson($expNames) #end #if( !${expValues.isEmpty()} ) ,"expressionValues" : $utils.toJson($expValues) #end }, "condition" : { "expression" : "version = :expectedVersion", "expressionValues" : { ":expectedVersion" : $util.dynamodb.toDynamoDBJson($ctx.args.expectedVersion) } } }
有关 DynamoDB UpdateItem
API 的更多信息,请参阅 DynamoDB API 文档。
DeleteItem
这些区域有:DeleteItem
请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个DeleteItem
请求发送到 DynamoDB,并使您能够指定以下各项:
-
DynamoDB 中项目的键
-
操作成功执行的条件
DeleteItem
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "DeleteItem", "key": { "foo" : ... typed value, "bar" : ... typed value }, "condition" : { ... }, "_version" : 1 }
字段定义如下:
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
DeleteItem
DynamoDB 操作,此字段必须设置为DeleteItem
。此值为必填项。 -
key
-
中项目的键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
DeleteItem
请求将删除项目,而不考虑其当前状态。有关条件的更多信息,请参阅条件表达式。该值为可选项。 -
_version
-
表示项目的最新已知版本的数值。该值为可选项。此字段用于冲突检测 ,仅受版本化数据源支持。
从 DynamoDB 删除的项目自动转换为 GraphQL 和 JSON 基元类型,并且可用于映射上下文 ($context.result
)。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射).
有关响应映射模板的更多信息,请参阅解析程序映射模板概述。
示例 1
下面是 GraphQL 更改 deleteItem(id:
ID!)
的一个映射模板:如果具有此 ID 的项目存在,它将被删除。
{ "version" : "2017-02-28", "operation" : "DeleteItem", "key" : { "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id) } }
示例 2
下面是 GraphQL 更改 deleteItem(id: ID!,
expectedVersion: Int!)
的一个映射模板:如果具有此 ID 的项目存在,它将被删除,但仅当其 version
字段设置为 expectedVersion
时:
{ "version" : "2017-02-28", "operation" : "DeleteItem", "key" : { "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id) }, "condition" : { "expression" : "attribute_not_exists(id) OR version = :expectedVersion", "expressionValues" : { ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion) } } }
有关 DynamoDB DeleteItem
API 的更多信息,请参阅 DynamoDB API 文档。
Query
这些区域有:Query
请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个Query
请求发送到 DynamoDB,并使您能够指定以下各项:
-
键表达式
-
要使用的索引
-
任何额外的筛选条件
-
要返回多少个项目
-
是否使用一致性读取
-
查询方向(向前或向后)
-
分页标记
Query
映射文档具有以下结构:
{ "version" : "2017-02-28", "operation" : "Query", "query" : { "expression" : "some expression", "expressionNames" : { "#foo" : "foo" }, "expressionValues" : { ":bar" : ... typed value } }, "index" : "fooIndex", "nextToken" : "a pagination token", "limit" : 10, "scanIndexForward" : true, "consistentRead" : false, "select" : "ALL_ATTRIBUTES", "filter" : { ... } }
字段定义如下:
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的。要执行
Query
DynamoDB 操作,此字段必须设置为Query
。此值为必填项。 -
query
-
这些区域有:
query
部分让您指定一个键条件表达式,此表达式描述要从 DynamoDB 中检索哪些项目。有关如何编写键条件表达式的更多信息,请参阅DynamoDB KeyConditions 文档. 必须指定此部分。-
expression
-
查询表达式。必须指定此字段。
-
expressionNames
-
用于替代表达式属性名称 占位符,格式为键值对。键对应于中使用的名称占位符
expression
,而值必须是与 DynamoDB 中项目的属性名称相对应的字符串。此字段是可选的,应只填充expression
中使用的表达式属性名称占位符的替代内容。 -
expressionValues
-
用于替代表达式属性值 占位符,格式为键/值对。键对应于
expression
中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此值为必填项。此字段是可选的,应只填充expression
中使用的表达式属性值占位符的替代内容。
-
-
filter
-
另一个筛选条件,该筛选条件可用于在从 DynamoDB 返回结果之前先筛选结果。有关筛选条件的更多信息,请参阅筛选条件。此字段为可选项。
-
index
-
要查询的索引的名称。通过 DynamoDB 查询操作,您可以扫描本地二级索引和全局二级索引以及主键索引来搜索哈希键。如果指定,这会告知 DynamoDB 查询指定的索引。如果省略,则将查询主键索引。
-
nextToken
-
继续之前查询的分页标记。这应已从之前查询中获得。此字段为可选项。
-
limit
-
要计算的最大项目数(不一定是匹配项目数)。此字段为可选项。
-
scanIndexForward
-
一个布尔值,指示是向前还是向后查询。此字段是可选的,默认值为
true
。 -
consistentRead
-
一个布尔值,指示在查询 DynamoDB 时是否要使用一致性读取。此字段是可选的,默认值为
false
。 -
select
-
默认为Amazon AppSync DynamoDB 解析程序仅返回投影到索引中的属性。如果需要更多属性,则可以设置此字段。此字段为可选项。支持的值为:
-
ALL_ATTRIBUTES
-
返回指定表或索引中的所有项目属性。如果您查询本地二级索引,DynamoDB 将针对索引中的每个匹配项目从父表中提取整个项目。如果索引配置为投影所有项目属性,则可以从本地二级索引中获得所有数据,而不要求提取。
-
ALL_PROJECTED_ATTRIBUTES
-
仅在查询索引时才允许。检索已投影到索引的所有属性。如果索引配置为投影所有属性,则此返回值等同于指定
ALL_ATTRIBUTES
。
-
来自 DynamoDB 的结果自动转换为 GraphQL 和 JSON 基元类型,并且可用于映射上下文 ($context.result
)。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射).
有关响应映射模板的更多信息,请参阅解析程序映射模板概述。
结果的结构如下所示:
{ items = [ ... ], nextToken = "a pagination token", scannedCount = 10 }
字段定义如下:
-
items
-
包含DynamoDB 查询返回的列表。
-
nextToken
-
如果可能有更多结果,则
nextToken
包含可用于其他请求中的分页标记。注意Amazon AppSync 将加密和模糊从 DynamoDB 返回的分页标记。这可防止您的表数据无意中泄露给调用方。另请注意,无法跨不同解析程序使用这些分页标记。 -
scannedCount
-
在应用筛选表达式(如果有)之前与查询条件表达式匹配的项目的数量。
示例
下面是 GraphQL 查询 getPosts(owner:
ID!)
的一个映射模板。
在本示例中,将对表的全局二级索引执行查询,以返回指定的 ID 拥有的所有文章。
{ "version" : "2017-02-28", "operation" : "Query", "query" : { "expression" : "ownerId = :ownerId", "expressionValues" : { ":ownerId" : $util.dynamodb.toDynamoDBJson($context.arguments.owner) } }, "index" : "owner-index" }
有关 DynamoDB Query
API 的更多信息,请参阅 DynamoDB API 文档。
Scan
这些区域有:Scan
请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个Scan
请求发送到 DynamoDB,并使您能够指定以下各项:
-
排除结果的筛选条件
-
要使用的索引
-
要返回多少个项目
-
是否使用一致性读取
-
分页标记
-
并行扫描
Scan
映射文档具有以下结构:
{ "version" : "2017-02-28", "operation" : "Scan", "index" : "fooIndex", "limit" : 10, "consistentRead" : false, "nextToken" : "aPaginationToken", "totalSegments" : 10, "segment" : 1, "filter" : { ... } }
字段定义如下:
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的。要执行
Scan
DynamoDB 操作,此字段必须设置为Scan
。此值为必填项。 -
filter
-
一个筛选条件,可用于在从 DynamoDB 返回来自的结果之前先筛选结果。有关筛选条件的更多信息,请参阅筛选条件。此字段为可选项。
-
index
-
要查询的索引的名称。通过 DynamoDB 查询操作,您可以扫描本地二级索引和全局二级索引以及主键索引来搜索哈希键。如果指定,这会告知 DynamoDB 查询指定的索引。如果省略,则将查询主键索引。
-
limit
-
单次评估的最大项目数。此字段为可选项。
-
consistentRead
-
一个布尔值,指示在查询 DynamoDB 时是否要使用一致性读取。此字段是可选的,默认值为
false
。 -
nextToken
-
继续之前查询的分页标记。这应已从之前查询中获得。此字段为可选项。
-
select
-
默认为Amazon AppSync DynamoDB 解析程序仅返回投影到索引中的任何属性。如果需要更多属性,则可以设置此字段。此字段为可选项。支持的值为:
-
ALL_ATTRIBUTES
-
返回指定表或索引中的所有项目属性。如果您查询本地二级索引,DynamoDB 会从父表中提取索引中的每个匹配项目。如果索引配置为投影所有项目属性,则可以从本地二级索引中获得所有数据,而不要求提取。
-
ALL_PROJECTED_ATTRIBUTES
-
仅在查询索引时才允许。检索已投影到索引的所有属性。如果索引配置为投影所有属性,则此返回值等同于指定
ALL_ATTRIBUTES
。
-
-
totalSegments
-
执行并行扫描时对表进行分区的分段数。此字段是可选的,但如果指定
segment
,则必须指定此字段。 -
segment
-
执行并行扫描时,此操作中的表分段。此字段是可选的,但如果指定
totalSegments
,则必须指定此字段。
DynamoDB 扫描返回的结果自动转换为 GraphQL 和 JSON 基元类型,并且可用于映射上下文 ($context.result
)。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射).
有关响应映射模板的更多信息,请参阅解析程序映射模板概述。
结果的结构如下所示:
{ items = [ ... ], nextToken = "a pagination token", scannedCount = 10 }
字段定义如下:
-
items
-
包含DynamoDB 扫描返回的列表。
-
nextToken
-
如果可能有更多结果,则
nextToken
包含可用于其他请求中的分页标记。Amazon AppSync 将加密和模糊从 DynamoDB 返回的分页标记。这可防止您的表数据无意中泄露给调用方。另外,无法跨不同的解析程序使用这些分页标记。 -
scannedCount
-
在应用筛选表达式(如果有)之前,DynamoDB 检索的项目的数量。
示例 1
下面是 GraphQL 查询 allPosts
的一个映射模板。
在本示例中,将返回表中的所有条目。
{ "version" : "2017-02-28", "operation" : "Scan" }
示例 2
下面是 GraphQL 查询 postsMatching(title:
String!)
的一个映射模板。
在本示例中,将返回表中标题以 title
参数开头的所有条目。
{ "version" : "2017-02-28", "operation" : "Scan", "filter" : { "expression" : "begins_with(title, :title)", "expressionValues" : { ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title) }, } }
有关 DynamoDB Scan
API 的更多信息,请参阅 DynamoDB API 文档。
Sync(同步)
这些区域有:Sync
请求映射文档允许您从 DynamoDB 表中检索所有结果,然后仅接收自上次查询(增量更新)以来更改的数据。Sync
只能向受版本控制的 DynamoDB 数据源发出请求。您可以指定:
-
排除结果的筛选条件
-
要返回多少个项目
-
分页标记
-
上次
Sync
操作开始时间
Sync
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "Sync", "limit" : 10, "nextToken" : "aPaginationToken", "lastSync" : 1550000000000, "filter" : { ... } }
字段定义如下:
-
version
-
模板定义版本。当前仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
Sync
操作,此字段必须设置为Sync
。此值为必填项。 -
filter
-
一个筛选条件,可用于在从 DynamoDB 返回来自的结果之前先筛选结果。有关筛选条件的更多信息,请参阅筛选条件。此字段为可选项。
-
limit
-
单次评估的最大项目数。此字段为可选项。如果省略,则默认限制将设置为
100
个项目。此字段的最大值为1000
个项目。 -
nextToken
-
继续之前查询的分页标记。这应已从之前查询中获得。此字段为可选项。
-
lastSync
-
最后一次成功
Sync
操作开始的时刻(以纪元毫秒为单位)。如果指定,则仅返回lastSync
之后更改的项目。此字段是可选的,只有在从初始Sync
操作中检索所有页面后才能填充。如果省略,将返回基本 表中的结果,否则将返回增量 表中的结果。
DynamoDB 同步返回的结果自动转换为 GraphQL 和 JSON 基元类型,并且可用于映射上下文 ($context.result
)。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射).
有关响应映射模板的更多信息,请参阅解析程序映射模板概述。
结果的结构如下所示:
{ items = [ ... ], nextToken = "a pagination token", scannedCount = 10, startedAt = 1550000000000 }
字段定义如下:
-
items
-
包含同步操作返回的项目的列表。
-
nextToken
-
如果可能有更多结果,则
nextToken
包含可用于其他请求中的分页标记。Amazon AppSync 将加密和模糊从 DynamoDB 返回的分页标记。这可防止您的表数据无意中泄露给调用方。另外,无法跨不同的解析程序使用这些分页标记。 -
scannedCount
-
在应用筛选表达式(如果有)之前,DynamoDB 检索的项目的数量。
-
startedAt
-
同步操作开始的时刻,以纪元毫秒为单位,您可以在本地存储该值并在其他请求中将其用作
lastSync
参数。如果请求中包含分页令牌,则该值将与请求针对第一页结果返回的值相同。
示例 1
下面是 GraphQL 查询 syncPosts(nextToken:
String, lastSync: AWSTimestamp)
的一个映射模板。
在此示例中,如果省略 lastSync
,则返回基本表中的所有条目。如果提供了 lastSync
,则只返回增量同步表中自 lastSync
以来发生更改的条目。
{ "version" : "2018-05-29", "operation" : "Sync", "limit": 100, "nextToken": $util.toJson($util.defaultIfNull($ctx.args.nextToken, null)), "lastSync": $util.toJson($util.defaultIfNull($ctx.args.lastSync, null)) }
BatchGetItem
这些区域有:BatchGetItem
请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个BatchGetItem
向 DynamoDB 发出请求以检索多个项目,可能会跨多个表。对于此请求模板,您必须指定以下各项:
-
要从中检索项目的表名称
-
要从每个表中检索的项目的键
DynamoDB BatchGetItem
限制适用,并且无法提供任何条件表达式。
BatchGetItem
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "BatchGetItem", "tables" : { "table1": { "keys": [ ## Item to retrieve Key { "foo" : ... typed value, "bar" : ... typed value }, ## Item2 to retrieve Key { "foo" : ... typed value, "bar" : ... typed value } ], "consistentRead": true|false }, "table2": { "keys": [ ## Item3 to retrieve Key { "foo" : ... typed value, "bar" : ... typed value }, ## Item4 to retrieve Key { "foo" : ... typed value, "bar" : ... typed value } ], "consistentRead": true|false } } }
字段定义如下:
-
version
-
模板定义版本。仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
BatchGetItem
DynamoDB 操作,此字段必须设置为BatchGetItem
。此值为必填项。 -
tables
-
要从中检索项目的表。该值是一个映射,其中表名称被指定为映射的键。必须提供至少一个表。该
tables
值为必填项。-
keys
-
DynamoDB 键列表,这些键表示要检索的项目的主键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。
-
consistentRead
-
执行的操作时使用一致性读取GetItemoperation. 此值是可选的,默认为 false。
-
要记住的事项:
-
如果尚未从表中检索某个项目,则 null 元素将显示在该表的数据块中。
-
根据在请求映射模板中提供调用结果的顺序,针对每个表对这些结果进行排序。
-
BatchGetItem
中的每条 Get 命令都是原子的,但是,可以部分处理批处理。如果由于错误而部分处理一个批处理,则未处理的键将作为 unprocessedKeys 块内的调用结果的一部分返回。 -
BatchGetItem
限制为 100 个键。
对于以下示例请求映射模板:
{ "version": "2018-05-29", "operation": "BatchGetItem", "tables": { "authors": [ { "author_id": { "S": "a1" } }, ], "posts": [ { "author_id": { "S": "a1" }, "post_id": { "S": "p2" } } ], } }
$ctx.result
中可用的调用结果如下所示:
{ "data": { "authors": [null], "posts": [ # Was retrieved { "author_id": "a1", "post_id": "p2", "post_title": "title", "post_description": "description", } ] }, "unprocessedKeys": { "authors": [ # This item was not processed due to an error { "author_id": "a1" } ], "posts": [] } }
$ctx.error
包含有关该错误的详细信息。保证键数据、unprocessedKeys 和请求映射模板中提供的每个表键都出现在调用结果中。已删除的项目显示在数据块中。尚未处理的项目将在数据块中标记为 null 并置于 unprocessedKeys 块中。
有关更完整的示例,请按照DynamoDB Batch 教程: AppSync 这里教程:DynamoDB Batch 解析程序.
BatchDeleteItem
这些区域有:BatchDeleteItem
请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个BatchWriteItem
向 DynamoDB 发出请求以删除多个项目,可能会跨多个表。对于此请求模板,您必须指定以下各项:
-
要从中删除项目的表名称
-
要从每个表中删除的项目的键
DynamoDB BatchWriteItem
限制适用,并且无法提供任何条件表达式。
BatchDeleteItem
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "BatchDeleteItem", "tables" : { "table1": [ ## Item to delete Key { "foo" : ... typed value, "bar" : ... typed value }, ## Item2 to delete Key { "foo" : ... typed value, "bar" : ... typed value }], "table2": [ ## Item3 to delete Key { "foo" : ... typed value, "bar" : ... typed value }, ## Item4 to delete Key { "foo" : ... typed value, "bar" : ... typed value }], } }
字段定义如下:
-
version
-
模板定义版本。仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
BatchDeleteItem
DynamoDB 操作,此字段必须设置为BatchDeleteItem
。此值为必填项。 -
tables
-
要从中删除项目表。每个表都是一个 DynamoDB 键列表,表示要删除的项目的主键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。必须提供至少一个表。该
tables
值为必填项。
要记住的事项:
-
与
DeleteItem
操作相反,响应中不会返回完全删除的项目。只返回传递的键。 -
如果尚未从表中删除某个项目,null 元素将显示在该表的数据块中。
-
根据在请求映射模板中提供调用结果的顺序,针对每个表对这些结果进行排序。
-
BatchDeleteItem
中的每个删除命令都是原子命令。但是,可以部分处理一个批处理。如果由于错误而部分处理一个批处理,则未处理的键将作为 unprocessedKeys 块内的调用结果的一部分返回。 -
BatchDeleteItem
限制为 25 个键。
对于以下示例请求映射模板:
{ "version": "2018-05-29", "operation": "BatchDeleteItem", "tables": { "authors": [ { "author_id": { "S": "a1" } }, ], "posts": [ { "author_id": { "S": "a1" }, "post_id": { "S": "p2" } } ], } }
$ctx.result
中可用的调用结果如下所示:
{ "data": { "authors": [null], "posts": [ # Was deleted { "author_id": "a1", "post_id": "p2" } ] }, "unprocessedKeys": { "authors": [ # This key was not processed due to an error { "author_id": "a1" } ], "posts": [] } }
$ctx.error
包含有关该错误的详细信息。保证键数据、unprocessedKeys 和请求映射模板中提供的每个表键都出现在调用结果中。已删除的项目存在于数据块中。尚未处理的项目将在数据块中标记为 null 并置于 unprocessedKeys 块中。
有关更完整的示例,请按照DynamoDB Batch 教程: AppSync 这里教程:DynamoDB Batch 解析程序.
BatchPutItem
这些区域有:BatchPutItem
请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个BatchWriteItem
向 DynamoDB 发出请求以放置多个项目,可能会跨多个表。对于此请求模板,您必须指定以下各项:
-
要将项目放置在其中的表名称
-
要放置在每个表中的完整项目
DynamoDB BatchWriteItem
限制适用,并且无法提供任何条件表达式。
BatchPutItem
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "BatchPutItem", "tables" : { "table1": [ ## Item to put { "foo" : ... typed value, "bar" : ... typed value }, ## Item2 to put { "foo" : ... typed value, "bar" : ... typed value }], "table2": [ ## Item3 to put { "foo" : ... typed value, "bar" : ... typed value }, ## Item4 to put { "foo" : ... typed value, "bar" : ... typed value }], } }
字段定义如下:
-
version
-
模板定义版本。仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
BatchPutItem
DynamoDB 操作,此字段必须设置为BatchPutItem
。此值为必填项。 -
tables
-
要将项目放置在其中的DynamoDB 表。每个条目均表示要为此特定表列表。必须提供至少一个表。此值为必填项。
要记住的事项:
-
如果成功,响应中将返回完全插入的项目。
-
如果尚未向表中插入项目,null 元素将显示在该表的数据块中。
-
根据在请求映射模板中提供插入的项目的顺序,针对每个表对这些项目进行排序。
-
BatchPutItem
中的每条放置命令都是原子的,但是,可以部分处理批处理。如果由于错误而部分处理一个批处理,则未处理的键将作为 unprocessedKeys 块内的调用结果的一部分返回。 -
BatchPutItem
限制为 25 个项目。
对于以下示例请求映射模板:
{ "version": "2018-05-29", "operation": "BatchPutItem", "tables": { "authors": [ { "author_id": { "S": "a1" }, "author_name": { "S": "a1_name" } }, ], "posts": [ { "author_id": { "S": "a1" }, "post_id": { "S": "p2" }, "post_title": { "S": "title" } } ], } }
$ctx.result
中可用的调用结果如下所示:
{ "data": { "authors": [ null ], "posts": [ # Was inserted { "author_id": "a1", "post_id": "p2", "post_title": "title" } ] }, "unprocessedItems": { "authors": [ # This item was not processed due to an error { "author_id": "a1", "author_name": "a1_name" } ], "posts": [] } }
$ctx.error
包含有关该错误的详细信息。保证键数据、unprocessedItems 和请求映射模板中提供的每个表键都出现在调用结果中。已插入的项目存在于数据块中。尚未处理的项目将在数据块中标记为 null 并置于 unprocessedItems 块中。
有关更完整的示例,请按照DynamoDB Batch 教程: AppSync 这里教程:DynamoDB Batch 解析程序.
TransactGetItems
这些区域有:TransactGetItems
请求映射文档可以让你告诉Amazon AppSync DynamoDB 解析器创建一个TransactGetItems
向 DynamoDB 发出请求以检索多个项目,可能会跨多个表。对于此请求模板,您必须指定以下各项:
-
从中检索项目的每个请求项目的表名称
-
要从每个表中检索的每个请求项的键
DynamoDB TransactGetItems
限制适用,并且无法提供任何条件表达式。
TransactGetItems
映射文档具有以下结构:
{ "version": "2018-05-29", "operation": "TransactGetItems", "transactItems": [ ## First request item { "table": "table1", "key": { "foo": ... typed value, "bar": ... typed value } }, ## Second request item { "table": "table2", "key": { "foo": ... typed value, "bar": ... typed value } } ] }
字段定义如下:
-
version
-
模板定义版本。仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
TransactGetItems
DynamoDB 操作,此字段必须设置为TransactGetItems
。此值为必填项。 -
transactItems
-
要包含的请求项目。该值是请求项目的数组。必须提供至少一个请求项目。该
transactItems
值为必填项。-
table
-
要从中检索项目表。该值是表名的字符串。该
table
值为必填项。 -
key
-
DynamoDB 键,表示要检索的项目的主键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。
-
要记住的事项:
-
如果事务成功,
items
块中检索项目的顺序将与请求项目的顺序相同。 -
事务在 all-or-nothing 方式。如果任何请求项目导致错误,则整个交易都不会执行,并返回错误详细信息。
-
无法检索的请求项目不是错误。相反,null 元素会出现在相应位置的 items 块中。
-
如果一个事务的错误是TransactionCanceledException,
cancellationReasons
块将被填充。cancellationReasons
块中取消原因的顺序将与请求项目的顺序相同。 -
TransactGetItems
仅限于 25 个请求项目。
对于以下示例请求映射模板:
{ "version": "2018-05-29", "operation": "TransactGetItems", "transactItems": [ ## First request item { "table": "posts", "key": { "post_id": { "S": "p1" } } }, ## Second request item { "table": "authors", "key": { "author_id": { "S": a1 } } } ] }
如果事务成功并且只检索第一个请求的项目,则 $ctx.result
中可用的调用结果如下所示:
{ "items": [ { // Attributes of the first requested item "post_id": "p1", "post_title": "title", "post_description": "description" }, // Could not retrieve the second requested item null, ], "cancellationReasons": null }
如果交易由于以下原因而失败TransactionCanceledException由第一个请求项目引起,调用结果可用$ctx.result
如下所示:
{ "items": null, "cancellationReasons": [ { "type":"Sample error type", "message":"Sample error message" }, { "type":"None", "message":"None" } ] }
$ctx.error
包含有关该错误的详细信息。键 items 和 cancellationReasons 保证出现在 $ctx.result
中。
有关更完整的示例,请按照教程:DynamoDB 事务教程: AppSync 这里教程:DynamoDB 事务解析程序.
TransactWriteItems
这些区域有:TransactWriteItems
请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个TransactWriteItems
向 DynamoDB 发出请求以写入多个项目,可能跨多个表。对于此请求模板,您必须指定以下各项:
-
每个请求项目的目标表名称
-
要执行的每个请求项目的操作。支持四种类型的操作:PutItem、UpdateItem、DeleteItem, 和ConditionCheck
-
要写入的每个请求项目的键
DynamoDB TransactWriteItems
限制适用。
TransactWriteItems
映射文档具有以下结构:
{ "version": "2018-05-29", "operation": "TransactWriteItems", "transactItems": [ { "table": "table1", "operation": "PutItem", "key": { "foo": ... typed value, "bar": ... typed value }, "attributeValues": { "baz": ... typed value }, "condition": { "expression": "someExpression", "expressionNames": { "#foo": "foo" }, "expressionValues": { ":bar": ... typed value }, "returnValuesOnConditionCheckFailure": true|false } }, { "table":"table2", "operation": "UpdateItem", "key": { "foo": ... typed value, "bar": ... typed value }, "update": { "expression": "someExpression", "expressionNames": { "#foo": "foo" }, "expressionValues": { ":bar": ... typed value } }, "condition": { "expression": "someExpression", "expressionNames": { "#foo":"foo" }, "expressionValues": { ":bar": ... typed value }, "returnValuesOnConditionCheckFailure": true|false } }, { "table": "table3", "operation": "DeleteItem", "key":{ "foo": ... typed value, "bar": ... typed value }, "condition":{ "expression": "someExpression", "expressionNames": { "#foo": "foo" }, "expressionValues": { ":bar": ... typed value }, "returnValuesOnConditionCheckFailure": true|false } }, { "table": "table4", "operation": "ConditionCheck", "key":{ "foo": ... typed value, "bar": ... typed value }, "condition":{ "expression": "someExpression", "expressionNames": { "#foo": "foo" }, "expressionValues": { ":bar": ... typed value }, "returnValuesOnConditionCheckFailure": true|false } } ] }
- 字段定义如下:
-
-
version
-
模板定义版本。仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
TransactWriteItems
DynamoDB 操作,此字段必须设置为TransactWriteItems
。此值为必填项。 -
transactItems
-
要包含的请求项目。该值是请求项目的数组。必须提供至少一个请求项目。该
transactItems
值为必填项。对于
PutItem
,字段定义如下:-
table
-
目标 DynamoDB 表。该值是表名的字符串。该
table
值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
PutItem
DynamoDB 操作,此字段必须设置为PutItem
。此值为必填项。 -
key
-
DynamoDB 键,表示要放置的项目的主键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
attributeValues
-
要放入 DynamoDB 中的项目的其余属性。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此字段为可选项。
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
PutItem
请求将覆盖该项目的任何现有条目。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的详细信息,请参阅事务条件表达式。该值为可选项。
对于
UpdateItem
,字段定义如下:-
table
-
要更新的 DynamoDB 表。该值是表名的字符串。该
table
值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
UpdateItem
DynamoDB 操作,此字段必须设置为UpdateItem
。此值为必填项。 -
key
-
DynamoDB 键,表示要更新的项目的主键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
update
-
这些区域有:
update
部分让您指定一个更新表达式,该表达式描述如何更新 DynamoDB 中的项目。有关如何编写更新表达式的更多信息,请参阅DynamoDB UpdateExpressions 文档. 此部分是必需的。 -
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
UpdateItem
请求将更新现有条目,而不考虑其当前状态。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的详细信息,请参阅事务条件表达式。该值为可选项。
对于
DeleteItem
,字段定义如下:-
table
-
要删除其中项目的表。该值是表名的字符串。该
table
值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
DeleteItem
DynamoDB 操作,此字段必须设置为DeleteItem
。此值为必填项。 -
key
-
DynamoDB 键,表示要删除的项目的主键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
DeleteItem
请求将删除项目,而不考虑其当前状态。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的详细信息,请参阅事务条件表达式。该值为可选项。
对于
ConditionCheck
,字段定义如下:-
table
-
要在其中检查条件表。该值是表名的字符串。该
table
值为必填项。 -
operation
-
要执行的DynamoDB 操作。要执行
ConditionCheck
DynamoDB 操作,此字段必须设置为ConditionCheck
。此值为必填项。 -
key
-
表示要进行条件检查的项目的主键的 DynamoDB 键。DynamoDB 项目可能有单个哈希键(或哈希键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的详细信息,请参阅事务条件表达式。此值为必填项。
-
-
要记住的事项:
-
如果成功,响应中只返回请求项目的键。键的顺序将与请求项目的顺序相同。
-
事务在 all-or-nothing 方式。如果任何请求项目导致错误,则整个交易都不会执行,并返回错误详细信息。
-
不能有两个请求项目针对同一个项目。否则,它们将导致TransactionCanceledException错误消息。
-
如果一个事务的错误是TransactionCanceledException,
cancellationReasons
块将被填充。如果请求项目的条件检查失败且 您没有将returnValuesOnConditionCheckFailure
指定为false
,则表中存在的项目将被检索并存储在cancellationReasons
块的相应位置的item
中。 -
TransactWriteItems
仅限于 25 个请求项目。
对于以下示例请求映射模板:
{ "version": "2018-05-29", "operation": "TransactWriteItems", "transactItems": [ { "table": "posts", "operation": "PutItem", "key": { "post_id": { "S": "p1" } }, "attributeValues": { "post_title": { "S": "New title" }, "post_description": { "S": "New description" } }, "condition": { "expression": "post_title = :post_title", "expressionValues": { ":post_title": { "S": "Expected old title" } } } }, { "table":"authors", "operation": "UpdateItem", "key": { "author_id": { "S": "a1" }, }, "update": { "expression": "SET author_name = :author_name", "expressionValues": { ":author_name": { "S": "New name" } } }, } ] }
如果事务成功,$ctx.result
中可用的调用结果如下所示:
{ "keys": [ // Key of the PutItem request { "post_id": "p1", }, // Key of the UpdateItem request { "author_id": "a1" } ], "cancellationReasons": null }
如果事务因条件检查失败而失败 PutItem 请求,调用结果如下所示$ctx.result
如下所示:
{ "keys": null, "cancellationReasons": [ { "item": { "post_id": "p1", "post_title": "Actual old title", "post_description": "Old description" }, "type": "ConditionCheckFailed", "message": "The condition check failed." }, { "type": "None", "message": "None" } ] }
$ctx.error
包含有关该错误的详细信息。键 keys 和 cancellationReasons 保证出现在 $ctx.result
中。
有关更完整的示例,请按照教程:DynamoDB 事务教程: AppSync 这里教程:DynamoDB 事务解析程序.
类型系统(请求映射)
使用Amazon AppSync DynamoDB 解析器来调用你的 DynamoDB 表,Amazon AppSync 需要知道该调用中要使用的每个值的类型。这是因为 DynamoDB 比 GraphQL 或 JSON 支持更多的基元类型(如集和二进制数据)。Amazon AppSync 当在 GraphQL 和 DynamoDB 之间转换时,需要一些提示,否则它会对如何设定表中数据的结构做出一些假设。
有关 DynamoDB 数据类型的更多信息,请参阅 DynamoDB数据类型描述符和数据类型文档中)。
DynamoDB 值由包含单个键值对的 JSON 对象表示。键指定 DynamoDB 类型,而值指定值本身。在下面的示例中,键 S
表示值是一个字符串,值 identifier
是字符串值本身。
{ "S" : "identifier" }
请注意,JSON 对象不能具有多于一个键值对。如果指定了多个键值对,将不会解析请求映射文档。
DynamoDB 值用在请求映射文档中您需要指定一个值用在请求映射文档中您需要指定一个值。您需要这样做的一些地方包括:key
和 attributeValue
部分以及表达式部分的 expressionValues
部分。在以下示例中,DynamoDB 字符串值identifier
正在分配给id
中返回的子位置类型key
部分(可能在GetItem
请求映射文档)。
"key" : { "id" : { "S" : "identifier" } }
支持的类型
Amazon AppSync 支持以下 DynamoDB 标量、文档和集类型:
- 字符串类型
S
-
单个字符串值。DynamoDB 字符串值由以下内容指示:
{ "S" : "some string" }
示例用法如下:
"key" : { "id" : { "S" : "some string" } }
- 字符串集类型
SS
-
一组字符串值。DynamoDB 字符串集值由以下内容指示:
{ "SS" : [ "first value", "second value", ... ] }
示例用法如下:
"attributeValues" : { "phoneNumbers" : { "SS" : [ "+1 555 123 4567", "+1 555 234 5678" ] } }
- 数字类型
N
-
单个数字值。DynamoDB 数字值由以下内容指示:
{ "N" : 1234 }
示例用法如下:
"expressionValues" : { ":expectedVersion" : { "N" : 1 } }
- 数字集类型
NS
-
一组数字值。DynamoDB 数字集值由以下内容指示:
{ "NS" : [ 1, 2.3, 4 ... ] }
示例用法如下:
"attributeValues" : { "sensorReadings" : { "NS" : [ 67.8, 12.2, 70 ] } }
- 二进制类型
B
-
二进制值。DynamoDB 二进制值由以下内容指示:
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
请注意,该值实际上是一个字符串,此字符串是二进制数据的 base64 编码表示。Amazon AppSync 将此字符串解码回其二进制值,然后将此值发送到 DynamoDB。Amazon AppSync 按照 RFC 2045 的定义使用 base64 解码方案:忽略未包含在 base64 字母表中的任何字符。
示例用法如下:
"attributeValues" : { "binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" } }
- 二进制集类型
BS
-
一组二进制值。DynamoDB 二进制文件集值由以下内容指示:
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
请注意,该值实际上是一个字符串,此字符串是二进制数据的 base64 编码表示。Amazon AppSync 将此字符串解码回其二进制值,然后将此值发送到 DynamoDB。Amazon AppSync 按照 RFC 2045 的定义使用 base64 解码方案:忽略未包含在 base64 字母表中的任何字符。
示例用法如下:
"attributeValues" : { "binaryMessages" : { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ] } }
- 布尔值类型
BOOL
-
布尔值。DynamoDB 布尔值由以下内容指示:
{ "BOOL" : true }
请注意,只有
true
和false
是有效值。示例用法如下:
"attributeValues" : { "orderComplete" : { "BOOL" : false } }
- 列表类型
L
-
任何其他受支持的 DynamoDB 值的列表。DynamoDB 列表值由以下内容指示:
{ "L" : [ ... ] }
请注意该值是一个复合值,其中,列表可以包含零个或零个以上任何受支持的 DynamoDB 值(包括其他列表)。此列表还可以包含不同类型的混合。
示例用法如下:
{ "L" : [ { "S" : "A string value" }, { "N" : 1 }, { "SS" : [ "Another string value", "Even more string values!" ] } ] }
- 映射类型
M
-
表示其他受支持的 DynamoDB 值的无序集合。DynamoDB 映射值由以下内容指示:
{ "M" : { ... } }
请注意,一个映射可以包含零个或零个以上的键值对。键必须是字符串,而值可以是任何受支持的 DynamoDB 值(包括其他映射)。此映射还可以包含不同类型的混合。
示例用法如下:
{ "M" : { "someString" : { "S" : "A string value" }, "someNumber" : { "N" : 1 }, "stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] } } }
- Null 类型
NULL
-
Null 值。DynamoDB Null 值由以下内容指示:
{ "NULL" : null }
示例用法如下:
"attributeValues" : { "phoneNumbers" : { "NULL" : null } }
有关每个类型的更多信息,请参阅 DynamoDB 文档。
类型系统(响应映射)
收到来自 DynamoDB 的响应时,Amazon AppSync 会自动将其转换为 GraphQL 和 JSON 基元类型。DynamoDB 中的每个属性都会被解码并在响应映射上下文中返回。
例如,如果 DynamoDB 返回以下内容:
{ "id" : { "S" : "1234" }, "name" : { "S" : "Nadia" }, "age" : { "N" : 25 } }
然后是Amazon AppSync DynamoDB 解析程序将其转换为 GraphQL 和 JSON 类型,如下所示:
{ "id" : "1234", "name" : "Nadia", "age" : 25 }
本部分说明 Amazon AppSync 如何转换以下 DynamoDB 标量、文档和集类型:
- 字符串类型
S
-
单个字符串值。DynamoDB 字符串值作为字符串返回。
例如,如果 DynamoDB 返回以下 DynamoDB 字符串值:
{ "S" : "some string" }
Amazon AppSync 将其转换为字符串:
"some string"
- 字符串集类型
SS
-
一组字符串值。DynamoDB 字符串列表返回。
例如,如果 DynamoDB 返回以下 DynamoDB 字符串集值:
{ "SS" : [ "first value", "second value", ... ] }
Amazon AppSync 将其转换为字符串的列表:
[ "+1 555 123 4567", "+1 555 234 5678" ]
- 数字类型
N
-
单个数字值。DynamoDB 数字值作为数字返回。
例如,如果 DynamoDB 返回以下 DynamoDB 数字值:
{ "N" : 1234 }
Amazon AppSync 将其转换为数字:
1234
- 数字集类型
NS
-
一组数字值。DynamoDB 数字列表返回。
例如,如果 DynamoDB 返回以下 DynamoDB 数字集值:
{ "NS" : [ 67.8, 12.2, 70 ] }
Amazon AppSync 将其转换为数字的列表:
[ 67.8, 12.2, 70 ]
- 二进制类型
B
-
二进制值。DynamoDB 二进制值作为字符串返回,其中包含该值的 base64 表示形式。
例如,如果 DynamoDB 返回以下 DynamoDB 二进制值:
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
Amazon AppSync 将其转换为包含该值的 base64 表示形式的字符串:
"SGVsbG8sIFdvcmxkIQo="
- 二进制集类型
BS
-
一组二进制值。DynamoDB 二进制集作为字符串列表返回,其中包含这些值的 base64 表示形式。
例如,如果 DynamoDB 返回以下 DynamoDB 二进制集值:
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
Amazon AppSync 将其转换为包含这些值的 base64 表示形式的字符串列表:
[ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ]
- 布尔值类型
BOOL
-
布尔值。DynamoDB 布尔值作为布尔值返回。
例如,如果 DynamoDB 返回以下 DynamoDB 布尔值:
{ "BOOL" : true }
Amazon AppSync 将其转换为布尔值:
true
- 列表类型
L
-
任何其他受支持的 DynamoDB 值的列表。DynamoDB 列表作为值列表返回,其中每个内部值也会被转换。
例如,如果 DynamoDB 返回以下 DynamoDB 列表值:
{ "L" : [ { "S" : "A string value" }, { "N" : 1 }, { "SS" : [ "Another string value", "Even more string values!" ] } ] }
Amazon AppSync 将其转换为已转换值的列表:
[ "A string value", 1, [ "Another string value", "Even more string values!" ] ]
- 映射类型
M
-
任何其他受支持的 DynamoDB 值的键/值集合。DynamoDB 映射值作为 JSON 对象返回,其中每个键/值也会被转换。
例如,如果 DynamoDB 返回以下 DynamoDB 映射值:
{ "M" : { "someString" : { "S" : "A string value" }, "someNumber" : { "N" : 1 }, "stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] } } }
Amazon AppSync 将其转换为 JSON 对象:
{ "someString" : "A string value", "someNumber" : 1, "stringSet" : [ "Another string value", "Even more string values!" ] }
- Null 类型
NULL
-
Null 值。
例如,如果 DynamoDB 返回以下 DynamoDB Null 值:
{ "NULL" : null }
Amazon AppSync 将其转换为 null:
null
Filters
在 DynamoDB 中使用查询对象时Query
和Scan
操作,您可选择指定filter
,将计算结果并仅返回所需值。
Query
或 Scan
映射文档的筛选映射部分具有以下结构:
"filter" : { "expression" : "filter expression" "expressionNames" : { "#name" : "name", }, "expressionValues" : { ":value" : ... typed value }, }
字段定义如下:
-
expression
-
查询表达式。有关如何编写筛选条件表达式的更多信息,请参阅DynamoDB QueryFilter和DynamoDB ScanFilter文档中)。必须指定此字段。
-
expressionNames
-
用于替代表达式属性名称 占位符,格式为键值对。键对应于
expression
中使用的名称占位符。该值必须是与 DynamoDB 中项目的属性名称对应的字符串。此字段是可选的,应只填充expression
中使用的表达式属性名称占位符的替代内容。 -
expressionValues
-
用于替代表达式属性值 占位符,格式为键/值对。键对应于
expression
中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。必须指定此值。此字段是可选的,应只填充expression
中使用的表达式属性值占位符的替代内容。
示例
下面是映射模板的筛选条件部分,其中,如果标题以title
参数。
"filter" : { "expression" : "begins_with(#title, :title)", "expressionNames" : { "#title" : "title" }, "expressionValues" : { ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title) } }
条件表达式
当您在 DynamoDB 中使用变更对象时PutItem
、UpdateItem
, 和DeleteItem
DynamoDB 操作,您可以选择性地指定条件表达式,以根据在执行操作前已在 DynamoDB 中的对象状态控制请求是否应成功。
这些区域有:Amazon AppSync DynamoDB 解析器允许在中指定条件表达式PutItem
、UpdateItem
, 和DeleteItem
请求映射文档,还提供了一个策略供在条件失败和未更新对象时遵循。
示例 1
以下 PutItem
映射文档没有条件表达式。因此,它会将项目放置在 DynamoDB 中,从而覆盖现有项目,从而覆盖现有项目。
{ "version" : "2017-02-28", "operation" : "PutItem", "key" : { "id" : { "S" : "1" } } }
示例 2
以下PutItem
映射文档确实有一个条件表达式,仅当具有相同键(或在具有相同键)时,此表达式才允许操作成功不中返回的DynamoDB。
{ "version" : "2017-02-28", "operation" : "PutItem", "key" : { "id" : { "S" : "1" } }, "condition" : { "expression" : "attribute_not_exists(id)" } }
默认情况下,如果条件检查失败,则Amazon AppSync DynamoDB 解析程序将对更改返回错误,并在 DynamoDB 中返回中对象的当前值data
中返回的子位置类型error
GraphQL 响应的部分。但是,Amazon AppSync DynamoDB 解析程序提供了一些额外功能,以帮助开发人员处理一些常见的边缘情况:
-
如果Amazon AppSync DynamoDB 解析程序可以确定 DynamoDB 中的当前值与所需的结果匹配,它会将操作视为已成功。
-
此时不是返回错误,而是可以将解析程序配置为调用自定义 Lambda 函数,以决定Amazon AppSync DynamoDB 解析器应处理该故障。
这些内容将在处理条件检查失败部分中更详细地介绍。
有关 DynamoDB 条件表达式的更多信息,请参阅DynamoDB ConditionExpressions 文档.
指定条件
PutItem
、UpdateItem
和 DeleteItem
请求映射文档都允许指定可选的 condition
部分。如果省略,则不会进行条件检查。如果指定,条件必须为 true,操作才能成功。
condition
部分具有以下结构:
"condition" : { "expression" : "someExpression" "expressionNames" : { "#foo" : "foo" }, "expressionValues" : { ":bar" : ... typed value }, "equalsIgnore" : [ "version" ], "consistentRead" : true, "conditionalCheckFailedHandler" : { "strategy" : "Custom", "lambdaArn" : "arn:..." } }
下列字段指定条件:
-
expression
-
更新表达式本身。有关如何编写条件表达式的更多信息,请参阅DynamoDB ConditionExpressions 文档. 必须指定此字段。
-
expressionNames
-
用于替代表达式属性名称占位符,格式为键值对。键对应于中使用的名称占位符表情,而值必须是与 DynamoDB 中项目的属性名称相对应的字符串。此字段是可选的,应只填充 expression 中使用的表达式属性名称占位符的替代内容。
-
expressionValues
-
用于替代表达式属性值占位符,格式为键值对。键对应于表达式中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅“类型系统(请求映射)”。必须指定此值。此字段是可选的,应只填充表达式中使用的表达式属性值占位符的替代内容。
剩下的字段告诉Amazon AppSync DynamoDB 解析程序如何处理条件检查失败:
-
equalsIgnore
-
当条件检查失败时使用
PutItem
operation.Amazon AppSync DynamoDB 解析程序会将中目前的项目与它试图写入的项目进行比较。如果两者相同,则它会将操作视为已成功。可以使用equalsIgnore
字段指定当 Amazon AppSync 执行该比较时应忽略的属性的列表。例如,如果唯一差异是version
属性,则它会将该操作视为已成功。此字段为可选项。 -
consistentRead
-
当条件检查失败时,Amazon AppSync 使用强一致性读取从 DynamoDB 获取项目的当前值。您可以使用此字段告知Amazon AppSync DynamoDB 解析程序将改用最终一致性读取。此字段是可选的,默认值为
true
。 -
conditionalCheckFailedHandler
-
此部分允许您指定Amazon AppSync DynamoDB 解析程序在比较中的当前值与预期结果后将处理条件检查失败。此部分是可选的。如果省略,它默认为
Reject
策略。-
strategy
-
策略Amazon AppSync DynamoDB 解析程序在比较 DynamoDB 中的当前值与预期结果进行比较。此字段为必填字段,有以下可能的值:
-
Reject
-
更改失败,对更改返回错误,并在 DynamoDB 中返回中对象的当前值
data
中返回的子位置类型error
GraphQL 响应的部分。 -
Custom
-
这些区域有:Amazon AppSync DynamoDB 解析程序将调用自定义 Lambda 函数,以决定如何处理条件检查失败。当
strategy
设置为Custom
时,lambdaArn
字段必须包含要调用的 Lambda 函数的 ARN。
-
-
lambdaArn
-
Lambda 函数的 ARN,将调用该函数来确定Amazon AppSync DynamoDB 解析器应处理条件检查失败。当
strategy
设置为Custom
时,必须指定此字段。有关如何使用此功能的更多信息,请参阅处理条件检查失败。
-
处理条件检查失败
默认情况下,当条件检查失败时,Amazon AppSync DynamoDB 解析程序将对更改返回错误,并在 DynamoDB 中返回中对象的当前值data
中返回的子位置类型error
GraphQL 响应的部分。但是,Amazon AppSync DynamoDB 解析程序提供了一些额外功能,以帮助开发人员处理一些常见的边缘情况:
-
如果Amazon AppSync DynamoDB 解析程序可以确定 DynamoDB 中的当前值与所需的结果匹配,它会将操作视为已成功。
-
此时不是返回错误,而是可以将解析程序配置为调用自定义 Lambda 函数,以决定Amazon AppSync DynamoDB 解析器应处理该故障。
此过程的流程图为:

检查所需结果
当条件检查失败时,Amazon AppSync DynamoDB 解析器执行GetItem
DynamoDB 请求从 DynamoDB 获取项目的当前值。默认情况下,它将使用强一致性读取,但这可以使用 condition
数据块中的 consistentRead
字段进行配置,并将当前值与预期结果进行比较:
-
对于
PutItem
operation.Amazon AppSync DynamoDB 解析程序会将当前值与其试图写入的值进行比较,但中所列的任何属性都不在中列出的任何属性equalsIgnore
从比较中返回的子位置类型。如果项目相同,它会将操作视为已成功,并返回从 DynamoDB 中检索的项目。否则,它将遵循所配置的策略。例如,如果
PutItem
请求映射文档如下所示:{ "version" : "2017-02-28", "operation" : "PutItem", "key" : { "id" : { "S" : "1" } }, "attributeValues" : { "name" : { "S" : "Steve" }, "version" : { "N" : 2 } }, "condition" : { "expression" : "version = :expectedVersion", "expressionValues" : { ":expectedVersion" : { "N" : 1 } }, "equalsIgnore": [ "version" ] } }
当前位于 DynamoDB 中的项目如下所示:
{ "id" : { "S" : "1" }, "name" : { "S" : "Steve" }, "version" : { "N" : 8 } }
这些区域有:Amazon AppSync DynamoDB 解析程序会将它试图写入的项目与当前值进行比较,并了解到唯一的差别是
version
字段,但是因为它被配置为忽略version
字段,它会将操作视为已成功,并返回从 DynamoDB 中检索的项目。 -
对于
DeleteItem
operation.Amazon AppSync DynamoDB 解析程序将进行检查,以验证是否从 DynamoDB 返回了项目。如果没有返回项目,它会将该操作视为已成功。否则,它将遵循所配置的策略。 -
对于
UpdateItem
operation.Amazon AppSync DynamoDB 解析程序没有足够的信息来确定 DynamoDB 中当前的项目是否与预期结果匹配,因此将遵循所配置的策略。
如果 DynamoDB 中对象的当前状态与预期结果不同,则Amazon AppSync DynamoDB 解析程序将遵循所配置的策略,以拒绝更改或者调用 Lambda 函数来确定接下来要做什么。
遵循“拒绝”策略
当关注Reject
策略,Amazon AppSync DynamoDB 解析程序将对更改返回错误,也会在 DynamoDB 中返回中对象的当前值data
中返回的子位置类型error
GraphQL 响应的部分。从 DynamoDB 返回的项目将放入响应映射模板,以便将其转换为客户端预期的格式,也将按选择集进行筛选。
例如,给定以下更改请求:
mutation { updatePerson(id: 1, name: "Steve", expectedVersion: 1) { Name theVersion } }
如果从 DynamoDB 返回的项目如下所示:
{ "id" : { "S" : "1" }, "name" : { "S" : "Steve" }, "version" : { "N" : 8 } }
并且响应映射模板如下所示:
{ "id" : $util.toJson($context.result.id), "Name" : $util.toJson($context.result.name), "theVersion" : $util.toJson($context.result.version) }
GraphQL 响应如下所示:
{ "data": null, "errors": [ { "message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ)" "errorType": "DynamoDB:ConditionalCheckFailedException", "data": { "Name": "Steve", "theVersion": 8 }, ... } ] }
另外,如果返回的对象中的任何字段在更改成功后已由其他解析程序填充,则当在 error
部分中返回此对象时,将不会对这些字段进行解析。
遵循“自定义”策略
当关注Custom
策略,Amazon AppSync DynamoDB 解析程序将调用 Lambda 函数以决定后续操作。Lambda 函数选择下列选项之一:
-
reject
更改。这告诉了Amazon AppSync DynamoDB 解析器表现得好像配置的策略是Reject
,对更改返回错误,并在 DynamoDB 中返回中对象的当前值(如上一部分所述)。 -
discard
更改。这告诉了Amazon AppSync DynamoDB 解析程序无提示忽略条件检查失败,并在 DynamoDB 中返回中的值。 -
retry
更改。这告诉了Amazon AppSync DynamoDB 解析程序使用新的请求映射文档重试更改。
Lambda 调用请求
这些区域有:Amazon AppSync DynamoDB 解析程序将调用在lambdaArn
. 它将使用在数据源上配置的相同 service-role-arn
。调用的负载具有以下结构:
{ "arguments": { ... }, "requestMapping": {... }, "currentValue": { ... }, "resolver": { ... }, "identity": { ... } }
字段定义如下:
-
arguments
-
来自 GraphQL 更改的参数。这与可用于
$context.arguments
中的请求映射文档的参数相同。 -
requestMapping
-
用于此操作的请求映射文档。
-
currentValue
-
DynamoDB 中对象的当前值。
-
resolver
-
有关 Amazon AppSync 解析程序的信息。
-
identity
-
有关调用方的信息。这与可用于
$context.identity
中的请求映射文档的身份信息相同。
负载的完整示例:
{ "arguments": { "id": "1", "name": "Steve", "expectedVersion": 1 }, "requestMapping": { "version" : "2017-02-28", "operation" : "PutItem", "key" : { "id" : { "S" : "1" } }, "attributeValues" : { "name" : { "S" : "Steve" }, "version" : { "N" : 2 } }, "condition" : { "expression" : "version = :expectedVersion", "expressionValues" : { ":expectedVersion" : { "N" : 1 } }, "equalsIgnore": [ "version" ] } }, "currentValue": { "id" : { "S" : "1" }, "name" : { "S" : "Steve" }, "version" : { "N" : 8 } }, "resolver": { "tableName": "People", "awsRegion": "us-west-2", "parentType": "Mutation", "field": "updatePerson", "outputType": "Person" }, "identity": { "accountId": "123456789012", "sourceIp": "x.x.x.x", "user": "AIDAAAAAAAAAAAAAAAAAA", "userArn": "arn:aws:iam::123456789012:user/appsync" } }
Lambda 调用响应
Lambda 函数可以检查调用负载并应用任何业务逻辑,以决定Amazon AppSync DynamoDB 解析器应处理该故障。有三种选项可用于处理条件检查失败:
-
reject
更改。此选项的响应负载必须具有此结构:{ "action": "reject" }
这告诉了Amazon AppSync DynamoDB 解析器表现得好像配置的策略是
Reject
,对更改返回错误并在 DynamoDB 中返回中对象的当前值(如上一部分所述)。 -
discard
更改。此选项的响应负载必须具有此结构:{ "action": "discard" }
这告诉了Amazon AppSync DynamoDB 解析程序无提示忽略条件检查失败,并在 DynamoDB 中返回中的值。
-
retry
更改。此选项的响应负载必须具有此结构:{ "action": "retry", "retryMapping": { ... } }
这告诉了Amazon AppSync DynamoDB 解析程序使用新的请求映射文档重试更改。的结构
retryMapping
部分的子集取决于 DynamoDB 操作,它是该操作的完整请求映射文档的子集。对于
PutItem
,retryMapping
部分具有以下结构。有关的说明attributeValues
字段,请参阅PutItem.{ "attributeValues": { ... }, "condition": { "equalsIgnore" = [ ... ], "consistentRead" = true } }
对于
UpdateItem
,retryMapping
部分具有以下结构。有关的说明update
部分中返回的子位置类型UpdateItem.{ "update" : { "expression" : "someExpression" "expressionNames" : { "#foo" : "foo" }, "expressionValues" : { ":bar" : ... typed value } }, "condition": { "consistentRead" = true } }
对于
DeleteItem
,retryMapping
部分具有以下结构。{ "condition": { "consistentRead" = true } }
无法指定要使用的不同的操作或键。这些区域有:Amazon AppSync DynamoDB 解析程序仅允许对同一对象重试同一操作。另外,
condition
部分不允许指定conditionalCheckFailedHandler
。如果重试失败,Amazon AppSync DynamoDB 解析器遵循Reject
策略。
在下面的示例中,Lambda 函数处理失败的 PutItem
请求。业务逻辑将查看进行调用的用户。如果是由jeffTheAdmin
,它会重试请求,更新version
和expectedVersion
来自当前位于 DynamoDB 中的项目。否则,业务逻辑将拒绝更改。
exports.handler = (event, context, callback) => { console.log("Event: "+ JSON.stringify(event)); // Business logic goes here. var response; if ( event.identity.user == "jeffTheAdmin" ) { response = { "action" : "retry", "retryMapping" : { "attributeValues" : event.requestMapping.attributeValues, "condition" : { "expression" : event.requestMapping.condition.expression, "expressionValues" : event.requestMapping.condition.expressionValues } } } response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 } response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version } else { response = { "action" : "reject" } } console.log("Response: "+ JSON.stringify(response)) callback(null, response) };
事务条件表达式
事务条件表达式可用于 TransactWriteItems
中所有四种类型的操作的请求映射模板,即 PutItem
、DeleteItem
、UpdateItem
和 ConditionCheck
。
对于 PutItem
、DeleteItem
和 UpdateItem
,事务条件表达式是可选的。对于 ConditionCheck
,事务条件表达式是必需的。
示例 1
以下事务 DeleteItem
映射文档没有条件表达式。因此,它会删除 DynamoDB 中的项目。
{ "version": "2018-05-29", "operation": "TransactWriteItems", "transactItems": [ { "table": "posts", "operation": "DeleteItem", "key": { "id": { "S" : "1" } } } ] }
示例 2
以下事务型 DeleteItem
映射文档确实有一个事务条件表达式,只有当该文章的作者等于某个名称时,才允许操作成功。
{ "version": "2018-05-29", "operation": "TransactWriteItems", "transactItems": [ { "table": "posts", "operation": "DeleteItem", "key": { "id": { "S" : "1" } } "condition": { "expression": "author = :author", "expressionValues": { ":author": { "S" : "Chunyan" } } } } ] }
如果条件检查失败,则会导致 TransactionCanceledException
,错误详细信息将在 $ctx.result.cancellationReasons
中返回。请注意,默认情况下,DynamoDB 中使条件检查失败的旧项目将在中返回$ctx.result.cancellationReasons
指定条件
PutItem
、UpdateItem
和 DeleteItem
请求映射文档都允许指定可选的 condition
部分。如果省略,则不会进行条件检查。如果指定,条件必须为 true,操作才能成功。ConditionCheck
必须具有要指定的 condition
部分。条件必须为 true,整个事务才能成功。
condition
部分具有以下结构:
"condition": { "expression": "someExpression", "expressionNames": { "#foo": "foo" }, "expressionValues": { ":bar": ... typed value }, "returnValuesOnConditionCheckFailure": false }
下列字段指定条件:
-
expression
-
更新表达式本身。有关如何编写条件表达式的更多信息,请参阅DynamoDB ConditionExpressions 文档. 必须指定此字段。
-
expressionNames
-
用于替代表达式属性名称占位符,格式为键值对。键对应于中使用的名称占位符表情,而值必须是与 DynamoDB 中项目的属性名称相对应的字符串。此字段是可选的,应只填充 expression 中使用的表达式属性名称占位符的替代内容。
-
expressionValues
-
用于替代表达式属性值占位符,格式为键值对。键对应于表达式中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅“类型系统(请求映射)”。必须指定此值。此字段是可选的,应只填充表达式中使用的表达式属性值占位符的替代内容。
-
returnValuesOnConditionCheckFailure
-
指定在条件检查失败时是否检索中 DynamoDB 中的项目。检索到的项目将位于
$ctx.result.cancellationReasons[$index].item
中,其中$index
是未通过条件检查的请求项目的索引。默认值为 true。