Web API 类型和操作
发布日期： 2017年1月
适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online
若要使用 Web API，您必须查找您可使用的信息。 服务通过您可以访问的服务和元数据文档描述自己。 本主题将介绍重要概念，描述您如何使用从服务和元数据文档生成的文档查找信息，以及系统实体类型、函数和操作文档。
本主题内容
术语
服务文档
实体类型
属性
导航属性
操作
Functions
复杂类型
枚举类型
术语
Web API 通过使用一组您必须熟悉的特定术语的 OData v4 标准进行实施。实体数据模型 (EDM) 是用来描述由 OData 服务公开的数据的抽象数据模型。 下表列出了在 OData 版本 4.0 第 1 部分：协议和勘误表 02 中定义的部分术语，您应当对此有所了解。
术语 |
定义 |
|---|---|
实体类型 |
使用密钥命名的结构类型。 它们定义实体的已命名属性和关系。 实体类型可能通过单次继承其他实体类型而衍生。 |
实体 |
实体类型实例（例如 account、opportunity）。 |
实体集 |
已命名的实体集合（例如 accounts 是包含 account 实体的实体集）。 实体密钥唯一标识实体集中的实体 |
复杂类型 |
包含一组属性的无密钥已命名结构类型。 复杂类型通常作为模型实体中的属性值，或者作为操作的参数或返回值。 |
枚举类型或枚举类型 |
使用基础整数值将值命名为常数的已命名原始类型。 |
Functions |
没有副作用且可能支持进一步组合的操作，例如，使用其他筛选器操作、函数或操作 |
操作 |
允许副作用，例如数据修改，并且为了避免非判定性行为而无法进一步组合的操作 |
服务文档
您可以参考两个服务文档了解有关 Web API 的更多信息。
服务文档
键入到您的浏览器的地址字段以下查询返回服务文档，完整列出对您的组织可用的所有实体集。 请注意，[组织 URI] 表示您的组织的 URL。
[组织 URI]/api/data/v8.2
实体集以 JSON 数组的形式返回。 数组中的每一个项目均具有此表中列出的三个属性。
属性 |
说明 |
|---|---|
name |
这是实体集的名称。 此数据来自实体的EntityMetadata EntityTypeEntitySetName属性。 |
kind |
对于 Web API，仅列出了实体集。 |
url |
该值与name属性相同，表示检索实体数据的资源路径的一部分。 |
该信息可以通过 GET 请求进行检索，可用于获取使用该服务可用的所有实体集的列表。
CSDL 元数据文档
对以下 URL 发送 GET 请求将返回一个非常大的（超过 3.5 MB）的公共架构定义语言 (CSDL) 文档，或者描述该服务公开的数据和操作的元数据文档。
[组织 URI]/api/data/v8.2/$metadata
该文档可用作数据源，生成将为该服务提供强类型对象的类。 但如果您不使用生成的类，您可能需要查看此信息生成的文档。Web API Reference主要使用从非自定义系统获取的此文档的信息。
您可以在 OData 版本 4.0 第 3 部分：公共架构定义语言 (CSDL) 和勘误表 02 中了解有关此文档的更多信息。
提示
在您阅读本主题的其余内容前，请下载您组织的 CSDL，查看所述类型、函数和操作如何包含在 CSDL 和支持文档中。
实体类型
Web API EntityType Reference列出了通过 Web API 公开的存储业务数据的每一个系统实体类型。 实体类型是使用密钥的已命名结构类型。 它定义了实体的已命名属性和关系。 实体类型可能通过单次继承其他实体类型而衍生。Web API Metadata EntityType Reference列出了用于管理系统元数据的每一个实体类型。 两个都是实体类型，但您使用它们的方式不同。 请查阅使用具有 Dynamics 365 元数据的 Web API了解有关使用模型实体的信息。 每个实体类型都包含在 CSDL 中的EntityType元素中。 下面是来自 CSDL 的移除了属性和导航属性的account EntityType。
<EntityType Name="account" BaseType="mscrm.crmbaseentity">
<Key>
<PropertyRef Name="accountid" />
</Key>
<!--Properties and navigation properties removed for brevity-->
<Annotation Term="Org.OData.Core.V1.Description" String="Business that represents a customer or potential customer. The company that is billed in business transactions." />
</EntityType>
SDK 文档中的每一个EntityType参考页面均使用来自 CSDL 或元数据的信息显示下列可用信息。
Information |
说明 |
|---|---|
说明 |
实体说明。 EntityMetadata EntityTypeDescription属性信息包含在使用Annotation元素和Org.OData.Core.V1.Description的Term属性值的EntityType元素中。 |
集合 URL |
访问每个类型的集合的 URL。 EntityMetadata EntityTypeEntitySetName属性信息使用 CSDL EntityContainer元素包含在其中。 每个EntitySet元素的Name属性控制通过 URL 访问数据的方式。 |
基本类型 |
实体类型继承自该实体类型。 EntityType元素的BaseType属性包含实体类型的名称。 此名称的前缀是 Microsoft.Dynamics.CRM 命名空间：mscrm 的别称。详细信息：类型继承 |
显示名称 |
此信息不包含在 CSDL 中，而是从EntityMetadata EntityTypeDisplayName中检索。 |
主键 |
包含唯一标识符的属性值，用于引用实体实例。 EntityMetadata EntityTypePrimaryIdAttribute属性信息包含在EntityTypeKey元素中。 每个实体只能有一个主键。 备用键未在此处列出。详细信息：备用键 |
主属性 |
许多实体要求设置主属性值，因此为了方便而包含在其中。 此信息不包含在 CSDL 中，而是从元数据EntityMetadata EntityTypePrimaryNameAttribute属性中检索。 |
属性 |
请参阅“属性”。 |
单一值导航属性 |
请参阅“单一值导航属性”。 |
集合值导航属性 |
请参阅“集合值导航属性”。 |
与实体类型绑定的操作 |
操作与具体的实体类型绑定时，为了方便而列出。 |
使用实体类型的操作 |
该列表显示了可能使用实体类型执行的所有操作。 这衍生自在参数中或作为返回值引用当前类型的所有操作的引用的集合。 |
继承自实体类型的实体类型 |
此列表包含从实体类型直接继承的实体类型。 有关更多信息，请参阅 类型继承。 |
更改实体集的名称
默认情况下，实体集名称匹配EntityMetadata EntityTypeLogicalCollectionName（EntityMetadataLogicalCollectionName）属性值。 如果您有想使用不同的实体集名称进行处理的自定义实体，您可以更新EntityMetadata EntityTypeEntitySetName (EntityMetadata.EntitySetName) 属性值以使用不同名称。
备用键
尽管 Microsoft Dynamics 365 允许创建备用键，但 Microsoft Dynamics 365 SDK 文档中只能找到主键。
系统实体都没有定义备用键。 如果您定义实体的备用键，这些备用键将作为Annotation包含在 CSDL EntityType元素中，例如：
<Annotation Term="OData.Community.Keys.V1.AlternateKeys">
<Collection>
<Record Type="OData.Community.Keys.V1.AlternateKey">
<PropertyValue Property="Key">
<Collection>
<Record Type="OData.Community.Keys.V1.PropertyRef">
<PropertyValue Property="Alias" String="key name" />
<PropertyValue Property="Name" PropertyPath="key name" />
</Record>
</Collection>
</PropertyValue>
</Record>
</Collection>
</Annotation>
有关备用键的信息还能通过使用 Web API 的EntityMetadata EntityTypeKeys集合值导航属性或者通过使用组织服务的 EntityMetadata.Keys 属性从元数据中检索。
类型继承
继承允许共享公用属性和对实体类型分组。 Web API 中的所有实体类型均继承自以下两种实体类型。 所有业务实体类型均继承自 crmbaseentity EntityType，所有模型实体均继承自 crmmodelbaseentity EntityType。
基本实体 |
说明 |
|---|---|
所有业务实体均继承自该实体。 它不具有属性。 它只用作抽象的基本实体。 |
|
所有活动实体继承自该实体。 它为活动实体定义一组公用属性和导航属性。 |
|
systemuser EntityType和team EntityType从该实体继承一个公用ownerid属性。 |
|
仅MetadataBase EntityType从该实体直接继承。 它不具有属性。 它只用作抽象的基本实体。 |
|
所有模型实体继承自该实体。 它为所有模型实体提供MetadataId和HasChanged属性。 |
|
表示不同属性类型的所有模型实体均继承自该实体。 |
|
表示包含一组选项的属性的模型实体继承自该实体。 |
|
该模型实体类型提供BooleanOptionSetMetadata EntityType和继承自该实体的OptionSetMetadata EntityType模型实体类型使用的一组公用属性。 |
|
该实体类型提供ManyToManyRelationshipMetadata EntityType和继承自该实体的OneToManyRelationshipMetadata EntityType模型实体类型使用的一组公用属性。 |
属性
每个实体类型都可以声明与属性相对应的属性。 在 Web API EntityType Reference和Web API Metadata EntityType Reference 内容中，从基本实体类型继承的属性合并列在为每个实体类型声明的属性列表中。 继承在每个属性的说明中调用。
在 CSDL EntityType元素中，每个属性均包含在Property元素中，具有与您在代码中设置的属性相对应的Name属性。Type属性值指定了属性的数据类型。 业务实体类型的属性通常使用 OData 原始类型。
以下是 CSDL 中定义的account EntityTypename属性的示例。
<Property Name="name" Type="Edm.String" Unicode="false">
<Annotation Term="Org.OData.Core.V1.Description" String="Type the company or business name." />
</Property>
属性说明在 Org.OData.Core.V1.Description 使用Term属性的Annotation元素中可用。 此说明从AttributeMetadata EntityTypeDescription属性值中获取。 并不是所有的属性都有一项说明。
每个属性可以进行计算。 这意味着值可以由系统设置。 这在 Org.OData.Core.V1.Computed 使用Term属性值的Annotation元素中指定。
每个属性也可能限制是否可以更新。 这在 Org.OData.Core.V1.Permissions 使用Term属性值的Annotation元素中定义。 为其设置的唯一选项是 Org.OData.Core.V1.PermissionType/Read，表示其属性为只读。
原始类型
OData 支持各种数据类型，但 Microsoft Dynamics 365 并不全部使用。 下表介绍了 Dynamics 365 组织服务类型如何映射到 OData 原始类型。
组织服务类型 |
Web API 类型 |
说明 |
|---|---|---|
BigInt |
Edm.Int64 |
64 位带符号整数 |
Boolean |
Edm.Boolean |
二进制值逻辑 |
CalendarRules |
单一值导航属性 |
calendarrule EntityType的具体单一值导航属性。 |
客户 |
单一值导航属性 |
具有该属性类型的实体的客户可能是使用相应的单一值导航属性设置为account或contact实体类型的单一值导航属性。 设置其中一种相应的单一值集合属性时，另外一种被清除。 |
DateTime |
Edm.DateTimeOffset |
具有时区偏移的日期和时间，无闰秒 |
十进制 |
Edm.Decimal |
具有固定精度和比例的数值 |
Double |
Edm.Double |
IEEE 754 binary64 浮点数（15-17 十进制数） |
EntityName |
Edm.String |
UTF-8 字符序列 |
图像 |
Edm.Binary |
二进制数据 |
整数 |
Edm.Int32 |
32 位带符号整数 |
查找 |
单一值导航属性 |
对特定实体的引用 |
托管属性 |
不适用 |
仅供内部使用。 |
Memo |
Edm.String |
UTF-8 字符序列 |
Money |
Edm.Decimal |
具有固定精度和比例的数值 |
负责人 |
单一值导航属性 |
对principal EntityType的引用。systemuser和team实体类型均从prinicipal实体类型继承其ownerid属性。 |
PartyList |
activityparty实体类型的集合值导航属性。 |
activitypartyparticipationtypemask属性包含表示参与者角色的值。 有关更多信息，请参阅 活动方类型。 |
Picklist |
Edm.Int32 |
32 位带符号整数 |
状态 |
Edm.Int32 |
32 位带符号整数 |
状态 |
Edm.Int32 |
32 位带符号整数 |
字符串 |
Edm.String |
UTF-8 字符序列 |
Uniqueidentifier |
Edm.Guid |
16 位（128 位）唯一标识符 |
查找属性
对于大部分单一值导航属性，您将找到使用下列命名约定的计算而得的只读属性：_<name>_value，其中 <name> 匹配单一值导航属性的名称。 此模式的例外情形是当实体的查找属性可以接受多种类型的实体引用时。 一个常见示例是incident实体customerid属性可以如何设置为是contact或account实体的引用。 在incident EntityTypeSingle-valued navigation properties中，您将找到customerid_account和customerid_contact作为单独的单一值导航属性以反映与商机关联的客户。 如果您设置了其中一个单一值导航属性，另外一个将被设置为 null，因此它们都与customerid属性绑定。 在incident EntityTypeProperties中，您将找到**_customerid_value**查找属性，其中包含的值与为包含值的单一值导航属性设置的值相同。
通常，您应避免使用查找属性，而是使用相应的单一值导航属性。 这些属性包含在其中是因为他们可能对某些集成方案有用。 这些属性只读并且通过计算而得，因为他们将只是反映使用相应的单一值导航属性应用的更改。
如果您在查询中包含查找属性，您可以请求包含注释，提供为那些单一值导航属性无法表示的基本属性设置的数据的其他相关信息。详细信息：检索有关查找属性的数据
导航属性
在 OData 中，导航属性允许您访问与当前实体相关的数据。 检索实体时，您可以选择扩展导航属性，以包含相关数据。 导航属性有两种：单一值和集合值。
单一值导航属性
这些属性对应于查找属性，支持多对一关系，并允许设置对其他实体的引用。 在 CSDL EntityType元素中，这些被定义为在Type属性设置为单一类别的NavigationProperty元素。 以下是 CSDL 中的account EntityTypecreatedby单一值导航属性的示例：
<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby">
<ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" />
</NavigationProperty>
每一个表示单一值导航属性的导航属性将有一个对应的集合值导航属性，通过Partner属性值表示。 每一个单一值导航属性还有一个ReferentialConstraint元素，具有Property属性值，表示计算而得只读查找属性，可以用于检索相关实体相应的 GUID 值。详细信息：查找属性
集合值导航属性
这些属性对应于一对多或多对多关系。 在 CSDL EntityType元素中，这些被定义为在Type属性设置为类型集合的NavigationProperty元素。 以下表示代表一对多关系的account EntityTypeAccount_Tasks集合值导航属性：
<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />
当集合值导航属性表示多对多关系时，导航属性的名称将和合作伙伴的名称相同。 以下表示代表多对多关系的account EntityTypeaccountleads_association集合值导航属性：
<NavigationProperty Name="accountleads_association" Type="Collection(mscrm.lead)" Partner="accountleads_association" />
在使用 Web API 时，一对多关系和多对多关系之间的差异并不重要。 无论是何种关系类型，您关联实体的方法都是一样的。 尽管多对多关系仍然使用后台的相交实体，但仅有一些特殊的系统相交实体包含在 Web API EntityType Reference中。 例如，从技术上说，campaignactivityitem EntityType是一个相交实体，但也包含在其中，因为它具有比普通相交实体更多的属性。
普通相交实体仅具有为了维护多对多关系所必需的四个基本属性。 在您在实体间创建自定义多对多关系时，将创建普通相交实体，以支持该关系。 因为您要使用导航属性执行涉及多对多关系的操作，因此普通相交实体虽然没有记录，但仍然通过 Web API 可用。 这些相交实体类型可以通过使用以下命名约定的实体集名称进行访问：<相交实体的逻辑名称> + ‘集合’。 例如，您可以使用 [组织 URI]/api/data/v8.2/contactleadscollection 从contactleads相交实体检索信息。 只有在您想要应用修改跟踪时，才应使用这些普通相交实体。
操作
操作是允许副作用，例如数据修改，并且为了避免非判定性行为而无法进一步组合的操作。
Web API Action Reference主题列出了每一个可用的系统操作。详细信息：使用 Web API 操作。
Functions
函数是没有副作用且可能支持进一步组合的操作，例如，使用其他筛选器操作、函数或操作
Web API 中定义了两种类型的函数：
Web API Function Reference列出了每一个可用的系统函数。
Web API Query Function Reference主题列出了可用作查询条件的函数。
详细信息：使用 Web API 功能
复杂类型
复杂类型是包含一组属性的无密钥已命名结构类型。 复杂类型通常作为模型实体中的属性值，或者作为操作的参数或返回值。
Web API ComplexType Reference列出了系统的所有复杂类型。复杂类型是包含一组属性的无密钥已命名结构类型。 它们通常作为模型实体中的属性值，或者作为操作的参数或返回值。 以下是来自 CSDL 的WhoAmIResponse ComplexType。
<ComplexType Name="WhoAmIResponse">
<Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
<Property Name="UserId" Type="Edm.Guid" Nullable="false" />
<Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
枚举类型
枚举类型或枚举类型是使用基础整数值将值命名为常数的已命名原始类型。
Web API EnumType Reference列出了系统的所有枚举类型。枚举类型是使用基础整数值将值命名为常数的已命名原始类型。 以下是来自 CSDL 的AccessRights EnumType。
<EnumType Name="AccessRights">
<Member Name="None" Value="0" />
<Member Name="ReadAccess" Value="1" />
<Member Name="WriteAccess" Value="2" />
<Member Name="AppendAccess" Value="4" />
<Member Name="AppendToAccess" Value="16" />
<Member Name="CreateAccess" Value="32" />
<Member Name="DeleteAccess" Value="65536" />
<Member Name="ShareAccess" Value="262144" />
<Member Name="AssignAccess" Value="524288" />
</EnumType>
另请参阅
使用 Microsoft Dynamics 365 Web API
使用 Web API 对 Microsoft Dynamics 365 进行身份验证
使用 Web API 执行操作
Microsoft Dynamics 365
© 2017 Microsoft。 保留所有权利。 版权