Amazon Kinesis Data Streams の新機能「サービス管理パーティションキー」を CLI で試してみた
はじめに
2026年9月23日、Amazon Kinesis Data Streams に「サービス管理パーティションキー」が追加されました。
On-Demand モードのストリームでレコード分散戦略を AUTO に切り替えると、パーティションキーの指定が任意になり、シャードへの配分を Kinesis のアルゴリズムに任せられます。
この記事では AWS CLI を利用して、レコード分散戦略の切り替え手順と、パーティションキーを省略した put-record が成功するか、書き込んだレコードの PartitionKey がどうなるかを確認しました。
検証環境
CLI は次のバージョンを使いました。リージョンは ap-northeast-1 です。
aws-cli/2.37.2 Python/3.14.6 Linux/7.1.13-402.asahi.fc44.aarch64+16k
ストリームを作成して初期状態を確認する
On-Demand モードでストリームを作成します。
aws kinesis create-stream \
--stream-name <stream-name> \
--stream-mode-details StreamMode=ON_DEMAND \
--region ap-northeast-1
作成したストリームを describe-stream-summary で確認します。StreamStatus が ACTIVE になっていれば作成完了です。以降のコマンドで使う ARN もここで取得できます(出力は抜粋)。
{
"StreamARN": "arn:aws:kinesis:ap-northeast-1:<account-id>:stream/<stream-name>",
"RecordDistributionStrategy": "USER_PARTITION_KEY"
}
On-Demand モードで作成しても初期値は USER_PARTITION_KEY です。サービス管理パーティションキーを使うには明示的な切り替えが必要です。
切り替え前にパーティションキーを省略する
USER_PARTITION_KEY のまま --partition-key を付けずに put-record を実行すると、バリデーションエラーになりました。
An error occurred (ValidationException) when calling the PutRecord operation:
1 validation error detected: Value null at 'partitionKey' failed to satisfy constraint: Member must not be null
AUTO へ切り替える
戦略の変更は update-stream-record-distribution-strategy で行います。対象は --stream-arn で指定する必要があります。
aws kinesis update-stream-record-distribution-strategy \
--stream-arn <stream-arn> \
--record-distribution-strategy AUTO \
--region ap-northeast-1
コマンド実行直後のストリームは StreamStatus が UPDATING になりました。次の put-record へ進む前に、describe-stream-summary で状態が ACTIVE に戻り、戦略が AUTO になったことを確認します。
{
"StreamStatus": "ACTIVE",
"RecordDistributionStrategy": "AUTO"
}
aws kinesis put-record help によれば、AUTO のストリームではパーティションキーは任意項目になり、値を渡してもシャードの配分先の決定には使われません。ExplicitHashKey も同様に無視され、レコードはサービス管理のアルゴリズムでシャードへ配分されます。つまり、同じパーティションキーのレコードが同じシャードに入る保証はなくなります。
また、戦略の切り替えは On-Demand モードのストリーム専用です。update-stream-record-distribution-strategy の help によれば、Provisioned モードのストリームに AUTO を設定しようとすると InvalidArgumentException になります。
パーティションキーあり・なしで put-record を比較する
まず、AUTO に切り替えたストリームへパーティションキーを指定して送ります。
aws kinesis put-record \
--stream-arn <stream-arn> \
--data "$(echo -n 'record-with-pk' | base64)" \
--partition-key "user-specified-key" \
--region ap-northeast-1
{
"ShardId": "shardId-000000000003",
"SequenceNumber": "49678656XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3154"
}
次に --partition-key を外して送ります。
aws kinesis put-record \
--stream-arn <stream-arn> \
--data "$(echo -n 'record-no-pk' | base64)" \
--region ap-northeast-1
{
"ShardId": "shardId-000000000002",
"SequenceNumber": "49678656XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2626"
}
パーティションキーを省略した put-record もエラーにならず、レスポンスのフィールドは指定ありの場合と同じです。レスポンスだけでは、どちらの送り方をしたか区別できません。
GetRecords でレコードの PartitionKey を確認する
put-record のレスポンスに含まれていた ShardId をそのまま使い、シャードごとにレコードを読み出します。
# 対象シャードの ShardIterator を取得
aws kinesis get-shard-iterator \
--stream-arn <stream-arn> \
--shard-id <shard-id> \
--shard-iterator-type TRIM_HORIZON \
--region ap-northeast-1
# レコードを取得(ShardIterator の値は前のコマンドの出力から代入)
aws kinesis get-records \
--shard-iterator <shard-iterator> \
--limit 10 \
--region ap-northeast-1
パーティションキーを指定して送ったレコードでは、キーは配分に使われないものの、PartitionKey に指定した値がそのまま入っていました。
{
"Records": [
{
"SequenceNumber": "49678656XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3154",
"ApproximateArrivalTimestamp": "2026-09-25T09:19:21.123000+09:00",
"Data": "cmVjb3JkLXdpdGgtcGs=",
"PartitionKey": "user-specified-key"
}
]
}
省略して送ったレコードでは、Data は送信した値のまま返りましたが、PartitionKey フィールド自体が返りませんでした。
{
"Records": [
{
"SequenceNumber": "49678656XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2626",
"ApproximateArrivalTimestamp": "2026-09-25T09:19:21.584000+09:00",
"Data": "cmVjb3JkLW5vLXBr"
}
]
}
パーティションキーを省略して送る運用に切り替える場合は、コンシューマ側で PartitionKey を参照していないことを確認しておく必要があります。
まとめ
これまではキーの分散が偏って特定のシャードに書き込みが集中すると、Put がスロットルされることがありました。これを避けるため、ハッシュ値を組み合わせたキーの加工など、送信側での対策が必要でしたが、AUTO ならこうした作業が不要になります。
一方、AUTO ではキー単位の順序が維持されないため、たとえば店舗IDをパーティションキーにして店舗ごとの入出金を順番どおりに処理したいような設計では、従来どおり USER_PARTITION_KEY を選んでシャード分散を自分で意識することになります。戦略はストリーム単位で選べるので、順序が要るストリームと要らないストリームを分けておけば両方に対応できます。
ログ集約や IoT テレメトリのようにレコードの順序を必要とせず、シャードの偏りによるスロットル対策が必要な用途では、最新の AWS SDK や KPL とあわせて、レコード分散戦略 AUTO をお試しください。
