使用 Web API 函数

函数是可以使用 Web API 执行的可重用操作。 Web API 包括两种类型的函数：

函数：对列出的GET函数使用Web API Function Reference请求来执行没有副作用的操作。这些函数通常检索数据（集合或复杂类型）。每个函数在组织服务中都有相应的消息。
查询函数：使用Web API Query Function Reference中列出的函数来评估查询中属性和值的组合。每个查询函数都有相应的 ConditionOperator 值。

将参数传递给函数

对于需要参数的函数，请使用参数别名传递值。

例如，使用 GetTimeZoneCodeByLocalizedName 函数时，必须包含 LocalizedStandardName 和 LocaleId 参数值。可以使用以下内联语法：

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

但是，几个问题可能会导致请求失败，除非使用参数别名发送这些请求：

如果超出400 Bad Request - Invalid URL，则会出现错误。
将 DateTimeOffset 值与内联语法结合使用时出现问题，如以下文章中所述： DateTimeOffset 为查询参数 #204。

通过使用参数别名传入值来避免这些问题，如以下代码示例所示：

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

多次使用参数值时，参数别名允许重复使用它以减少 URL 的长度。

将记录引用传递给函数

某些函数需要传递对现有记录的引用。例如，以下函数具有一个需要 crmbaseentity 实体类型的参数：

CalculateRollupField

IncrementKnowledgeArticleViewCount

InitializeFrom

IsValidStateTransition

RetrieveDuplicates

RetrieveLocLabels

RetrievePrincipalAccess

RetrieveRecordWall

ValidateRecurrenceRule

当您传递现有记录的引用时，请在该记录的 Uri 中添加 @odata.id 注释。例如，如果使用 RetrievePrincipalAccess 函数，可以使用以下 URI 来指定检索对特定联系人记录的访问权限：

GET /systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(aaaabbbb-0000-cccc-1111-dddd2222eeee)'}

注解 @odata.id 可以是完整的 URI 或相对 URI。

绑定和未绑定函数

您只能绑定在Web API Function Reference中找到的函数或您作为自定义 API 创建的函数。查询函数永远不会绑定。

绑定函数

在 CSDL $metadata 文档中，当元素Function表示绑定函数时，它具有一个值为true的IsBound属性。函数中定义的第一个 Parameter 元素表示函数绑定到的实体。当 Type 参数的属性是集合时，该函数将绑定到实体集合。

以下示例是 CSDL 中RetrieveUserPrivileges函数和RetrieveUserPrivilegesResponse复杂类型的定义。

<ComplexType Name="RetrieveUserPrivilegesResponse">
  <Property Name="RolePrivileges" Type="Collection(mscrm.RolePrivilege)" />
</ComplexType
<Function Name="RetrieveUserPrivileges" IsBound="true">
    <Parameter Name="entity" Type="mscrm.systemuser" Nullable="false" />
    <ReturnType Type="mscrm.RetrieveUserPrivilegesResponse" Nullable="false" />
</Function>

此绑定函数等效于 .NET RetrieveUserPrivilegesRequest 类的 SDK。在 Web API 中，此函数绑定到表示 SDK for .NET 的 RetrieveUserPrivilegesRequest.UserId 属性的 systemuser 实体类型。此函数返回的不是 SDK for .NET RetrieveUserPrivilegesResponse 类的实例，而是一个 RetrieveUserPrivilegesResponse 复合类型。当函数返回复杂类型时，其定义通常直接显示在 CSDL $metadata 文档中函数的定义之上。

若要调用绑定函数，请将函数的全名追加到 URL 中，并在函数名称之后的括号中包含任何命名参数。完整函数名称包括命名空间 Microsoft.Dynamics.CRM。未绑定的函数不得使用全名。

重要

使用 URI 调用绑定函数以设置第一个参数值。不能将其设置为命名参数值。

以下示例使用绑定到 systemuser 表的 RetrieveUserPrivileges 函数。

请求：

