DynamoDB 解析程序映射模板参考 - AWS AppSync
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

DynamoDB 解析程序映射模板参考

借助 AWS AppSync DynamoDB 解析程序,您可以使用 GraphQL 在您账户的现有 Amazon DynamoDB 表中存储和检索数据。此解析程序的工作方式是:使您可以将传入的 GraphQL 请求映射到 DynamoDB 调用,然后将 DynamoDB 响应映射回 GraphQL。本节介绍支持的 DynamoDB 操作的映射模板。

GetItem

GetItem 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 GetItem 请求,并使您能够指定:

  • DynamoDB 中项目的键

  • 是否使用一致性读取

GetItem 映射文档具有以下结构:

{ "version" : "2017-02-28", "operation" : "GetItem", "key" : { "foo" : ... typed value, "bar" : ... typed value }, "consistentRead" : true }

字段定义如下:

version

模板定义版本。目前支持 2017-02-282018-05-29。此值为必填项。

operation

要执行的 DynamoDB 操作。要执行 GetItem DynamoDB 操作,此字段必须设置为 GetItem。此值为必填项。

key

DynamoDB 中项目的键。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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 PutItem 请求,并使您能够指定以下各项:

  • DynamoDB 中项目的键

  • 项目的完整内容(包括 keyattributeValues

  • 操作成功执行的条件

PutItem 映射文档具有以下结构:

{ "version" : "2018-05-29", "operation" : "PutItem", "key": { "foo" : ... typed value, "bar" : ... typed value }, "attributeValues" : { "baz" : ... typed value }, "condition" : { ... }, "_version" : 1 }

字段定义如下:

version

模板定义版本。目前支持 2017-02-282018-05-29。此值为必填项。

operation

要执行的 DynamoDB 操作。要执行 PutItem DynamoDB 操作,此字段必须设置为 PutItem。此值为必填项。

key

DynamoDB 中项目的键。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 请求映射文档使您能够告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 UpdateItem 请求,并允许您指定以下各项:

  • 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-282018-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

表示项目的最新已知版本的数值。该值为可选项。此字段用于冲突检测 ,仅受版本化数据源支持。

在 DynamoDB 中更新的项目自动转换为 GraphQL 和 JSON 基元类型,并且可用于映射上下文 ($context.result) 中。

有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射)

有关响应映射模板的更多信息,请参阅解析程序映射模板概述

示例 1

下面是 GraphQL 更改 upvote(id: ID!) 的一个映射模板:

在本示例中,DynamoDB 中的一个项目就会让其 upvotesversion 字段递增 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!) 的一个映射模板:

这是一个复杂的示例,用于检查参数并动态生成更新表达式,此表达式仅包含由客户端提供的参数。例如,如果省略了 titleauthor,则不会更新它们。如果指定了参数但其值为 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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 DeleteItem 请求,并使您能够指定以下各项:

  • DynamoDB 中项目的键

  • 操作成功执行的条件

DeleteItem 映射文档具有以下结构:

{ "version" : "2018-05-29", "operation" : "DeleteItem", "key": { "foo" : ... typed value, "bar" : ... typed value }, "condition" : { ... }, "_version" : 1 }

字段定义如下:

version

模板定义版本。目前支持 2017-02-282018-05-29。此值为必填项。

operation

要执行的 DynamoDB 操作。要执行 DeleteItem DynamoDB 操作,此字段必须设置为 DeleteItem。此值为必填项。

key

DynamoDB 中项目的键。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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 Query 请求,并使您能够指定以下各项:

  • 键表达式

  • 要使用的索引

  • 任何额外的筛选条件

  • 要返回多少个项目

  • 是否使用一致性读取

  • 查询方向(向前或向后)

  • 分页标记

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-282018-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

默认情况下,AWS 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 包含可用于其他请求中的分页标记。请注意,AWS 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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 Scan 请求,并使您能够指定以下各项:

  • 排除结果的筛选条件

  • 要使用的索引

  • 要返回多少个项目

  • 是否使用一致性读取

  • 分页标记

  • 并行扫描

