使用备用键引用记录

使用 Web API 时，使用 URL 引用特定记录。 然后，使用POST或 PATCHDELETE HTTP 方法执行数据操作。 你还可以使用 URL 通过 @odata.bind 语法设置单值导航属性的值，或者将 URL 用作函数和操作的参数。

下表提供了演示如何使用相对 URL 引用记录的示例：

在 Web API 中使用备用密钥时出现异常

使用备用键时，请注意以下条件和可能的异常：

• 如果指定未定义为唯一键的列，则会发生错误。 错误消息为：The key in the request URI is not valid for resource 'Microsoft.Dynamics.CRM.<table logical name>'. Ensure that the names and number of key properties match the declared or alternate key properties for the resource 'Microsoft.Dynamics.CRM.<table logical name>'.

• 备用键值不能包含一些特殊字符。

  不支持具有以下字符/的备用键值、<、>*、%&、:、\\、?+。 这些特殊字符在 URL 路径段中具有保留或结构意义。 如果在 URL 的括号内发送 GET 包含这些值的请求，Dataverse 将返回错误。 解决方法不是检索单个记录，而是使用备用键值来 $filter 检索包含与备用键值匹配的一条记录的集合。

  例如，不要使用这个会失败的请求：

  GET [Organization URI]/api/data/v9.2/new_skts(new_name='M%26M')
  

  使用 $filter 查询：

  GET [Organization URI]/api/data/v9.2/new_skts?$filter=new_name eq 'M%26M'&$select=new_name
  

  如果只需要访问记录，则可以从返回的集合中的 value 第一条（且仅）匹配记录中获取数据。 如果需要执行一些其他操作（例如更新或删除记录），可以使用此方法获取匹配记录的 ID，然后使用 ID 值而不是备用键的值来引用记录。

  Note

  参数别名 （@param） 不适用于备用键语法。 在键谓词中使用参数别名时，即使对于不含特殊字符的值，也会返回 400 错误。 改用 $filter。

详细信息： 使用备用键检索记录

使用适用于 .NET 的 SDK 时，可以通过两种方式使用备用键。

使用 Entity 类

创建 Entity 类的实例时，使用以下 实体构造函数指定用于标识记录的键：

// For use with the primary key
public Entity (string logicalName, Guid id) {…} 
// For use with a single alternate key value
public Entity (string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public Entity (string logicalName, KeyAttributeCollection keyAttributes) {…}  

这些构造函数将值添加到 Entity.KeyAttributes 属性，而不是 Entity.Attributes 属性。 用于 KeyAttributes 标识记录。 Attributes 包含该记录的数据。

例如，当表具有包含两个备用键列的备用键时，可以这样定义实体。

KeyAttributeCollection keys = new KeyAttributeCollection() {
   { "example_key1", 5 },
   { "example_key2", 5 }
};

Entity thing = new Entity("example_thing", keys);
thing["example_name"] = "Test Name";

使用 EntityReference 类

创建 EntityReference 类的实例时，使用以下 EntityReference 构造函数 （与 Entity 类 构造函数相同的模式）指定用于标识记录的键。

// For use with the primary key
public EntityReference(string logicalName, Guid id) {…}
// For use with a single alternate key value
public EntityReference(string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public EntityReference(string logicalName, KeyAttributeCollection keyAttributeCollection) {…}    

• 使用 EntityReference 设置实体查找列的值。 使用它设置查找列时，键值会定位到主键值，并且主键值会存储在数据库中。
• 对于将此类型用作属性的消息，请使用 EntityReference，例如通过使用 DeleteRequest 类 的 Delete。

使用 .NET SDK 时采用备用密钥会引发的异常

使用备用键时，请注意以下条件和可能的异常：

• 如果提供 Entity.Id 属性，SDK 将使用该 属性 。 如果你未提供，SDK 将检查 KeyAttributeCollection。 如果未提供 KeyAttributeCollection，SDK 会抛出错误。
• 如果提供的 KeyAttributeCollection 一列是表的主键且值有效，则 SDK 将使用提供的值填充 Entity.Id 属性 或 EntityReference.Id 属性 。
• 如果你提供了键列，系统会尝试将你提供的这组列与为 Entity 定义的键进行匹配。 如果找不到匹配项，则会引发错误。 如果找到匹配项，它将验证为这些列提供的值。 如果有效，它将检索与提供的备用键值匹配的记录的主键值，并使用此值填充 Entity.Id 属性 或 EntityReference.Id 属性 。
• 如果指定未定义为唯一键的列，则 SDK 将引发一个错误，指示需要使用唯一键列。