AWS EmulatorでDynamoDBの条件付き書き込みを試す方法

​​AWS Emulator​AWS CLI,Boto3,DynamoDB,Python

DynamoDB の書き込みに条件式(--condition-expression)を付けると、「まだないときだけ作る」「在庫が足りるときだけ減らす」「読んだときから誰も変えていないときだけ更新する」といった書き込みができます。会員の二重登録の防止や、在庫の引き当て、同時に更新したときに片方の変更が消える問題の対策(楽観的ロック)に使うものです。ここでは、AWS のアカウントを使わずに手元の AWS Emulator を相手にして、条件が合うときと合わないときの動きを、検証環境で実行したコマンドと出力のまま載せます。

補足

検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.487(2026年11月17日リリース)、AWS CLI 2.40.4、Python 3.11 と Boto3 1.44.4 です。AWS のアカウントと認証情報は使っていません。本物の DynamoDB での動き(料金、条件が合わなかった書き込みで消費される容量、たくさんの書き込みが同時に届いたときの動き、グローバルテーブルでの動き)は確かめていません。本物の AWS について書いているところは、公式ドキュメントを出どころにしています。出力の中の12桁のアカウントIDは置き換えています。

エミュレーターを起動して、テーブルを作る

AWS Emulator は、AWS の API を手元で受け付けるエミュレーターです。公式ドキュメントによると、AWS のアカウントは要らず、リクエストは AWS に送られません。

入れ方は別の記事「AWS EmulatorをUbuntuに入れて使い始める方法」で詳しく扱っています。検証環境では、Linux 向けの手順にある Debian パッケージを、gpg で署名を確かめてから入れました(署名の確かめ方は、その記事と公式の手順にあります)。私は root で作業したので sudo を付けていませんが、下のコマンドでは一般のユーザー向けに付けています。

bash
curl -fsSLo aws-emulator_amd64.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator_amd64.deb
aws-emulator -t off

-t off は、既定で AWS に送られる利用状況のデータ(テレメトリー)を止める指定です。エミュレーターはその端末で動き続けるので、AWS CLI は別の端末で使います。別の端末では、公式ドキュメントにある環境変数を設定して、接続先をエミュレーターに向けます。

bash
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
注意

公式ドキュメントでは、AWS_ENDPOINT_URL が設定されていないシェルでコマンドを実行すると、見つかった認証情報で本物の AWS に送られると注意しています。本物の認証情報があるマシンでは、上の環境変数をすべて設定したシェルで実行してください。

接続先の確かめ方にあるとおり、ARN の最後が user/emulator なら、エミュレーターが答えています。続けて、id をパーティションキーにした Cats テーブルを作り、ACTIVE になるまで待ちます。

text
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator
$ aws dynamodb create-table --table-name Cats \
    --attribute-definitions AttributeName=id,AttributeType=S \
    --key-schema AttributeName=id,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST \
    --query TableDescription.TableStatus --output text
CREATING
$ aws dynamodb wait table-exists --table-name Cats

同じキーの項目がないときだけ作る

put-item は、同じキーの項目があると黙って上書きします。条件式の CLI の例にあるとおり、attribute_not_exists(id) を条件にすると、そのキーの項目がまだないときだけ書き込まれます。新しい会員やメールアドレスの登録で、二重登録を防ぎたいときの書き方です。

1回目は項目がないので書き込まれます。food はごはんの残りの数、version は後で楽観的ロックに使う番号です。

text
$ aws dynamodb put-item --table-name Cats \
    --item '{"id": {"S": "tama"}, "name": {"S": "タマ"}, "food": {"N": "3"}, "version": {"N": "1"}}' \
    --condition-expression 'attribute_not_exists(id)'

同じ id でもう一度書こうとすると、ConditionalCheckFailedException で断られました。終了コードは 254 です。

