遷移至 DynamoDB Java 用戶端加密程式庫的 3.x 版

我們的用戶端加密程式庫已重新命名為 AWS 資料庫加密 SDK。此開發人員指南仍提供有關 DynamoDB 加密用戶端的資訊。

適用於 DynamoDB 的 Java 用戶端加密程式庫 3.x 版是 2.x 程式碼基礎的主要重寫。它包含許多更新，例如新的結構化資料格式、改善的多租戶支援、無縫結構描述變更，以及可搜尋的加密支援。本主題提供如何將程式碼遷移至 3.x 版的指引。

從 1.x 版遷移至 2.x 版

遷移至 2.x 版，然後再遷移至 3.x 版。2.x 版將最近提供者的符號從變更為 MostRecentProvider CachingMostRecentProvider。如果您目前使用適用於 DynamoDB 的 Java 用戶端加密程式庫 1.x 版搭配 MostRecentProvider符號，則必須將程式碼中的符號名稱更新為 CachingMostRecentProvider。如需詳細資訊，請參閱最近供應商的更新。

從 2.x 版遷移至 3.x

下列程序說明如何將程式碼從 2.x 版遷移至 DynamoDB Java 用戶端加密程式庫的 3.x 版。

步驟 1. 準備讀取新格式的項目

請完成下列步驟，以準備您的 AWS Database Encryption SDK 用戶端以讀取新格式的項目。部署下列變更之後，您的用戶端會繼續以與 2.x 版相同的方式運作。您的用戶端將繼續讀取和寫入 2.x 版格式的項目，但這些變更可讓用戶端準備好讀取新格式的項目。

將更新適用於 Java 的 AWS SDK 至 2.x 版

DynamoDB 的 Java 用戶端加密程式庫版本 3.x 需要 DynamoDB 增強型用戶端。DynamoDB 增強型用戶端會取代先前版本中使用的 DynamoDBMapper。若要使用增強型用戶端，您必須使用 AWS SDK for Java 2.x。

遵循從 1.x 版遷移至 2.x 版適用於 Java 的 AWS SDK的指示。

如需需要哪些 AWS SDK for Java 2.x 模組的詳細資訊，請參閱先決條件。

將用戶端設定為讀取舊版加密的項目

下列程序提供以下程式碼範例中示範的步驟概觀。

建立 keyring。

Keyring 和密碼編譯資料管理員會取代 DynamoDB 舊版 Java 用戶端加密程式庫中使用的密碼編譯資料提供者。

重要
您在建立 keyring 時指定的包裝金鑰，必須與您在 2.x 版中與密碼編譯資料提供者搭配使用的包裝金鑰相同。
在註釋的類別上建立資料表結構描述。

此步驟定義了當您開始以新格式寫入項目時將使用的屬性動作。

如需使用新 DynamoDB 增強型用戶端的指引，請參閱《 適用於 Java 的 AWS SDK 開發人員指南》中的產生 TableSchema。

下列範例假設您使用新的屬性動作註釋，從 2.x 版更新您的註釋類別。如需註釋屬性動作的更多指引，請參閱使用標註的資料類別。

注意
如果您指定任何SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT屬性，則分割區和排序屬性也必須是 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。如需顯示用於定義之註釋的範例SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT，請參閱 SimpleClass4.java。
定義要從簽章中排除哪些屬性。
設定 2.x 版模型化類別中所設定屬性動作的明確映射。

此步驟定義用於以舊格式寫入項目的屬性動作。
設定DynamoDBEncryptor您在 DynamoDB 的 Java 用戶端加密程式庫 2.x 版中使用的。
設定舊版行為。
建立 DynamoDbEncryptionInterceptor。
建立新的 AWS SDK DynamoDB 用戶端。
建立 DynamoDBEnhancedClient並使用模型化類別建立資料表。

如需 DynamoDB 增強型用戶端的詳細資訊，請參閱建立增強型用戶端。


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. 以新格式寫入項目

將步驟 1 的變更部署到所有讀取器之後，請完成下列步驟，以設定 AWS 資料庫加密 SDK 用戶端以新格式寫入項目。部署下列變更後，用戶端會繼續讀取舊格式的項目，並開始寫入和讀取新格式的項目。

下列程序提供以下程式碼範例中示範的步驟概觀。

繼續設定 keyring、資料表結構描述、舊版屬性動作、和 allowedUnsignedAttributes，DynamoDBEncryptor如您在步驟 1 中所執行。
更新您的舊版行為，只使用新格式撰寫新項目。
建立 DynamoDbEncryptionInterceptor
建立新的 AWS SDK DynamoDB 用戶端。
建立 DynamoDBEnhancedClient並使用模型化類別建立資料表。

如需 DynamoDB 增強型用戶端的詳細資訊，請參閱建立增強型用戶端。


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。沒有您可以執行的單一指標或查詢，以快速加密現有的項目。使用對您的系統最有意義的程序。例如，您可以使用慢速掃描資料表的非同步程序，並使用您定義的新屬性動作和加密組態重寫項目。

步驟 3。僅讀取和寫入新格式的項目

使用新格式重新加密資料表中的所有項目之後，您可以從組態中移除舊版行為。完成下列步驟，將用戶端設定為僅讀取和寫入新格式的項目。

下列程序提供以下程式碼範例中示範的步驟概觀。

繼續設定 keyring、資料表結構描述，allowedUnsignedAttributes如您在步驟 1 中所執行。DynamoDBEncryptor 從組態中移除舊版屬性動作和。
建立 DynamoDbEncryptionInterceptor。
建立新的 AWS SDK DynamoDB 用戶端。
建立 DynamoDBEnhancedClient並使用模型化類別建立資料表。

如需 DynamoDB 增強型用戶端的詳細資訊，請參閱建立增強型用戶端。


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);
    }
}

顯示較多

顯示較少

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

將 3.x 版新增至現有資料表

.NET

遷移至 DynamoDB Java 用戶端加密程式庫的 3.x 版

從 1.x 版遷移至 2.x 版

從 2.x 版遷移至 3.x

步驟 1. 準備讀取新格式的項目

重要

注意

步驟 2. 以新格式寫入項目

步驟 3。僅讀取和寫入新格式的項目