本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
DynamoDB 的 JavaScript 解析器函数参考
通过使用 Amazon AppSync DynamoDB 函数,您可以使用 GraphQL
GetItem
通过使用 GetItem
请求,您可以指示 Amazon AppSync DynamoDB 函数向 DynamoDB 发出 GetItem
请求,并允许您指定:
-
DynamoDB 中的项目的键
-
是否使用一致性读取
GetItem
请求具有以下结构:
type DynamoDBGetItem = { operation: 'GetItem'; key: { [key: string]: any }; consistentRead?: ConsistentRead; projection?: { expression: string; expressionNames?: { [key: string]: string }; }; };
字段定义如下:
GetItem 字段
-
operation
-
要执行的 DynamoDB 操作。要执行
GetItem
DynamoDB 操作,该字段必须设置为GetItem
。该值为必填项。 -
key
-
DynamoDB 中的项目的键。DynamoDB 项目可能具有单个哈希键,也可能具有哈希键和排序键,具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。该值为必填项。
-
consistentRead
-
是否对 DynamoDB 执行强一致性读取。这是可选的,默认值为
false
。 projection
-
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息,请参阅投影。该字段是可选的。
从 DynamoDB 返回的项目自动转换为 GraphQL 和 JSON 基元类型,并在上下文结果 (context.result
) 中提供。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射)。
有关 JavaScript 解析器的更多信息,请参阅 JavaScript 解析器概述。
示例
以下示例是 GraphQL 查询 getThing(foo: String!, bar: String!)
的函数请求处理程序:
export function request(ctx) { const {foo, bar} = ctx.args return { operation : "GetItem", key : util.dynamodb.toMapValues({foo, bar}), consistentRead : true } }
有关 DynamoDB GetItem
API 的更多信息,请参阅 DynamoDB API 文档。
PutItem
通过使用 PutItem
请求映射文档,您可以指示 Amazon AppSync DynamoDB 函数向 DynamoDB 发出 PutItem
请求,并允许您指定以下内容:
-
DynamoDB 中的项目的键
-
项目的完整内容(包括
key
和attributeValues
) -
操作成功执行的条件
PutItem
请求具有以下结构:
type DynamoDBPutItemRequest = { operation: 'PutItem'; key: { [key: string]: any }; attributeValues: { [key: string]: any}; condition?: ConditionCheckExpression; customPartitionKey?: string; populateIndexFields?: boolean; _version?: number; };
字段定义如下:
PutItem 字段
-
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 的项目自动转换为 GraphQL 和 JSON 基元类型,并在上下文结果 (context.result
) 中提供。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射)。
有关 JavaScript 解析器的更多信息,请参阅 JavaScript 解析器概述。
示例 1
以下示例是 GraphQL 变更 updateThing(foo: String!, bar:
String!, name: String!, version: Int!)
的函数请求处理程序。
如果带指定键的项目不存在,则会创建它。如果带指定键的项已存在,则会覆盖它。
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { foo, bar, ...values} = ctx.args return { operation: 'PutItem', key: util.dynamodb.toMapValues({foo, bar}), attributeValues: util.dynamodb.toMapValues(values), }; }
示例 2
以下示例是 GraphQL 变更 updateThing(foo: String!, bar: String!, name:
String!, expectedVersion: Int!)
的函数请求处理程序。
该示例验证当前位于 DynamoDB 中的项目的 version
字段是否设置为 expectedVersion
。
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { foo, bar, name, expectedVersion } = ctx.args; const values = { name, version: expectedVersion + 1 }; let condition = util.transform.toDynamoDBConditionExpression({ version: { eq: expectedVersion }, }); return { operation: 'PutItem', key: util.dynamodb.toMapValues({ foo, bar }), attributeValues: util.dynamodb.toMapValues(values), condition, }; }
有关 DynamoDB PutItem
API 的更多信息,请参阅 DynamoDB API 文档。
UpdateItem
通过使用 UpdateItem
请求,您可以指示 Amazon AppSync DynamoDB 函数向 DynamoDB 发出 UpdateItem
请求,并允许您指定以下内容:
-
DynamoDB 中的项目的键
-
描述如何更新 DynamoDB 中的项目的更新表达式
-
操作成功执行的条件
UpdateItem
请求具有以下结构:
type DynamoDBUpdateItemRequest = { operation: 'UpdateItem'; key: { [key: string]: any }; update: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; condition?: ConditionCheckExpression; customPartitionKey?: string; populateIndexFields?: boolean; _version?: number; };
字段定义如下:
UpdateItem 字段
-
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 类型转换的更多信息,请参阅类型系统(响应映射)。
有关 JavaScript 解析器的更多信息,请参阅 JavaScript 解析器概述。
示例 1
以下示例是 GraphQL 变更 upvote(id: ID!)
的函数请求处理程序。
在该示例中,DynamoDB 中的项目的 upvotes
和 version
字段递增 1。
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { id } = ctx.args; return { operation: 'UpdateItem', key: util.dynamodb.toMapValues({ 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
:
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { args: { input: { id, ...values } } } = ctx; const condition = { id: { attributeExists: true }, version: { eq: values.expectedVersion }, }; values.expectedVersion += 1; return dynamodbUpdateRequest({ keys: { id }, values, condition }); } /** * Helper function to update an item * @returns an UpdateItem request */ function dynamodbUpdateRequest(params) { const { keys, values, condition: inCondObj } = params; const sets = []; const removes = []; const expressionNames = {}; const expValues = {}; // Iterate through the keys of the values for (const [key, value] of Object.entries(values)) { expressionNames[`#${key}`] = key; if (value) { sets.push(`#${key} = :${key}`); expValues[`:${key}`] = value; } else { removes.push(`#${key}`); } } let expression = sets.length ? `SET ${sets.join(', ')}` : ''; expression += removes.length ? ` REMOVE ${removes.join(', ')}` : ''; const condition = JSON.parse( util.transform.toDynamoDBConditionExpression(inCondObj) ); return { operation: 'UpdateItem', key: util.dynamodb.toMapValues(keys), condition, update: { expression, expressionNames, expressionValues: util.dynamodb.toMapValues(expValues), }, }; }
有关 DynamoDB UpdateItem
API 的更多信息,请参阅 DynamoDB API 文档。
DeleteItem
通过使用 DeleteItem
请求,您可以指示 Amazon AppSync DynamoDB 函数向 DynamoDB 发出 DeleteItem
请求,并允许您指定以下内容:
-
DynamoDB 中的项目的键
-
操作成功执行的条件
DeleteItem
请求具有以下结构:
type DynamoDBDeleteItemRequest = { operation: 'DeleteItem'; key: { [key: string]: any }; condition?: ConditionCheckExpression; customPartitionKey?: string; populateIndexFields?: boolean; _version?: number; };
字段定义如下:
DeleteItem 字段
-
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 类型转换的更多信息,请参阅类型系统(响应映射)。
有关 JavaScript 解析器的更多信息,请参阅 JavaScript 解析器概述。
示例 1
以下示例是 GraphQL 变更 deleteItem(id: ID!)
的函数请求处理程序。如果具有此 ID 的项目存在,它将被删除。
import { util } from '@aws-appsync/utils'; export function request(ctx) { return { operation: 'DeleteItem', key: util.dynamodb.toMapValues({ id: ctx.args.id }), }; }
示例 2
以下示例是 GraphQL 变更 deleteItem(id: ID!, expectedVersion: Int!)
的函数请求处理程序。如果具有此 ID 的项目存在,它将被删除,但仅当其 version
字段设置为 expectedVersion
时:
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { id, expectedVersion } = ctx.args; const condition = { id: { attributeExists: true }, version: { eq: expectedVersion }, }; return { operation: 'DeleteItem', key: util.dynamodb.toMapValues({ id }), condition: util.transform.toDynamoDBConditionExpression(condition), }; }
有关 DynamoDB DeleteItem
API 的更多信息,请参阅 DynamoDB API 文档。
Query
通过使用 Query
请求对象,您可以指示 Amazon AppSync DynamoDB 解析器向 DynamoDB 发出 Query
请求,并允许您指定以下内容:
-
键表达式
-
要使用的索引
-
任何额外的筛选条件
-
要返回多少个项目
-
是否使用一致性读取
-
查询方向(向前或向后)
-
分页标记
Query
请求对象具有以下结构:
type DynamoDBQueryRequest = { operation: 'Query'; query: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; index?: string; nextToken?: string; limit?: number; scanIndexForward?: boolean; consistentRead?: boolean; select?: 'ALL_ATTRIBUTES' | 'ALL_PROJECTED_ATTRIBUTES' | 'SPECIFIC_ATTRIBUTES'; filter?: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; projection?: { expression: string; expressionNames?: { [key: string]: string }; }; };
字段定义如下:
Query 字段
-
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
-
仅返回
projection
的expression
中列出的属性。该返回值相当于指定projection
的Select
,而不指定expression
的任何值。
-
projection
-
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息,请参阅投影。该字段是可选的。
来自 DynamoDB 的结果自动转换为 GraphQL 和 JSON 基元类型,并在上下文结果 (context.result
) 中提供。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射)。
有关 JavaScript 解析器的更多信息,请参阅 JavaScript 解析器概述。
结果的结构如下所示:
{ items = [ ... ], nextToken = "a pagination token", scannedCount = 10 }
字段定义如下:
-
items
-
包含 DynamoDB 查询返回的项目的列表。
-
nextToken
-
如果可能有更多结果,则
nextToken
包含一个分页标记,您可以在另一个请求中使用该标记。请注意,Amazon AppSync 对从 DynamoDB 返回的分页标记进行加密和模糊处理。这可防止您的表数据无意中泄露给调用方。另请注意,这些分页标记不能在不同的函数或解析器中使用。 -
scannedCount
-
在应用筛选表达式(如果有)之前与查询条件表达式匹配的项目的数量。
示例
以下示例是 GraphQL 查询 getPosts(owner: ID!)
的函数请求处理程序。
在本示例中,将对表的全局二级索引执行查询,以返回指定的 ID 拥有的所有文章。
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { owner } = ctx.args; return { operation: 'Query', query: { expression: 'ownerId = :ownerId', expressionValues: util.dynamodb.toMapValues({ ':ownerId': owner }), }, index: 'owner-index', }; }
有关 DynamoDB Query
API 的更多信息,请参阅 DynamoDB API 文档。
Scan
通过使用 Scan
请求,您可以指示 Amazon AppSync DynamoDB 函数向 DynamoDB 发出 Scan
请求,并允许您指定以下内容:
-
排除结果的筛选条件
-
要使用的索引
-
要返回多少个项目
-
是否使用一致性读取
-
分页标记
-
并行扫描
Scan
请求对象具有以下结构:
type DynamoDBScanRequest = { operation: 'Scan'; index?: string; limit?: number; consistentRead?: boolean; nextToken?: string; totalSegments?: number; segment?: number; filter?: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; projection?: { expression: string; expressionNames?: { [key: string]: string }; }; };
字段定义如下:
Scan 字段
-
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
-
仅返回
projection
的expression
中列出的属性。该返回值相当于指定projection
的Select
,而不指定expression
的任何值。
-
-
totalSegments
-
执行并行扫描时对表进行分区的分段数。该字段是可选的,但如果指定
segment
,则必须指定该字段。 -
segment
-
执行并行扫描时,此操作中的表分段。该字段是可选的,但如果指定
totalSegments
,则必须指定该字段。 projection
-
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息,请参阅投影。该字段是可选的。
DynamoDB 扫描返回的结果自动转换为 GraphQL 和 JSON 基元类型,并在上下文结果 (context.result
) 中提供。
有关 DynamoDB 类型转换的更多信息,请参阅类型系统(响应映射)。
有关 JavaScript 解析器的更多信息,请参阅 JavaScript 解析器概述。
结果的结构如下所示:
{ items = [ ... ], nextToken = "a pagination token", scannedCount = 10 }
字段定义如下:
-
items
-
包含 DynamoDB 扫描返回的项目的列表。
-
nextToken
-
如果可能有更多结果,则
nextToken
包含一个分页标记,您可以在另一个请求中使用该标记。AmazonAppSync 对从 DynamoDB 返回的分页标记进行加密和模糊处理。这可防止您的表数据无意中泄露给调用方。此外,这些分页标记不能在不同的函数或解析器中使用。 -
scannedCount
-
在应用筛选条件表达式(如果有)之前 DynamoDB 检索的项目数。
示例 1
以下示例是 GraphQL 查询 allPosts
的函数请求处理程序。
在本示例中,将返回表中的所有条目。
export function request(ctx) { return { operation: 'Scan' }; }
示例 2
以下示例是 GraphQL 查询 postsMatching(title: String!)
的函数请求处理程序。
在本示例中,将返回表中标题以 title
参数开头的所有条目。
export function request(ctx) { const { title } = ctx.args; const filter = { filter: { beginsWith: title } }; return { operation: 'Scan', filter: JSON.parse(util.transform.toDynamoDBFilterExpression(filter)), }; }
有关 DynamoDB Scan
API 的更多信息,请参阅 DynamoDB API 文档。
Sync(同步)
通过使用 Sync
请求对象,您可以从 DynamoDB 表中检索所有结果,然后仅接收自上次查询以来更改的数据(增量更新)。只能对版本控制的 DynamoDB 数据源发出 Sync
请求。您可以指定:
-
排除结果的筛选条件
-
要返回多少个项目
-
分页标记
-
上次
Sync
操作开始时间
Sync
请求对象具有以下结构:
type DynamoDBSyncRequest = { operation: 'Sync'; basePartitionKey?: string; deltaIndexName?: string; limit?: number; nextToken?: string; lastSync?: number; filter?: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; };
字段定义如下:
Sync 字段
-
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 类型转换的更多信息,请参阅类型系统(响应映射)。
有关 JavaScript 解析器的更多信息,请参阅 JavaScript 解析器概述。
结果的结构如下所示:
{ items = [ ... ], nextToken = "a pagination token", scannedCount = 10, startedAt = 1550000000000 }
字段定义如下:
-
items
-
包含同步操作返回的项目的列表。
-
nextToken
-
如果可能有更多结果,则
nextToken
包含一个分页标记,您可以在另一个请求中使用该标记。AmazonAppSync 对从 DynamoDB 返回的分页标记进行加密和模糊处理。这可防止您的表数据无意中泄露给调用方。此外,这些分页标记不能在不同的函数或解析器中使用。 -
scannedCount
-
在应用筛选条件表达式(如果有)之前 DynamoDB 检索的项目数。
-
startedAt
-
同步操作开始的时刻,以纪元毫秒为单位,您可以在本地存储该值并在其他请求中将其用作
lastSync
参数。如果请求中包含分页令牌,则该值将与请求针对第一页结果返回的值相同。
示例 1
以下示例是 GraphQL 查询 syncPosts(nextToken: String, lastSync:
AWSTimestamp)
的函数请求处理程序。
在此示例中,如果省略 lastSync
,则返回基表中的所有条目。如果提供了 lastSync
,则只返回增量同步表中自 lastSync
以来发生更改的条目。
export function request(ctx) { const { nextToken, lastSync } = ctx.args; return { operation: 'Sync', limit: 100, nextToken, lastSync }; }
BatchGetItem
通过使用 BatchGetItem
请求对象,您可以指示 Amazon AppSync DynamoDB 函数对 DynamoDB 发出 BatchGetItem
请求以检索多个项目(可能位于多个表中)。对于该请求对象,您必须指定以下内容:
-
要从中检索项目的表名称
-
要从每个表中检索的项目的键
DynamoDB BatchGetItem
限制适用,并且无法提供任何条件表达式。
BatchGetItem
请求对象具有以下结构:
type DynamoDBBatchGetItemRequest = { operation: 'BatchGetItem'; tables: { [tableName: string]: { keys: { [key: string]: any }[]; consistentRead?: boolean; projection?: { expression: string; expressionNames?: { [key: string]: string }; }; }; }; };
字段定义如下:
BatchGetItem 字段
-
operation
-
要执行的 DynamoDB 操作。要执行
BatchGetItem
DynamoDB 操作,该字段必须设置为BatchGetItem
。该值为必填项。 -
tables
-
要从中检索项目的 DynamoDB 表。该值是一个映射,其中表名称被指定为映射的键。必须提供至少一个表。该
tables
值为必填项。-
keys
-
DynamoDB 键列表,表示要检索的项目的主键。DynamoDB 项目可能具有单个哈希键,也可能具有哈希键和排序键,具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。
-
consistentRead
-
是否在执行 GetItem 操作时使用一致性读取。此值是可选的,默认为 false。
projection
-
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息,请参阅投影。该字段是可选的。
-
要记住的事项:
-
如果尚未从表中检索某个项目,则 null 元素将显示在该表的数据块中。
-
根据在请求对象中提供调用结果的顺序,将按表对这些结果进行排序。
-
BatchGetItem
中的每个Get
命令都是原子性的,但可以部分处理一个批次。如果由于错误而部分处理一个批处理,则未处理的键将作为 unprocessedKeys 块内的调用结果的一部分返回。 -
BatchGetItem
限制为 100 个键。
对于以下示例函数请求处理程序:
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId } = ctx.args; return { operation: 'BatchGetItem', tables: { authors: [util.dynamodb.toMapValues({ authorId })], posts: [util.dynamodb.toMapValues({ authorId, postId })], }, }; }
ctx.result
中可用的调用结果如下所示:
{ "data": { "authors": [null], "posts": [ // Was retrieved { "authorId": "a1", "postId": "p2", "postTitle": "title", "postDescription": "description", } ] }, "unprocessedKeys": { "authors": [ // This item was not processed due to an error { "authorId": "a1" } ], "posts": [] } }
ctx.error
包含有关该错误的详细信息。在调用结果中,确保会出现 data 和 unprocessedKeys 键以及在函数请求对象结果中提供的每个表键。已删除的项目显示在数据块中。尚未处理的项目将在数据块中标记为 null 并置于 unprocessedKeys 块中。
BatchDeleteItem
通过使用 BatchDeleteItem
请求对象,您可以指示 Amazon AppSync DynamoDB 函数对 DynamoDB 发出 BatchWriteItem
请求以删除多个项目(可能位于多个表中)。对于该请求对象,您必须指定以下内容:
-
要从中删除项目的表名称
-
要从每个表中删除的项目的键
DynamoDB BatchWriteItem
限制适用,并且无法提供任何条件表达式。
BatchDeleteItem
请求对象具有以下结构:
type DynamoDBBatchDeleteItemRequest = { operation: 'BatchDeleteItem'; tables: { [tableName: string]: { [key: string]: any }[]; }; };
字段定义如下:
BatchDeleteItem 字段
-
operation
-
要执行的 DynamoDB 操作。要执行
BatchDeleteItem
DynamoDB 操作,该字段必须设置为BatchDeleteItem
。该值为必填项。 -
tables
-
要从中删除项目的 DynamoDB 表。每个表是 DynamoDB 键列表,表示要删除的项目的主键。DynamoDB 项目可能具有单个哈希键,也可能具有哈希键和排序键,具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。必须提供至少一个表。
tables
值是必需的。
要记住的事项:
-
与
DeleteItem
操作相反,响应中不会返回完全删除的项目。只返回传递的键。 -
如果尚未从表中删除某个项目,null 元素将显示在该表的数据块中。
-
根据在请求对象中提供调用结果的顺序,将按表对这些结果进行排序。
-
BatchDeleteItem
中的每个Delete
命令都是原子性的。但是,可以部分处理一个批处理。如果由于错误而部分处理一个批处理,则未处理的键将作为 unprocessedKeys 块内的调用结果的一部分返回。 -
BatchDeleteItem
限制为 25 个键。
对于以下示例函数请求处理程序:
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId } = ctx.args; return { operation: 'BatchDeleteItem', tables: { authors: [util.dynamodb.toMapValues({ authorId })], posts: [util.dynamodb.toMapValues({ authorId, postId })], }, }; }
ctx.result
中可用的调用结果如下所示:
{ "data": { "authors": [null], "posts": [ // Was deleted { "authorId": "a1", "postId": "p2" } ] }, "unprocessedKeys": { "authors": [ // This key was not processed due to an error { "authorId": "a1" } ], "posts": [] } }
ctx.error
包含有关该错误的详细信息。在调用结果中,确保会出现 data 和 unprocessedKeys 键以及在函数请求对象中提供的每个表键。已删除的项目存在于数据块中。尚未处理的项目将在数据块中标记为 null 并置于 unprocessedKeys 块中。
BatchPutItem
通过使用 BatchPutItem
请求对象,您可以指示 Amazon AppSync DynamoDB 函数对 DynamoDB 发出 BatchWriteItem
请求以放置多个项目(可能位于多个表中)。对于该请求对象,您必须指定以下内容:
-
要将项目放置在其中的表名称
-
要放置在每个表中的完整项目
DynamoDB BatchWriteItem
限制适用,并且无法提供任何条件表达式。
BatchPutItem
请求对象具有以下结构:
type DynamoDBBatchPutItemRequest = { operation: 'BatchPutItem'; tables: { [tableName: string]: { [key: string]: any}[]; }; };
字段定义如下:
BatchPutItem 字段
-
operation
-
要执行的 DynamoDB 操作。要执行
BatchPutItem
DynamoDB 操作,该字段必须设置为BatchPutItem
。该值为必填项。 -
tables
-
要在其中放置项目的 DynamoDB 表。每个表条目表示要为该特定表插入的 DynamoDB 项目列表。必须提供至少一个表。该值为必填项。
要记住的事项:
-
如果成功,响应中将返回完全插入的项目。
-
如果尚未向表中插入项目,null 元素将显示在该表的数据块中。
-
根据在请求对象中提供插入的项目的顺序,将按表对这些结果进行排序。
-
BatchPutItem
中的每个Put
命令都是原子性的,但可以部分处理一个批次。如果由于错误而部分处理一个批处理,则未处理的键将作为 unprocessedKeys 块内的调用结果的一部分返回。 -
BatchPutItem
限制为 25 个项目。
对于以下示例函数请求处理程序:
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId, name, title } = ctx.args; return { operation: 'BatchPutItem', tables: { authors: [util.dynamodb.toMapValues({ authorId, name })], posts: [util.dynamodb.toMapValues({ authorId, postId, title })], }, }; }
ctx.result
中可用的调用结果如下所示:
{ "data": { "authors": [ null ], "posts": [ // Was inserted { "authorId": "a1", "postId": "p2", "title": "title" } ] }, "unprocessedItems": { "authors": [ // This item was not processed due to an error { "authorId": "a1", "name": "a1_name" } ], "posts": [] } }
ctx.error
包含有关该错误的详细信息。在调用结果中,确保会出现 data 和 unprocessedItems 键以及在请求对象中提供的每个表键。已插入的项目存在于数据块中。尚未处理的项目将在数据块中标记为 null 并置于 unprocessedItems 块中。
TransactGetItems
通过使用 TransactGetItems
请求对象,您可以指示 Amazon AppSync DynamoDB 函数对 DynamoDB 发出 TransactGetItems
请求以检索多个项目(可能位于多个表中)。对于该请求对象,您必须指定以下内容:
-
从中检索项目的每个请求项目的表名称
-
要从每个表中检索的每个请求项的键
DynamoDB TransactGetItems
限制适用,并且无法提供任何条件表达式。
TransactGetItems
请求对象具有以下结构:
type DynamoDBTransactGetItemsRequest = { operation: 'TransactGetItems'; transactItems: { table: string; key: { [key: string]: any }; projection?: { expression: string; expressionNames?: { [key: string]: string }; }[]; }; };
字段定义如下:
TransactGetItems 字段
-
operation
-
要执行的 DynamoDB 操作。要执行
TransactGetItems
DynamoDB 操作,该字段必须设置为TransactGetItems
。该值为必填项。 -
transactItems
-
要包含的请求项目。该值是请求项目的数组。必须提供至少一个请求项目。该
transactItems
值为必填项。-
table
-
要从中检索项目的 DynamoDB 表。该值是表名的字符串。该
table
值为必填项。 -
key
-
DynamoDB 键,表示要检索的项目的主键。DynamoDB 项目可能具有单个哈希键,也可能具有哈希键和排序键,具体取决于表结构。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。
projection
-
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息,请参阅投影。该字段是可选的。
-
要记住的事项:
-
如果事务成功,
items
块中检索项目的顺序将与请求项目的顺序相同。 -
事务以全部或全不的方式执行。如果任何请求项目导致错误,则整个交易都不会执行,并返回错误详细信息。
-
无法检索的请求项目不是错误。相反,null 元素会出现在相应位置的 items 块中。
-
如果一个事务的错误是 TransactionCanceledException,则
cancellationReasons
块将被填充。cancellationReasons
块中取消原因的顺序将与请求项目的顺序相同。 -
TransactGetItems
仅限于 25 个请求项目。
对于以下示例函数请求处理程序:
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId } = ctx.args; return { operation: 'TransactGetItems', transactItems: [ { table: 'posts', key: util.dynamodb.toMapValues({ postId }), }, { table: 'authors', key: util.dynamodb.toMapValues({ authorId }), }, ], }; }
如果事务成功并且只检索第一个请求的项目,则 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
中。
TransactWriteItems
通过使用 TransactWriteItems
请求对象,您可以指示 Amazon AppSync DynamoDB 函数对 DynamoDB 发出 TransactWriteItems
请求以写入多个项目(可能写入到多个表中)。对于该请求对象,您必须指定以下内容:
-
每个请求项目的目标表名称
-
要执行的每个请求项目的操作。支持四种类型的操作:PutItem、UpdateItem、DeleteItem 和 ConditionCheck
-
要写入的每个请求项目的键
DynamoDB TransactWriteItems
限制适用。
TransactWriteItems
请求对象具有以下结构:
type DynamoDBTransactWriteItemsRequest = { operation: 'TransactWriteItems'; transactItems: TransactItem[]; }; type TransactItem = | TransactWritePutItem | TransactWriteUpdateItem | TransactWriteDeleteItem | TransactWriteConditionCheckItem; type TransactWritePutItem = { table: string; operation: 'PutItem'; key: { [key: string]: any }; attributeValues: { [key: string]: string}; condition?: TransactConditionCheckExpression; }; type TransactWriteUpdateItem = { table: string; operation: 'UpdateItem'; key: { [key: string]: any }; update: DynamoDBExpression; condition?: TransactConditionCheckExpression; }; type TransactWriteDeleteItem = { table: string; operation: 'DeleteItem'; key: { [key: string]: any }; condition?: TransactConditionCheckExpression; }; type TransactWriteConditionCheckItem = { table: string; operation: 'ConditionCheck'; key: { [key: string]: any }; condition?: TransactConditionCheckExpression; }; type TransactConditionCheckExpression = { expression: string; expressionNames?: { [key: string]: string}; expressionValues?: { [key: string]: any}; returnValuesOnConditionCheckFailure: boolean; };
TransactWriteItems 字段
- 字段定义如下:
-
-
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 个请求项目。
对于以下示例函数请求处理程序:
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId, title, description, oldTitle, authorName } = ctx.args; return { operation: 'TransactWriteItems', transactItems: [ { table: 'posts', operation: 'PutItem', key: util.dynamodb.toMapValues({ postId }), attributeValues: util.dynamodb.toMapValues({ title, description }), condition: util.transform.toDynamoDBConditionExpression({ title: { eq: oldTitle }, }), }, { table: 'authors', operation: 'UpdateItem', key: util.dynamodb.toMapValues({ authorId }), update: { expression: 'SET authorName = :name', expressionValues: util.dynamodb.toMapValues({ ':name': authorName }), }, }, ], }; }
如果事务成功,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
中。
类型系统(请求映射)
在使用 Amazon AppSync DynamoDB 函数调用 DynamoDB 表时,Amazon AppSync 需要知道该调用中使用的每个值的类型。这是因为 DynamoDB 支持的基元类型比 GraphQL 或 JSON 多(例如集和二进制数据)。Amazon在 GraphQL 和 DynamoDB 之间转换时,AppSync 需要一些提示,否则,它必须对如何在表中设置数据结构做出一些假设。
有关 DynamoDB 数据类型的更多信息,请参阅 DynamoDB 数据类型描述符和数据类型文档。
DynamoDB 值由包含单个键值对的 JSON 对象表示。键指定 DynamoDB 类型,值指定值本身。在下面的示例中,键 S
表示值是一个字符串,值 identifier
是字符串值本身。
{ "S" : "identifier" }
请注意,JSON 对象不能具有多于一个键值对。如果指定了多个键值对,则不会解析请求对象。
DynamoDB 值用于请求对象中您需要指定值的任何位置。您需要这样做的一些地方包括:key
和 attributeValue
部分以及表达式部分的 expressionValues
部分。在以下示例中,DynamoDB 字符串值 identifier
分配给 key
部分中的 id
字段(可能位于 GetItem
请求对象中)。
"key" : { "id" : { "S" : "identifier" } }
支持的类型
Amazon AppSync 支持以下 DynamoDB 标量、文档和集类型:
- 字符串类型
S
-
单个字符串值。DynamoDB 字符串值表示为:
{ "S" : "some string" }
示例用法如下:
"key" : { "id" : { "S" : "some string" } }
- 字符串集类型
SS
-
一组字符串值。DynamoDB 字符串集值表示为:
{ "SS" : [ "first value", "second value", ... ] }
示例用法如下:
"attributeValues" : { "phoneNumbers" : { "SS" : [ "+1 555 123 4567", "+1 555 234 5678" ] } }
- 数字类型
N
-
单个数字值。DynamoDB 数字值表示为:
{ "N" : 1234 }
示例用法如下:
"expressionValues" : { ":expectedVersion" : { "N" : 1 } }
- 数字集类型
NS
-
一组数字值。DynamoDB 数字集值表示为:
{ "NS" : [ 1, 2.3, 4 ... ] }
示例用法如下:
"attributeValues" : { "sensorReadings" : { "NS" : [ 67.8, 12.2, 70 ] } }
- 二进制类型
B
-
二进制值。DynamoDB 二进制值表示为:
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
请注意,该值实际上是一个字符串,其中,字符串是二进制数据的 Base64 编码表示形式。AmazonAppSync 将该字符串解码回二进制值,然后再将其发送到 DynamoDB。AmazonAppSync 使用 RFC 2045 定义的 Base64 解码方案:忽略没有位于 Base64 字母表中的任何字符。
示例用法如下:
"attributeValues" : { "binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" } }
- 二进制集类型
BS
-
一组二进制值。DynamoDB 二进制集值表示为:
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
请注意,该值实际上是一个字符串,其中,字符串是二进制数据的 Base64 编码表示形式。AmazonAppSync 将该字符串解码回二进制值,然后再将其发送到 DynamoDB。AmazonAppSync 使用 RFC 2045 定义的 Base64 解码方案:忽略没有位于 Base64 字母表中的任何字符。
示例用法如下:
"attributeValues" : { "binaryMessages" : { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ] } }
- 布尔值类型
BOOL
-
布尔值。DynamoDB 布尔值表示为:
{ "BOOL" : true }
请注意,只有
true
和false
是有效值。示例用法如下:
"attributeValues" : { "orderComplete" : { "BOOL" : false } }
- 列表类型
L
-
任何其他支持的 DynamoDB 值列表。DynamoDB 列表值表示为:
{ "L" : [ ... ] }
请注意,该值是一个复合值,其中,列表可以包含零个或更多任何支持的 DynamoDB 值(包括其他列表)。此列表还可以包含不同类型的混合。
示例用法如下:
{ "L" : [ { "S" : "A string value" }, { "N" : 1 }, { "SS" : [ "Another string value", "Even more string values!" ] } ] }
- 映射类型
M
-
表示其他支持的 DynamoDB 值的键值对的无序集合。DynamoDB 映射值表示为:
{ "M" : { ... } }
请注意,一个映射可以包含零个或零个以上的键值对。键必须是一个字符串,值可以是任何支持的 DynamoDB 值(包括其他映射)。此映射还可以包含不同类型的混合。
示例用法如下:
{ "M" : { "someString" : { "S" : "A string value" }, "someNumber" : { "N" : 1 }, "stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] } } }
- Null 类型
NULL
-
Null 值。DynamoDB Null 值表示为:
{ "NULL" : null }
示例用法如下:
"attributeValues" : { "phoneNumbers" : { "NULL" : null } }
有关每个类型的更多信息,请参阅 DynamoDB 文档。
类型系统(响应映射)
在从 DynamoDB 收到响应时,Amazon AppSync 自动将其转换为 GraphQL 和 JSON 基元类型。将解码 DynamoDB 中的每个属性,并在响应处理程序的上下文中返回。
例如,如果 DynamoDB 返回以下内容:
{ "id" : { "S" : "1234" }, "name" : { "S" : "Nadia" }, "age" : { "N" : 25 } }
从管道解析器中返回结果时,Amazon AppSync 将其转换为 GraphQL 和 JSON 类型,如下所示:
{ "id" : "1234", "name" : "Nadia", "age" : 25 }
本节介绍了 Amazon AppSync 如何转换以下 DynamoDB 标量、文档和集类型:
- 字符串类型
S
-
单个字符串值。DynamoDB 字符串值以字符串形式返回。
例如,如果 DynamoDB 返回以下 DynamoDB 字符串值:
{ "S" : "some string" }
Amazon AppSync 将其转换为字符串:
"some string"
- 字符串集类型
SS
-
一组字符串值。DynamoDB 字符串集值以字符串列表形式返回。
例如,如果 DynamoDB 返回以下 DynamoDB 字符串集值:
{ "SS" : [ "first value", "second value", ... ] }
Amazon AppSync 将其转换为字符串列表:
[ "+1 555 123 4567", "+1 555 234 5678" ]
- 数字类型
N
-
单个数字值。DynamoDB 数字值以数字形式返回。
例如,如果 DynamoDB 返回以下 DynamoDB 数字值:
{ "N" : 1234 }
Amazon AppSync 将其转换为数字:
1234
- 数字集类型
NS
-
一组数字值。DynamoDB 数字集值以数字列表形式返回。
例如,如果 DynamoDB 返回以下 DynamoDB 数字集值:
{ "NS" : [ 67.8, 12.2, 70 ] }
Amazon AppSync 将其转换为数字列表:
[ 67.8, 12.2, 70 ]
- 二进制类型
B
-
二进制值。DynamoDB 二进制值以字符串形式返回,其中包含该值的 Base64 表示形式。
例如,如果 DynamoDB 返回以下 DynamoDB 二进制值:
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
Amazon AppSync 将其转换为包含该值的 Base64 表示形式的字符串:
"SGVsbG8sIFdvcmxkIQo="
- 二进制集类型
BS
-
一组二进制值。DynamoDB 二进制集值以字符串列表形式返回,其中包含这些值的 Base64 表示形式。
例如,如果 DynamoDB 返回以下 DynamoDB 二进制集值:
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
Amazon AppSync 将其转换为包含这些值的 Base64 表示形式的字符串列表:
[ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ]
- 布尔值类型
BOOL
-
布尔值。DynamoDB 布尔值以布尔值形式返回。
例如,如果 DynamoDB 返回以下 DynamoDB 布尔值:
{ "BOOL" : true }
Amazon AppSync 将其转换为布尔值:
true
- 列表类型
L
-
任何其他支持的 DynamoDB 值列表。DynamoDB 列表值以值列表形式返回,其中还会转换每个内部值。
例如,如果 DynamoDB 返回以下 DynamoDB 列表值:
{ "L" : [ { "S" : "A string value" }, { "N" : 1 }, { "SS" : [ "Another string value", "Even more string values!" ] } ] }
Amazon AppSync 将其转换为转换的值列表:
[ "A string value", 1, [ "Another string value", "Even more string values!" ] ]
- 映射类型
M
-
任何其他支持的 DynamoDB 值的键/值集合。DynamoDB 映射值以 JSON 对象形式返回,其中还会转换每个键/值。
例如,如果 DynamoDB 返回以下 DynamoDB 映射值:
{ "M" : { "someString" : { "S" : "A string value" }, "someNumber" : { "N" : 1 }, "stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] } } }
Amazon AppSync 将其转换为 JSON 对象:
{ "someString" : "A string value", "someNumber" : 1, "stringSet" : [ "Another string value", "Even more string values!" ] }
- Null 类型
NULL
-
Null 值。
例如,如果 DynamoDB 返回以下 DynamoDB Null 值:
{ "NULL" : null }
Amazon AppSync 将其转换为 Null:
null
Filters
在使用 Query
和 Scan
操作查询 DynamoDB 中的对象时,您可以选择指定 filter
以评估结果并仅返回所需的值。
Query
或 Scan
请求的 filter 属性具有以下结构:
type DynamoDBExpression = { expression: string; expressionNames?: { [key: string]: string}; expressionValues?: { [key: string]: any}; };
字段定义如下:
-
expression
-
查询表达式。有关如何编写筛选条件表达式的更多信息,请参阅 DynamoDB QueryFilter 和 DynamoDB ScanFilter 文档。必须指定该字段。
-
expressionNames
-
以键值对形式替换表达式属性名称 占位符。键对应于
expression
中使用的名称占位符。该值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的,只应填充expression
中使用的表达式属性名称占位符的替换内容。 -
expressionValues
-
以键值对形式替换表达式属性值 占位符。键对应于
expression
中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。必须指定此值。该字段是可选的,只应填充expression
中使用的表达式属性值占位符的替换内容。
示例
以下示例是请求的筛选条件部分,其中,只有在标题以 title
参数开头时,才会返回从 DynamoDB 中检索的条目。
此处,我们使用 util.transform.toDynamoDBFilterExpression
从对象中自动创建筛选条件:
const filter = util.transform.toDynamoDBFilterExpression({ title: { beginsWith: 'far away' }, }); const request = {}; request.filter = JSON.parse(filter);
这会生成以下筛选条件:
{ "filter": { "expression": "(begins_with(#title,:title_beginsWith))", "expressionNames": { "#title": "title" }, "expressionValues": { ":title_beginsWith": { "S": "far away" } } } }
条件表达式
在您使用 PutItem
、UpdateItem
和 DeleteItem
DynamoDB 操作变更 DynamoDB 中的对象时,您可以选择指定一个条件表达式,以根据执行操作之前 DynamoDB 中的已有对象状态控制请求是否应成功。
Amazon AppSync DynamoDB 函数允许在 PutItem
、UpdateItem
和 DeleteItem
请求对象中指定条件表达式,并提供在条件失败并且未更新对象时遵循的策略。
示例 1
以下 PutItem
请求对象没有条件表达式。因此,即使已存在具有相同键的项目,它也会将项目放置在 DynamoDB 中,从而覆盖现有的项目。
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { foo, bar, ...values} = ctx.args return { operation: 'PutItem', key: util.dynamodb.toMapValues({foo, bar}), attributeValues: util.dynamodb.toMapValues(values), }; }
示例 2
以下 PutItem
对象确实具有一个条件表达式,只有在 DynamoDB 中不 存在具有相同键的项目时,该操作才会成功。
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { foo, bar, ...values} = ctx.args return { operation: 'PutItem', key: util.dynamodb.toMapValues({foo, bar}), attributeValues: util.dynamodb.toMapValues(values), condition: { expression: "attribute_not_exists(id)" } }; }
默认情况下,如果条件检查失败,则 Amazon AppSync DynamoDB 函数在 ctx.error
中提供一个错误。您可以返回变更错误,并在 GraphQL 响应 error
部分的 data
字段中返回 DynamoDB 中的对象的当前值。
不过,Amazon AppSync DynamoDB 函数提供了一些额外的功能,以帮助开发人员处理一些常见的边缘情况:
-
如果 Amazon AppSync DynamoDB 函数可以确定 DynamoDB 中的当前值与所需的结果匹配,则会将该操作视为成功。
-
您可以将函数配置为调用自定义 Lambda 函数以决定 Amazon AppSync DynamoDB 函数应如何处理失败,而不是返回错误。
在处理条件检查失败一节中更详细地介绍了这些内容。
有关 DynamoDB 条件表达式的更多信息,请参阅 DynamoDB 条件表达式文档。
指定条件
PutItem
、UpdateItem
和 DeleteItem
请求对象都允许指定可选的 condition
部分。如果省略,则不会进行条件检查。如果指定,条件必须为 true,操作才能成功。
condition
部分具有以下结构:
type ConditionCheckExpression = { expression: string; expressionNames?: { [key: string]: string}; expressionValues?: { [key: string]: any}; equalsIgnore?: string[]; consistentRead?: boolean; conditionalCheckFailedHandler?: { strategy: 'Custom' | 'Reject'; lambdaArn?: string; }; };
下列字段指定条件:
-
expression
-
更新表达式本身。有关如何编写条件表达式的更多信息,请参阅 DynamoDB ConditionExpressions 文档。必须指定该字段。
-
expressionNames
-
以键值对形式替换表达式属性名称占位符。键对应于 expression 中使用的名称占位符,值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的,只应填充 expression 中使用的表达式属性名称占位符的替换内容。
-
expressionValues
-
以键值对形式替换表达式属性值占位符。键对应于 expression 中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。必须指定此值。该字段是可选的,只应填充 expression 中使用的表达式属性值占位符的替换内容。
其余字段指示 Amazon AppSync DynamoDB 函数如何处理条件检查失败:
-
equalsIgnore
-
如果在使用
PutItem
操作时条件检查失败,则 Amazon AppSync DynamoDB 函数将当前位于 DynamoDB 中的项目与它尝试写入的项目进行比较。如果两者相同,则它会将操作视为已成功。您可以使用equalsIgnore
字段指定 Amazon AppSync 在执行该比较时应忽略的属性列表。例如,如果唯一的区别是version
属性,则会将操作视为成功。该字段是可选的。 -
consistentRead
-
在条件检查失败时,Amazon AppSync 使用强一致性读取从 DynamoDB 中获取项目的当前值。您可以使用该字段指示 Amazon AppSync DynamoDB 函数改用最终一致性读取。该字段是可选的,默认值为
true
。 -
conditionalCheckFailedHandler
-
在该部分中,您可以指定 Amazon AppSync DynamoDB 函数在将 DynamoDB 中的当前值与预期结果进行比较后如何处理条件检查失败。此部分是可选的。如果省略,它默认为
Reject
策略。-
strategy
-
Amazon AppSync DynamoDB 函数在将 DynamoDB 中的当前值与预期结果进行比较后采取的策略。该字段为必填字段,有以下可能的值:
-
Reject
-
变更失败,将返回变更错误,并在 GraphQL 响应
error
部分的data
字段中返回 DynamoDB 中的对象的当前值。 -
Custom
-
Amazon AppSync DynamoDB 函数调用自定义 Lambda 函数,以决定如何处理条件检查失败。当
strategy
设置为Custom
时,lambdaArn
字段必须包含要调用的 Lambda 函数的 ARN。
-
-
lambdaArn
-
要调用的 Lambda 函数的 ARN,用于确定 Amazon AppSync DynamoDB 函数应如何处理条件检查失败。当
strategy
设置为Custom
时,必须指定该字段。有关如何使用该功能的更多信息,请参阅处理条件检查失败。
-
处理条件检查失败
在条件检查失败时,Amazon AppSync DynamoDB 函数可以使用 util.appendError
实用程序传递变更错误和对象的当前值。这会在 GraphQL 响应的 error
部分中添加 data
字段。不过,Amazon AppSync DynamoDB 函数提供了一些额外的功能,以帮助开发人员处理一些常见的边缘情况:
-
如果 Amazon AppSync DynamoDB 函数可以确定 DynamoDB 中的当前值与所需的结果匹配,则会将该操作视为成功。
-
您可以将函数配置为调用自定义 Lambda 函数以决定 Amazon AppSync DynamoDB 函数应如何处理失败,而不是返回错误。
此过程的流程图为:
检查所需的结果
在条件检查失败时,Amazon AppSync DynamoDB 函数执行 GetItem
DynamoDB 请求,以从 DynamoDB 中获取项目的当前值。默认情况下,它将使用强一致性读取,但这可以使用 condition
数据块中的 consistentRead
字段进行配置,并将当前值与预期结果进行比较:
-
对于
PutItem
操作,Amazon AppSync DynamoDB 函数将当前值与它尝试写入的值进行比较,以从比较中排除equalsIgnore
中列出的任何属性。如果项目相同,则将操作视为成功并返回从 DynamoDB 中检索的项目。否则,它将遵循所配置的策略。例如,如果
PutItem
请求对象如下所示:import { util } from '@aws-appsync/utils'; export function request(ctx) { const { id, name, version} = ctx.args return { operation: 'PutItem', key: util.dynamodb.toMapValues({foo, bar}), attributeValues: util.dynamodb.toMapValues({ name, version: version+1 }), condition: { expression: "version = :expectedVersion", expressionValues: util.dynamodb.toMapValues({':expectedVersion': version}), 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”策略
在遵循 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 } }
函数响应处理程序如下所示:
import { util } from '@aws-appsync/utils'; export function response(ctx) { const { version, ...values } = ctx.result; const result = { ...values, theVersion: version }; if (ctx.error) { if (error) { return util.appendError(error.message, error.type, result, null); } } return result }
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”策略
在遵循 Custom
策略时,Amazon AppSync DynamoDB 函数调用 Lambda 函数以决定后续操作。Lambda 函数选择下列选项之一:
-
reject
变更。这会指示 Amazon AppSync DynamoDB 函数的行为就像配置的策略是Reject
一样,返回变更错误和 DynamoDB 中的对象的当前值,如上一节所述。 -
discard
变更。这会指示 Amazon AppSync DynamoDB 函数静默忽略条件检查失败并返回 DynamoDB 中的值。 -
retry
变更。这会指示 Amazon AppSync DynamoDB 函数使用新的请求对象重试变更。
Lambda 调用请求
Amazon AppSync DynamoDB 函数调用 lambdaArn
中指定的 Lambda 函数。它将使用在数据源上配置的相同 service-role-arn
。调用的负载具有以下结构:
{ "arguments": { ... }, "requestMapping": {... }, "currentValue": { ... }, "resolver": { ... }, "identity": { ... } }
字段定义如下:
-
arguments
-
来自 GraphQL 变更的参数。这与
context.arguments
中的请求对象的可用参数相同。 -
requestMapping
-
该操作的请求对象。
-
currentValue
-
DynamoDB 中的对象的当前值。
-
resolver
-
有关 Amazon AppSync 解析器或函数的信息。
-
identity
-
有关调用方的信息。这与
context.identity
中的请求对象的可用身份信息相同。
负载的完整示例:
{ "arguments": { "id": "1", "name": "Steve", "expectedVersion": 1 }, "requestMapping": { "version" : "2017-02-28", "operation" : "PutItem", "key" : { "id" : { "S" : "1" } }, "attributeValues" : { "name" : { "S" : "Steve" }, "version" : { "N" : 2 } }, "condition" : { "expression" : "version = :expectedVersion", "expressionValues" : { ":expectedVersion" : { "N" : 1 } }, "equalsIgnore": [ "version" ] } }, "currentValue": { "id" : { "S" : "1" }, "name" : { "S" : "Steve" }, "version" : { "N" : 8 } }, "resolver": { "tableName": "People", "awsRegion": "us-west-2", "parentType": "Mutation", "field": "updatePerson", "outputType": "Person" }, "identity": { "accountId": "123456789012", "sourceIp": "x.x.x.x", "user": "AIDAAAAAAAAAAAAAAAAAA", "userArn": "arn:aws:iam::123456789012:user/appsync" } }
Lambda 调用响应
Lambda 函数可以检查调用负载,并应用任何业务逻辑以决定 Amazon AppSync DynamoDB 函数应如何处理失败。有三种选项可用于处理条件检查失败:
-
reject
变更。此选项的响应负载必须具有此结构:{ "action": "reject" }
这会指示 Amazon AppSync DynamoDB 解析器的行为就像配置的策略是
Reject
一样,返回变更错误和 DynamoDB 中的对象的当前值,如上一节所述。 -
discard
变更。此选项的响应负载必须具有此结构:{ "action": "discard" }
这会指示 Amazon AppSync DynamoDB 函数静默忽略条件检查失败并返回 DynamoDB 中的值。
-
retry
变更。此选项的响应负载必须具有此结构:{ "action": "retry", "retryMapping": { ... } }
这会指示 Amazon AppSync DynamoDB 函数使用新的请求对象重试变更。
retryMapping
部分的结构取决于 DynamoDB 操作,并且是该操作的完整请求对象的子集。对于
PutItem
,retryMapping
部分具有以下结构。有关attributeValues
字段的描述,请参阅 PutItem。{ "attributeValues": { ... }, "condition": { "equalsIgnore" = [ ... ], "consistentRead" = true } }
对于
UpdateItem
,retryMapping
部分具有以下结构。有关update
部分的说明,请参阅 UpdateItem。{ "update" : { "expression" : "someExpression" "expressionNames" : { "#foo" : "foo" }, "expressionValues" : { ":bar" : ... typed value } }, "condition": { "consistentRead" = true } }
对于
DeleteItem
,retryMapping
部分具有以下结构。{ "condition": { "consistentRead" = true } }
无法指定要使用的不同的操作或键。Amazon AppSync DynamoDB 函数仅允许对同一对象重试相同操作。另外,
condition
部分不允许指定conditionalCheckFailedHandler
。如果重试失败,Amazon AppSync DynamoDB 函数将遵循Reject
策略。
在下面的示例中,Lambda 函数处理失败的 PutItem
请求。业务逻辑将查看进行调用的用户。如果调用是由 jeffTheAdmin
进行的,则会重试该请求,并从当前位于 DynamoDB 的项目中更新 version
和 expectedVersion
。否则,业务逻辑将拒绝变更。
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
中的所有 4 种类型的操作(PutItem
、DeleteItem
、UpdateItem
和 ConditionCheck
)的请求中使用事务条件表达式。
对于 PutItem
、DeleteItem
和 UpdateItem
,事务条件表达式是可选的。对于 ConditionCheck
,事务条件表达式是必需的。
示例 1
以下事务 DeleteItem
函数请求处理程序没有条件表达式。因此,它删除 DynamoDB 中的项目。
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { postId } = ctx.args; return { operation: 'TransactWriteItems', transactItems: [ { table: 'posts', operation: 'DeleteItem', key: util.dynamodb.toMapValues({ postId }), } ], }; }
示例 2
以下事务 DeleteItem
函数请求处理程序确实具有一个事务条件表达式,只有在该文章的作者等于特定姓名时,操作才会成功。
import { util } from '@aws-appsync/utils'; export function request(ctx) { const { postId, authorName} = ctx.args; return { operation: 'TransactWriteItems', transactItems: [ { table: 'posts', operation: 'DeleteItem', key: util.dynamodb.toMapValues({ postId }), condition: util.transform.toDynamoDBConditionExpression({ authorName: { eq: authorName }, }), } ], }; }
如果条件检查失败,则会导致 TransactionCanceledException
,错误详细信息将在 ctx.result.cancellationReasons
中返回。请注意,默认情况下,DynamoDB 中导致条件检查失败的旧项目将在 ctx.result.cancellationReasons
中返回。
指定条件
PutItem
、UpdateItem
和 DeleteItem
请求对象都允许指定可选的 condition
部分。如果省略,则不会进行条件检查。如果指定,条件必须为 true,操作才能成功。ConditionCheck
必须具有要指定的 condition
部分。条件必须为 true,整个事务才能成功。
condition
部分具有以下结构:
type TransactConditionCheckExpression = { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: string }; returnValuesOnConditionCheckFailure: boolean; };
下列字段指定条件:
-
expression
-
更新表达式本身。有关如何编写条件表达式的更多信息,请参阅 DynamoDB ConditionExpressions 文档。必须指定该字段。
-
expressionNames
-
以键值对形式替换表达式属性名称占位符。键对应于 expression 中使用的名称占位符,值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的,只应填充 expression 中使用的表达式属性名称占位符的替换内容。
-
expressionValues
-
以键值对形式替换表达式属性值占位符。键对应于 expression 中使用的值占位符,而值必须为类型化值。有关如何指定“类型化值”的更多信息,请参阅类型系统(请求映射)。必须指定此值。该字段是可选的,只应填充 expression 中使用的表达式属性值占位符的替换内容。
-
returnValuesOnConditionCheckFailure
-
指定在条件检查失败时是否重新检索 DynamoDB 中的项目。检索到的项目将位于
ctx.result.cancellationReasons[<index>].item
中,其中<index>
是未通过条件检查的请求项目的索引。该值默认为 true。
投影
在使用 GetItem
、Scan
、Query
、BatchGetItem
和 TransactGetItems
操作读取 DynamoDB 中的对象时,您可以选择指定一个投影以指定所需的属性。投影属性具有以下结构,与筛选条件类似:
type DynamoDBExpression = { expression: string; expressionNames?: { [key: string]: string} };
字段定义如下:
-
expression
-
投影表达式,它是一个字符串。要检索单个属性,请指定其名称。对于多个属性,名称必须是逗号分隔值。有关编写投影表达式的更多信息,请参阅 DynamoDB 投影表达式文档。该字段为必填。
-
expressionNames
-
以键值对形式替换表达式属性名称占位符。键对应于
expression
中使用的名称占位符。该值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的,只应填充expression
中使用的表达式属性名称占位符的替换内容。有关expressionNames
的更多信息,请参阅 DynamoDB 文档。
示例 1
以下示例是 JavaScript 函数的投影部分,其中仅从 DynamoDB 返回 author
和 id
属性:
projection : { expression : "#author, id", expressionNames : { "#author" : "author" } }
提示
您可以使用 selectionSetList 访问 GraphQL 请求选择集。可以通过该字段根据您的要求动态构建投影表达式。
注意
在将投影表达式与 Query
和 Scan
运算一起使用时,select
的值必须为 SPECIFIC_ATTRIBUTES
。有关更多信息,请参阅 DynamoDB 文档。