Scan 映射文档具有以下结构:

{ "version" : "2017-02-28", "operation" : "Scan", "index" : "fooIndex", "limit" : 10, "consistentRead" : false, "nextToken" : "aPaginationToken", "totalSegments" : 10, "segment" : 1, "filter" : { ... } }

字段定义如下:

version

模板定义版本。目前支持 2017-02-282018-05-29。此值为必填项。

operation

要执行的 DynamoDB 操作。要执行 Scan DynamoDB 操作,此字段必须设置为 Scan。此值为必填项。

filter

一个筛选条件,可用于在返回来自 DynamoDB 的结果之前先筛选结果。有关筛选条件的更多信息,请参阅筛选条件。此字段为可选项。

index

要查询的索引的名称。通过 DynamoDB 查询操作,您可以扫描本地二级索引和全局二级索引以及主键索引来搜索哈希键。如果指定,这会告知 DynamoDB 查询指定的索引。如果省略,则将查询主键索引。

limit

单次评估的最大项目数。此字段为可选项。

consistentRead

一个布尔值,指示在查询 DynamoDB 时是否要使用一致性读取。此字段是可选的,默认值为 false

nextToken

继续之前查询的分页标记。这应已从之前查询中获得。此字段为可选项。

select

默认情况下,AWS 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 包含可用于其他请求中的分页标记。AWS 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 表中检索所有结果,然后仅接收自上次查询(增量更新)以来更改的数据。只能对版本化的 DynamoDB 数据源发出 Sync 请求。您可以指定:

  • 排除结果的筛选条件

  • 要返回多少个项目

  • 分页标记

  • 上次 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 包含可用于其他请求中的分页标记。AWS 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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 BatchGetItem 请求以检索多个项目,可能会跨多个表。对于此请求模板,您必须指定以下各项:

  • 要从中检索项目的表名称

  • 要从每个表中检索的项目的键

DynamoDBBatchGetItem 限制适用,并且无法提供任何条件表达式

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 操作。要执行 BatchGetItemDynamoDB 操作,此字段必须设置为 BatchGetItem。此值为必填项。

tables

要从中检索项目的 DynamoDB 表。该值是一个映射,其中表名称被指定为映射的键。必须提供至少一个表。该 tables 值为必填项。

keys

表示要检索的项目的主键的 DynamoDB 键的列表。DynamoDB 项目可能有单个哈希键(或哈希键和排序键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)

consistentRead

是否在执行 GetItem 操作时使用一致性读取。此值是可选的,默认为 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 块中。

有关更完整的示例,请遵循此处的 AppSync 的 DynamoDB 批处理教程教程:DynamoDB 批处理解析程序

BatchDeleteItem

BatchDeleteItem 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 BatchWriteItem 请求以删除多个项目,可能跨多个表。对于此请求模板,您必须指定以下各项:

  • 要从中删除项目的表名称

  • 要从每个表中删除的项目的键

DynamoDBBatchWriteItem 限制适用,并且无法提供任何条件表达式

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 键的列表。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 块中。

有关更完整的示例,请遵循此处的 AppSync 的 DynamoDB 批处理教程教程:DynamoDB 批处理解析程序

BatchPutItem

BatchPutItem 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 BatchWriteItem 请求以放置多个项目,可能跨多个表。对于此请求模板,您必须指定以下各项:

  • 要将项目放置在其中的表名称

  • 要放置在每个表中的完整项目

DynamoDBBatchWriteItem 限制适用,并且无法提供任何条件表达式

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 表。每个表条目均表示要为此特定表插入的一个 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 块中。

有关更完整的示例,请遵循此处的 AppSync 的 DynamoDB 批处理教程教程:DynamoDB 批处理解析程序

TransactGetItems

TransactGetItems 请求映射文档可让您告知 AWS 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 } }, ## Second request item { "table": "table2", "key": { "foo": ... typed value, "bar": ... typed value } } ] }

字段定义如下:

version

模板定义版本。仅支持 2018-05-29。此值为必填项。

operation

