PutItem

PutItem リクエストマッピングドキュメントでは、 AWS AppSync DynamoDB リゾルバーに DynamoDB へのPutItemリクエストを行うように指示し、以下を指定できます。

• DynamoDB の項目のキー

• 項目の完全なコンテンツ (key および attributeValues で構成されます)

• 処理が成功する条件

PutItem マッピングドキュメントの構造は次のとおりです。

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

各フィールドの定義は以下のようになります。

PutItem フィールド

PutItem フィールドリスト

version

テンプレート定義バージョン 2017-02-28 と 2018-05-29 は現在サポートされています。この値は必須です。

operation

実行する DynamoDB の処理。PutItem DynamoDB の処理を実行するには、これを PutItem に設定する必要があります。この値は必須です。

key

DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。

attributeValues

DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。このフィールドはオプションです。

condition

DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、PutItem リクエストはその項目の既存のエントリを上書きします。条件の詳細については、「条件式」を参照してください。この値はオプションです。

_version

項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは競合の検出に使用され、バージョン管理されたデータソースでのみサポートされます。

customPartitionKey

有効にすると、この文字列値は、バージョニングが有効になっているときにデルタ同期テーブルで使用される ds_sk および ds_pk レコードの形式を変更します (詳細については、「AWS AppSyncデベロッパーガイド」の「競合検出と同期」を参照)。有効にすると、populateIndexFields エントリの処理も有効になります。このフィールドはオプションです。

populateIndexFields

ブール値で、customPartitionKey と一緒に有効にすると、差分同期テーブル、具体的には gsi_ds_pk と gsi_ds_sk 列のレコードごとに新しいエントリが作成されます。詳細については、「AWS AppSyncデベロッパーガイド」の「競合検出と同期」を参照してください。このフィールドはオプションです。

PutItem フィールドリスト

version

テンプレート定義バージョン 2017-02-28 と 2018-05-29 は現在サポートされています。この値は必須です。

operation

実行する DynamoDB の処理。PutItem DynamoDB の処理を実行するには、これを PutItem に設定する必要があります。この値は必須です。

key

DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。

attributeValues

DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。このフィールドはオプションです。

condition

DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、PutItem リクエストはその項目の既存のエントリを上書きします。条件の詳細については、「条件式」を参照してください。この値はオプションです。

_version

項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは競合の検出に使用され、バージョン管理されたデータソースでのみサポートされます。

customPartitionKey

有効にすると、この文字列値は、バージョニングが有効になっているときにデルタ同期テーブルで使用される ds_sk および ds_pk レコードの形式を変更します (詳細については、「AWS AppSyncデベロッパーガイド」の「競合検出と同期」を参照)。有効にすると、populateIndexFields エントリの処理も有効になります。このフィールドはオプションです。

populateIndexFields

ブール値で、customPartitionKey と一緒に有効にすると、差分同期テーブル、具体的には gsi_ds_pk と gsi_ds_sk 列のレコードごとに新しいエントリが作成されます。詳細については、「AWS AppSyncデベロッパーガイド」の「競合検出と同期」を参照してください。このフィールドはオプションです。

DynamoDB に書き込まれた項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト ($context.result) で参照できます。

DynamoDB の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。

レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。

例 1

以下は、GraphQL ミューテーション updateThing(foo: String!, bar: String!, name: String!, version: Int!) のマッピングテンプレートです。

指定したキーに対応する項目がない場合は、作成されます。指定したキーに対応する項目がすでにある場合は、上書きされます。

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        "version" : $util.dynamodb.toDynamoDBJson($ctx.args.version)
    }
}

例 2

以下は、GraphQL ミューテーション updateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!) のマッピングテンプレートです。

この例では、DynamoDB に現在ある項目の version フィールドに expectedVersion が設定されていることを確認します。

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        #set( $newVersion = $context.arguments.expectedVersion + 1 )
        "version" : $util.dynamodb.toDynamoDBJson($newVersion)
    },
    "condition" : {
        "expression" : "version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
        }
    }
}

DynamoDB PutItem API の詳細については、「DynamoDB API のドキュメント」を参照してください。