text
$ aws dynamodb put-item --table-name Cats \
    --item '{"id": {"S": "tama"}, "name": {"S": "二匹目のタマ"}, "food": {"N": "0"}, "version": {"N": "1"}}' \
    --condition-expression 'attribute_not_exists(id)'

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the PutItem operation: The conditional request failed

断られたときに、今の項目の中身も受け取る

何が入っていたせいで断られたのかを知りたいときは、--return-values-on-condition-check-failure ALL_OLD を付けます。開発者ガイドの条件付き書き込みの説明によると、これを付けると、エラーに今の項目の属性が入り、読み直さなくても中身を確かめられます。

ただし、AWS CLI の既定のエラー表示では、項目の中身は Item: <complex value> としか出ませんでした。

text
$ aws dynamodb put-item --table-name Cats \
    --item '{"id": {"S": "tama"}, "name": {"S": "二匹目のタマ"}, "food": {"N": "0"}, "version": {"N": "1"}}' \
    --condition-expression 'attribute_not_exists(id)' \
    --return-values-on-condition-check-failure ALL_OLD

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the PutItem operation: The conditional request failed

Additional error details:
Item: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

案内のとおり、AWS CLI のエラーの出力形式を --cli-error-format json で JSON にすると、Item の中身が見えました。

text
$ aws dynamodb put-item --table-name Cats \
    --item '{"id": {"S": "tama"}, "name": {"S": "二匹目のタマ"}, "food": {"N": "0"}, "version": {"N": "1"}}' \
    --condition-expression 'attribute_not_exists(id)' \
    --return-values-on-condition-check-failure ALL_OLD --cli-error-format json
{
    "Message": "The conditional request failed",
    "Code": "ConditionalCheckFailedException",
    "message": "The conditional request failed",
    "Item": {
        "name": {
            "S": "タマ"
        },
        "food": {
            "N": "3"
        },
        "version": {
            "N": "1"
        },
        "id": {
            "S": "tama"
        }
    }
}

読み直すと、項目は最初に書いた「タマ」のままでした。

text
$ aws dynamodb get-item --table-name Cats --key '{"id": {"S": "tama"}}' --consistent-read \
    --query 'Item.{name: name.S, food: food.N, version: version.N}'
{
    "name": "タマ",
    "food": "3",
    "version": "1"
}

項目があるときだけ更新する

update-item は、指定したキーの項目がないと、新しく作ります(UpdateItem の API リファレンス)。エミュレーターでも、まだない kuro を更新すると、項目が作られました。

text
$ aws dynamodb update-item --table-name Cats --key '{"id": {"S": "kuro"}}' \
    --update-expression 'SET food = :f' \
    --expression-attribute-values '{":f": {"N": "2"}}' --return-values ALL_NEW
{
    "Attributes": {
        "id": {
            "S": "kuro"
        },
        "food": {
            "N": "2"
        }
    }
}

キーを打ち間違えたときなどに項目が増えては困る場合は、attribute_exists(id) を条件にします。まだない shiro の更新は断られ、テーブルにあるのは kuro と tama だけでした。

text
$ aws dynamodb update-item --table-name Cats --key '{"id": {"S": "shiro"}}' \
    --update-expression 'SET food = :f' \
    --expression-attribute-values '{":f": {"N": "2"}}' \
    --condition-expression 'attribute_exists(id)'

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the UpdateItem operation: The conditional request failed
$ aws dynamodb scan --table-name Cats --query 'Items[].id.S' --consistent-read
[
    "kuro",
    "tama"
]

数が足りるときだけ減らす

在庫やポイントのように、0 より下に減らしたくない値は、比べる条件を付けて減らします。tama の food(3)から 2 を引く更新を、food >= :n を条件にして2回送りました。