要执行的 DynamoDB 操作。要执行 TransactGetItems DynamoDB 操作,此字段必须设置为 TransactGetItems。此值为必填项。

transactItems

要包含的请求项目。该值是请求项目的数组。必须提供至少一个请求项目。该 transactItems 值为必填项。

table

要从中检索项目的 DynamoDB 表。该值是表名的字符串。该 table 值为必填项。

key

表示要检索的项目的主键的 DynamoDB 键。DynamoDB 项目可能有单个哈希键(或哈希键和排序键),具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)

要记住的事项:

  • 如果事务成功,items 块中检索项目的顺序将与请求项目的顺序相同。

  • 事务以全部或全不的方式执行。如果任何请求项目导致错误,则整个交易都不会执行,并返回错误详细信息。

  • 无法检索的请求项目不是错误。相反,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 包含有关该错误的详细信息。键 itemscancellationReasons 保证出现在 $ctx.result 中。

有关更完整的示例,请按照此处的 DynamoDB 事务教程与 AppSync教程:DynamoDB 事务解析程序操作。

TransactWriteItems

TransactWriteItems 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 TransactWriteItems 请求以写入多个项目,可能跨多个表。对于此请求模板,您必须指定以下各项:

  • 每个请求项目的目标表名称

  • 要执行的每个请求项目的操作。支持四种类型的操作:PutItemUpdateItemDeleteItemConditionCheck

  • 要写入的每个请求项目的键

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

要删除其中项目的 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 中已有的对象的状态,确定请求是否应成功的条件。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的详细信息,请参阅事务条件表达式。此值为必填项。

要记住的事项:

  • 如果成功,响应中只返回请求项目的键。键的顺序将与请求项目的顺序相同。

  • 事务以全部或全不的方式执行。如果任何请求项目导致错误,则整个交易都不会执行,并返回错误详细信息。

  • 不能有两个请求项目针对同一个项目。否则,它们将导致 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 包含有关该错误的详细信息。键 keyscancellationReasons 保证出现在 $ctx.result 中。

有关更完整的示例,请按照此处的 DynamoDB 事务教程与 AppSync教程:DynamoDB 事务解析程序操作。

类型系统(请求映射)

当使用 AWS AppSync DynamoDB 解析程序调用 DynamoDB 表时,AWS AppSync 需要知道该调用中要使用的每个值的类型。这是因为 DynamoDB 比 GraphQL 或 JSON 支持更多的基元类型(如集和二进制数据)。当在 GraphQL 和 DynamoDB 之间转换时,AWS AppSync 需要一些提示,否则它会对如何设定表中数据的结构做出一些假设。

有关 DynamoDB 数据类型的更多信息,请参阅 DynamoDB 数据类型描述符数据类型文档。

DynamoDB 值由包含单个键值对的 JSON 对象表示。键指定 DynamoDB 类型,而值指定值本身。在下面的示例中,键 S 表示值是一个字符串,值 identifier 是字符串值本身。

{ "S" : "identifier" }

请注意,JSON 对象不能具有多于一个键值对。如果指定了多个键值对,将不会解析请求映射文档。

DynamoDB 值用在请求映射文档中您需要指定一个值的任何位置。您需要这样做的一些地方包括:keyattributeValue 部分以及表达式部分的 expressionValues 部分。在以下示例中,DynamoDB 字符串值 identifier 分配给 key 部分(可能位于 GetItem 字段映射文档中)的 id 字段。

"key" : { "id" : { "S" : "identifier" } }

支持的类型

AWS 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 编码表示。AWS AppSync 会将此字符串解码回其二进制值,然后将此值发送到 DynamoDB。AWS AppSync 按照 RFC 2045 的定义使用 base64 解码方案:忽略未包含在 base64 字母表中的任何字符。

示例用法如下:

"attributeValues" : { "binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" } }
二进制集类型 BS

一组二进制值。DynamoDB 二进制集值由以下内容指示:

{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }

