Microsoft Dataverse 中的备用键允许使用业务列而不是仅 GUID 主键来唯一标识表行。 这些标识符是每个表的主键。 当需要与外部数据存储集成时，可以将列添加到外部数据库表，以包含对 Dataverse 中行的唯一标识符的引用。 但是，有时无法修改外部数据库。 通过使用备用键，可以定义 Dataverse 表中的列，以对应于外部数据存储使用的唯一标识符（或列的唯一组合）。 此替代键可代替主键唯一标识 Dataverse 中的行。 必须能够定义哪些列标识每行的唯一身份。 标识表中特有的列后，您可以通过自定义用户界面（UI）或代码将其声明为候选键。 本文提供有关在数据模型中定义备用键的信息。
创建备用键
可以通过编程方式或使用自定义工具创建备用密钥。 有关使用自定义工具的详细信息，请参阅 使用 Power Apps 定义备用键。
若要以编程方式定义备用键，请先创建类型 EntityKeyMetadata 对象（或使用 EntityKeyMetadata EntityType （如果使用 Web API）。 此类包含键列。 设置键列后，使用CreateEntityKey为表创建键。 此消息将表名称和 EntityKeyMetadata 值作为输入来创建键。
创建备用键时请注意以下约束：
关键表定义中的有效列
仅在备用键表定义中包含以下类型的列：
列类型 显示名称 DecimalAttributeMetadata 十进制数 IntegerAttributeMetadata 整数 StringAttributeMetadata 单行文本 DateTimeAttributeMetadata 日期时间 LookupAttributeMetadata 查找 PicklistAttributeMetadata 选项集 属性不得应用字段级安全性
有效的键大小
创建密钥时，系统会验证密钥，包括总密钥大小不会违反基于 SQL 的索引约束，例如每个键 900 字节和每个键 16 列。 如果密钥大小不符合约束，则会显示一条错误消息。
表中备用键表定义的最大数量
Dataverse 实例中的表最多可以有 10 个备用键表定义。
键值中的 Unicode 字符
如果在备用键所用的列中包含了以下任意一个字符
/,<,>,*,%,&,:,\\,?,+，则检索、更新或合并插入操作将无法正常执行。 如果只需要唯一性，则此方法有效，但如果需要将这些键用作数据集成的一部分，最好对不具有这些字符数据的列创建键。虚拟表中不支持
虚拟表中不支持备用键，因为当数据在另一个系统上时，系统无法强制实施唯一性。 有关详细信息，请参阅 虚拟表（实体）入门。
检索和删除备用键
若要检索或删除备用密钥，请使用自定义 UI。 无需编写任何代码。 但是，SDK 提供以下两条消息，以编程方式检索和删除备用密钥：
| 消息请求类 | 说明 |
|---|---|
| RetrieveEntityKeyRequest | 检索指定的备用键。 |
| DeleteEntityKeyRequest | 删除指定的备用键。 |
要检索表的所有键，请使用 EntityMetadata（EntityMetadata EntityType 或 EntityMetadata 类）的 Keys 属性。 它将返回该表的键数组。
使用此 Web API 查询查看所有表，并查看哪些表具有备用键：
GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$expand=Keys($select=KeyAttributes)
此请求返回的一些示例：
{
"SchemaName": "Account",
"MetadataId": "70816501-edb9-4740-a16c-6a5efbc05d84",
"Keys": [
{
"KeyAttributes": [
"accountnumber"
],
"MetadataId": "1dc7b1d2-6beb-ec11-bb3d-0022482ea769"
}
]
},
{
"SchemaName": "example_Table",
"MetadataId": "8f521e41-8934-ec11-b6e6-002248242f3b",
"Keys": [
{
"KeyAttributes": [
"example_key1",
"example_key2"
],
"MetadataId": "2f16d0c6-88ea-ec11-bb3d-0022482ea769"
}
]
}
监视备用键的索引创建
备用键使用数据库索引来强制实施唯一性、优化查找性能。 如果表具有许多现有记录，则创建索引可能需要很长时间。 若要使自定义 UI 和解决方案导入响应性更高，请在后台进程中创建索引。 属性 EntityKeyMetadata.AsyncJob （EntityKeyMetadata EntityType 或 EntityKeyMetadata） 引用创建索引的异步作业。
EntityKeyMetadata.EntityKeyIndexStatus 属性指定键在索引创建作业进行时的状态。 状态可以是以下任一值：
- 待处理
- 正在进行中
- 积极
- Failed
当使用 API 创建备用键并创建索引失败时，可以查看失败原因的详细信息，纠正问题，并使用 ReactivateEntityKey (ReactivateEntityKey 操作 或 ReactivateEntityKeyRequest 消息) 重新激活键请求。
如果在索引创建作业仍在挂起或正在进行时删除备用键，则会取消该作业并删除索引。