text
$ aws dynamodb update-item --table-name Cats --key '{"id": {"S": "tama"}}' \
    --update-expression 'SET food = food - :n' \
    --condition-expression 'food >= :n' \
    --expression-attribute-values '{":n": {"N": "2"}}' --return-values UPDATED_NEW
{
    "Attributes": {
        "food": {
            "N": "1"
        }
    }
}
$ aws dynamodb update-item --table-name Cats --key '{"id": {"S": "tama"}}' \
    --update-expression 'SET food = food - :n' \
    --condition-expression 'food >= :n' \
    --expression-attribute-values '{":n": {"N": "2"}}' --return-values UPDATED_NEW

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the UpdateItem operation: The conditional request failed
$ aws dynamodb get-item --table-name Cats --key '{"id": {"S": "tama"}}' --consistent-read \
    --query 'Item.food.N' --output text
1

1回目で 1 になり、2回目は 1 から 2 を引けないので断られ、値は 1 のままでした。

同じ更新を、まだない mugi に送ったときも断られました。項目がないので比べる food もなく、条件は成り立ちませんでした。なお、条件を付けずに送っても、引く元の food がないので ValidationException になり、どちらの場合も項目は作られませんでした。

text
$ aws dynamodb update-item --table-name Cats --key '{"id": {"S": "mugi"}}' \
    --update-expression 'SET food = food - :n' \
    --condition-expression 'food >= :n' \
    --expression-attribute-values '{":n": {"N": "2"}}'

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the UpdateItem operation: The conditional request failed
$ aws dynamodb update-item --table-name Cats --key '{"id": {"S": "mugi"}}' \
    --update-expression 'SET food = food - :n' \
    --expression-attribute-values '{":n": {"N": "2"}}'

aws: [ERROR]: An error occurred (ValidationException) when calling the UpdateItem operation: The provided expression refers to an attribute that does not exist in the item
$ aws dynamodb scan --table-name Cats --query 'Items[].id.S' --consistent-read
[
    "kuro",
    "tama"
]

version を比べて、ほかの人の変更を上書きしない

項目を読んでから書き戻すあいだに、ほかの処理が同じ項目を書き換えると、後から書いた側が前の変更を消してしまいます。同時更新の扱い方のベストプラクティスでは、こうした「読んで、変えて、書き戻す」処理には、バージョンの属性と条件付き書き込みを使う楽観的ロックを挙げています。衝突を書き込みのときに見つけ、見つけたら書き込みは失敗し、アプリがやり直すというやり方です。

ここでは、書き手Aと書き手Bがどちらも version が 1 のときに tama を読み、そのあとで名前を変えようとした場面を再現します。どちらも「version が、読んだときの 1 のままなら、名前を変えて version を 1 増やす」という更新を送ります。

書き手Aと書き手Bがどちらも version 1 を読み、先に更新したAが version 2 にしたあと、同じ条件のBの更新が ConditionalCheckFailedException で断られる流れ
version を条件にした更新で、後から来た書き手Bの更新が断られる流れ

先に送った書き手Aの更新は通り、version は 2 になりました。

text
$ aws dynamodb update-item --table-name Cats --key '{"id": {"S": "tama"}}' \
    --update-expression 'SET #n = :name, version = version + :one' \
    --condition-expression 'version = :expected' \
    --expression-attribute-names '{"#n": "name"}' \
    --expression-attribute-values '{":name": {"S": "タマ(A)"}, ":one": {"N": "1"}, ":expected": {"N": "1"}}' \
    --return-values ALL_NEW --query 'Attributes.{name: name.S, version: version.N}'
{
    "name": "タマ(A)",
    "version": "2"
}

name は DynamoDB の予約語なので、式の中では #n という別名で書いています。

続けて、書き手Bが同じく version = 1 を条件にして送ると、断られました。項目は書き手Aの変更のまま残っています。

text
$ aws dynamodb update-item --table-name Cats --key '{"id": {"S": "tama"}}' \
    --update-expression 'SET #n = :name, version = version + :one' \
    --condition-expression 'version = :expected' \
    --expression-attribute-names '{"#n": "name"}' \
    --expression-attribute-values '{":name": {"S": "タマ(B)"}, ":one": {"N": "1"}, ":expected": {"N": "1"}}' \
    --return-values ALL_NEW --query 'Attributes.{name: name.S, version: version.N}'

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the UpdateItem operation: The conditional request failed
$ aws dynamodb get-item --table-name Cats --key '{"id": {"S": "tama"}}' --consistent-read \
    --query 'Item.{name: name.S, version: version.N}'
{
    "name": "タマ(A)",
    "version": "2"
}