请注意,该值实际上是一个字符串,此字符串是二进制数据的 base64 编码表示。AWS AppSync 会将此字符串解码回其二进制值,然后将此值发送到 DynamoDB。AWS AppSync 按照 RFC 2045 的定义使用 base64 解码方案:忽略未包含在 base64 字母表中的任何字符。

示例用法如下:

"attributeValues" : { "binaryMessages" : { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ] } }
布尔值类型 BOOL

布尔值。DynamoDB 布尔值由以下内容指示:

{ "BOOL" : true }

请注意,只有 truefalse 是有效值。

示例用法如下:

"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 的响应时,AWS AppSync 会自动将其转换为 GraphQL 和 JSON 基元类型。DynamoDB 中的每个属性都会被解码并在响应映射上下文中返回。

例如,如果 DynamoDB 返回以下内容:

{ "id" : { "S" : "1234" }, "name" : { "S" : "Nadia" }, "age" : { "N" : 25 } }

则 AWS AppSync DynamoDB 解析程序将其转换为 GraphQL 和 JSON 类型,如下所示:

{ "id" : "1234", "name" : "Nadia", "age" : 25 }

本部分说明 AWS AppSync 如何转换以下 DynamoDB 标量、文档和集类型:

字符串类型 S

单个字符串值。DynamoDB 字符串值作为字符串返回。

例如,如果 DynamoDB 返回以下 DynamoDB 字符串值:

{ "S" : "some string" }

AWS AppSync 将其转换为字符串:

"some string"
字符串集类型 SS

一组字符串值。DynamoDB 字符串集值作为字符串列表返回。

例如,如果 DynamoDB 返回以下 DynamoDB 字符串集值:

{ "SS" : [ "first value", "second value", ... ] }

AWS AppSync 将其转换为字符串的列表:

[ "+1 555 123 4567", "+1 555 234 5678" ]
数字类型 N

单个数字值。DynamoDB 数字值作为数字返回。

例如,如果 DynamoDB 返回以下 DynamoDB 数字值:

{ "N" : 1234 }

AWS AppSync 将其转换为数字:

1234
数字集类型 NS

一组数字值。DynamoDB 数字集值作为数字列表返回。

例如,如果 DynamoDB 返回以下 DynamoDB 数字集值:

{ "NS" : [ 67.8, 12.2, 70 ] }

AWS AppSync 将其转换为数字的列表:

[ 67.8, 12.2, 70 ]
二进制类型 B

二进制值。DynamoDB 二进制值作为字符串返回,其中包含该值的 base64 表示形式。

例如,如果 DynamoDB 返回以下 DynamoDB 二进制值:

{ "B" : "SGVsbG8sIFdvcmxkIQo=" }

AWS AppSync 将其转换为包含该值的 base64 表示形式的字符串:

"SGVsbG8sIFdvcmxkIQo="

请注意,二进制数据按照 RFC 4648RFC 2045 中指定的方式根据 base64 编码方案进行编码。

二进制集类型 BS

一组二进制值。DynamoDB 二进制集值作为字符串列表返回,其中包含这些值的 base64 表示形式。

例如,如果 DynamoDB 返回以下 DynamoDB 二进制集值:

{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }

AWS AppSync 将其转换为包含这些值的 base64 表示形式的字符串列表:

[ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ]

请注意,二进制数据按照 RFC 4648RFC 2045 中指定的方式根据 base64 编码方案进行编码。

布尔值类型 BOOL

布尔值。DynamoDB 布尔值作为布尔值返回。

例如,如果 DynamoDB 返回以下 DynamoDB 布尔值:

{ "BOOL" : true }

AWS AppSync 将其转换为布尔值:

true
列表类型 L

任何其他受支持的 DynamoDB 值的列表。DynamoDB 列表值作为值列表返回,其中每个内部值也将被转换。

例如,如果 DynamoDB 返回以下 DynamoDB 列表值:

{ "L" : [ { "S" : "A string value" }, { "N" : 1 }, { "SS" : [ "Another string value", "Even more string values!" ] } ] }

AWS 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!" ] } } }

AWS AppSync 将其转换为 JSON 对象:

