翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# DynamoDB 用の Java クライアント側の暗号化ライブラリのバージョン 3.x に移行する
<a name="ddb-java-migrate"></a>


****  

|  | 
| --- |
| クライアント側の暗号化ライブラリの名前が AWS Database Encryption SDK に変更されました。このデベロッパーガイドでは、引き続き [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md) に関する情報を提供します。 | 

DynamoDB 用の Java クライアント側の暗号化ライブラリのバージョン 3.x は、2.x コードベースを大幅に書き直したものです。これには、新しい構造化データ形式、マルチテナンシーのサポートの改善、シームレスなスキーマの変更、検索可能な暗号化のサポートなど、多くの更新が含まれています。このトピックでは、コードをバージョン 3.x に移行する方法について説明します。

## バージョン 1.x から 2.x への移行
<a name="ddb-java-v1-to-v2"></a>

バージョン 3.x に移行する前に、バージョン 2.x に移行してください。バージョン 2.x では、最新プロバイダーの符号が `MostRecentProvider` から `CachingMostRecentProvider` に変更されました。現在、符号が `MostRecentProvider` である DynamoDB 用の Java クライアント側の暗号化ライブラリのバージョン 1.x を使用している場合は、コード内の符号名を `CachingMostRecentProvider` に更新する必要があります。詳細については、「[最新のプロバイダーに更新する](most-recent-provider.md#mrp-versions)」を参照してください。

## バージョン 2.x から 3.x への移行
<a name="ddb-java-v2-to-v3"></a>

次の手順では、DynamoDB 用の Java クライアント側の暗号化ライブラリのコードをバージョン 2.x からバージョン 3.x に移行する方法について説明します。

### ステップ 1. 新しい形式で項目を読み取る準備をする
<a name="ddb-java-migrate-step1"></a>

Database Encryption SDK AWS クライアントが新しい形式の項目を読み取る準備をするには、次の手順を実行します。次の変更をデプロイした後、クライアントは引き続きバージョン 2.x と同じように動作します。クライアントは引き続きバージョン 2.x 形式で項目の読み取りと書き込みを行いますが、これらの変更により、クライアントが新しい形式で項目を読み取る準備が整います。

**をバージョン 2.x AWS SDK for Java に更新する**  
DynamoDB 用の Java クライアント側の暗号化ライブラリのバージョン 3.x では、[DynamoDB Enhanced Client](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html) が必要です。DynamoDB Enhanced Client は、以前のバージョンで使用されていた [DynamoDBMapper](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html) を置き換えます。拡張クライアントを使用するには、 AWS SDK for Java 2.xを使用する必要があります。  
[AWS SDK for Javaのバージョン 1.x から 2.x に移行](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html)する手順に従います。  
必要な AWS SDK for Java 2.x モジュールの詳細については、「」を参照してください[前提条件](ddb-java.md#ddb-java-prerequisites)。

**従来のバージョンによって暗号化された項目を読み取るようにクライアントを設定する**  
次の手順では、以下のコード例で示されているステップの概要を説明します。  

1. キーリングを作成します。

   キーリングと[暗号マテリアルマネージャー](concepts.md#crypt-materials-manager)は、DynamoDB 用の Java クライアント側の暗号化ライブラリの以前のバージョンで使用されていた暗号マテリアルプロバイダーを置き換えます。
**重要**  
キーリングの作成時に指定するラッピングキーは、バージョン 2.x で暗号マテリアルプロバイダーで使用したのと同じラッピングキーである必要があります。

1. アノテーション付きクラスに基づいてテーブルスキーマを作成します。

   このステップでは、新しい形式で項目の書き込みを開始するときに使用される属性アクションを定義します。

   新しい DynamoDB Enhanced Client の使用に関するガイダンスについては、「AWS SDK for Java デベロッパーガイド」の「[`TableSchema` を生成する](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html)」を参照してください。

   次の例では、新しい属性アクションのアノテーションを使用して、アノテーション付きクラスをバージョン 2.x から更新したことを前提としています。属性アクションにアノテーションを付ける方法のガイダンスについては、「[アノテーション付きデータクラスを使用する](ddb-java-using.md#ddb-attribute-actions-annotated-data-class)」を参照してください。
**注記**  
`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` 属性を指定する場合、パーティション属性とソート属性も である必要があります`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`。の定義に使用される注釈の例については`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`、「[SimpleClass4.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass4.java)」を参照してください。

1. どの[属性を署名から除外](ddb-java-using.md#allowed-unauth)するかを定義します。

1. バージョン 2.x のモデル化されたクラスで設定された属性アクションの明示的なマッピングを設定します。

   このステップでは、古い形式で項目を書き込むために使用される属性アクションを定義します。

1. DynamoDB 用の Java クライアント側の暗号化ライブラリのバージョン 2.x で使用した `DynamoDBEncryptor` を設定します。

1. 従来の動作を設定します。

1. `DynamoDbEncryptionInterceptor` を作成します。

1. 新しい AWS SDK DynamoDB クライアントを作成します。

1. `DynamoDBEnhancedClient` を作成し、モデル化されたクラスを含むテーブルを作成します。

   DynamoDB Enhanced Client の詳細については、「[拡張クライアントを作成する](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient)」を参照してください。

```
public class MigrationExampleStep1 {

    public static void MigrationStep1(String kmsKeyId, String ddbTableName, int sortReadValue) {
        // 1. Create a Keyring.
        //    This example creates an AWS KMS Keyring that specifies the 
        //    same kmsKeyId previously used in the version 2.x configuration.
        //    It uses the 'CreateMrkMultiKeyring' method to create the 
        //    keyring, so that the keyring can correctly handle both single
        //    region and Multi-Region KMS Keys.
        //    Note that this example uses the AWS SDK for Java v2 KMS client.
        final MaterialProviders matProv = MaterialProviders.builder()
                .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
                .build();
        final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
                .generator(kmsKeyId)
                .build();
        final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

        // 2. Create a Table Schema over your annotated class.
        //    For guidance on using the new attribute actions 
        //    annotations, see SimpleClass.java in the 
        //    aws-database-encryption-sdk-dynamodb GitHub repository. 
        //    All primary key attributes must be signed but not encrypted 
        //    and by default all non-primary key attributes 
        //    are encrypted and signed (ENCRYPT_AND_SIGN).
        //    If you want a particular non-primary key attribute to be signed but
        //    not encrypted, use the 'DynamoDbEncryptionSignOnly' annotation.
        //    If you want a particular attribute to be neither signed nor encrypted
        //    (DO_NOTHING), use the 'DynamoDbEncryptionDoNothing' annotation.
        final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);

        // 3. Define which attributes the client should expect to be excluded 
        //    from the signature when reading items.
        //    This value represents all unsigned attributes across the entire 
        //    dataset.
        final List<String> allowedUnsignedAttributes = Arrays.asList("attribute3");

        // 4. Configure an explicit map of the attribute actions configured 
        //    in your version 2.x modeled class.
        final Map<String, CryptoAction> legacyActions = new HashMap<>();
        legacyActions.put("partition_key", CryptoAction.SIGN_ONLY);
        legacyActions.put("sort_key", CryptoAction.SIGN_ONLY);
        legacyActions.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
        legacyActions.put("attribute2", CryptoAction.SIGN_ONLY);
        legacyActions.put("attribute3", CryptoAction.DO_NOTHING);

        // 5. Configure the DynamoDBEncryptor that you used in version 2.x.
        final AWSKMS kmsClient = AWSKMSClientBuilder.defaultClient();
        final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kmsClient, kmsKeyId);
        final DynamoDBEncryptor oldEncryptor = DynamoDBEncryptor.getInstance(cmp);

        // 6. Configure the legacy behavior.
        //    Input the DynamoDBEncryptor and attribute actions created in 
        //    the previous steps. For Legacy Policy, use 
        //    'FORCE_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT'. This policy continues to read 
        //    and write items using the old format, but will be able to read
        //    items written in the new format as soon as they appear.
        final LegacyOverride legacyOverride = LegacyOverride
                .builder()
                .encryptor(oldEncryptor)
                .policy(LegacyPolicy.FORCE_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT)
                .attributeActionsOnEncrypt(legacyActions)
                .build();

        // 7. Create a DynamoDbEncryptionInterceptor with the above configuration.
        final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
        tableConfigs.put(ddbTableName,
                DynamoDbEnhancedTableEncryptionConfig.builder()
                        .logicalTableName(ddbTableName)
                        .keyring(kmsKeyring)
                        .allowedUnsignedAttributes(allowedUnsignedAttributes)
                        .schemaOnEncrypt(tableSchema)
                        .legacyOverride(legacyOverride)
                        .build());
        final DynamoDbEncryptionInterceptor interceptor =
                DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
                        CreateDynamoDbEncryptionInterceptorInput.builder()
                                .tableEncryptionConfigs(tableConfigs)
                                .build()
                );

        // 8. Create a new AWS SDK DynamoDb client using the 
        //    interceptor from Step 7.
        final DynamoDbClient ddb = DynamoDbClient.builder()
                .overrideConfiguration(
                        ClientOverrideConfiguration.builder()
                                .addExecutionInterceptor(interceptor)
                                .build())
                .build();

        // 9. Create the DynamoDbEnhancedClient using the AWS SDK DynamoDb client 
        //    created in Step 8, and create a table with your modeled class.
        final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
                .dynamoDbClient(ddb)
                .build();
        final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema);
    }
}
```

### ステップ 2. 新しい形式で項目を書き込む
<a name="ddb-java-migrate-step2"></a>

ステップ 1 からすべてのリーダーに変更をデプロイしたら、次のステップを実行して、新しい形式で項目を書き込むように AWS Database Encryption SDK クライアントを設定します。次の変更をデプロイした後、クライアントは引き続き古い形式で項目を読み取り、新しい形式で項目の書き込みと読み取りを開始します。

次の手順では、以下のコード例で示されているステップの概要を説明します。

1. [**ステップ 1**](#ddb-java-migrate-step1) と同様に、キーリング、テーブルスキーマ、従来の属性アクション、`allowedUnsignedAttributes`、および `DynamoDBEncryptor` の設定を続行します。

1. 新しい形式を使用して新しい項目のみを書き込むように、従来の動作を更新します。

1. `DynamoDbEncryptionInterceptor ` を作成する

1. 新しい AWS SDK DynamoDB クライアントを作成します。

1. `DynamoDBEnhancedClient` を作成し、モデル化されたクラスを含むテーブルを作成します。

   DynamoDB Enhanced Client の詳細については、「[拡張クライアントを作成する](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient)」を参照してください。

```
public class MigrationExampleStep2 {

    public static void MigrationStep2(String kmsKeyId, String ddbTableName, int sortReadValue) {
        // 1. Continue to configure your keyring, table schema, legacy 
        //    attribute actions, allowedUnsignedAttributes, and 
        //    DynamoDBEncryptor as you did in Step 1.
        final MaterialProviders matProv = MaterialProviders.builder()
                .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
                .build();
        final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
                .generator(kmsKeyId)
                .build();
        final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

        final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);

        final List<String> allowedUnsignedAttributes = Arrays.asList("attribute3");

        final Map<String, CryptoAction> legacyActions = new HashMap<>();
        legacyActions.put("partition_key", CryptoAction.SIGN_ONLY);
        legacyActions.put("sort_key", CryptoAction.SIGN_ONLY);
        legacyActions.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
        legacyActions.put("attribute2", CryptoAction.SIGN_ONLY);
        legacyActions.put("attribute3", CryptoAction.DO_NOTHING);

        final AWSKMS kmsClient = AWSKMSClientBuilder.defaultClient();
        final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kmsClient, kmsKeyId);
        final DynamoDBEncryptor oldEncryptor = DynamoDBEncryptor.getInstance(cmp);

        // 2. Update your legacy behavior to only write new items using the new
        //    format. 
        //    For Legacy Policy, use 'FORBID_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT'. This policy
        //    continues to read items in both formats, but will only write items
        //    using the new format.
        final LegacyOverride legacyOverride = LegacyOverride
                .builder()
                .encryptor(oldEncryptor)
                .policy(LegacyPolicy.FORBID_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT)
                .attributeActionsOnEncrypt(legacyActions)
                .build();

        // 3. Create a DynamoDbEncryptionInterceptor with the above configuration.
        final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
        tableConfigs.put(ddbTableName,
                DynamoDbEnhancedTableEncryptionConfig.builder()
                        .logicalTableName(ddbTableName)
                        .keyring(kmsKeyring)
                        .allowedUnsignedAttributes(allowedUnsignedAttributes)
                        .schemaOnEncrypt(tableSchema)
                        .legacyOverride(legacyOverride)
                        .build());
        final DynamoDbEncryptionInterceptor interceptor =
                DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
                        CreateDynamoDbEncryptionInterceptorInput.builder()
                                .tableEncryptionConfigs(tableConfigs)
                                .build()
                );

        // 4. Create a new AWS SDK DynamoDb client using the 
        //    interceptor from Step 3.
        final DynamoDbClient ddb = DynamoDbClient.builder()
                .overrideConfiguration(
                        ClientOverrideConfiguration.builder()
                                .addExecutionInterceptor(interceptor)
                                .build())
                .build();

        // 5. Create the DynamoDbEnhancedClient using the AWS SDK DynamoDb Client created
        //    in Step 4, and create a table with your modeled class.
        final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
                .dynamoDbClient(ddb)
                .build();
        final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema);
    }
}
```

ステップ 2 の変更をデプロイした後、[ステップ 3](#ddb-java-migrate-step3) に進む前に、テーブル内のすべての古い項目を新しい形式で再暗号化する必要があります。既存の項目を迅速に暗号化するために実行できる単一のメトリクスやクエリはありません。システムにとって最も合理的なプロセスを使用してください。例えば、定義した新しい属性アクションと暗号化設定を使用して、時間をかけてテーブルをスキャンし、項目を書き換える非同期プロセスを使用できます。

### ステップ 3. 新しい形式でのみ項目を読み書きする
<a name="ddb-java-migrate-step3"></a>

テーブル内のすべての項目を新しい形式で再暗号化した後、設定から従来の動作を削除できます。新しい形式でのみ項目を読み書きするようにクライアントを設定するには、次のステップを実行します。

次の手順では、以下のコード例で示されているステップの概要を説明します。

1. [**ステップ 1**](#ddb-java-migrate-step1) と同様に、キーリング、テーブルスキーマ、`allowedUnsignedAttributes` の設定を続行します。従来の属性アクションと `DynamoDBEncryptor` を設定から削除します。

1. `DynamoDbEncryptionInterceptor` を作成します。

1. 新しい AWS SDK DynamoDB クライアントを作成します。

1. `DynamoDBEnhancedClient` を作成し、モデル化されたクラスを含むテーブルを作成します。

   DynamoDB Enhanced Client の詳細については、「[拡張クライアントを作成する](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient)」を参照してください。

```
public class MigrationExampleStep3 {

    public static void MigrationStep3(String kmsKeyId, String ddbTableName, int sortReadValue) {
        // 1. Continue to configure your keyring, table schema,
        //    and allowedUnsignedAttributes as you did in Step 1.
        //    Do not include the configurations for the DynamoDBEncryptor or 
        //    the legacy attribute actions.
        final MaterialProviders matProv = MaterialProviders.builder()
                .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
                .build();
        final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
                .generator(kmsKeyId)
                .build();
        final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

        final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);

        final List<String> allowedUnsignedAttributes = Arrays.asList("attribute3");


        // 3. Create a DynamoDbEncryptionInterceptor with the above configuration.
        //    Do not configure any legacy behavior.
        final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
        tableConfigs.put(ddbTableName,
                DynamoDbEnhancedTableEncryptionConfig.builder()
                        .logicalTableName(ddbTableName)
                        .keyring(kmsKeyring)
                        .allowedUnsignedAttributes(allowedUnsignedAttributes)
                        .schemaOnEncrypt(tableSchema)
                        .build());
        final DynamoDbEncryptionInterceptor interceptor =
                DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
                        CreateDynamoDbEncryptionInterceptorInput.builder()
                                .tableEncryptionConfigs(tableConfigs)
                                .build()
                );

        // 4. Create a new AWS SDK DynamoDb client using the 
        //    interceptor from Step 3.
        final DynamoDbClient ddb = DynamoDbClient.builder()
                .overrideConfiguration(
                        ClientOverrideConfiguration.builder()
                                .addExecutionInterceptor(interceptor)
                                .build())
                .build();

        // 5. Create the DynamoDbEnhancedClient using the AWS SDK Client 
        //    created in Step 4, and create a table with your modeled class.
        final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
                .dynamoDbClient(ddb)
                .build();
        final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema);
    }
}
```