開発者ガイドの条件付き書き込みの説明にも、条件を付けずに2人が同じ項目を更新すると、後の更新が通って先の更新が失われる例が載っています。断られた側は、項目を読み直して最新の version で更新をやり直すようにします。

なお、ベストプラクティスのページには、リージョンをまたいで同期するグローバルテーブルでは、バージョン番号を使う楽観的ロックが期待どおりには働かないとも書かれています。

アプリの中で、断られたことと今の値を受け取る

アプリでは、例外を受け取って処理を分けます。Python の Boto3 で、書き手Bと同じ更新を ReturnValuesOnConditionCheckFailure="ALL_OLD" を付けて送ってみました。cond_fail.py の中身です。

python
import boto3
client = boto3.client("dynamodb")
try:
    client.update_item(
        TableName="Cats",
        Key={"id": {"S": "tama"}},
        UpdateExpression="SET #n = :name, version = version + :one",
        ConditionExpression="version = :expected",
        ExpressionAttributeNames={"#n": "name"},
        ExpressionAttributeValues={":name": {"S": "タマ(B)"}, ":one": {"N": "1"}, ":expected": {"N": "1"}},
        ReturnValuesOnConditionCheckFailure="ALL_OLD",
    )
except client.exceptions.ConditionalCheckFailedException as e:
    print(e.response["Error"]["Code"])
    item = e.response.get("Item")
    print("name:", item["name"]["S"], "version:", item["version"]["N"])

同じシェル(環境変数を設定したもの)で実行すると、ConditionalCheckFailedException を受け取れて、例外の response の Item から、今の名前と version を取り出せました。

text
$ python3 cond_fail.py
ConditionalCheckFailedException
name: タマ(A) version: 2

値を確かめてから削除する

delete-item にも条件を付けられます(条件式の CLI の例のうち、条件付きで削除する例)。kuro の food は 2 なので、food = 0 を条件にした削除は断られ、food = 2 を条件にした削除は通りました。

text
$ aws dynamodb delete-item --table-name Cats --key '{"id": {"S": "kuro"}}' \
    --condition-expression 'food = :zero' \
    --expression-attribute-values '{":zero": {"N": "0"}}'

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the DeleteItem operation: The conditional request failed
$ aws dynamodb delete-item --table-name Cats --key '{"id": {"S": "kuro"}}' \
    --condition-expression 'food = :two' \
    --expression-attribute-values '{":two": {"N": "2"}}' \
    --return-values ALL_OLD --query 'Attributes.id.S' --output text
kuro
$ aws dynamodb scan --table-name Cats --query 'Items[].id.S' --consistent-read
[
    "tama"
]

別の項目の条件を見てから書く(トランザクション)

ここまでの条件は、書き込む項目そのものの値しか見ません。「棚(pantry)に在庫が2つ以上あるときだけ、tama のごはんを2つ増やす」のように、別の項目の値を条件にしたいときは、TransactWriteItems の ConditionCheck を使います。API リファレンスによると、ConditionCheck は、トランザクションで書き換えない項目に条件をかけるもので、トランザクションの中の操作は、すべて成功するか、すべて失敗するかのどちらかです。

棚の在庫を 1 にしてから、次の tx.json を送ります。

text
$ aws dynamodb put-item --table-name Cats --item '{"id": {"S": "pantry"}, "stock": {"N": "1"}}'
$ cat tx.json
[
  {"ConditionCheck": {"TableName": "Cats", "Key": {"id": {"S": "pantry"}},
    "ConditionExpression": "stock >= :n", "ExpressionAttributeValues": {":n": {"N": "2"}},
    "ReturnValuesOnConditionCheckFailure": "ALL_OLD"}},
  {"Update": {"TableName": "Cats", "Key": {"id": {"S": "tama"}},
    "UpdateExpression": "SET food = food + :n", "ExpressionAttributeValues": {":n": {"N": "2"}}}}
]

