Uso de funciones de API web

Las funciones son operaciones reutilizables que puede realizar mediante la API web. La API web incluye dos tipos de funciones:

• Funciones: use una GET solicitud con las funciones enumeradas en Web API Function Reference para realizar operaciones que no tengan efectos secundarios. Estas funciones suelen recuperar datos, ya sea una colección o un tipo complejo. Cada función tiene un mensaje correspondiente en el servicio de la organización.

• Funciones de consulta: use las funciones enumeradas en Web API Query Function Reference para evaluar propiedades y valores en la composición de una consulta. Cada función de consulta tiene un valor correspondiente ConditionOperator .

Pasar parámetros a una función

En el caso de las funciones que requieren parámetros, pase los valores mediante alias de parámetro.

Por ejemplo, cuando utiliza la función GetTimeZoneCodeByLocalizedName, debe incluir los valores de los parámetros LocalizedStandardName y LocaleId. Puede usar la siguiente sintaxis en línea:

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

Sin embargo, un par de problemas pueden provocar un error en las solicitudes a menos que envíe estas solicitudes mediante alias de parámetro:

• Se produce un 400 Bad Request - Invalid URL error si supera la longitud máxima del segmento OData.
• Hay un problema al usar valores DateTimeOffset con la sintaxis insertada, como se explica en el siguiente artículo: DateTimeOffset como parámetro de consulta #204.

Evita estos problemas pasando los valores mediante alias de parámetros, como se muestra en el ejemplo de código siguiente.

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

Cuando se usa un valor de parámetro varias veces, los alias de parámetro permiten reutilizarlo para reducir la longitud de la dirección URL.

Pasar la referencia de un registro a una función

Algunas funciones requieren pasar una referencia a un registro existente. Por ejemplo, las siguientes funciones tienen un parámetro que requiere un crmbaseentity tipo de entidad:

Cuando pase una referencia a un registro existente, agregue la @odata.id anotación al URI del registro. Por ejemplo, si usa la RetrievePrincipalAccess función , puede usar el siguiente URI para especificar la recuperación del acceso a un registro de contacto específico:

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

La @odata.id anotación puede ser el URI completo o un URI relativo.

Funciones enlazadas y sin enlazar

Solo puede enlazar funciones que se encuentren en Web API Function Reference o funciones que cree como API personalizada. Las funciones de consulta nunca están enlazadas.

Funciones vinculadas

En el documento $metadata CSDL, cuando un Function elemento representa una función enlazada, tiene un IsBound atributo con el valor true. El primer Parameter elemento definido en la función representa la entidad a la que está enlazada la función. Cuando el Type atributo del parámetro es una colección, la función se enlaza a una colección de entidades.

El ejemplo siguiente es la definición de la función RetrieveUserPrivileges y del tipo complejo RetrieveUserPrivilegesResponse en el 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>

Esta función enlazada es equivalente al SDK para la clase RetrieveUserPrivilegesRequest de .NET. En la API web, esta función está vinculada al tipo de entidad systemuser que representa la propiedad RetrieveUserPrivilegesRequest.UserId del SDK para .NET. En lugar de devolver una instancia del SDK para la clase RetrieveUserPrivilegesResponse de .NET, esta función devuelve un RetrieveUserPrivilegesResponse tipo complejo. Cuando una función devuelve un tipo complejo, su definición suele aparecer directamente encima de la definición de la función en el documento de $metadata CSDL.

Para invocar una función enlazada, anexe el nombre completo de la función a la dirección URL e incluya los parámetros con nombre entre paréntesis después del nombre de la función. El nombre completo de la función incluye el espacio de nombres Microsoft.Dynamics.CRM. Las funciones que no están enlazadas no deben usar el nombre completo.

En el ejemplo siguiente se usa la RetrieveUserPrivileges función , que está enlazada a la systemuser tabla.

Solicitud:

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  

Respuesta:

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

Funciones sin enlazar

La WhoAmI función no está enlazada a una entidad. Se define en el documento de $metadata CSDL sin atributo 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>  

Esta función corresponde al SDK para la clase WhoAmIRequest de .NET y devuelve un WhoAmIResponse tipo complejo que corresponde al SDK para la clase WhoAmIResponse de .NET. Esta función no tiene ningún parámetro.

Al invocar una función sin enlazar, use solo el nombre de la función, como se muestra en el ejemplo siguiente:

Solicitud:

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

Respuesta:

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

Redacción de una consulta con funciones

Puede usar funciones de dos maneras para controlar los datos devueltos por las consultas. Determinadas funciones le permiten controlar las columnas o condiciones que devuelven. También puede usar funciones de consulta para evaluar las condiciones de una consulta.

Funciones que se pueden componer

Algunas funciones enumeradas en Web API Function Reference devuelven una colección de entidades. Un subconjunto de estas funciones son componibles, lo que significa que puede incluir una opción de consulta del sistema $select o $filter para controlar qué columnas se devuelven en los resultados. Estas funciones tienen un IsComposable atributo en el CSDL. Cada una de estas funciones tiene un mensaje complementario en el SDK que acepta un parámetro de tipo de clase ColumnSet de .NET o un parámetro de tipo de clase QueryBase de .NET. Las opciones de consulta del sistema OData proporcionan la misma funcionalidad, por lo que estas funciones no tienen los mismos parámetros que sus mensajes complementarios en el SDK para .NET . En la tabla siguiente se muestra una lista de funciones que se pueden componer:

Funciones de consulta

Use las funciones enumeradas en Web API Query Function Reference para redactar una consulta. Puede usarlos de forma similar a las funciones de consulta de OData, pero hay algunas diferencias importantes. Debe usar el nombre completo de la función e incluir los nombres de los parámetros.

En el ejemplo siguiente se usa la LastXHours función de consulta para devolver todas las entidades de cuenta modificadas en las últimas 12 horas:

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

Limitaciones de las funciones de consulta

Una limitación de las funciones de consulta es que no se puede usar el not operador para negar las funciones de consulta.

Por ejemplo, la consulta siguiente, que usa EqualUserId, produce el error : 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'

Varias funciones de consulta tienen una función de consulta negada complementaria. Por ejemplo, NotEqualUserId niega EqualUserId, por lo que la consulta siguiente devuelve los resultados esperados:

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

Otras funciones de consulta se pueden negar de diferentes maneras. Por ejemplo, en lugar de intentar anular la función de consulta Last7Days como esta (lo cual produce el mismo error mencionado anteriormente):

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

Use la función de consulta de OlderThanXDays de esta manera:

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

Consulte también

Ejemplo de acciones y funciones de API web (C#)
Ejemplo de acciones y funciones de API web (JavaScript del lado cliente)
Ejemplo de acciones y funciones de API web (PowerShell)
Consultar datos utilizando la API web
Usar acciones de la API web