本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # DynamoDB 的AWS AppSync JavaScript 解析程式函數參考 The AWS AppSync DynamoDB 函數可讓您使用 [GraphQL](https://graphql.org)，將傳入的 GraphQL 請求映射至 DynamoDB DynamoDB 呼叫，然後將 DynamoDB 回應映射回 GraphQL，以在帳戶中現有的 Amazon DynamoDB 資料表中存放和擷取資料。本節說明受支援 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 中指定項目的金鑰、項目的完整內容 （由金鑰和attributeValues組成），以及操作成功的條件。 + [ 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 中指定項目的索引鍵，以及操作成功的條件。 + [ 查詢 ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-query.html) - 查詢請求物件可讓您指示 DynamoDB 解析程式向 DynamoDB 提出查詢請求，並可讓您指定金鑰表達式、要使用的索引、額外的篩選條件、要傳回的項目數、是否使用一致的讀取、查詢方向 （向前或向後） 和分頁字符。 + [ 掃描 ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-scan.html) - 掃描請求可讓您指示 DynamoDB 函數向 DynamoDB 發出掃描請求，並可讓您指定篩選條件以排除結果、要使用的索引、要傳回的項目數、是否使用一致的讀取、分頁字符和平行掃描。 + [ Sync ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-sync.html) - Sync 請求物件可讓您從 DynamoDB 資料表擷取所有結果，然後只接收自上次查詢後更改的資料 （差異更新）。同步請求只能對版本控制的 DynamoDB 資料來源提出。您可以指定篩選條件來排除結果、要傳回的項目數、分頁權杖，以及上次同步操作啟動的時間。 + [ 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` 請求映射文件可讓您指示 AWS 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 欄位 ### 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` 請求可讓您指示 AWS 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 欄位 ### 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` ** 表達式屬性 *name* 預留位置的替代，形式為鍵值組。金鑰對應至 中使用的名稱預留位置`expression`，且值必須是對應於 DynamoDB 中項目屬性名稱的字串。此欄位為選用的，應只能填入用於 `expression` 中表達式屬性名稱預留位置的替代。 ** `expressionValues` ** 表達式屬性 *value* 預留位置的替代，形式為鍵值組。鍵對應用於 `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` 請求可讓您指示 AWS AppSync DynamoDB 函數向 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` 請求物件可讓您指示 AWS 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 }; }; }; ``` 欄位定義如下： ## 查詢欄位 ### 查詢欄位清單 ** `operation` ** 要執行的 DynamoDB 操作。若要執行 `Query` DynamoDB 操作，這必須設為 `Query`。此值為必填。 ** `query` ** `query` 本節可讓您指定金鑰條件表達式，描述要從 DynamoDB 擷取哪些項目。如需如何編寫索引鍵條件表達式的詳細資訊，請參閱 [DynamoDB KeyConditions 文件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.KeyConditions.html)。必須指定此區段。 ** `expression` ** 查詢表達式。必須指定此欄位。 ** `expressionNames` ** 表達式屬性 *name* 預留位置的替代，形式為鍵值組。金鑰對應至 中使用的名稱預留位置`expression`，且值必須是對應於 DynamoDB 中項目屬性名稱的字串。此欄位為選用的，應只能填入用於 `expression` 中表達式屬性名稱預留位置的替代。 ** `expressionValues` ** 表達式屬性 *value* 預留位置的替代，形式為鍵值組。鍵對應用於 `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`的 ，`expression`而不指定 的任何值`Select`。 **`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` 請求可讓您指示 AWS 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 }; }; }; ``` 欄位定義如下： ## 掃描欄位 ### 掃描欄位清單 ** `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`的 ，`expression`而不指定 的任何值`Select`。 ** `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 `Sync` 請求物件可讓您從 DynamoDB 資料表擷取所有結果，然後只接收自上次查詢後變更的資料 （差異更新）。 `Sync` 請求只能對版本控制的 DynamoDB 資料來源提出。您可以指定下列項目： + 排除結果的篩選結果 + 要傳回多少項目 + 分頁字符 + 上次起始 `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 }; }; }; ``` 欄位定義如下： ## 同步欄位 ### 同步欄位清單 ** `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` 操作擷取所有頁面之後才能填入。如果省略此值，將傳回 *Base* 資料表的結果，否則會傳回 *Delta* 資料表的結果。 **`basePartitionKey`** 執行`Sync`操作時使用之 *Base* 資料表的分割區索引鍵。此欄位允許在資料表使用自訂分割區索引鍵時執行`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` 引數的時間 (以 epoch 毫秒為單位)。如果請求中包含分頁字符，則該值將與請求針對第一頁結果傳回的值相同。 ## 範例 下列範例是 GraphQL 查詢的函數請求處理常式：`syncPosts(nextToken: String, lastSync: AWSTimestamp)`。 在此範例中，如果省略 `lastSync`，則會傳回 Base 資料表中的所有項目。如果提供 `lastSync`，只會傳回自 `lastSync` 變更之 Delta Sync 資料表中的項目。 ``` export function request(ctx) { const { nextToken, lastSync } = ctx.args; return { operation: 'Sync', limit: 100, nextToken, lastSync }; } ``` # BatchGetItem `BatchGetItem` 請求物件可讓您指示 AWS 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 欄位 ### 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)。此欄位為選用欄位。 注意事項： + 如果未從資料表中擷取任何項目，該資料表的 data 區塊中會顯示 *null* 元素。 + 調用結果會根據在請求物件內提供的順序，依資料表排序。 + 中的每個`Get`命令`BatchGetItem`都是原子的，但批次可以部分處理。如果因錯誤而部分批次處理，則未處理的索引鍵會透過 *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` 包含錯誤的詳細資訊。金鑰**資料**、**unprocessedKeys** 和在函數請求物件結果中提供的每個資料表金鑰，保證會出現在調用結果中。已刪除的項目會出現在 **data** 區塊中。尚未處理的項目在該 data 區塊中會標示為 *null*，並置於 **unprocessedKeys** 區塊。 # BatchDeleteItem `BatchDeleteItem` 請求物件可讓您指示 AWS AppSync DynamoDB 函數向 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` 操作，回應中未傳回完整刪除的項目。只會傳回已傳遞的索引鍵。 + 如果資料表中未刪除任何項目，該資料表的 data 區塊中就會顯示 *null* 元素。 + 調用結果會根據在請求物件內提供的順序，依資料表排序。 + 中的每個`Delete`命令`BatchDeleteItem`都是原子的。但是，批次可以部分處理。如果因錯誤而部分批次處理，則未處理的索引鍵會透過 *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` 包含錯誤的詳細資訊。函數請求物件中提供的索引鍵**資料**、**unprocessedKeys** 和每個資料表索引鍵保證會出現在調用結果中。已刪除的項目會出現在 **data** 區塊中。尚未處理的項目在該 data 區塊中會標示為 *null*，並置於 **unprocessedKeys** 區塊。 # BatchPutItem `BatchPutItem` 請求物件可讓您指示 AWS AppSync DynamoDB 函數向 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 項目清單。至少必須提供一個資料表。此值為必填。 注意事項： + 若插入成功，回應會傳回完全插入的項目。 + 如果資料表中並未插入任何項目，該資料表的 data 區塊中就會顯示 *null* 元素。 + 插入的項目會根據在請求物件內提供的順序，依資料表排序。 + 不過， 內的每個`Put`命令`BatchPutItem`都是原子的，但可以部分處理批次。如果因錯誤而部分批次處理，則未處理的索引鍵會透過 *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` 包含錯誤的詳細資訊。請求物件中提供的金鑰**資料**、**unprocessedItems** 和每個資料表金鑰都保證會出現在調用結果中。已插入的項目會出現在 **data** 區塊中。尚未處理的項目在該 data 區塊中會標示為 *null*，並置於 **unprocessedItems** 區塊。 # TransactGetItems `TransactGetItems` 請求物件可讓您指示 AWS 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 欄位 ### 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` 區塊中擷取項目的順序會與請求項目的順序相同。 + 以全有或全無的方式執行交易。如果任何請求項目造成錯誤，將不執行整個交易，而且將傳回錯誤詳細資料。 + 無法擷取的請求項目不是錯誤。相反地，*null* 元素會出現在對應位置的*項目*區塊。 + 如果交易錯誤是 *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` 請求物件可讓您指示 AWS 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 欄位 ### 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)。此值為必填。 注意事項： + 如果成功，只會在回應中傳回請求項目的索引鍵。索引鍵的順序將與請求項目的順序相同。 + 以全有或全無的方式執行交易。如果任何請求項目造成錯誤，將不執行整個交易，而且將傳回錯誤詳細資料。 + 沒有兩個請求項目可以定位到相同項目。否則，它們將造成 *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` 中。 # 類型系統 （請求映射） 使用 AWS AppSync DynamoDB 函數呼叫 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 Map 值以下列表示： ``` { "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=" ``` 請注意，二進位資料以 base64 編碼配置編碼，如 [RFC 4648](https://tools.ietf.org/html/rfc4648) 和 [RFC 2045](https://tools.ietf.org/html/rfc2045) 中所定義。 **二進位集類型 `BS` ** 二進位值的集合。DynamoDB 二進位集值會以包含 base64 表示值的字串清單傳回。 例如，如果 DynamoDB 傳回下列 DynamoDB 二進位集值： ``` { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] } ``` AWS AppSync 將其轉換為包含 base64 表示值的字串清單： ``` [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] ``` 請注意，二進位資料以 base64 編碼配置編碼，如 [RFC 4648](https://tools.ietf.org/html/rfc4648) 和 [RFC 2045](https://tools.ietf.org/html/rfc2045) 中所定義。 **布林類型 `BOOL` ** 布林值。DynamoDB 布林值會以布林值傳回。 例如，如果 DynamoDB 傳回下列 DynamoDB 布林值： ``` { "BOOL" : true } ``` AWS AppSync 將其轉換為布林值： ``` true ``` **清單類型 `L` ** 任何其他支援的 DynamoDB 值清單。DynamoDB 清單值會傳回為值清單，其中每個內部值也會轉換。 例如，如果 DynamoDB 傳回下列 DynamoDB 清單值： ``` { "L" : [ { "S" : "A string value" }, { "N" : 1 }, { "SS" : [ "Another string value", "Even more string values!" ] } ] } ``` AWS AppSync 將其轉換為轉換值的清單： ``` [ "A string value", 1, [ "Another string value", "Even more string values!" ] ] ``` **映射類型 `M` ** 任何其他支援的 DynamoDB 值的金鑰/值集合。DynamoDB Map 值會以 JSON 物件傳回，其中每個索引鍵/值也會轉換。 例如，如果 DynamoDB 傳回下列 DynamoDB Map 值： ``` { "M" : { "someString" : { "S" : "A string value" }, "someNumber" : { "N" : 1 }, "stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] } } } ``` AWS AppSync 將其轉換為 JSON 物件： ``` { "someString" : "A string value", "someNumber" : 1, "stringSet" : [ "Another string value", "Even more string values!" ] } ``` **Null 類型 `NULL` ** null 值。 例如，如果 DynamoDB 傳回下列 DynamoDB Null 值： ``` { "NULL" : null } ``` AWS AppSync 將其轉換為 null： ``` null ``` # 篩選條件 使用 `Query`和 `Scan`操作查詢 DynamoDB 中的物件時，您可以選擇指定`filter`評估結果並僅傳回所需值的 。 `Query` 或 `Scan`請求的篩選條件屬性具有下列結構： ``` type DynamoDBExpression = { expression: string; expressionNames?: { [key: string]: string}; expressionValues?: { [key: string]: any}; }; ``` 欄位定義如下： ** `expression` ** 查詢表達式。如需如何編寫篩選條件表達式的詳細資訊，請參閱 [DynamoDB QueryFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.QueryFilter.html) 和 [DynamoDB ScanFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.ScanFilter.html) 文件。必須指定此欄位。 ** `expressionNames` ** 表達式屬性 *name* 預留位置的替代，形式為鍵值組。索引鍵對應至用於 `expression` 的名稱預留位置。值必須是對應於 DynamoDB 中項目屬性名稱的字串。此欄位為選用的，應只能填入用於 `expression` 中表達式屬性名稱預留位置的替代。 ** `expressionValues` ** 表達式屬性 *value* 預留位置的替代，形式為鍵值組。鍵對應用於 `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`和 DynamoDB 操作來變更 `DeleteItem` DynamoDB 中的物件時，您可以選擇指定條件表達式，以根據在執行操作之前已在 DynamoDB 中的物件狀態來控制請求是否成功。 The AWS 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)" } }; } ``` 根據預設，如果條件檢查失敗， AWS AppSync DynamoDB 函數會提供變動的錯誤。 不過， AWS AppSync DynamoDB 函數提供一些額外的功能，以協助開發人員處理一些常見的邊緣案例： + If AWS AppSync DynamoDB 函數可以判斷 DynamoDB 中的目前值是否符合所需的結果，仍會將操作視為成功。 + 您可以設定函數來叫用自訂 Lambda 函數，以決定 AWS AppSync DynamoDB 函數應如何處理失敗，而不是傳回錯誤。 這些會在[處理條件檢查失敗](#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` ** 表達式屬性名稱預留位置的替代，形式為索引鍵值對。索引鍵對應至*表達*式中使用的名稱預留位置，且值必須是對應於 DynamoDB 中項目屬性名稱的字串。此欄位為選用的，應只能填入於*表達式*中所用表達式屬性名稱預留位置的替代。 ** `expressionValues` ** 表達式屬性值預留位置的替代，形式為索引值對。鍵對應用於表達式的值預留位置，值必須是類型值。如需如何指定「輸入值」的詳細資訊，請參閱[類型系統 （請求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。此必須指定。此欄位為選用的，應只能填入用於表達式中表達式屬性值預留位置的替代。 其餘欄位會告知 AWS AppSync DynamoDB 函數如何處理條件檢查失敗： ** `equalsIgnore` ** 當條件檢查在使用 `PutItem`操作時失敗時， AWS AppSync DynamoDB 函數會將目前在 DynamoDB 中的項目與嘗試寫入的項目進行比較。如果兩者相同，則操作視為成功。您可以使用 `equalsIgnore` 欄位來指定執行該比較時 AWS AppSync 應忽略的屬性清單。例如，如果唯一的差異是`version`屬性，它會將操作視為成功。此欄位為選用欄位。 ** `consistentRead` ** 當條件檢查失敗時， AWS AppSync 會使用強式一致讀取，從 DynamoDB 取得項目的目前值。您可以使用此欄位，指示 AWS AppSync DynamoDB 函數改用最終一致讀取。此欄位為選用，預設值為 `true`。 ** `conditionalCheckFailedHandler` ** 本節可讓您指定 AWS AppSync DynamoDB 函數在將 DynamoDB 中的目前值與預期結果進行比較後，如何處理條件檢查失敗。此區段為選用。若省略，則會預設為 `Reject` 策略。 ** `strategy` ** AWS AppSync DynamoDB 函數在將 DynamoDB 中的目前值與預期結果進行比較後所採用的策略。此欄位為必填，且採用下列可能值： ** `Reject` ** 變動會失敗，並會將錯誤新增至 GraphQL 回應。 ** `Custom` ** The AWS AppSync DynamoDB 函數會叫用自訂 Lambda 函數，以決定如何處理條件檢查失敗。當 `strategy` 設定為 `Custom`，`lambdaArn` 欄位必須包含要叫用 Lambda 函數的 ARN。 ** `lambdaArn` ** 要叫用的 Lambda 函數 ARN，決定 AWS AppSync DynamoDB 函數應如何處理條件檢查失敗。只有在 `strategy` 設定為 `Custom` 時，此欄位才必須指定。如需如何使用此功能的詳細資訊，請參閱[處理條件檢查失敗](#condition-check)。 ## 處理條件檢查失敗 當條件檢查失敗時， AWS AppSync DynamoDB 函數可以使用 `util.appendError`公用程式傳遞變動的錯誤和物件的目前值。不過， AWS AppSync DynamoDB 函數提供一些額外的功能，以協助開發人員處理一些常見的邊緣案例： + If AWS AppSync DynamoDB 函數可以判斷 DynamoDB 中的目前值是否符合所需的結果，仍會將操作視為成功。 + 您可以設定函數來叫用自訂 Lambda 函數，以決定 AWS AppSync DynamoDB 函數應如何處理失敗，而不是傳回錯誤。 此程序的流程圖為： ![\[Flowchart showing process for transforming requests with mutation attempts and value checks.\]](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/DynamoDB-condition-check-failure-handling.png) ### 檢查所需結果 當條件檢查失敗時， AWS AppSync DynamoDB 函數會執行 `GetItem` DynamoDB 請求，從 DynamoDB 取得項目的目前值。在預設情況下，它會使用強式一致性讀取，但這可使用 `condition` 區塊中的 `consistentRead` 欄位來設定，並和預期結果進行比較： + 對於 `PutItem`操作， AWS 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 } } ``` The AWS AppSync DynamoDB 函數會將嘗試寫入的項目與目前值進行比較，查看 欄位的唯一差異，`version`但因為它設定為忽略 `version` 欄位，它會將操作視為成功，並傳回從 DynamoDB 擷取的項目。 + 對於 `DeleteItem`操作， AWS AppSync DynamoDB 函數會檢查以確認項目已從 DynamoDB 傳回。如果沒有項目傳回，則操作視為成功。否則，其將按照設定的策略。 + 對於 `UpdateItem`操作， AWS AppSync DynamoDB 函數沒有足夠的資訊來判斷目前在 DynamoDB 中的項目是否符合預期結果，因此遵循設定的策略。 如果 DynamoDB 中物件的目前狀態與預期結果不同， AWS AppSync DynamoDB 函數會遵循設定的策略，以拒絕變動或叫用 Lambda 函數來決定接下來要做什麼。 ### 遵循「拒絕」策略 遵循 `Reject`策略時， AWS AppSync DynamoDB 函數會傳回變動的錯誤。 例如，假設變動要求如下： ``` 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`策略時， AWS AppSync DynamoDB 函數會叫用 Lambda 函數來決定接下來要做什麼。Lambda 函數會選擇下列其中一個選項： + `reject` 變動。這可讓 AWS AppSync DynamoDB 函數的行為如同設定的策略為 `Reject`，傳回 DynamoDB 中物件的變動錯誤和目前值，如上一節所述。 + `discard` 變動。這會通知 AWS AppSync DynamoDB 函數無提示地忽略條件檢查失敗，並在 DynamoDB 中傳回 值。 + `retry` 變動。這會通知 AWS AppSync DynamoDB 函數使用新的請求物件重試變動。 **Lambda 叫用要求** The 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 函數可以檢查調用承載並套用任何商業邏輯，以決定 AWS AppSync DynamoDB 函數應如何處理失敗。處理條件檢查失敗有三個選項： + `reject` 變動。此選項的回應承載必須具有此架構： ``` { "action": "reject" } ``` 這可讓 AWS AppSync DynamoDB 函數的行為如同設定的策略為 `Reject`，傳回 DynamoDB 中物件的變動和目前值的錯誤，如上節所述。 + `discard` 變動。此選項的回應承載必須具有此架構： ``` { "action": "discard" } ``` 這會通知 AWS AppSync DynamoDB 函數無提示地忽略條件檢查失敗，並在 DynamoDB 中傳回 值。 + `retry` 變動。此選項的回應承載必須具有此架構： ``` { "action": "retry", "retryMapping": { ... } } ``` 這會通知 AWS AppSync DynamoDB 函數使用新的請求物件重試變動。`retryMapping` 區段的結構取決於 DynamoDB 操作，並且是該操作完整請求物件的子集。 若是 `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`。如果重試失敗， AWS AppSync DynamoDB 函數會遵循 `Reject`策略。 此為 Lambda 函數處理失敗 `PutItem` 要求的範例。商業邏輯的重點是發起人為何。如果是由 提出`jeffTheAdmin`，它會重試請求，`expectedVersion`從目前在 DynamoDB 中的項目更新 `version`和 。否則，它會拒絕變動。 ``` exports.handler = (event, context, callback) => { console.log("Event: "+ JSON.stringify(event)); // Business logic goes here. var response; if ( event.identity.user == "jeffTheAdmin" ) { response = { "action" : "retry", "retryMapping" : { "attributeValues" : event.requestMapping.attributeValues, "condition" : { "expression" : event.requestMapping.condition.expression, "expressionValues" : event.requestMapping.condition.expressionValues } } } response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 } response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version } else { response = { "action" : "reject" } } console.log("Response: "+ JSON.stringify(response)) callback(null, response) }; ``` # 交易條件表達式 交易條件表達式可在 中所有四種操作類型的請求中使用`TransactWriteItems`，即 、`PutItem``DeleteItem`、 `UpdateItem`和 `ConditionCheck`。 對於 `PutItem`、 `DeleteItem`和 `UpdateItem`，交易條件表達式是選用的。對於 `ConditionCheck`，需要交易條件表達式。 ## 範例 1 下列交易`DeleteItem`函數請求處理常式沒有條件表達式。因此，它會刪除 DynamoDB 中的項目。 ``` 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` ** 表達式屬性名稱預留位置的替代，形式為索引鍵值對。索引鍵對應至*表達*式中使用的名稱預留位置，且值必須是對應於 DynamoDB 中項目屬性名稱的字串。此欄位為選用的，應只能填入於*表達式*中所用表達式屬性名稱預留位置的替代。 ** `expressionValues` ** 表達式屬性值預留位置的替代，形式為索引值對。鍵對應用於表達式的值預留位置，值必須是類型值。如需如何指定「輸入值」的詳細資訊，請參閱[類型系統 （請求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。此必須指定。此欄位為選用的，應只能填入用於表達式中表達式屬性值預留位置的替代。 ** `returnValuesOnConditionCheckFailure` ** 指定是否在條件檢查失敗時擷取 DynamoDB 中的項目。擷取的項目將位於 `ctx.result.cancellationReasons[].item` 中，其中 `` 是條件檢查失敗之請求項目的索引。此值預設為 true。 # 投影 使用 `GetItem`、`BatchGetItem`、、 `Scan` `Query`和 `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 函數的投影區段，其中只有屬性 `id` `author`和 會從 DynamoDB 傳回： ``` projection : { expression : "#author, id", expressionNames : { "#author" : "author" } } ``` **提示** 您可以使用 [selectionSetList](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html#aws-appsync-resolver-context-reference-info-js) 存取 GraphQL 請求選取集。此欄位可讓您根據您的需求動態架構投影表達式。 **注意** 搭配 `Query`和 `Scan`操作使用投影表達式時， 的值`select`必須是 `SPECIFIC_ATTRIBUTES`。如需詳細資訊，請參閱 [DynamoDB 文件](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html#DDB-Query-request-Select)。