{ "someString" : "A string value", "someNumber" : 1, "stringSet" : [ "Another string value", "Even more string values!" ] }
Null 类型 NULL

Null 值。

例如,如果 DynamoDB 返回以下 DynamoDB Null 值:

{ "NULL" : null }

AWS AppSync 将其转换为 null:

null

筛选条件

在 DynamoDB 中使用 QueryScan 操作查询对象时,您可以选择指定 filter,以评估结果并仅返回所需的值。

QueryScan 映射文档的筛选映射部分具有以下结构:

"filter" : { "expression" : "filter expression" "expressionNames" : { "#name" : "name", }, "expressionValues" : { ":value" : ... typed value }, }

字段定义如下:

expression

查询表达式。有关如何编写筛选条件表达式的更多信息,请参阅 DynamoDB QueryFilterDynamoDB 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) } }

条件表达式

当您使用 DynamoDB、PutItemUpdateItem 等 DynamoDB 操作在 DeleteItem 中更改对象时,您可以选择性地指定条件表达式,以根据在执行操作之前 DynamoDB 中已有的对象状态控制请求是否应成功。

AWS AppSync DynamoDB 解析程序允许在 PutItemUpdateItemDeleteItem 请求映射文档中指定条件表达式,还提供了一个策略供在条件失败和未更新对象时遵循。

示例 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)" } }

默认情况下,如果条件检查失败,AWS AppSync DynamoDB 解析程序将对更改返回错误,并在 GraphQL 响应的 error 部分的 data 字段中返回 DynamoDB 中对象的当前值。但是,AWS AppSync DynamoDB 解析程序提供了一些额外功能,以帮助开发人员处理一些常见的边缘情况:

  • 如果 AWS AppSync DynamoDB 解析程序可以确定 DynamoDB 中的当前值与所需的结果匹配,则它会将操作视为已成功。

  • 此时不是返回错误,而是可以将解析程序配置为调用自定义 Lambda 函数,以决定 AWS AppSync DynamoDB 解析程序应如何处理失败。

这些内容将在处理条件检查失败部分中更详细地介绍。

有关 DynamoDB 条件表达式的更多信息,请参阅 DynamoDB ConditionExpressions 文档

指定条件

PutItemUpdateItemDeleteItem 请求映射文档都允许指定可选的 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

用于替代表达式属性名称占位符,格式为键值对。键对应于 expression 中使用的名称占位符,而值必须为与 DynamoDB 中项目的属性名称相对应的字符串。此字段是可选的,应只填充 expression 中使用的表达式属性名称占位符的替代内容。

expressionValues

用于替代表达式属性值占位符,格式为键值对。键对应于表达式中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅“类型系统(请求映射)”。必须指定此值。此字段是可选的,应只填充表达式中使用的表达式属性值占位符的替代内容。

其余字段告知 AWS AppSync DynamoDB 解析程序如何处理条件检查失败:

equalsIgnore

如果在使用 PutItem 操作时条件检查失败,AWS AppSync DynamoDB 解析程序会将 DynamoDB 中目前的项目与它试图编写的项目进行比较。如果两者相同,则它会将操作视为已成功。可以使用 equalsIgnore 字段指定当 AWS AppSync 执行该比较时应忽略的属性的列表。例如,如果唯一差异是 version 属性,则它会将该操作视为已成功。此字段为可选项。

consistentRead

当条件检查失败时,AWS AppSync 将使用强一致性读取从 DynamoDB 获取项目的当前值。您可以使用此字段告知 AWS AppSync DynamoDB 解析程序改用最终一致性读取。此字段是可选的,默认值为 true

conditionalCheckFailedHandler

本部分可让您指定 AWS AppSync DynamoDB 解析程序在比较 DynamoDB 中的当前值与预期结果后,将如何处理条件检查失败。此部分是可选的。如果省略,它默认为 Reject 策略。

strategy

AWS AppSync DynamoDB 解析程序在比较 DynamoDB 中的当前值与预期结果后将采取的策略。此字段为必填字段,有以下可能的值:

Reject

