本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
DynamoDB 的解析器映射模板参考
Amazon AppSync DynamoDB 解析器使您能够使用 GraphQL
GetItem
GetItem
请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBGetItem
发出请求,并允许您指定:
-
DynamoDB 中物品的密钥
-
是否使用一致性读取
GetItem
映射文档具有以下结构:
{ "version" : "2017-02-28", "operation" : "GetItem", "key" : { "foo" : ... typed value, "bar" : ... typed value }, "consistentRead" : true, "projection" : { ... } }
字段定义如下:
GetItem 字段
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
GetItem
DynamoDB 操作,此字段必须设置为GetItem
。此值为必填项。 -
key
-
DynamoDB 中物品的密钥。DynamoDB 项目可能具有单个哈希键或哈希键和排序键,具体取决于表结构。有关如何指定 “类型化值” 的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
consistentRead
-
是否要使用 DynamoDB 执行强一致性读取。这是可选的,默认值为
false
。 projection
-
一种投影,用于指定要从 DynamoDB 操作返回的属性。有关投影的更多信息,请参阅投影。此字段为可选项。
从 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 解析器向 DynamoDBPutItem
发出请求,并允许您指定以下内容:
-
DynamoDB 中物品的密钥
-
项目的完整内容(包括
key
和attributeValues
) -
操作成功执行的条件
PutItem
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "PutItem", "customPartitionKey" : "foo", "populateIndexFields" : boolean value, "key": { "foo" : ... typed value, "bar" : ... typed value }, "attributeValues" : { "baz" : ... typed value }, "condition" : { ... }, "_version" : 1 }
字段定义如下:
PutItem 字段
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
PutItem
DynamoDB 操作,此字段必须设置为PutItem
。此值为必填项。 -
key
-
DynamoDB 中物品的密钥。DynamoDB 项目可能具有单个哈希键或哈希键和排序键,具体取决于表结构。有关如何指定 “类型化值” 的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
attributeValues
-
要放入 DynamoDB 中的项目的其余属性。有关如何指定 “类型化值” 的更多信息,请参阅类型系统(请求映射)。此字段为可选项。
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
PutItem
请求将覆盖该项目的任何现有条目。有关条件的更多信息,请参阅条件表达式。该值为可选项。 -
_version
-
表示项目的最新已知版本的数值。该值为可选项。此字段用于冲突检测 ,仅受版本化数据源支持。
customPartitionKey
-
启用后,此字符串值会修改启用版本控制时增量同步表使用的
ds_sk
和ds_pk
记录的格式(有关更多信息,请参阅《Amazon AppSync 开发者指南》中的冲突检测和同步)。启用后,还会启用对populateIndexFields
条目的处理。此字段为可选项。 populateIndexFields
-
一个布尔值,与一起启用时
customPartitionKey
,会为增量同步表中的每条记录,特别是在gsi_ds_pk
和gsi_ds_sk
列中创建新条目。有关更多信息,请参阅Amazon AppSync 开发者指南中的冲突检测和同步。此字段为可选项。
写入 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 解析器向 DynamoDBUpdateItem
发出请求,并允许您指定以下内容:
-
DynamoDB 中物品的密钥
-
描述如何在 DynamoDB 中更新项目的更新表达式
-
操作成功执行的条件
UpdateItem
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "UpdateItem", "customPartitionKey" : "foo", "populateIndexFields" : boolean value, "key": { "foo" : ... typed value, "bar" : ... typed value }, "update" : { "expression" : "someExpression", "expressionNames" : { "#foo" : "foo" }, "expressionValues" : { ":bar" : ... typed value } }, "condition" : { ... }, "_version" : 1 }
字段定义如下:
UpdateItem 字段
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
UpdateItem
DynamoDB 操作,此字段必须设置为UpdateItem
。此值为必填项。 -
key
-
DynamoDB 中物品的密钥。DynamoDB 项目可能具有单个哈希键或哈希键和排序键,具体取决于表结构。有关指定 “类型值” 的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
update
-
该
update
部分允许您指定更新表达式,该表达式描述如何更新 DynamoDB 中的项目。有关如何编写更新表达式的更多信息,请参阅 DynamoDB UpdateExpressions 文档。此部分是必需的。update
部分有三个组成部分:-
expression
-
更新表达式。此值为必填项。
-
expressionNames
-
用于替代表达式属性名称 占位符,格式为键值对。该密钥对应于中使用的名称占位符
expression
,并且该值必须是与 DynamoDB 中项目的属性名称对应的字符串。此字段是可选的,应只填充expression
中使用的表达式属性名称占位符的替代内容。 -
expressionValues
-
用于替代表达式属性值 占位符,格式为键/值对。键对应于
expression
中使用的值占位符,而值必须为类型化值。有关如何指定 “类型化值” 的更多信息,请参阅类型系统(请求映射)。必须指定此值。此字段是可选的,应只填充expression
中使用的表达式属性值占位符的替代内容。
-
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
UpdateItem
请求将更新现有条目,而不考虑其当前状态。有关条件的更多信息,请参阅条件表达式。该值为可选项。 -
_version
-
表示项目的最新已知版本的数值。该值为可选项。此字段用于冲突检测 ,仅受版本化数据源支持。
customPartitionKey
-
启用后,此字符串值会修改启用版本控制时增量同步表使用的
ds_sk
和ds_pk
记录的格式(有关更多信息,请参阅《Amazon AppSync 开发者指南》中的冲突检测和同步)。启用后,还会启用对populateIndexFields
条目的处理。此字段为可选项。 populateIndexFields
-
一个布尔值,与一起启用时
customPartitionKey
,会为增量同步表中的每条记录,特别是在gsi_ds_pk
和gsi_ds_sk
列中创建新条目。有关更多信息,请参阅Amazon AppSync 开发者指南中的冲突检测和同步。此字段为可选项。
在 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 解析器向 DynamoDBDeleteItem
发出请求,并允许您指定以下内容:
-
DynamoDB 中物品的密钥
-
操作成功执行的条件
DeleteItem
映射文档具有以下结构:
{ "version" : "2018-05-29", "operation" : "DeleteItem", "customPartitionKey" : "foo", "populateIndexFields" : boolean value, "key": { "foo" : ... typed value, "bar" : ... typed value }, "condition" : { ... }, "_version" : 1 }
字段定义如下:
DeleteItem 字段
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
DeleteItem
DynamoDB 操作,此字段必须设置为DeleteItem
。此值为必填项。 -
key
-
DynamoDB 中物品的密钥。DynamoDB 项目可能具有单个哈希键或哈希键和排序键,具体取决于表结构。有关指定 “类型值” 的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
DeleteItem
请求将删除项目,而不考虑其当前状态。有关条件的更多信息,请参阅条件表达式。该值为可选项。 -
_version
-
表示项目的最新已知版本的数值。该值为可选项。此字段用于冲突检测 ,仅受版本化数据源支持。
customPartitionKey
-
启用后,此字符串值会修改启用版本控制时增量同步表使用的
ds_sk
和ds_pk
记录的格式(有关更多信息,请参阅《Amazon AppSync 开发者指南》中的冲突检测和同步)。启用后,还会启用对populateIndexFields
条目的处理。此字段为可选项。 populateIndexFields
-
一个布尔值,与一起启用时
customPartitionKey
,会为增量同步表中的每条记录,特别是在gsi_ds_pk
和gsi_ds_sk
列中创建新条目。有关更多信息,请参阅Amazon AppSync 开发者指南中的冲突检测和同步。此字段为可选项。
从 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
请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBQuery
发出请求,并允许您指定以下内容:
-
键表达式
-
要使用的索引
-
任何额外的筛选条件
-
要返回多少个项目
-
是否使用一致性读取
-
查询方向(向前或向后)
-
分页标记
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" | "ALL_PROJECTED_ATTRIBUTES" | "SPECIFIC_ATTRIBUTES", "filter" : { ... }, "projection" : { ... } }
字段定义如下:
查询字段
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
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
。 SPECIFIC_ATTRIBUTES
-
仅返回中列出的属性
expression
。projection
此返回值等同于在projection
不为其指定任何值expression
的情况下指定Select
。
-
projection
-
一种投影,用于指定要从 DynamoDB 操作返回的属性。有关投影的更多信息,请参阅投影。此字段为可选项。
DynamoDB 的结果会自动转换为 GraphQL 和 JSON 原始类型,可在映射上下文中找到 ($context.result
)。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射)。
有关响应映射模板的更多信息,请参阅解析程序映射模板概述。
结果的结构如下所示:
{ items = [ ... ], nextToken = "a pagination token", scannedCount = 10 }
字段定义如下:
-
items
-
包含 DynamoDB 查询返回的项目的列表。
-
nextToken
-
如果可能有更多结果,则
nextToken
包含可用于其他请求中的分页标记。请注意,它会对从 DynamoDB 返回的分页令牌Amazon AppSync 进行加密和模糊处理。这可防止您的表数据无意中泄露给调用方。另请注意,无法跨不同解析程序使用这些分页标记。 -
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 解析器向 DynamoDBScan
发出请求,并允许您指定以下内容:
-
排除结果的筛选条件
-
要使用的索引
-
要返回多少个项目
-
是否使用一致性读取
-
分页标记
-
并行扫描
Scan
映射文档具有以下结构:
{ "version" : "2017-02-28", "operation" : "Scan", "index" : "fooIndex", "limit" : 10, "consistentRead" : false, "nextToken" : "aPaginationToken", "totalSegments" : 10, "segment" : 1, "filter" : { ... }, "projection" : { ... } }
字段定义如下:
扫描字段
-
version
-
模板定义版本。目前支持
2017-02-28
和2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
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
。 SPECIFIC_ATTRIBUTES
-
仅返回中列出的属性
expression
。projection
此返回值等同于在projection
不为其指定任何值expression
的情况下指定Select
。
-
-
totalSegments
-
执行并行扫描时对表进行分区的分段数。此字段是可选的,但如果指定
segment
,则必须指定此字段。 -
segment
-
执行并行扫描时,此操作中的表分段。此字段是可选的,但如果指定
totalSegments
,则必须指定此字段。 projection
-
一种投影,用于指定要从 DynamoDB 操作返回的属性。有关投影的更多信息,请参阅投影。此字段为可选项。
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", "basePartitionKey": "Base Tables PartitionKey", "deltaIndexName": "delta-index-name", "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
操作中检索所有页面后才能填充。如果省略,将返回基本 表中的结果,否则将返回增量 表中的结果。 basePartitionKey
-
执行
Sync
操作时使用的基表的分区键。此字段允许在表使用自定义分区键时执行Sync
操作。此为可选字段。 deltaIndexName
-
用于
Sync
操作的索引。当表使用自定义分区键时,需要使用此索引才能对整个增量存储表进行Sync
操作。该Sync
操作将在 GSI 上执行(在gsi_ds_pk
和上创建gsi_ds_sk
)。此字段为可选项。
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 解析器向 DynamoDB 发出BatchGetItem
请求,以检索多个项目,可能是跨多个表检索多个项目。对于此请求模板,您必须指定以下各项:
-
要从中检索项目的表名称
-
要从每个表中检索的项目的键
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, "projection" : { ... } }, "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, "projection" : { ... } } } }
字段定义如下:
BatchGetItem 字段
-
version
-
模板定义版本。仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
BatchGetItem
DynamoDB 操作,此字段必须设置为BatchGetItem
。此值为必填项。 -
tables
-
用于从中检索项目的 DynamoDB 表。该值是一个映射,其中表名称被指定为映射的键。必须提供至少一个表。该
tables
值为必填项。-
keys
-
DynamoDB 键的主键,DynamoDB 键的主键。DynamoDB 项目可能具有单个哈希键或哈希键和排序键,具体取决于表结构。有关如何指定 “类型化值” 的更多信息,请参阅类型系统(请求映射)。
-
consistentRead
-
执行GetItem操作时是否使用一致性读取。此值是可选的,默认为 false。
projection
-
一种投影,用于指定要从 DynamoDB 操作返回的属性。有关投影的更多信息,请参阅投影。此字段为可选项。
-
要记住的事项:
-
如果尚未从表中检索某个项目,则 null 元素将显示在该表的数据块中。
-
调用结果根据请求映射模板中提供的顺序按表排序。
-
a 中的每个
Get
命令BatchGetItem
都是原子命令,但是,批处理可以部分处理。如果由于错误而部分处理一个批处理,则未处理的键将作为 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 块中。
要获得更完整的示例,请按照 AppSync 此处的 DynamoDB Batch 教程进行操作:DynamoDB 批处理解析器。
BatchDeleteItem
BatchDeleteItem
请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBBatchWriteItem
发出请求,请求删除多个项目,可能跨多个表。对于此请求模板,您必须指定以下各项:
-
要从中删除项目的表名称
-
要从每个表中删除的项目的键
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 }], } }
字段定义如下:
BatchDeleteItem 字段
-
version
-
模板定义版本。仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
BatchDeleteItem
DynamoDB 操作,此字段必须设置为BatchDeleteItem
。此值为必填项。 -
tables
-
要从中删除项目的 DynamoDB 表。每个表都是 DynamoDB 密钥的列表,代表要删除的项目的主键。DynamoDB 项目可能具有单个哈希键或哈希键和排序键,具体取决于表结构。有关如何指定 “类型化值” 的更多信息,请参阅类型系统(请求映射)。必须提供至少一个表。必须提供
tables
值。
要记住的事项:
-
与
DeleteItem
操作相反,响应中不会返回完全删除的项目。只返回传递的键。 -
如果尚未从表中删除某个项目,null 元素将显示在该表的数据块中。
-
调用结果根据请求映射模板中提供的顺序按表排序。
-
a 中的每个
Delete
命令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 块中。
要获得更完整的示例,请按照 AppSync 此处的 DynamoDB Batch 教程进行操作:DynamoDB 批处理解析器。
BatchPutItem
BatchPutItem
请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBBatchWriteItem
发出请求,请求放置多个项目,可能跨多个表。对于此请求模板,您必须指定以下各项:
-
要将项目放置在其中的表名称
-
要放置在每个表中的完整项目
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 }], } }
字段定义如下:
BatchPutItem 字段
-
version
-
模板定义版本。仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
BatchPutItem
DynamoDB 操作,此字段必须设置为BatchPutItem
。此值为必填项。 -
tables
-
用于存放物品的 DynamoDB 表。每个表条目都表示要为该特定表插入的 DynamoDB 项目列表。必须提供至少一个表。此值为必填项。
要记住的事项:
-
如果成功,响应中将返回完全插入的项目。
-
如果尚未向表中插入项目,null 元素将显示在该表的数据块中。
-
根据请求映射模板中提供的顺序,对插入的项目按表进行排序。
-
a 中的每个
Put
命令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 块中。
要获得更完整的示例,请按照 AppSync 此处的 DynamoDB Batch 教程进行操作:DynamoDB 批处理解析器。
TransactGetItems
TransactGetItems
请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDB 发出TransactGetItems
请求,以检索多个项目,可能是跨多个表检索多个项目。对于此请求模板,您必须指定以下各项:
-
从中检索项目的每个请求项目的表名称
-
要从每个表中检索的每个请求项的键
DynamoDB TransactGetItems
限制适用,并且无法提供任何条件表达式。
TransactGetItems
映射文档具有以下结构:
{ "version": "2018-05-29", "operation": "TransactGetItems", "transactItems": [ ## First request item { "table": "table1", "key": { "foo": ... typed value, "bar": ... typed value }, "projection" : { ... } }, ## Second request item { "table": "table2", "key": { "foo": ... typed value, "bar": ... typed value }, "projection" : { ... } } ] }
字段定义如下:
TransactGetItems 字段
-
version
-
模板定义版本。仅支持
2018-05-29
。此值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
TransactGetItems
DynamoDB 操作,此字段必须设置为TransactGetItems
。此值为必填项。 -
transactItems
-
要包含的请求项目。该值是请求项目的数组。必须提供至少一个请求项目。该
transactItems
值为必填项。-
table
-
用于检索物品的 DynamoDB 表。该值是表名的字符串。该
table
值为必填项。 -
key
-
DynamoDB 键,代表要要要要要要要要要要要要要要要要要要要要要 DynamoDB 项目可能具有单个哈希键或哈希键和排序键,具体取决于表结构。有关如何指定 “类型化值” 的更多信息,请参阅类型系统(请求映射)。
projection
-
一种投影,用于指定要从 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
中。
要查看更完整的示例,请按 AppSync 此处的 DynamoDB 事务教程教程教程:DynamoDB 事务解析器。
TransactWriteItems
TransactWriteItems
请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBTransactWriteItems
发出请求,请求写入多个项目,可能写入多个表。对于此请求模板,您必须指定以下各项:
-
每个请求项目的目标表名称
-
要执行的每个请求项目的操作。支持四种类型的操作:PutItem、UpdateItemDeleteItem、和 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 } } ] }
TransactWriteItems 字段
- 字段定义如下:
-
-
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
-
用于删除项目的 DynamoDB 表。该值是表名的字符串。该
table
值为必填项。 -
operation
-
要执行的 DynamoDB。要执行
DeleteItem
DynamoDB 操作,此字段必须设置为DeleteItem
。此值为必填项。 -
key
-
DynamoDB 键,代表要要要要要要要要要要要要要要要要要要要要要 DynamoDB 项目可能具有单个哈希键或哈希键和排序键,具体取决于表结构。有关如何指定 “类型化值” 的更多信息,请参阅类型系统(请求映射)。此值为必填项。
-
condition
-
根据 DynamoDB 中已有的对象状态,确定请求是否应成功的条件。如果未指定条件,则
DeleteItem
请求将删除项目,而不考虑其当前状态。您可以指定在状况检查失败时是否重新检索现有项目。有关交易条件的更多信息,请参阅事务条件表达式。该值为可选项。
对于
ConditionCheck
,字段定义如下:-
table
-
用于检查条件的 DynamoDB 表。该值是表名的字符串。该
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
中。
要查看更完整的示例,请按 AppSync 此处的 DynamoDB 事务教程教程教程: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
值分配给某个key
部分(可能在GetItem
请求映射文档中)中的id
字段。
"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 }
示例用法如下:
"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 Map 值以 JSON 对象的形式返回,其中每个键/值也会被转换。
例如,如果 DynamoDB 返回了以下 DynamoDB Map 值:
{ "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 }
Amazon AppSync 将其转换为空值:
null
Filters
使用Query
和Scan
操作在 DynamoDB 中查询对象时filter
,您可以选择指定用于评估结果并仅返回所需值的。
Query
或 Scan
映射文档的筛选映射部分具有以下结构:
"filter" : { "expression" : "filter expression" "expressionNames" : { "#name" : "name", }, "expressionValues" : { ":value" : ... typed value }, }
字段定义如下:
-
expression
-
查询表达式。有关如何编写过滤器表达式的更多信息,请参阅 DynamoDB QueryFilter 和 D ynamoDB ScanFilter 文档。必须指定此字段。
-
expressionNames
-
用于替代表达式属性名称 占位符,格式为键值对。键对应于
expression
中使用的名称占位符。该值必须是与 DynamoDB 中项目的属性名称相对应的字符串。此字段是可选的,应只填充expression
中使用的表达式属性名称占位符的替代内容。 -
expressionValues
-
用于替代表达式属性值 占位符,格式为键/值对。键对应于
expression
中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。必须指定此值。此字段是可选的,应只填充expression
中使用的表达式属性值占位符的替代内容。
示例
以下示例是映射模板的过滤器部分,其中仅当标题以title
参数开头时才返回从 DynamoDB 检索的条目。
"filter" : { "expression" : "begins_with(#title, :title)", "expressionNames" : { "#title" : "title" }, "expressionValues" : { ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title) } }
条件表达式
当您使用PutItem
、UpdateItem
和 DynamoDB 操作更改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 解析器会在 GraphQL 响应error
部分的data
字段中返回变异错误以及 DynamoDB 中对象的当前值。但是,Amazon AppSync DynamoDB 解析器提供了一些额外功能,可帮助开发人员处理一些常见的边缘案例:
-
如果Amazon AppSync DynamoDB 解析器可以确定 DynamoDB 中的当前值与所需结果相匹配,则无论如何它都会将操作视为成功。
-
您可以将解析器配置为调用自定义 Lambda 函数来决定 DynamAmazon AppSync oDB 解析器应如何处理故障,而不是返回错误。
这些内容将在处理条件检查失败部分中更详细地介绍。
有关 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
操作时条件检查失败时,Amazon AppSync DynamoDB 解析器会将 DynamoDB 中当前的项目与它尝试写入的项目进行比较。如果两者相同,则它会将操作视为已成功。可以使用equalsIgnore
字段指定当 Amazon AppSync 执行该比较时应忽略的属性的列表。例如,如果唯一的区别是version
属性,则它将操作视为成功。此字段为可选项。 -
consistentRead
-
当条件检查失败时,使用强一致性读取从 DynamoDBAmazon AppSync 获取项目的当前值。您可以使用此字段告诉Amazon AppSync DynamoDB 解析器改用最终一致性读取。此字段是可选的,默认值为
true
。 -
conditionalCheckFailedHandler
-
本部分允许您指定Amazon AppSync DynamoDB 解析器在将 DynamoDB 中的当前值与预期结果进行比较后如何处理条件检查失败。此部分是可选的。如果省略,它默认为
Reject
策略。-
strategy
-
Amazon AppSync DynamoDB 解析器在将 DynamoDB 中的当前值与预期结果进行比较后采用的策略。此字段为必填字段,有以下可能的值:
-
Reject
-
突变失败,变异和 DynamoDB 中对象的当前值在 GraphQL 响应
error
部分的data
字段中出现错误。 -
Custom
-
Amazon AppSync DynamoDB 解析器调用自定义 Lambda 函数来决定如何处理条件检查失败。当
strategy
设置为Custom
时,lambdaArn
字段必须包含要调用的 Lambda 函数的 ARN。
-
-
lambdaArn
-
要调用的 Lambda 函数的 ARN,用于确定Amazon AppSync DynamoDB 解析程序应如何处理条件检查失败。当
strategy
设置为Custom
时,必须指定此字段。有关如何使用此功能的更多信息,请参阅处理条件检查失败。
-
处理状态检查失败
默认情况下,当条件检查失败时,Amazon AppSync DynamoDB 解析器会在 GraphQL 响应error
部分的data
字段中返回变异错误和 DynamoDB 中对象的当前值。但是,Amazon AppSync DynamoDB 解析器提供了一些额外功能,可帮助开发人员处理一些常见的边缘案例:
-
如果Amazon AppSync DynamoDB 解析器可以确定 DynamoDB 中的当前值与所需结果相匹配,则无论如何它都会将操作视为成功。
-
您可以将解析器配置为调用自定义 Lambda 函数来决定 DynamAmazon AppSync oDB 解析器应如何处理故障,而不是返回错误。
此过程的流程图为:

检查所需的结果
当条件检查失败时,Amazon AppSync DynamoDB 解析器执行GetItem
DynamoDB 请求以从 DynamoDB 获取项目的当前值。默认情况下,它将使用强一致性读取,但这可以使用 condition
数据块中的 consistentRead
字段进行配置,并将当前值与预期结果进行比较:
-
对于该
PutItem
操作,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
操作中,Amazon AppSync DynamoDB 解析器会检查是否从 DynamoDB 返回了项目。如果没有返回项目,它会将该操作视为已成功。否则,它将遵循所配置的策略。 -
对于该
UpdateItem
操作,Amazon AppSync DynamoDB 解析器没有足够的信息来确定 DynamoDB 中当前的项目是否与预期结果匹配,因此遵循了配置的策略。
如果 DynamoDB 中对象的当前状态与预期结果不同,则Amazon AppSync DynamoDB 解析器将遵循配置的策略,拒绝突变或调用 Lambda 函数来确定下一步要做什么。
遵循 “拒绝” 策略
遵循Reject
策略时,Amazon AppSync DynamoDB 解析器会返回变异错误,并且还会在 GraphQL 响应error
部分的data
字段中返回 DynamoDB 中对象的当前值。从 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 解析器的行为就像配置的策略一样,返回变异错误和 DynamoDB 中对象的当前值,如上一节所述。Reject
-
discard
更改。这告诉Amazon AppSync DynamoDB 解析器默默忽略条件检查失败并返回 DynamoDB 中的值。 -
retry
更改。这告诉Amazon AppSync DynamoDB 解析器使用新的请求映射文档重试突变。
Lambda 调用请求
Amazon AppSync DynamoDB 解析器调用中指定的 Lambda 函数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 解析器的行为就像配置的策略一样,返回变异和 DynamoDB 中对象的当前值的错误,如上节所述。
Reject
-
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
,它会重试请求,更新当前在 DynamoDBexpectedVersion
中的项目中的和。version
否则,业务逻辑将拒绝更改。
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。
投影
使用GetItem
、Scan
、、和TransactGetItems
操作读取 DynamoDB 中的对象时,您可以选择指定用于标识所需属性的投影。Query
BatchGetItem
投影具有以下结构,类似于滤镜:
"projection" : { "expression" : "projection expression" "expressionNames" : { "#name" : "name", } }
字段定义如下:
expression
-
投影表达式,字符串。要检索单个属性,请指定其名称。对于多个属性,名称必须是逗号分隔的值。有关编写投影表达式的更多信息,请参阅 DynamoDB 投影表达式文档。此字段为必填。
-
expressionNames
-
以键值对形式替换表达式属性名称占位符。键对应于
expression
中使用的名称占位符。该值必须是与 DynamoDB 中项目的属性名称相对应的字符串。此字段是可选字段,只能使用中使用的表达式属性名称占位符的替换来填充expression
。有关的更多信息expressionNames
,请参阅 DynamoDB 文档。
示例 1
以下示例是 VTL 映射模板的投影部分,其中仅从 DynamoDB 返回id
属author
性和和:
"projection" : { "expression" : "#author, id", "expressionNames" : { "#author" : "author" } }
你可以使用 $context.info 访问你的 GraphQL 请求选择集。 selectionSetList。此字段允许您根据要求动态构造投影表达式。
将投影表达式与Query
和Scan
运算一起使用时,的值select
必须为SPECIFIC_ATTRIBUTES
。有关更多信息,请参阅 DynamoDB 文档。