在庫が足りないので、トランザクションは TransactionCanceledException で取り消されました。既定のエラー表示では、理由は CancellationReasons: <complex value> としか出ません。

text
$ aws dynamodb transact-write-items --transact-items file://tx.json

aws: [ERROR]: An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]

Additional error details:
CancellationReasons: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

そこで、ここでも --cli-error-format json を付けて送り直しました。

text
$ aws dynamodb transact-write-items --transact-items file://tx.json --cli-error-format json
{
    "Message": "Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]",
    "Code": "TransactionCanceledException",
    "CancellationReasons": [
        {
            "Item": {
                "id": {
                    "S": "pantry"
                },
                "stock": {
                    "N": "1"
                }
            },
            "Code": "ConditionalCheckFailed",
            "Message": "The conditional request failed"
        },
        {
            "Code": "None"
        }
    ]
}
$ aws dynamodb get-item --table-name Cats --key '{"id": {"S": "tama"}}' --consistent-read \
    --query 'Item.food.N' --output text
1

CancellationReasons は、送った操作と同じ順に並びます。1つ目(棚の ConditionCheck)が ConditionalCheckFailed で、そのときの棚の中身も入っています。2つ目(tama の Update)は、エラーのない操作を表す None でした。この並び方と None の意味は、API リファレンスの TransactionCanceledException の説明と同じです。条件を付けていない tama の更新も行われず、food は 1 のままでした。

棚の在庫を 5 にして同じ tx.json を送ると、今度は通り、tama の food は 3 になりました。

text
$ aws dynamodb put-item --table-name Cats --item '{"id": {"S": "pantry"}, "stock": {"N": "5"}}'
$ aws dynamodb transact-write-items --transact-items file://tx.json
$ aws dynamodb get-item --table-name Cats --key '{"id": {"S": "tama"}}' --consistent-read \
    --query 'Item.food.N' --output text
3

本物の DynamoDB で気をつけること

本物の DynamoDB での料金や容量の消費は、この記事では確かめていません。公式ドキュメントには、次のことが書かれています。

  • 条件が合わずに断られた書き込みでも、テーブルの書き込みの容量は消費されます。量は既存の項目の大きさで決まり、項目がなかったときは 1 です(条件付き書き込みで消費される容量)。オンデマンドのテーブルでは、読み書きのリクエストごとに課金されます。
  • ReturnValuesOnConditionCheckFailure で項目を返させても、読み込みの容量は消費されません(UpdateItem の API リファレンス)。
  • TransactWriteItems にまとめられる操作は100個までで、同じ項目に2つの操作をかけることはできません(TransactWriteItems の API リファレンス)。棚の ConditionCheck と棚の Update を1つのトランザクションに入れる、といった書き方はできないということです。

エミュレーターがどこまで本物と同じ動きをするかは、サービスや機能ごとに違います。PutItem や UpdateItem のようなデータを読み書きする API(データプレーンの API)の忠実度もサービスによって違うと、公式ドキュメントの「Fidelity」のページに書かれています。

最後にテーブルを消して、エミュレーターを止めました。止めるには、起動した端末で Ctrl+C を押すか、プロセスに SIGTERM を送ります(検証環境では SIGTERM を送りました)。Linux 向けの手順によると、エミュレーターは止まるときに ~/.aws/emulator/9297/ に作ったファイルを消し、リソースはメモリーにだけ置いているので、それも消えます。止めたあとに数えると、ファイルは0個でした。

text
$ aws dynamodb delete-table --table-name Cats --query TableDescription.TableStatus --output text
DELETING
# ここで、エミュレーターに SIGTERM を送って止めた
$ ls ~/.aws/emulator/9297/ 2>/dev/null | wc -l
0

​Posted by 86