本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS AppSync JavaScript DynamoDB 的解析器函数参考 D AWS AppSync ynamoDB 函数允许您使用 [GraphQL](https://graphql.org) 存储和检索账户中现有亚马逊 DynamoDB 表中的数据，方法是将传入的 GraphQL 请求映射到 DynamoDB 调用，然后将 DynamoDB 响应映射回 GraphQL。本节介绍了支持的 DynamoDB 操作的请求和响应处理程序： + [GetItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-getitem.html)-该 GetItem 请求允许您告诉 DynamoDB 函数向 DynamoDB 发出 GetItem 请求，并允许您在 DynamoDB 中指定项目的密钥以及是否使用一致性读取。 + [ PutItem ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-putitem.html)- PutItem 请求映射文档允许您告诉 DynamoDB 函数向 DynamoDB 发出 PutItem 请求，并允许您指定 DynamoDB 中项目的密钥、项目的全部内容（由键和属性值组成）以及操作成功所需的条件。 + [ UpdateItem ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-updateitem.html)-该 UpdateItem 请求允许您告诉 DynamoDB 函数向 DynamoDB 发出 UpdateItem 请求，并允许您在 DynamoDB 中指定项目的密钥、描述如何在 DynamoDB 中更新项目的更新表达式以及操作成功的条件。 + [ DeleteItem ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-deleteitem.html)-该 DeleteItem 请求允许您告诉 DynamoDB 函数向 DynamoDB 发出 DeleteItem 请求，并允许您在 DynamoDB 中指定项目的密钥以及操作成功的条件。 + [Query](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-query.html)：通过使用 Query 请求对象，您可以指示 DynamoDB 解析器对 DynamoDB 发出 Query 请求，并可以指定键表达式、要使用的索引、其他筛选条件、要返回的项目数量、是否使用一致性读取、查询方向（向前或向后）以及分页标记。 + [Scan](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-scan.html)：通过使用 Scan 请求，您可以指示 DynamoDB 函数对 DynamoDB 发出 Scan 请求，并可以指定排除结果的筛选条件、要使用的索引、要返回的项目数量、是否使用一致性读取、分页令牌和并行扫描。 + [Sync](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-sync.html)：通过使用 Sync 请求对象，您可以从 DynamoDB 表中检索所有结果，然后仅接收自上次查询以来更改的数据（增量更新）。只能向版本控制的 DynamoDB 数据来源发出 Sync 请求。您可以指定排除结果的筛选条件、要返回的项目数量、分页令牌以及上次同步操作的启动时间。 + [ BatchGetItem ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-batch-get-item.html)- BatchGetItem 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出 BatchGetItem 请求，以检索多个项目，可能跨多个表。对于此请求对象，您必须指定要从中检索项目的表名称，以及要从每个表中检索的项目的键。 + [ BatchDeleteItem ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-batch-delete-item.html)- BatchDeleteItem 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出 BatchWriteItem 请求，要求删除多个项目，可能跨多个表。对于此请求对象，您必须指定要从中删除项目的表名称，以及要从每个表中删除的项目的键。 + [ BatchPutItem ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-batch-put-item.html)- BatchPutItem 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出 BatchWriteItem 请求，要求将多个项目放置在多个表中。对于此请求对象，您必须指定要放置项目的表名称和要放入每个表中的完整项目。 + [ TransactGetItems ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-transact-get-items.html)- TransactGetItems 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出 TransactGetItems 请求，以检索多个项目，可能跨多个表。对于此请求对象，您必须指定要从中检索项目的每个请求项目的表名称，以及要从每个表中检索的每个请求项目的键。 + [ TransactWriteItems ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-transact-write-items.html)- TransactWriteItems 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出写入多个项目（可能写入多个表）的 TransactWriteItems 请求。对于此请求对象，您必须指定每个请求项目的目标表名称、要执行的每个请求项目的操作以及要写入的每个请求项目的键。 + [类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-typed-values-request.html)-详细了解 DynamoDB 类型如何集成到请求中。 AWS AppSync + [类型系统（响应映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-typed-values-responses.html)：详细了解 DynamoDB 类型如何在响应有效载荷中自动转换为 GraphQL 或 JSON。 + [筛选条件](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-filter.html)：详细了解查询和扫描操作的筛选条件。 + [条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-condition-expressions.html)-了解有关 PutItem UpdateItem、和 DeleteItem 运算的条件表达式的更多信息。 + [交易条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions.html)-了解有关 TransactWriteItems 操作条件表达式的更多信息。 + [投影](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-projections.html)：详细了解如何在读取操作中指定属性。 # GetItem 该`GetItem`请求允许您告诉 AWS AppSync DynamoDB 函数向 DynamoDB 发出`GetItem`请求，并允许您指定： + DynamoDB 中的项目的键 + 是否使用一致性读取 `GetItem` 请求具有以下结构： ``` type DynamoDBGetItem = { operation: 'GetItem'; key: { [key: string]: any }; consistentRead?: ConsistentRead; projection?: { expression: string; expressionNames?: { [key: string]: string }; }; }; ``` 字段定义如下： ## GetItem 字段 ### GetItem 字段列表 **`operation`** 要执行的 DynamoDB 操作。要执行 `GetItem` DynamoDB 操作，该字段必须设置为 `GetItem`。该值为必填项。 **`key`** DynamoDB 中的项目的键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该值为必填项。 **`consistentRead`** 是否对 DynamoDB 执行强一致性读取。这是可选的，默认值为 `false`。 **`projection`** 用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)。该字段是可选的。 从 DynamoDB 返回的项目自动转换为 GraphQL 和 JSON 基元类型，并在上下文结果 (`context.result`) 中提供。 有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)。 有关 JavaScript 解析器的更多信息，请参阅解析[JavaScript 器](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)概述。 ## 示例 以下示例是 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)。 # PutItem `PutItem`请求映射文档允许您告诉 D AWS AppSync ynamoDB 函数向 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 字段 ### PutItem 字段列表 **`operation`** 要执行的 DynamoDB 操作。要执行 `PutItem` DynamoDB 操作，该字段必须设置为 `PutItem`。该值为必填项。 **`key`** DynamoDB 中的项目的键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该值为必填项。 **`attributeValues`** 要放入 DynamoDB 中的项目的其余属性。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该字段是可选的。 **`condition`** 根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `PutItem` 请求将覆盖该项目的任何现有条目。有关条件的更多信息，请参阅[条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-condition-expressions)。该值为可选项。 **`_version`** 表示项目的最新已知版本的数值。该值为可选项。该字段用于*冲突检测*，仅受版本控制的数据来源支持。 **`customPartitionKey`** 启用后，此字符串值将修改启用版本控制后增量同步表使用的`ds_sk`和`ds_pk`记录的格式（有关更多信息，请参阅*《AWS AppSync 开发人员指南》*中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)）。如果启用，还会启用 `populateIndexFields` 条目处理。该字段是可选的。 **`populateIndexFields`** 一个布尔值，在**与 `customPartitionKey` 一起**启用时，它为增量同步表中的每个记录创建新条目，具体来说是在 `gsi_ds_pk` 和 `gsi_ds_sk` 列中创建新条目。有关更多信息，请参阅《AWS AppSync 开发人员指南》中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)。**该字段是可选的。 写入到 DynamoDB 的项目自动转换为 GraphQL 和 JSON 基元类型，并在上下文结果 (`context.result`) 中提供。 写入到 DynamoDB 的项目自动转换为 GraphQL 和 JSON 基元类型，并在上下文结果 (`context.result`) 中提供。 有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)。 有关 JavaScript 解析器的更多信息，请参阅解析[JavaScript器](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)概述。 ## 示例 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)。 # UpdateItem 该`UpdateItem`请求允许您告诉 D AWS AppSync ynamoDB 函数向 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 字段 ### UpdateItem 字段列表 **`operation`** 要执行的 DynamoDB 操作。要执行 `UpdateItem` DynamoDB 操作，该字段必须设置为 `UpdateItem`。该值为必填项。 **`key`** DynamoDB 中的项目的键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该值为必填项。 **`update`** `update` 部分用于指定一个更新表达式，以描述如何更新 DynamoDB 中的项目。有关如何编写更新表达式的更多信息，请参阅 [DynamoDB 文档 UpdateExpressions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)。此部分是必需的。 `update` 部分有三个组成部分： ** `expression` ** 更新表达式。该值为必填项。 ** `expressionNames` ** 以键值对形式替换表达式属性*名称* 占位符。键对应于 `expression` 中使用的名称占位符，值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 `expression` 中使用的表达式属性名称占位符的替换内容。 ** `expressionValues` ** 以键值对形式替换表达式属性*值* 占位符。键对应于 `expression` 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。必须指定此值。该字段是可选的，只应填充 `expression` 中使用的表达式属性值占位符的替换内容。 **`condition`** 根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `UpdateItem` 请求将更新现有条目，而不考虑其当前状态。有关条件的更多信息，请参阅[条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-condition-expressions)。该值为可选项。 **`_version`** 表示项目的最新已知版本的数值。该值为可选项。该字段用于*冲突检测*，仅受版本控制的数据来源支持。 **`customPartitionKey`** 启用后，此字符串值将修改启用版本控制后增量同步表使用的`ds_sk`和`ds_pk`记录的格式（有关更多信息，请参阅*《AWS AppSync 开发人员指南》*中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)）。如果启用，还会启用 `populateIndexFields` 条目处理。该字段是可选的。 **`populateIndexFields`** 一个布尔值，在**与 `customPartitionKey` 一起**启用时，它为增量同步表中的每个记录创建新条目，具体来说是在 `gsi_ds_pk` 和 `gsi_ds_sk` 列中创建新条目。有关更多信息，请参阅《AWS AppSync 开发人员指南》中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)。**该字段是可选的。 在 DynamoDB 中更新的项目自动转换为 GraphQL 和 JSON 基元类型，并在上下文结果 (`context.result`) 中提供。 有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)。 有关 JavaScript 解析器的更多信息，请参阅解析[JavaScript 器](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)概述。 ## 示例 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)。 # DeleteItem 该`DeleteItem`请求允许您告诉 D AWS AppSync ynamoDB 函数向 DynamoDB 发出`DeleteItem`请求，并允许您指定以下内容： + DynamoDB 中的项目的键 + 操作成功执行的条件 `DeleteItem` 请求具有以下结构： ``` type DynamoDBDeleteItemRequest = { operation: 'DeleteItem'; key: { [key: string]: any }; condition?: ConditionCheckExpression; customPartitionKey?: string; populateIndexFields?: boolean; _version?: number; }; ``` 字段定义如下： ## DeleteItem 字段 ### DeleteItem 字段列表 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `DeleteItem` DynamoDB 操作，该字段必须设置为 `DeleteItem`。该值为必填项。 ** `key` ** DynamoDB 中的项目的键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该值为必填项。 ** `condition` ** 根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `DeleteItem` 请求将删除项目，而不考虑其当前状态。有关条件的更多信息，请参阅[条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-condition-expressions)。该值为可选项。 ** `_version` ** 表示项目的最新已知版本的数值。该值为可选项。该字段用于*冲突检测*，仅受版本控制的数据来源支持。 **`customPartitionKey`** 启用后，此字符串值将修改启用版本控制后增量同步表使用的`ds_sk`和`ds_pk`记录的格式（有关更多信息，请参阅*《AWS AppSync 开发人员指南》*中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)）。如果启用，还会启用 `populateIndexFields` 条目处理。该字段是可选的。 **`populateIndexFields`** 一个布尔值，在**与 `customPartitionKey` 一起**启用时，它为增量同步表中的每个记录创建新条目，具体来说是在 `gsi_ds_pk` 和 `gsi_ds_sk` 列中创建新条目。有关更多信息，请参阅《AWS AppSync 开发人员指南》中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)。**该字段是可选的。 从 DynamoDB 中删除的项目自动转换为 GraphQL 和 JSON 基元类型，并在上下文结果 (`context.result`) 中提供。 有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)。 有关 JavaScript 解析器的更多信息，请参阅解析[JavaScript 器](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)概述。 ## 示例 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html)。 # Query `Query`请求对象允许您告诉 D AWS AppSync ynamoDB 解析器向 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 字段 ### Query 字段列表 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `Query` DynamoDB 操作，该字段必须设置为 `Query`。该值为必填项。 ** `query` ** `query` 部分用于指定一个键条件表达式，用于描述要从 DynamoDB 中检索哪些项目。有关如何编写关键条件表达式的更多信息，请参阅 [DynamoDB 文档 KeyConditions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.KeyConditions.html)。必须指定此部分。 ** `expression` ** 查询表达式。必须指定该字段。 ** `expressionNames` ** 以键值对形式替换表达式属性*名称* 占位符。键对应于 `expression` 中使用的名称占位符，值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 `expression` 中使用的表达式属性名称占位符的替换内容。 ** `expressionValues` ** 以键值对形式替换表达式属性*值* 占位符。键对应于 `expression` 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该值为必填项。该字段是可选的，只应填充 `expression` 中使用的表达式属性值占位符的替换内容。 ** `filter` ** 另一个筛选条件，该筛选条件可用于在从 DynamoDB 返回结果之前先筛选结果。有关筛选条件的更多信息，请参阅[筛选条件](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-filter)。该字段是可选的。 ** `index` ** 要查询的索引的名称。除了哈希键的主键索引以外，您还可以通过 DynamoDB 查询操作扫描本地二级索引和全局二级索引。如果指定，这会指示 DynamoDB 查询指定的索引。如果省略，则将查询主键索引。 ** `nextToken` ** 继续之前查询的分页标记。这应已从之前查询中获得。该字段是可选的。 ** `limit` ** 要评估的最大项目数（不一定是匹配项目数）。该字段是可选的。 ** `scanIndexForward` ** 一个布尔值，指示是向前还是向后查询。该字段是可选的，默认值为 `true`。 ** `consistentRead` ** 一个布尔值，用于指示在查询 DynamoDB 时是否使用一致性读取。该字段是可选的，默认值为 `false`。 ** `select` ** 默认情况下， AWS AppSync DynamoDB 解析器仅返回投影到索引中的属性。如果需要更多属性，则可以设置该字段。该字段是可选的。支持的值为： ** `ALL_ATTRIBUTES` ** 返回指定的表或索引中的所有项目属性。如果您查询本地二级索引，则 DynamoDB 从父表中为索引中的每个匹配项目获取整个项目。如果索引配置为投影所有项目属性，则可以从本地二级索引中获得所有数据，而不要求提取。 ** `ALL_PROJECTED_ATTRIBUTES` ** 仅在查询索引时才允许。检索已投影到索引的所有属性。如果索引配置为投影所有属性，则此返回值等同于指定 `ALL_ATTRIBUTES`。 **`SPECIFIC_ATTRIBUTES`** 仅返回 `projection` 的 `expression` 中列出的属性。该返回值相当于指定 `projection` 的 `Select`，而不指定 `expression` 的任何值。 **`projection`** 用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)。该字段是可选的。 来自 DynamoDB 的结果自动转换为 GraphQL 和 JSON 基元类型，并在上下文结果 (`context.result`) 中提供。 有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)。 有关 JavaScript 解析器的更多信息，请参阅解析[JavaScript 器](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)概述。 结果的结构如下所示： ``` { items = [ ... ], nextToken = "a pagination token", scannedCount = 10 } ``` 字段定义如下： ** `items` ** 包含 DynamoDB 查询返回的项目的列表。 ** `nextToken` ** 如果可能有更多结果，则 `nextToken` 包含一个分页标记，您可以在另一个请求中使用该标记。请注意，它 AWS 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)。 # Scan 该`Scan`请求允许您告诉 D AWS AppSync ynamoDB 函数向 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 字段 ### Scan 字段列表 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `Scan` DynamoDB 操作，该字段必须设置为 `Scan`。该值为必填项。 ** `filter` ** 一个筛选条件，可用于在返回来自 DynamoDB 的结果之前对其进行筛选。有关筛选条件的更多信息，请参阅[筛选条件](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-filter)。该字段是可选的。 ** `index` ** 要查询的索引的名称。除了哈希键的主键索引以外，您还可以通过 DynamoDB 查询操作扫描本地二级索引和全局二级索引。如果指定，这会指示 DynamoDB 查询指定的索引。如果省略，则将查询主键索引。 ** `limit` ** 单次评估的最大项目数。该字段是可选的。 ** `consistentRead` ** 一个布尔值，用于指示在查询 DynamoDB 时是否使用一致性读取。该字段是可选的，默认值为 `false`。 ** `nextToken` ** 继续之前查询的分页标记。这应已从之前查询中获得。该字段是可选的。 ** `select` ** 默认情况下， AWS AppSync DynamoDB 函数仅返回投影到索引中的任何属性。如果需要更多属性，则可以设置该字段。该字段是可选的。支持的值为： ** `ALL_ATTRIBUTES` ** 返回指定的表或索引中的所有项目属性。如果您查询本地二级索引，则 DynamoDB 从父表中为索引中的每个匹配项目获取整个项目。如果索引配置为投影所有项目属性，则可以从本地二级索引中获得所有数据，而不要求提取。 ** `ALL_PROJECTED_ATTRIBUTES` ** 仅在查询索引时才允许。检索已投影到索引的所有属性。如果索引配置为投影所有属性，则此返回值等同于指定 `ALL_ATTRIBUTES`。 **`SPECIFIC_ATTRIBUTES`** 仅返回 `projection` 的 `expression` 中列出的属性。该返回值相当于指定 `projection` 的 `Select`，而不指定 `expression` 的任何值。 ** `totalSegments` ** 执行并行扫描时对表进行分区的分段数。该字段是可选的，但如果指定 `segment`，则必须指定该字段。 ** `segment` ** 执行并行扫描时，此操作中的表分段。该字段是可选的，但如果指定 `totalSegments`，则必须指定该字段。 **`projection`** 用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)。该字段是可选的。 DynamoDB 扫描返回的结果自动转换为 GraphQL 和 JSON 基元类型，并在上下文结果 (`context.result`) 中提供。 有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)。 有关 JavaScript 解析器的更多信息，请参阅解析[JavaScript 器](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)概述。 结果的结构如下所示： ``` { items = [ ... ], nextToken = "a pagination token", scannedCount = 10 } ``` 字段定义如下： ** `items` ** 包含 DynamoDB 扫描返回的项目的列表。 ** `nextToken` ** 如果可能有更多结果，则`nextToken`包含可在其他请求中使用的分页令牌。 AWS AppSync 加密并混淆从 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)。 # 同步 通过使用 `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 字段 ### Sync 字段列表 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `Sync` 操作，该字段必须设置为 `Sync`。该值为必填项。 ** `filter` ** 一个筛选条件，可用于在返回来自 DynamoDB 的结果之前对其进行筛选。有关筛选条件的更多信息，请参阅[筛选条件](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-filter)。该字段是可选的。 ** `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 类型转换的更多信息，请参阅[类型系统（响应映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)。 有关 JavaScript 解析器的更多信息，请参阅解析[JavaScript 器](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)概述。 结果的结构如下所示： ``` { items = [ ... ], nextToken = "a pagination token", scannedCount = 10, startedAt = 1550000000000 } ``` 字段定义如下： ** `items` ** 包含同步操作返回的项目的列表。 ** `nextToken` ** 如果可能有更多结果，则`nextToken`包含可在其他请求中使用的分页令牌。 AWS AppSync 加密并混淆从 DynamoDB 返回的分页令牌。这可防止您的表数据无意中泄露给调用方。此外，这些分页标记不能在不同的函数或解析器中使用。 ** `scannedCount` ** 在应用筛选条件表达式（如果有）之前 DynamoDB 检索的项目数。 ** `startedAt` ** 同步操作开始的时刻，以纪元毫秒为单位，您可以在本地存储该值并在其他请求中将其用作 `lastSync` 参数。如果请求中包含分页令牌，则该值将与请求针对第一页结果返回的值相同。 ## 示例 以下示例是 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`请求对象允许您告诉 D AWS AppSync ynamoDB 函数向 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 字段 ### BatchGetItem 字段列表 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `BatchGetItem` DynamoDB 操作，该字段必须设置为 `BatchGetItem`。该值为必填项。 ** `tables` ** 要从中检索项目的 DynamoDB 表。该值是一个映射，其中表名称被指定为映射的键。必须提供至少一个表。该 `tables` 值为必填项。 ** `keys` ** DynamoDB 键列表，表示要检索的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。 ** `consistentRead` ** 执行*GetItem*操作时是否使用一致性读取。此值是可选的，默认为 *false*。 **`projection`** 用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)。该字段是可选的。 要记住的事项： + 如果尚未从表中检索某个项目，则 *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`请求对象允许您告诉 D AWS AppSync ynamoDB 函数向 DynamoDB `BatchWriteItem` 请求删除多个项目，可能跨多个表。对于该请求对象，您必须指定以下内容： + 要从中删除项目的表名称 + 要从每个表中删除的项目的键 DynamoDB `BatchWriteItem` 限制适用，并且无法提供**任何条件表达式**。 `BatchDeleteItem` 请求对象具有以下结构： ``` type DynamoDBBatchDeleteItemRequest = { operation: 'BatchDeleteItem'; tables: { [tableName: string]: { [key: string]: any }[]; }; }; ``` 字段定义如下： ## BatchDeleteItem 字段 ### BatchDeleteItem 字段列表 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `BatchDeleteItem` DynamoDB 操作，该字段必须设置为 `BatchDeleteItem`。该值为必填项。 ** `tables` ** 要从中删除项目的 DynamoDB 表。每个表是 DynamoDB 键列表，表示要删除的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。必须提供至少一个表。`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`请求对象允许您告诉 D AWS AppSync ynamoDB 函数向 DynamoDB 发出`BatchWriteItem`请求，要求将多个项目放置在多个表中。对于该请求对象，您必须指定以下内容： + 要将项目放置在其中的表名称 + 要放置在每个表中的完整项目 DynamoDB `BatchWriteItem` 限制适用，并且无法提供**任何条件表达式**。 `BatchPutItem` 请求对象具有以下结构： ``` type DynamoDBBatchPutItemRequest = { operation: 'BatchPutItem'; tables: { [tableName: string]: { [key: string]: any}[]; }; }; ``` 字段定义如下： ## BatchPutItem 字段 ### 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`请求对象允许您告诉 D AWS AppSync ynamoDB 函数向 DynamoDB 发出`TransactGetItems`请求，以检索多个项目，可能跨多个表。对于该请求对象，您必须指定以下内容： + 从中检索项目的每个请求项目的表名称 + 要从每个表中检索的每个请求项的键 DynamoDB `TransactGetItems` 限制适用，并且无法提供**任何条件表达式**。 `TransactGetItems` 请求对象具有以下结构： ``` type DynamoDBTransactGetItemsRequest = { operation: 'TransactGetItems'; transactItems: { table: string; key: { [key: string]: any }; projection?: { expression: string; expressionNames?: { [key: string]: string }; }[]; }; }; ``` 字段定义如下： ## TransactGetItems 字段 ### TransactGetItems 字段列表 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `TransactGetItems` DynamoDB 操作，该字段必须设置为 `TransactGetItems`。该值为必填项。 ** `transactItems` ** 要包含的请求项目。该值是请求项目的数组。必须提供至少一个请求项目。该 `transactItems` 值为必填项。 ** `table` ** 要从中检索项目的 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。 ** `key` ** DynamoDB 键，表示要检索的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。 **`projection`** 用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)。该字段是可选的。 要记住的事项： + 如果事务成功，`items` 块中检索项目的顺序将与请求项目的顺序相同。 + 交易以 all-or-nothing某种方式执行。如果任何请求项目导致错误，则整个交易都不会执行，并返回错误详细信息。 + 无法检索的请求项目不是错误。相反，*null* 元素会出现在相应位置的 *items* 块中。 + 如果交易的错误是 *TransactionCanceledException*，则`cancellationReasons`区块将被填充。`cancellationReasons` 块中取消原因的顺序将与请求项目的顺序相同。 + `TransactGetItems` 限制为 100 个请求项目。 对于以下示例函数请求处理程序： ``` 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`请求对象允许您告诉 D AWS AppSync ynamoDB 函数向 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 字段 ### TransactWriteItems 字段列表 **字段定义如下：** ** `operation` ** 要执行的 DynamoDB 操作。要执行 `TransactWriteItems` DynamoDB 操作，该字段必须设置为 `TransactWriteItems`。该值为必填项。 ** `transactItems` ** 要包含的请求项目。该值是请求项目的数组。必须提供至少一个请求项目。该 `transactItems` 值为必填项。 对于 `PutItem`，字段定义如下： ** `table` ** 目标 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `PutItem` DynamoDB 操作，该字段必须设置为 `PutItem`。该值为必填项。 ** `key` ** DynamoDB 键，表示要放置的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该值为必填项。 ** `attributeValues` ** 要放入 DynamoDB 中的项目的其余属性。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该字段是可选的。 ** `condition` ** 根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `PutItem` 请求将覆盖该项目的任何现有条目。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的更多信息，请参阅[事务条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)。该值为可选项。 对于 `UpdateItem`，字段定义如下： ** `table` ** 要更新的 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `UpdateItem` DynamoDB 操作，该字段必须设置为 `UpdateItem`。该值为必填项。 ** `key` ** DynamoDB 键，表示要更新的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该值为必填项。 ** `update` ** `update` 部分用于指定一个更新表达式，以描述如何更新 DynamoDB 中的项目。有关如何编写更新表达式的更多信息，请参阅 [DynamoDB 文档 UpdateExpressions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)。此部分是必需的。 ** `condition` ** 根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `UpdateItem` 请求将更新现有条目，而不考虑其当前状态。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的更多信息，请参阅[事务条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)。该值为可选项。 对于 `DeleteItem`，字段定义如下： ** `table` ** 要在其中删除项目的 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `DeleteItem` DynamoDB 操作，该字段必须设置为 `DeleteItem`。该值为必填项。 ** `key` ** DynamoDB 键，表示要删除的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该值为必填项。 ** `condition` ** 根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `DeleteItem` 请求将删除项目，而不考虑其当前状态。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的更多信息，请参阅[事务条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)。该值为可选项。 对于 `ConditionCheck`，字段定义如下： ** `table` ** 要在其中检查条件的 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。 ** `operation` ** 要执行的 DynamoDB 操作。要执行 `ConditionCheck` DynamoDB 操作，该字段必须设置为 `ConditionCheck`。该值为必填项。 ** `key` ** DynamoDB 键，表示要检查条件的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。该值为必填项。 ** `condition` ** 根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的更多信息，请参阅[事务条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)。该值为必填项。 要记住的事项： + 如果成功，响应中只返回请求项目的键。键的顺序将与请求项目的顺序相同。 + 交易以 all-or-nothing某种方式执行。如果任何请求项目导致错误，则整个交易都不会执行，并返回错误详细信息。 + 不能有两个请求项目针对同一个项目。否则它们会导致*TransactionCanceledException*错误。 + 如果交易的错误是 *TransactionCanceledException*，则`cancellationReasons`区块将被填充。如果请求项目的条件检查失败**且** 您没有将 `returnValuesOnConditionCheckFailure` 指定为 `false`，则表中存在的项目将被检索并存储在 `cancellationReasons` 块的相应位置的 `item` 中。 + `TransactWriteItems` 限制为 100 个请求项目。 + **不**支持与冲突检测功能一起使用此操作。两者同时使用可能会导致错误。 对于以下示例函数请求处理程序： ``` 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` 中。 # 类型系统（请求映射） 使用 D AWS AppSync ynamoDB 函数调用您的 DynamoDB 表时 AWS AppSync ，需要知道要在该调用中使用的每个值的类型。这是因为 DynamoDB 支持的类型基元比 GraphQL 或 JSON 多（例如集合和二进制数据）。 AWS AppSync 在 GraphQL 和 DynamoDB 之间进行转换时需要一些提示，否则它将不得不对表中的数据结构做出一些假设。 有关 DynamoDB 数据类型的更多信息，请参阅 DynamoDB [数据类型描述符](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html#Programming.LowLevelAPI.DataTypeDescriptors)和[数据类型](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)文档。 DynamoDB 值由包含单个键值对的 JSON 对象表示。键指定 DynamoDB 类型，值指定值本身。在下面的示例中，键 `S` 表示值是一个字符串，值 `identifier` 是字符串值本身。 ``` { "S" : "identifier" } ``` 请注意，JSON 对象不能具有多于一个键值对。如果指定了多个键值对，则不会解析请求对象。 DynamoDB 值用于请求对象中您需要指定值的任何位置。您需要这样做的一些地方包括：`key` 和 `attributeValue` 部分以及表达式部分的 `expressionValues` 部分。在以下示例中，DynamoDB 字符串值 `identifier` 分配给 `key` 部分中的 `id` 字段（可能位于 `GetItem` 请求对象中）。 ``` "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 } ``` 请注意，只有 `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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html)。 # 类型系统（响应映射） 收到来自 DynamoDB 的响应时 AWS AppSync ，会自动将其转换为 GraphQL 和 JSON 原始类型。将解码 DynamoDB 中的每个属性，并在响应处理程序的上下文中返回。 例如，如果 DynamoDB 返回以下内容： ``` { "id" : { "S" : "1234" }, "name" : { "S" : "Nadia" }, "age" : { "N" : 25 } } ``` 当管道解析器返回结果时，将其 AWS AppSync 转换为 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 4648](https://tools.ietf.org/html/rfc4648) 和 [RFC 2045](https://tools.ietf.org/html/rfc2045) 中指定的方式根据 base64 编码方案进行编码。 **二进制集类型 `BS` ** 一组二进制值。DynamoDB 二进制集值以字符串列表形式返回，其中包含这些值的 Base64 表示形式。 例如，如果 DynamoDB 返回以下 DynamoDB 二进制集值： ``` { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] } ``` AWS AppSync 将其转换为包含以下值的 base64 表示形式的字符串列表： ``` [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] ``` 请注意，二进制数据按照 [RFC 4648](https://tools.ietf.org/html/rfc4648) 和 [RFC 2045](https://tools.ietf.org/html/rfc2045) 中指定的方式根据 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 值的 key/value 集合。DynamoDB 地图值以 JSON 对象的形式返回， key/value 每个值也将在其中进行转换。 例如，如果 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 ``` # 筛选条件 在使用 `Query` 和 `Scan` 操作查询 DynamoDB 中的对象时，您可以选择指定 `filter` 以评估结果并仅返回所需的值。 `Query` 或 `Scan` 请求的 filter 属性具有以下结构： ``` type DynamoDBExpression = { expression: string; expressionNames?: { [key: string]: string}; expressionValues?: { [key: string]: any}; }; ``` 字段定义如下： ** `expression` ** 查询表达式。有关如何编写筛选表达式的更多信息，请参阅 [DynamoDB 和 Dynam QueryFilter oDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.QueryFilter.html) 文档[。 ScanFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.ScanFilter.html)必须指定该字段。 ** `expressionNames` ** 以键值对形式替换表达式属性*名称* 占位符。键对应于 `expression` 中使用的名称占位符。该值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 `expression` 中使用的表达式属性名称占位符的替换内容。 ** `expressionValues` ** 以键值对形式替换表达式属性*值* 占位符。键对应于 `expression` 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。必须指定此值。该字段是可选的，只应填充 `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 中的已有对象状态控制请求是否应成功。 D AWS AppSync ynamoDB 函数允许`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)" } }; } ``` 默认情况下，如果条件检查失败，则 AWS AppSync DynamoDB 函数会为突变提供错误。 但是， AWS AppSync DynamoDB 函数提供了一些其他功能来帮助开发人员处理一些常见的边缘情况： + 如果 D AWS AppSync ynamoDB 函数可以确定 DynamoDB 中的当前值与所需结果相匹配，则它会将该操作视为成功了。 + 您可以将函数配置为调用自定义 Lambda 函数来决定 DynamoDB 函数应如何处理故障 AWS AppSync ，而不是返回错误。 在[处理条件检查失败](#condition-check)一节中更详细地介绍了这些内容。 [有关 DynamoDB 条件表达式的更多信息，请参阅 DynamoDB 文档。 ConditionExpressions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html) ## 指定条件 `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 ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)。必须指定该字段。 ** `expressionNames` ** 以键值对形式替换表达式属性名称占位符。键对应于 *expression* 中使用的名称占位符，值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 *expression* 中使用的表达式属性名称占位符的替换内容。 ** `expressionValues` ** 以键值对形式替换表达式属性值占位符。键对应于 expression 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。必须指定此值。该字段是可选的，只应填充 expression 中使用的表达式属性值占位符的替换内容。 其余字段告诉 AWS AppSync DynamoDB 函数如何处理条件检查失败： ** `equalsIgnore` ** 当使用`PutItem`操作时条件检查失败时，D AWS AppSync ynamoDB 函数会将当前在 DynamoDB 中的项目与它尝试写入的项目进行比较。如果两者相同，则它会将操作视为已成功。您可以使用该`equalsIgnore`字段来指定在执行比较时 AWS AppSync 应忽略的属性列表。例如，如果唯一的区别是 `version` 属性，则会将操作视为成功。该字段是可选的。 ** `consistentRead` ** 当条件检查失败时，使用强一致性读取从 DynamoDB AWS AppSync 获取项目的当前值。您可以使用此字段告诉 AWS AppSync DynamoDB 函数改用最终一致性读取。该字段是可选的，默认值为 `true`。 ** `conditionalCheckFailedHandler` ** 本节允许您指定 D AWS AppSync ynamoDB 函数在将 DynamoDB 中的当前值与预期结果进行比较后如何处理条件检查失败。此部分是可选的。如果省略，它默认为 `Reject` 策略。 ** `strategy` ** AWS AppSync DynamoDB 函数在将 DynamoDB 中的当前值与预期结果进行比较后采取的策略。该字段为必填字段，有以下可能的值： ** `Reject` ** 变更失败，向 GraphQL 响应中添加一个错误。 ** `Custom` ** AWS AppSync DynamoDB 函数调用自定义 Lambda 函数来决定如何处理条件检查失败。当 `strategy` 设置为 `Custom` 时，`lambdaArn` 字段必须包含要调用的 Lambda 函数的 ARN。 ** `lambdaArn` ** 要调用的 Lambda 函数的 ARN，用于确定 DynamoDB 函数应如何处理条件 AWS AppSync 检查失败。当 `strategy` 设置为 `Custom` 时，必须指定该字段。有关如何使用该功能的更多信息，请参阅[处理条件检查失败](#condition-check)。 ## 处理条件检查失败 当条件检查失败时，D AWS AppSync ynamoDB 函数可以使用该实用程序传递突变的错误和对象的当前值。`util.appendError`但是， AWS AppSync DynamoDB 函数提供了一些其他功能来帮助开发人员处理一些常见的边缘情况： + 如果 D AWS AppSync ynamoDB 函数可以确定 DynamoDB 中的当前值与所需结果相匹配，则它会将该操作视为成功了。 + 您可以将函数配置为调用自定义 Lambda 函数来决定 DynamoDB 函数应如何处理故障 AWS AppSync ，而不是返回错误。 此过程的流程图为： ![\[Flowchart showing process for transforming requests with mutation attempts and value checks.\]](http://docs.aws.amazon.com/zh_cn/appsync/latest/devguide/images/DynamoDB-condition-check-failure-handling.png) ### 检查所需的结果 当条件检查失败时，D AWS AppSync ynamoDB 函数会执行 Dyn `GetItem` amoDB 请求，以从 DynamoDB 获取项目的当前值。默认情况下，它将使用强一致性读取，但这可以使用 `condition` 数据块中的 `consistentRead` 字段进行配置，并将当前值与预期结果进行比较： + 对于该`PutItem`操作，D AWS AppSync ynamoDB 函数将当前值与其尝试写入的值进行比较，不包括比较`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 } } ``` D AWS AppSync ynamoDB 函数会将其尝试写入的项目与当前值进行比较，发现唯一的区别在于字段，但是由于它配置为忽略`version``version`该字段，因此它会将操作视为成功并返回从 DynamoDB 检索到的项目。 + 对于该`DeleteItem`操作， AWS AppSync DynamoDB 函数会进行检查以验证是否从 DynamoDB 返回了项目。如果没有返回项目，它会将该操作视为已成功。否则，它将遵循所配置的策略。 + 对于该`UpdateItem`操作，D AWS AppSync ynamoDB 函数没有足够的信息来确定 DynamoDB 中当前的项目是否与预期结果匹配，因此遵循了配置的策略。 如果 DynamoDB 中对象的当前状态与预期结果不同，则 D AWS AppSync ynamoDB 函数将遵循配置的策略，拒绝变更或调用 Lambda 函数来确定下一步要做什么。 ### 遵循“reject”策略 遵循`Reject`策略时， AWS AppSync 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", ... } ] } ``` 另外，如果返回的对象中的任何字段在变更成功后已由其他解析器填充，则当在 `error` 部分中返回此对象时，将不会对这些字段进行解析。 ### 遵循“custom”策略 遵循`Custom`策略时， AWS AppSync DynamoDB 函数会调用 Lambda 函数来决定下一步要做什么。Lambda 函数选择下列选项之一： + `reject` 变更。这告诉 D AWS AppSync ynamoDB 函数的行为就像配置的策略`Reject`一样，返回变异错误和 DynamoDB 中对象的当前值，如上一节所述。 + `discard` 变更。这会告诉 AWS AppSync DynamoDB 函数以静默方式忽略条件检查失败，并在 DynamoDB 中返回该值。 + `retry` 变更。这会告诉 AWS AppSync DynamoDB 函数使用新的请求对象重试变更。 **Lambda 调用请求** AWS AppSync DynamoDB 函数调用中指定的 Lambda 函数。`lambdaArn`它将使用在数据来源上配置的相同 `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 函数可以检查调用负载并应用任何业务逻辑来决定 DynamoDB 函数应如何处理 AWS AppSync 故障。有三种选项可用于处理条件检查失败： + `reject` 变更。此选项的响应负载必须具有此结构： ``` { "action": "reject" } ``` 这告诉 D AWS AppSync ynamoDB 函数的行为就像配置的策略`Reject`一样，返回变异错误以及该对象在 DynamoDB 中的当前值，如上一节所述。 + `discard` 变更。此选项的响应负载必须具有此结构： ``` { "action": "discard" } ``` 这会告诉 AWS AppSync DynamoDB 函数以静默方式忽略条件检查失败，并在 DynamoDB 中返回该值。 + `retry` 变更。此选项的响应负载必须具有此结构： ``` { "action": "retry", "retryMapping": { ... } } ``` 这会告诉 AWS AppSync DynamoDB 函数使用新的请求对象重试变更。`retryMapping` 部分的结构取决于 DynamoDB 操作，并且是该操作的完整请求对象的子集。 对于 `PutItem`，`retryMapping` 部分具有以下结构。有关该`attributeValues`字段的说明，请参见[PutItem](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-putitem)。 ``` { "attributeValues": { ... }, "condition": { "equalsIgnore" = [ ... ], "consistentRead" = true } } ``` 对于 `UpdateItem`，`retryMapping` 部分具有以下结构。有关该`update`部分的说明，请参见[UpdateItem](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-updateitem)。 ``` { "update" : { "expression" : "someExpression" "expressionNames" : { "#foo" : "foo" }, "expressionValues" : { ":bar" : ... typed value } }, "condition": { "consistentRead" = true } } ``` 对于 `DeleteItem`，`retryMapping` 部分具有以下结构。 ``` { "condition": { "consistentRead" = true } } ``` 无法指定要使用的不同的操作或键。 AWS AppSync DynamoDB 函数仅允许对同一个对象重试相同的操作。另外，`condition` 部分不允许指定 `conditionalCheckFailedHandler`。如果重试失败，则 Dynamo AWS AppSync DB 函数将遵循策略。`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 ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)。必须指定该字段。 ** `expressionNames` ** 以键值对形式替换表达式属性名称占位符。键对应于 *expression* 中使用的名称占位符，值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 *expression* 中使用的表达式属性名称占位符的替换内容。 ** `expressionValues` ** 以键值对形式替换表达式属性值占位符。键对应于 expression 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。必须指定此值。该字段是可选的，只应填充 expression 中使用的表达式属性值占位符的替换内容。 ** `returnValuesOnConditionCheckFailure` ** 指定在条件检查失败时是否重新检索 DynamoDB 中的项目。检索到的项目将位于 `ctx.result.cancellationReasons[].item` 中，其中 `` 是未通过条件检查的请求项目的索引。该值默认为 true。 # 投影 在使用 `GetItem`、`Scan`、`Query`、`BatchGetItem` 和 `TransactGetItems` 操作读取 DynamoDB 中的对象时，您可以选择指定一个投影以指定所需的属性。投影属性具有以下结构，与筛选条件类似： ``` type DynamoDBExpression = { expression: string; expressionNames?: { [key: string]: string} }; ``` 字段定义如下： ** `expression` ** 投影表达式，它是一个字符串。要检索单个属性，请指定其名称。对于多个属性，名称必须是逗号分隔值。有关编写投影表达式的更多信息，请参阅 [DynamoDB 投影表达式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html)文档。该字段为必填。 ** `expressionNames` ** 以键值对形式替换表达式属性*名称*占位符。键对应于 `expression` 中使用的名称占位符。该值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 `expression` 中使用的表达式属性名称占位符的替换内容。有关 `expressionNames` 的更多信息，请参阅 [DynamoDB 文档](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html)。 ## 示例 1 以下示例是一个函数的投影部分，在该 JavaScript 函数中，DynamoDB `id` 仅返回属`author`性和和： ``` projection : { expression : "#author, id", expressionNames : { "#author" : "author" } } ``` **提示** 您可以使用访问您的 GraphQL 请求选择集。[selectionSetList](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html#aws-appsync-resolver-context-reference-info-js)可以通过该字段根据您的要求动态构建投影表达式。 **注意** 在将投影表达式与 `Query` 和 `Scan` 运算一起使用时，`select` 的值必须为 `SPECIFIC_ATTRIBUTES`。有关更多信息，请参阅 [DynamoDB 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html#DDB-Query-request-Select)。