更改失败,对更改返回错误,并在 GraphQL 响应的 error 部分的 data 字段中返回 DynamoDB 中对象的当前值。

Custom

AWS AppSync DynamoDB 解析程序将调用自定义 Lambda 函数,以决定如何处理条件检查失败。当 strategy 设置为 Custom 时,lambdaArn 字段必须包含要调用的 Lambda 函数的 ARN。

lambdaArn

Lambda 函数的 ARN,将调用该函数来确定 AWS AppSync DynamoDB 解析程序应如何处理条件检查失败。当 strategy 设置为 Custom 时,必须指定此字段。有关如何使用此功能的更多信息,请参阅处理条件检查失败

处理条件检查失败

默认情况下,如果条件检查失败,AWS AppSync DynamoDB 解析程序将对更改返回错误,并在 GraphQL 响应的 error 部分的 data 字段中返回 DynamoDB 中对象的当前值。但是,AWS AppSync DynamoDB 解析程序提供了一些额外功能,以帮助开发人员处理一些常见的边缘情况:

  • 如果 AWS AppSync DynamoDB 解析程序可以确定 DynamoDB 中的当前值与所需的结果匹配,则它会将操作视为已成功。

  • 此时不是返回错误,而是可以将解析程序配置为调用自定义 Lambda 函数,以决定 AWS AppSync DynamoDB 解析程序应如何处理失败。

此过程的流程图为:

检查所需结果

当条件检查失败时,AWS AppSync DynamoDB 解析程序将执行 GetItem DynamoDB 请求,以从 DynamoDB 获取项目的当前值。默认情况下,它将使用强一致性读取,但这可以使用 condition 数据块中的 consistentRead 字段进行配置,并将当前值与预期结果进行比较:

  • 对于 PutItem 操作,AWS 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 } }

    AWS AppSync DynamoDB 解析程序会将它试图写入的项目与当前值进行比较,并了解到唯一的差别是 version 字段,但因为它已配置为忽略 version 字段,所以它将该操作视为成功并返回从 DynamoDB 中检索的项目。

  • 对于 DeleteItem 操作,AWS AppSync DynamoDB 解析程序将检查以验证是否从 DynamoDB 返回了项目。如果没有返回项目,它会将该操作视为已成功。否则,它将遵循所配置的策略。

  • 对于 UpdateItem 操作,AWS AppSync DynamoDB 解析程序没有足够的信息来确定 DynamoDB 中当前的项目是否与预期结果匹配,因此将遵循所配置的策略。

如果 DynamoDB 中对象的当前状态与预期结果不同,则 AWS AppSync DynamoDB 解析程序将遵循所配置的策略,以拒绝更改或者调用 Lambda 函数来确定接下来要做什么。

遵循“拒绝”策略

当遵循 Reject 策略时,AWS 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 策略时,AWS AppSync DynamoDB 解析程序将调用 Lambda 函数以决定后续操作。Lambda 函数选择下列选项之一:

  • reject 更改。这将告知 AWS AppSync DynamoDB 解析程序按照已配置的策略为 Reject 的情形发挥作用,对更改返回错误并返回 DynamoDB 中对象的当前值(如上一部分所述)。

  • discard 更改。这将告知 AWS AppSync DynamoDB 解析程序无提示忽略条件检查失败,并且返回 DynamoDB 中的值。

  • retry 更改。这将告知 AWS AppSync DynamoDB 解析程序使用新的请求映射文档重试更改。

Lambda 调用请求

AWS AppSync DynamoDB 解析程序将调用在 lambdaArn 中指定的 Lambda 函数。它将使用在数据源上配置的相同 service-role-arn。调用的负载具有以下结构:

{ "arguments": { ... }, "requestMapping": {... }, "currentValue": { ... }, "resolver": { ... }, "identity": { ... } }

字段定义如下:

arguments

来自 GraphQL 更改的参数。这与可用于 $context.arguments 中的请求映射文档的参数相同。

requestMapping

用于此操作的请求映射文档。

currentValue

DynamoDB 中对象的当前值。

resolver

