Web API 导航属性

在 CSDL $metadata文档中，不抽象的每个实体类型都有 NavigationProperty 元素。 NavigationProperty 元素描述与当前实体类型相关的数据。检索记录时，可以展开导航属性以包含相关数据。

下表描述了元素的属性 NavigationProperty 。

Attribute	Description
`Name`	导航属性的名称;区分大小写
`Type`	相关的实体类型;可以是单个值或类型的集合
`Partner`	关系另一端的导航属性的名称
`Nullable="false"`	值是否可以为 null

重要

有两种类型的导航属性：单值和 集合值。这一区别很重要，因为每种导航属性的功能都不同。

使用 OData 构造查询时，我们不引用一对多、多对一或多对多关系。这两种类型的导航属性描述如何导航这些关系。

当导航属性 Type 引用单个值时，它表示一对多关系，该关系创建对另一个表记录的引用。此关系通常称为查找。以下示例是 account 表 createdby 导航属性：

<NavigationProperty 
    Name="createdby" 
    Type="mscrm.systemuser" 
    Nullable="false" 
    Partner="lk_accountbase_createdby">
    <ReferentialConstraint 
        Property="_createdby_value" 
        ReferencedProperty="systemuserid" />
</NavigationProperty>

此单值导航属性将多个 account 记录连接到单个 systemuser 记录。每个 systemuser 记录都有一个名为 lk_accountbase_createdby 的集合值导航属性，将其与用户创建的 account 记录连接起来。

这些值存储在关系定义中。可以使用 SDK OneToManyRelationshipMetadata 或 Web API OneToManyRelationshipMetadata 实体类型访问它们，如下表所述。

Attribute	OneToManyRelationshipMetadata 属性	Description
`Name`	`ReferencingEntityNavigationPropertyName`	单值导航属性的名称。
`Partner`	`ReferencedEntityNavigationPropertyName`	集合值导航属性的名称。

查找属性

单值导航属性具有一个带有 Property 属性的 ReferentialConstraint，该属性引用查找属性。查找属性使用以下命名约定： _<name>_value 了解有关查找属性的详细信息。

该 ReferentialConstraint 属性标识相关实体类型的ReferencedProperty主键名称。

在大多数情况下，在查找属性中找到的<name>与导航属性的名称完全匹配，除非单值导航属性表示多表查找。

多表查找

当单值导航属性是多表或多态查找的一部分时，单个查找属性是多个单值导航属性的 ReferentialConstraint。

实体类型可能具有以下组合，其中单个 _customerid_value 查找属性支持表示多表查找的多个单值导航属性。多表查找支持的每种类型的表都有一个单值导航属性。

<EntityType 
    Name="socialprofile" 
    BaseType="mscrm.crmbaseentity">
    <Key>
        <PropertyRef Name="socialprofileid" />
    </Key>
    <Property 
        Name="_customerid_value" <!-- lookup property -->
        Type="Edm.Guid">
        <Annotation 
            Term="Org.OData.Core.V1.Description" 
            String="Shows the customer that this social profile belongs to." />
    </Property>
    <NavigationProperty 
        Name="customerid_contact" <!-- Name different from lookup property -->
        Type="mscrm.contact" 
        Nullable="false" 
        Partner="Socialprofile_customer_contacts">
        <ReferentialConstraint 
            Property="_customerid_value" <!--  Reference to lookup property  -->
            ReferencedProperty="contactid" />
    </NavigationProperty>
    <NavigationProperty 
        Name="customerid_account" <!-- Name different from lookup property -->
        Type="mscrm.account" 
        Nullable="false" 
        Partner="Socialprofile_customer_accounts">
        <ReferentialConstraint 
            Property="_customerid_value"  <!--  Reference to lookup property  -->
            ReferencedProperty="accountid" />
    </NavigationProperty>
</EntityType>

在这些情况下，将任一单值导航属性的值设定后，所有其他相关的单值导航属性值都将被设置为 null。相应的查找属性 GUID 值会更改，但你需要检索特定的批注，以了解它现在引用的表。详细信息：查找属性数据

当导航属性 Type 引用集合值时，它表示多对一或多对多关系。以下示例是帐户实体 Account_Tasks 导航属性：

<NavigationProperty 
    Name="Account_Tasks" 
    Type="Collection(mscrm.task)" 
    Partner="regardingobjectid_account_task" 
/>

此导航属性将记录 account 连接到许多 task 记录。每个 task 都有一个名为 regardingobjectid_account_task 的单值导航属性，用于指向 account 作为相关对象。

使用 OData 处理集合值导航属性的方式是相同的，无论关系是一对多还是多对多。这两个集合都被视为集合，你与它们交互的方式相同。

多对一关系

多对一关系是“一对多”关系的镜像。它具有合作伙伴单值导航属性。在前面的单值导航属性示例中，我们查看了account实体类型的createdby单值导航属性。

在 systemuser 实体类型中，名为 lk_accountbase_createdby 的集合值导航属性合作伙伴存在。

<NavigationProperty Name="lk_accountbase_createdby"
    Type="Collection(mscrm.account)"
    Partner="createdby" />

多对多关系

当集合型导航属性的Name与Partner相同时，它表示多对多关系。

多对多关系的某些实现详细信息可以在服务文档中找到。对于大多数用例，可以忽略它们。

例如，每个多对多关系都有一个支持它的相交表。这些相交表中的实体类型通常具有四个只读属性。在以下示例中，teammembership实体类型是一个交叉表，支持systemuser和team实体类型之间的多对多关系：

<EntityType Name="teammembership"
    BaseType="mscrm.crmbaseentity">
    <Key>
        <PropertyRef Name="teammembershipid" />
    </Key>
    <Property Name="systemuserid"
        Type="Edm.Guid" />
    <Property Name="versionnumber"
        Type="Edm.Int64" />
    <Property Name="teammembershipid"
        Type="Edm.Guid" />
    <Property Name="teamid"
        Type="Edm.Guid" />
</EntityType>

不能直接处理表示相交表的实体类型，因为所有属性都是只读的。针对每个实体类型的集合值导航属性执行操作。详细信息：使用 Web API 关联和取消关联表行

对于此多对多关系， systemuser 实体类型具有以下集合值导航属性：

<NavigationProperty Name="teammembership_association"
    Type="Collection(mscrm.team)"
    Partner="teammembership_association" />

实体 team 类型具有此集合值导航属性：

<NavigationProperty Name="teammembership_association"
    Type="Collection(mscrm.systemuser)"
    Partner="teammembership_association" />

这些值存储在关系定义中。可以使用 SDK ManyToManyRelationshipMetadata 或 Web API ManyToManyRelationshipMetadata 实体类型访问它们，如下表所述。

Attribute	ManyToManyRelationshipMetadata 属性	Description
`Name`	`Entity1NavigationPropertyName`	某一实体类型的集合值导航属性的名称
`Partner`	`Entity2NavigationPropertyName`	其他实体类型的集合值导航属性的名称

后续步骤

了解有关操作定义。

动作定义

另请参阅

Web API 类型和操作
 Web API 服务文档
 Web API EntityTypes
Web API 属性
 Web API动作
 Web API 函数
 Web API 复杂和枚举类型
 使用 Dataverse Web API
OData 版本 4.0。第 3 部分：通用架构定义语言 (CSDL) 加上 Errata 03 7.1 元素 edm:NavigationProperty

反馈

此页面是否有帮助？

Last updated on 2026-01-08