本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用适用于 Python 的 DynamoDB 加密客户端
<a name="python-using"></a>

**注意**  
我们的客户端加密库已[重命名为 AWS 数据库加密 SDK](DDBEC-rename.md)。以下主题提供有关适用于 Java 的 DynamoDB 加密客户端版本 1.*x*—2.*x* 以及适用于 Python 的 DynamoDB 加密客户端版本 1.*x*—3.*x* 的信息。有关更多信息，请参阅[适用于 DynamoDB 的AWS 数据库加密 SDK 版本支持](legacy-dynamodb-encryption-client.md#legacy-support)。

本主题介绍了适用于 Python 的 DynamoDB 加密客户端的可能在其他编程语言实施中找不到的一些功能。这些功能旨在更轻松地以最安全的方式使用 DynamoDB 加密客户端。除非您有不寻常的使用案例，否则我们建议您使用这些功能。

[有关使用 DynamoDB 加密客户端进行编程的详细信息，请参阅本指南中的 [Python](python-examples.md) 示例、存储库 GitHub中的 aws-dynamodb-encryption-python示例以及 DynamoDB 加密客户端的 [Python](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/) 文档。](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples)

**Topics**
+ [客户端帮助程序类](#python-helpers)
+ [TableInfo 班级](#table-info)
+ [Python 中的属性操作](#python-attribute-actions)

## 客户端帮助程序类
<a name="python-helpers"></a>

适用于 Python 的 DynamoDB 加密客户端包括多个对 DynamoDB 的 Boto 3 类进行镜像的客户端帮助程序类。这些帮助程序类旨在更轻松地向您的现有 DynamoDB 应用程序添加加密和签名并且避免最常见问题，如下所示：
+ 通过向对象添加主密钥的覆盖操作，或者在您的[AttributeActions](#python-attribute-actions)`AttributeActions`对象明确要求客户端加密主密钥时抛出异常，防止您对项目中的主密钥进行加密。如果您的 `AttributeActions` 对象中的默认操作为 `DO_NOTHING`，则客户端帮助程序类会对主键使用该操作。否则，它们使用 `SIGN_ONLY`。
+ 创建[TableInfo 对象](#python-helpers)并根据对 Dynamo [DB 的调用填充 DynamoDB 加密](concepts.md#encryption-context)上下文。这有助于确保您的 DynamoDB 加密上下文准确且客户端可以标识主键。
+ 支持方法（如 `put_item` 和 `get_item`），这些方法在您在 DynamoDB 表中写入或读取时会以透明方式加密和解密表项目。仅不支持 `update_item` 方法。

您可以使用客户端帮助程序类而不是直接与较低级别的[项目加密程序](DDBEC-legacy-concepts.md#item-encryptor)交互。除非您需要在项目加密程序中设置高级选项，否则使用这些类。

客户端帮助程序类包括：
+ [EncryptedTable](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/table.html#module-dynamodb_encryption_sdk.encrypted.table)适用于使用 DynamoDB 中的[表](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table)资源一次处理一张表的应用程序。
+ [EncryptedResource](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/resource.html)适用于使用 DynamoDB 中的[服务资源](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#service-resource)类进行批处理的应用程序。
+ [EncryptedClient](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/client.html)适用于在 DynamoDB 中使用[较低级别客户端](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#client)的应用程序。

要使用客户端帮助程序类，调用者必须具有在目标表上调用 Dynam [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)oDB 操作的权限。

## TableInfo 班级
<a name="table-info"></a>

该[TableInfo](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/tools/structures.html#dynamodb_encryption_sdk.structures.TableInfo)类是一个代表一个 DynamoDB 表的辅助类，其中包含用于其主键和二级索引的字段。它有助于您获取有关表的准确的实时信息。

如果您使用的是[客户端帮助程序类](#python-helpers)，它会为您创建并使用 `TableInfo` 对象。否则，您可以明确创建一个。有关示例，请参阅[使用项目加密程序](python-examples.md#python-example-item-encryptor)。

当您在`TableInfo`对象上调用该`refresh_indexed_attributes`方法时，它会通过调用 DynamoDB [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)操作来填充该对象的属性值。查询表要比硬编码索引名称更加可靠。`TableInfo` 类还包括 `encryption_context_values` 属性，该属性提供了 [DynamoDB 加密上下文](concepts.md#encryption-context)所需的值。

要使用该`refresh_indexed_attributes`方法，调用者必须具有在目标表上调用 Dynam [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)oDB 操作的权限。

## Python 中的属性操作
<a name="python-attribute-actions"></a>

[属性操作](DDBEC-legacy-concepts.md#legacy-attribute-actions)告知项目加密程序将对项目的每个属性执行哪些操作。要在 Python 中指定属性操作，请创建具有默认操作和针对特定属性的任何例外的 `AttributeActions` 对象。有效值将在 `CryptoAction` 枚举类型中定义。

**重要**  
使用属性操作对表项进行加密后，在数据模型中添加或删除属性可能会导致签名验证错误，从而使您无法解密数据。有关详细说明，请参阅[更改数据模型](data-model.md)。

```
DO_NOTHING = 0
SIGN_ONLY = 1
ENCRYPT_AND_SIGN = 2
```

例如，此 `AttributeActions` 对象建立 `ENCRYPT_AND_SIGN` 作为所有属性的默认值，并且指定 `ISBN` 和 `PublicationYear` 属性的例外。

```
actions = AttributeActions(
    default_action=CryptoAction.ENCRYPT_AND_SIGN,
    attribute_actions={
        'ISBN': CryptoAction.DO_NOTHING,
        'PublicationYear': CryptoAction.SIGN_ONLY
    }
)
```

如果您使用的是[客户端帮助程序类](#python-helpers)，则无需指定主键属性的属性操作。该客户端帮助程序类阻止您加密主键。

如果您未使用客户端帮助程序类且默认操作为 `ENCRYPT_AND_SIGN`，则必须为主键指定操作。对主键建议的操作为 `SIGN_ONLY`。要轻松实现此操作，请使用 `set_index_keys` 方法，该方法对主键使用 SIGN\$1ONLY，或者使用 DO\$1NOTHING，这是默认操作。

**警告**  
请勿加密主键属性。它们必须保留为明文，以便 DynamoDB 查找项目而无需运行全表扫描。

```
actions = AttributeActions(
    default_action=CryptoAction.ENCRYPT_AND_SIGN,
)
actions.set_index_keys(*table_info.protected_index_keys())
```