使用 Web API 功能

项目
10/31/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

函数和操作表示您可使用 Web API 执行的可重用操作。下面是 Web API 中的两种类型的函数：

Functions
将 GET 请求与 Web API Function Reference中列出的函数结合使用以执行无副作用的操作。这些函数通常会检索数据。它们会返回集合或复杂的类型。这些函数在组织服务中各有一个对应的消息。
查询函数
使用 Web API Query Function Reference 中列出的函数来评估查询组合中的属性和值。这些函数各有一个对应的 ConditionOperator 值。

在本主题中

将参数传递给函数

将引用传递至函数的实体

绑定和未绑定函数

使用函数组成查询

将参数传递给函数

对于需要参数的函数，最佳做法是传递使用参数的值。例如，当您使用 GetTimeZoneCodeByLocalizedName Function 时，必须包含 LocalizedStandardName 和 LocaleId 参数值。因此，您可以使用以下内联语法，如此处所示。

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

但是，当将 DateTimeOffset 值与内联语法一起使用时还有一个开放问题，如以下文章中所述：DateTimeOffset 作为查询参数 #204。

因此，最佳做法是将值作为参数传递，如以下代码示例中所示。如果您使用此最佳做法，则可以避免适用于 DateTimeOffset 的开放问题。

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

当多次使用某些参数值时，参数别名还允许您重用这些参数值来缩短 URL 的总长度。

将引用传递至函数的实体

某些函数需要将引用传递到现有实体。例如，以下函数具有需要 crmbaseentity EntityType 的参数：

CalculateRollupField Function	IncrementKnowledgeArticleViewCount Function	InitializeFrom Function
IsValidStateTransition Function	RetrieveDuplicates Function	RetrieveLocLabels Function
RetrievePrincipalAccess Function	RetrieveRecordWall Function	ValidateRecurrenceRule Function

将引用传递至现有实体时，对该实体的 Uri 使用 @odata.id 批注。例如，如果您使用 RetrievePrincipalAccess Function，可通过下列 Uri 指定检索对特定联系人的访问：

GET cc_WebAPI_ServiceURI/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'}

@odata.id 批注可以是完整 Uri，也可以是相对 Uri。

绑定和未绑定函数

只能绑定在 Web API Function Reference中找到的函数。查询函数无法绑定。

绑定函数

在 d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl中，当 Function 元素代表绑定函数时，该元素具有包含值 true 的 IsBound 属性。该函数中定义的第一个 Parameter 元素代表该函数绑定到的实体。当参数的 Type 属性为集合时，该函数将绑定到实体集合。举例来说，下面是 CSDL 中的 CalculateTotalTimeIncident Function和 CalculateTotalTimeIncidentResponse ComplexType 的定义。

<ComplexType Name="CalculateTotalTimeIncidentResponse">
  <Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
  <Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
  <ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>

此绑定函数等效于组织服务使用的 CalculateTotalTimeIncidentRequest。在 Web API 中，此函数将绑定到代表 CalculateTotalTimeIncidentRequest.IncidentId 属性的 incident EntityType。此函数不会返回 CalculateTotalTimeIncidentResponse，而会返回 CalculateTotalTimeIncidentResponse ComplexType。当某个函数返回复杂类型时，该函数的定义将直接显示在 CSDL 中的函数的定义的上方。

要调用绑定函数，请将该函数的完整名称追加到 URL，并将任何已命名的参数用括号括起并后跟函数名。完整名称包括命名空间 Microsoft.Dynamics.CRM。未绑定的函数不能使用完整名称。

重要

必须使用 URI 调用绑定函数以设置第一个参数值。您无法将其设置为已命名的参数值。

以下示例显示使用 CalculateTotalTimeIncident Function（绑定到事件实体）的示例。

请求

GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse","TotalTime":30
}

未绑定函数

WhoAmI Function未绑定到实体。它是在不带 IsBound 属性的 CSDL 中定义的。

<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>
<Function Name="WhoAmI">
  <ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />
</Function>

此函数与 WhoAmIRequest 对应并返回与组织服务使用的 WhoAmIResponse 对应的 WhoAmIResponse ComplexType。此函数不包含任何参数。

当调用未绑定函数时，应仅使用函数名称，如以下示例所示。

请求

GET cc_WebAPI_ServiceURI/WhoAmI() HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
 "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1",
 "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1",
 "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1"
}

使用函数组成查询

有两种可用于控制利用查询返回的数据的方法。某些函数允许控制其返回的列或条件，您可使用查询函数来评估查询中的条件。

可组合的函数

Web API Function Reference 中列出的某些函数返回实体集合。这些函数中有一些是可组合的，这意味着您可以包含其他 $select 或 $filter 系统查询选项来控制结果中返回的列。这些函数具有 CSDL 中的 IsComposable 属性。这些函数在组织服务中各有一个接受 ColumnSet 或 QueryBase 类型参数的伴随消息。OData 系统查询选项提供了相同的功能，因此这些函数在组织服务中和它们的伴随消息中具有不同的参数。下表显示了本版本中的这些可组合的函数的列表。

GetDefaultPriceLevel Function	RetrieveAllChildUsersSystemUser Function	RetrieveBusinessHierarchyBusinessUnit Function
RetrieveByGroupResource Function	RetrieveByResourceResourceGroup Function	RetrieveMembersBulkOperation Function
RetrieveParentGroupsResourceGroup Function	RetrieveSubGroupsResourceGroup Function	RetrieveUnpublishedMultiple Function
SearchByBodyKbArticle Function	SearchByKeywordsKbArticle Function	SearchByTitleKbArticle Function

查询函数

Web API Query Function Reference 中列出的函数用于组成查询。可以通过与标准查询函数类似的方式使用这些函数，但存在一些重大差别。

您必须使用函数的完整名称并包含参数的名称。以下示例演示如何使用 LastXHours Function 返回在过去 12 个小时内修改的所有客户实体。

GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

另请参阅

Web API 函数和操作示例 (C#)
Web API 函数和操作示例（客户端 JavaScript）
使用 Web API 执行操作
 撰写 HTTP 请求并处理错误
 使用 Web API 查询数据
 使用 Web API 创建实体
 使用 Web API 检索实体
 使用 Web API 更新和删除实体
 使用 Web API 关联和解除关联实体
 使用 Web API 操作
 使用 Web API 执行批处理操作
 使用 Web API 模拟其他用户
 使用 Web API 执行条件操作

Microsoft Dynamics 365

使用 Web API 功能

在本主题中

将参数传递给函数

将引用传递至函数的实体

绑定和未绑定函数

绑定函数

未绑定函数

使用函数组成查询

可组合的函数

查询函数

另请参阅

其他资源