有关 AWS 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 函数可以检查调用负载并应用任何业务逻辑,以决定 AWS AppSync DynamoDB 解析程序应如何处理失败。有三种选项可用于处理条件检查失败:

  • reject 更改。此选项的响应负载必须具有此结构:

    { "action": "reject" }

    这将告知 AWS AppSync DynamoDB 解析程序按照已配置的策略为 Reject 的情形发挥作用,对更改返回错误并返回 DynamoDB 中对象的当前值(如上一部分所述)。

  • discard 更改。此选项的响应负载必须具有此结构:

    { "action": "discard" }

    这将告知 AWS AppSync DynamoDB 解析程序无提示忽略条件检查失败,并且返回 DynamoDB 中的值。

  • retry 更改。此选项的响应负载必须具有此结构:

    { "action": "retry", "retryMapping": { ... } }

    这将告知 AWS AppSync DynamoDB 解析程序使用新的请求映射文档重试更改。retryMapping 部分的结构取决于 DynamoDB 操作,它是该操作的完整请求映射文档的子集。

    对于 PutItemretryMapping 部分具有以下结构。有关 attributeValues 字段的描述,请参阅 PutItem

    { "attributeValues": { ... }, "condition": { "equalsIgnore" = [ ... ], "consistentRead" = true } }

    对于 UpdateItemretryMapping 部分具有以下结构。有关 update 部分的说明,请参阅 UpdateItem

    { "update" : { "expression" : "someExpression" "expressionNames" : { "#foo" : "foo" }, "expressionValues" : { ":bar" : ... typed value } }, "condition": { "consistentRead" = true } }

    对于 DeleteItemretryMapping 部分具有以下结构。

    { "condition": { "consistentRead" = true } }

    无法指定要使用的不同的操作或键。AWS AppSync DynamoDB 解析程序仅允许对同一对象重试同一操作。另外,condition 部分不允许指定 conditionalCheckFailedHandler。如果重试失败,AWS AppSync DynamoDB 解析程序将遵循 Reject 策略。

在下面的示例中,Lambda 函数处理失败的 PutItem 请求。业务逻辑将查看进行调用的用户。如果调用是由 jeffTheAdmin 进行的,则业务逻辑将重试此请求,同时从当前位于 DynamoDB 中的项目更新 versionexpectedVersion。否则,业务逻辑将拒绝更改。

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 中所有四种类型的操作的请求映射模板,即 PutItemDeleteItemUpdateItemConditionCheck

对于 PutItemDeleteItemUpdateItem,事务条件表达式是可选的。对于 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 中返回

指定条件

PutItemUpdateItemDeleteItem 请求映射文档都允许指定可选的 condition 部分。如果省略,则不会进行条件检查。如果指定,条件必须为 true,操作才能成功。ConditionCheck 必须具有要指定的 condition 部分。条件必须为 true,整个事务才能成功。

condition 部分具有以下结构:

"condition": { "expression": "someExpression", "expressionNames": { "#foo": "foo" }, "expressionValues": { ":bar": ... typed value }, "returnValuesOnConditionCheckFailure": false }

下列字段指定条件:

expression

更新表达式本身。有关如何编写条件表达式的更多信息,请参阅 DynamoDB ConditionExpressions 文档。必须指定此字段。

expressionNames

用于替代表达式属性名称占位符,格式为键值对。键对应于 expression 中使用的名称占位符,而值必须为与 DynamoDB 中项目的属性名称相对应的字符串。此字段是可选的,应只填充 expression 中使用的表达式属性名称占位符的替代内容。

expressionValues

用于替代表达式属性值占位符,格式为键值对。键对应于表达式中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅“类型系统(请求映射)”。必须指定此值。此字段是可选的,应只填充表达式中使用的表达式属性值占位符的替代内容。

returnValuesOnConditionCheckFailure

指定在条件检查失败时是否检索 DynamoDB 中的项目。检索到的项目将位于 $ctx.result.cancellationReasons[$index].item 中,其中 $index 是未通过条件检查的请求项目的索引。默认值为 true。