GET [Organization URI]/api/data/v9.2/systemusers(da455fec-68b7-ec11-9840-000d3a13d713)/Microsoft.Dynamics.CRM.RetrieveUserPrivileges
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": "[Organization URI]/api/data/v8.2/$metadata#Microsoft.Dynamics.CRM.RetrieveUserPrivilegesResponse",
  "RolePrivileges": [
    {
      "Depth": "Global",
      "PrivilegeId": "20db4bf7-60c4-4eb9-ab95-0949766fef1a",
      "BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
      "PrivilegeName": "prvCreateflowsession"
    },
    {
      "Depth": "Global",
      "PrivilegeId": "d8db8e4c-5b76-48eb-b5ec-171b8c661917",
      "BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
      "PrivilegeName": "prvWriteworkflowbinary"
    },
    ... <full list of privileges removed for brevity>
    {
      "Depth": "Global",
      "PrivilegeId": "b234db9f-27a2-4d12-8b51-fc34fbef9d87",
      "BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
      "PrivilegeName": "prvWriteflowsession"
    }
  ]
}

未绑定函数

该 WhoAmI 函数未绑定到实体。它在 CSDL $metadata 文档中定义，没有属性 IsBound 。

<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>

此函数对应于 .NET WhoAmIRequest 类的 SDK ，并返回与 WhoAmIResponse .NET WhoAmIResponse 类的 SDK 对应的复杂类型。此函数没有任何参数。

调用未绑定函数时，只需使用函数名称，如以下示例所示：

请求：

GET [Organization URI]/api/data/v9.2/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": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",  
 "BusinessUnitId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",  
 "UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",  
 "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"  
}

使用函数编写查询

可以通过两种方式使用函数来控制查询返回的数据。某些函数允许你控制它们返回的列或条件。还可以使用查询函数来评估查询中的条件。

可组合函数

在Web API Function Reference中列出的一些函数返回实体集合。这些函数的一个子集是可组合的，这意味着您可以包含$select或$filter系统查询选项，以控制结果中返回的列。这些函数在 CSDL 中有一个 IsComposable 属性。其中每个函数在 SDK 中都有一条配套消息，该消息接受 SDK for .NET ColumnSet 类或 SDK for .NET QueryBase 类类型参数。 OData 系统查询选项提供的功能相同，因此这些函数在 SDK for .NET 中没有与其配套消息相同的参数。下表显示了可组合函数的列表：

RetrieveAllChildUsersSystemUser

RetrieveBusinessHierarchyBusinessUnit

RetrieveUnpublishedMultiple

SearchByBodyKbArticle

SearchByKeywordsKbArticle

SearchByTitleKbArticle

查询函数

请使用Web API Query Function Reference 中列出的函数来组成查询。可以使用它们的方式类似于 OData 查询函数，但存在一些重要的差异。必须使用函数的完整名称，并包括参数的名称。

以下示例使用 LastXHours 查询函数返回过去 12 小时内修改的所有帐户实体：

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

查询函数的限制

查询函数的一个限制是无法使用 not 运算符来否定查询函数。

例如，使用以下查询EqualUserId时，运行失败并出现错误：Not operator along with the Custom Named Condition operators is not allowed。

GET /systemusers?$select=fullname,systemuserid&$filter=not Microsoft.Dynamics.CRM.EqualUserId(PropertyName=@p1)&@p1='systemuserid'

多个查询函数具有配套的否定查询函数。例如， NotEqualUserId 求反 EqualUserId，因此以下查询返回预期结果：

GET /systemusers?$select=fullname,systemuserid&$filter=Microsoft.Dynamics.CRM.NotEqualUserId(PropertyName=@p1)&@p1='systemuserid'

可以通过不同的方式否定其他查询函数。例如，不要像这样尝试否定 Last7Days 查询函数（这会因与之前提到的相同错误而失败）：

GET /accounts?$select=name&$filter=not Microsoft.Dynamics.CRM.Last7Days(PropertyName=@p1)&@p1='createdon'

使用如下所示的 OlderThanXDays 查询函数：

GET /accounts?$select=name&$filter=Microsoft.Dynamics.CRM.OlderThanXDays(PropertyName=@p1,PropertyValue=@p2)&@p1='createdon'&@p2=7

另见

Web API 函数和操作示例（C#）
Web API 函数和操作示例（客户端 JavaScript）
Web API 函数和操作示例（PowerShell）
使用 Web API 查询数据
 使用 Web API 操作

反馈

此页面是否有帮助？

Last updated on 2026-04-06