UpdateItem - AWS AppSync
UpdateItem 欄位範例 1範例 2

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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 欄位

operation

要執行的 DynamoDB 操作。若要執行 UpdateItem DynamoDB 操作，這必須設為 UpdateItem。此值為必填。

key

DynamoDB 中項目的索引鍵。DynamoDB 項目可能具有單一雜湊金鑰，或雜湊金鑰和排序金鑰，具體取決於資料表結構。如需指定「輸入值」的詳細資訊，請參閱類型系統 （請求映射）。此值為必填。

update

update 本節可讓您指定更新表達式，描述如何在 DynamoDB 中更新項目。如需有關如何寫入更新表達式的詳細資訊，請參閱 DynamoDB UpdateExpressions 文件 。此區段是必須的。

update 區段有三個元件：

expression

更新表達式。此值為必填。

expressionNames

表達式屬性 name 預留位置的替代，形式為鍵值組。金鑰對應於 中使用的名稱預留位置expression，且值必須是對應於 DynamoDB 中項目屬性名稱的字串。此欄位為選用的，應只能填入用於 expression 中表達式屬性名稱預留位置的替代。

expressionValues

表達式屬性 value 預留位置的替代，形式為鍵值組。鍵對應用於 expression 的值預留位置，值必須是類型值。如需如何指定「輸入值」的詳細資訊，請參閱類型系統 （請求映射）。此必須指定。此欄位為選用的，應只能填入用於 expression 中表達式屬性值預留位置的替代。

condition

決定要求是否成功的條件，可根據已存在於 DynamoDB 的物件狀態。如果沒有指定條件，UpdateItem 要求會更新現有的資料項目，無論項目的目前狀態為何。如需條件的詳細資訊，請參閱條件表達式 。此值是選用的。

_version

代表項目之最新已知版本的數值。此值是選用的。此欄位用於衝突偵測，而且僅支援已建立版本的資料來源。

customPartitionKey

啟用時，此字串值會修改啟用版本控制時，delta 同步表使用的 ds_sk和ds_pk記錄格式 （如需詳細資訊，請參閱 AWS AppSync 開發人員指南 中的衝突偵測和同步）。啟用時，也會啟用populateIndexFields項目的處理。此欄位為選用欄位。

populateIndexFields

布林值，當 與 一起customPartitionKey啟用時，會為 Delta 同步表中的每個記錄建立新的項目，特別是在 gsi_ds_pk和 gsi_ds_sk欄中。如需詳細資訊，請參閱 AWS AppSync 開發人員指南 中的衝突偵測和同步。此欄位為選用欄位。

在 DynamoDB 中更新的項目會自動轉換為 GraphQL JSON 和原始類型，並且可在內容結果 （） 中使用context.result。

如需 DynamoDB 類型轉換的詳細資訊，請參閱類型系統 （回應映射）。

如需 JavaScript 解析器的詳細資訊，請參閱JavaScript 解析器概觀 。

範例 1

下列範例是 GraphQL 突變 的函數請求處理常式upvote(id: ID!)。

在此範例中，DynamoDB 中的項目其 upvotes和 version 欄位增量為 1。

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { id } = ctx.args;
  return {
    operation: 'UpdateItem',
    key: util.dynamodb.toMapValues({ id }),
    update: {
      expression: 'ADD #votefield :plusOne, version :plusOne',
      expressionNames: { '#votefield': 'upvotes' },
      expressionValues: { ':plusOne': { N: 1 } },
    },
  };
}

範例 2

下列範例是 GraphQL 突變 的函數請求處理常式updateItem(id: ID!, title: String, author: String, expectedVersion: Int!)。

這個複雜的範例會檢查引數，並持續產生更新表達式，其只包含由用戶端提供的引數。例如，如果 title 和 author 遭到省略，則不會更新。如果指定了引數，但其值為 null，則該欄位會從 DynamoDB 中的物件中刪除。最後，操作有一個條件，可驗證目前 DynamoDB 中的項目是否將 version 欄位設定為 expectedVersion：

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { args: { input: { id, ...values } } } = ctx;

  const condition = {
    id: { attributeExists: true },
    version: { eq: values.expectedVersion },
  };
  values.expectedVersion += 1;
  return dynamodbUpdateRequest({ keys: { id }, values, condition });
}


/**
 * Helper function to update an item
 * @returns an UpdateItem request
 */
function dynamodbUpdateRequest(params) {
  const { keys, values, condition: inCondObj } = params;

  const sets = [];
  const removes = [];
  const expressionNames = {};
  const expValues = {};

  // Iterate through the keys of the values
  for (const [key, value] of Object.entries(values)) {
    expressionNames[`#${key}`] = key;
    if (value) {
      sets.push(`#${key} = :${key}`);
      expValues[`:${key}`] = value;
    } else {
      removes.push(`#${key}`);
    }
  }

  let expression = sets.length ? `SET ${sets.join(', ')}` : '';
  expression += removes.length ? ` REMOVE ${removes.join(', ')}` : '';

  const condition = JSON.parse(
    util.transform.toDynamoDBConditionExpression(inCondObj)
  );

  return {
    operation: 'UpdateItem',
    key: util.dynamodb.toMapValues(keys),
    condition,
    update: {
      expression,
      expressionNames,
      expressionValues: util.dynamodb.toMapValues(expValues),
    },
  };
}

如需 DynamoDB UpdateItem 的詳細資訊API，請參閱 DynamoDB API 文件 。