Use Web API functions

Άρθρο
08/08/2023

Functions are reusable operations that you can perform using the Web API. There are two types of functions in the Web API:

Functions: Use a GET request with the functions listed in the Web API Function Reference to perform operations that have no side-effects. These functions generally retrieve data, either a collection or a complex type. Each function has a corresponding message in the organization service.
Query functions: Use the functions listed in the Web API Query Function Reference to evaluate properties and values in the composition of a query. Each query function has a corresponding ConditionOperator value.

Passing parameters to a function

For those functions that require parameters, the best practice is to pass the values using parameters.

For example, when you use the GetTimeZoneCodeByLocalizedName function, you must include the LocalizedStandardName and LocaleId parameter values. You could use the following inline syntax:

GET [Organization URI]/api/data/v9.0/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

However, there's an issue using DateTimeOffset values with the inline syntax, as explained in the following article: DateTimeOffset as query parameter #204.

Avoid the DateTimeOffset issue by passing the values in as parameters, as shown in the following code sample:

GET [Organization URI]/api/data/v9.0/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

When a parameter value is used multiple times, parameter aliases allow you to reuse it to reduce the length of the URL.

Pass record reference to a function

Certain functions require passing a reference to an existing record. For example, the following functions have a parameter that requires a crmbaseentity entity type:

Functions
CalculateRollupField	IncrementKnowledgeArticleViewCount	InitializeFrom
IsValidStateTransition	RetrieveDuplicates	RetrieveLocLabels
RetrievePrincipalAccess	RetrieveRecordWall	ValidateRecurrenceRule

When you pass a reference to an existing record, use the @odata.id annotation to the Uri for the record. For example if you're using the RetrievePrincipalAccess function you can use the following Uri to specify retrieving access to a specific contact record:

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

The @odata.id annotation can be either the full URI or a relative URI.

Bound and unbound functions

Only functions found in Web API Function Reference, or created as a custom API may be bound. Query functions are never bound.

Bound functions

In the CSDL $metadata document, when a Function element represents a bound function, it has an IsBound attribute with the value true. The first Parameter element defined in the function represents the entity that the function is bound to. When the Type attribute of the parameter is a collection, the function is bound to an entity collection.

The following example is the definition of the RetrieveUserPrivileges function and RetrieveUserPrivilegesResponse complex type in the CSDL.

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

This bound function is equivalent to the RetrieveUserPrivilegesRequest class used by the SDK for .NET. In the Web API this function is bound to the systemuser entity type that represents the RetrieveUserPrivilegesRequest.UserId property property. Instead of returning an instance of the RetrieveUserPrivilegesResponse class, this function returns a RetrieveUserPrivilegesResponse complex type. When a function returns a complex type, its definition usually appears directly above the definition of the function in the CSDL.

To invoke a bound function, append the full name of the function to the URL and include any named parameters in parentheses following the function name. The full function name includes the namespace Microsoft.Dynamics.CRM. Functions that aren't bound must not use the full name.

Important

Invoke a bound function using a URI to set the first parameter value. You can't set it as a named parameter value.

The following example uses the RetrieveUserPrivileges function, which is bound to the systemuser table.

Request:

GET [Organization URI]/api/data/v9.2/systemusers(da455fec-68b7-ec11-9840-000d3a13d713)/Microsoft.Dynamics.CRM.RetrieveUserPrivileges HTTP/1.1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Response:

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"
    }
  ]
}

Unbound functions

The WhoAmI function isn't bound to an entity. It's defined in the CSDL without an IsBound attribute.

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

This function corresponds to the WhoAmIRequest class and returns a WhoAmIResponse complex type that corresponds to the WhoAmIResponse class used by the SDK for .NET. This function doesn't have any parameters.

When you invoke an unbound function, use just the function name, as shown in the following example:

Request:

GET [Organization URI]/api/data/v9.0/WhoAmI() HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Response:

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

Compose a query with functions

There are two ways that functions can be used to control the data returned with queries. Certain functions allow for control over the columns or conditions that they return, and you can use query functions to evaluate conditions in a query.

Composable functions

Some functions listed in Web API Function Reference return a collection of entities. A subset of these functions are composable, which means that you can include a $select or $filter system query option to control which columns are returned in the results. These functions have an IsComposable attribute in the CSDL. Each of these functions has a companion message in the SDK that accept either a ColumnSet or QueryBase type parameter. The OData system query options provide the same functionality so these functions don't have the same parameters as their companion messages in the SDK. The following table shows a list of those composable functions in this release.

Functions
RetrieveAllChildUsersSystemUser	RetrieveBusinessHierarchyBusinessUnit	RetrieveUnpublishedMultiple
SearchByBodyKbArticle	SearchByKeywordsKbArticle	SearchByTitleKbArticle

Query functions

Functions listed in the Web API Query Function Reference are intended to be used to compose a query. You can use them in a manner similar to the OData query functions, but there are some important differences. You must use the full name of the function and include the names of the parameters.

The following example uses the LastXHours query function to return all account entities modified in the past 12 hours:

GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

Limitations of query functions

One of the limitations of query functions is that you can't use the not operator to negate query functions.

For example, the following query, which uses EqualUserId, fails with the error: Not operator along with the Custom Named Condition operators is not allowed.

GET [Organization URI]/api/data/v9.1/systemusers?$select=fullname,systemuserid&$filter=not Microsoft.Dynamics.CRM.EqualUserId(PropertyName=@p1)&@p1='systemuserid'

Several query functions have a companion negated query function. For example, NotEqualUserId negates EqualUserId, so the following query returns the expected results:

GET [Organization URI]/api/data/v9.1/systemusers?$select=fullname,systemuserid&$filter=Microsoft.Dynamics.CRM.NotEqualUserId(PropertyName=@p1)&@p1='systemuserid'

Other query functions can be negated in different ways. For example, rather than trying to negate the Last7Days query function like this (which fail with the same error as mentioned previously):

GET [Organization URI]/api/data/v9.1/accounts?$select=name&$filter=not Microsoft.Dynamics.CRM.Last7Days(PropertyName=@p1)&@p1='createdon'

Use the OlderThanXDays query function like this:

GET [Organization URI]/api/data/v9.1/accounts?$select=name&$filter=Microsoft.Dynamics.CRM.OlderThanXDays(PropertyName=@p1,PropertyValue=@p2)&@p1='createdon'&@p2=7