Web API Functions

Artikel
01/01/2023

Within the CSDL $metadata document, you will find Function elements. Function operations are different from actions because they should not change data. They are typically used only to retrieve data.

Every function has a Name attribute. This name will be part of the URL when you use HTTP GET, sending any defined parameters for the function in the url of the request.

Bound Functions

Just like actions, functions may have a IsBound="true" attribute. This means it is a bound function. Functions without the IsBound attribute are unbound. A bound function means that the first parameter is a reference to a to a table record or to an entity set.

When an function is bound, it will have a reference to a specific item within the service namespace. To use the function, you must use the fully qualified name including the Microsoft.Dynamics.CRM namespace. More information: Service namespace

Composable functions

Functions may have a IsComposable="true" attribute. This means that you can append some system query options such as $filter or $select to the URL to specify the results returned. This option is only available for specific system functions. You cannot create a function using custom API that is composable.

Parameters

Functions usually have one or more Parameter elements. Each parameter will have the following attributes:

Attribute	Description
`Name`	The name of the parameter. The name is unique unless the `Function` is overloaded. More information: Overloaded Functions.
`Type`	The type of the parameter.
`Nullable="false"`	Whether the parameter can accept a null value

ReturnType

Functions must return values. A function will always have a ReturnType element.

Attribute	Description
`Type`	The type of the parameter.
`Nullable="false"`	Whether the value may be null.

Function definition examples

The following represent some fictional examples of Function definitions showing different binding patterns. Each of these examples returns an integer value.

Unbound functions

An unbound function with a single integer Number parameter.

<Function Name="UnBoundFunctionExample">
    <Parameter Name="Number" Type="Edm.Int32" Nullable="false" />
    <ReturnType Type="Edm.Int32" Nullable="false" />
</Function>

Function bound to an entity

A function bound to the account entity with a single integer Number parameter.

<Function Name="EntityBoundFunctionExample" IsBound="true">
    <Parameter Name="entity" Type="mscrm.account" Nullable="false" />
    <Parameter Name="Number" Type="Edm.Int32" Nullable="false" />
    <ReturnType Type="Edm.Int32" Nullable="false" />
</Function>

Function bound to an entity set

A function bound to the account EntitySet with a single integer Number parameter.

<Function Name="EntityCollectionBoundFunctionExample" IsBound="true">
    <Parameter Name="entityset" Type="Collection(mscrm.account)" Nullable="false" />
    <Parameter Name="Number" Type="Edm.Int32" Nullable="false" />
    <ReturnType Type="Edm.Int32" Nullable="false" />
</Function>

Overloaded functions

Usually, each function you find in the $metadata will be the only function with that name. However bound functions can have multiple definitions when bound to different types. The system RetrieveUnpublished and RetrieveUnpublishedMultiple functions are some examples. You cannot create an overloaded function using custom API.

More information: OData 4.0 Function Overload Rules

Next steps

Learn about Complex & Enum types.

Complex & Enum types

Dela via