Usar funciones de la API web

Las funciones son operaciones reutilizables que puede realizar utilizando la API web. Existen dos tipos de funciones en la API web:

• Funciones: Use una solicitud GET con las funciones que aparecen en Web API Function Reference para realizar operaciones que tienen efectos secundarios. Estas funciones generalmente recuperan datos, ya sea una colección o un tipo complejo. Cada funcioń 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 creación de una consulta. Cada fución de consulta tiene un valor ConditionOperator correspondiente.

Paso de parámetros a una función

Para las funciones que requieren parámetros, se recomienda pasar los valores mediante parámetros.

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

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

Sin embargo, habrá un problema cuando use los valores DateTimeOffset con la sintaxis en línea, como se explica en el siguiente artículo: DateTimeOffset como parámetro de consulta #204.

Evite el problema DateTimeOffset pasando los valores como parámetros, como se muestra en el siguiente código de ejemplo:

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

Cuando un valor de parámetro se utiliza varias veces, los alias de parámetro le permiten reutilizarlo para reducir la longitud de la URL.

Pasar referencia de registro a una función

Determinadas funciones requireen el pase de una referencia a un registro existente. Por ejemplo, las siguientes funciones tienen un parámetro que requiere un tipo de entidad crmbaseentity:

Al pasar una referencia a un registro existente, use la anotación @odata.id en el URI para el registro. Por ejemplo, si está utilizando la función RetrievePrincipalAccess, puede usar el siguiente Uri para especificar la recuperación del acceso a un registro de contacto específico:

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)'}

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

Funciones enlazadas y sin enlazar

Solo se pueden vincular las funciones que se encuentran en Web API Function Reference o creadas como una API personalizada. Las funciones de consulta nunca están enlazadas.

Funciones enlazadas

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

El siguiente ejemplo es la definición de la función RetrieveUserPrivileges y del tipo complejo RetrieveUserPrivilegesResponse en 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 vinculada a la entidad es equivalente a la clase RetrieveUserPrivilegesRequest utilizada por el SDK para .NET. En la API web, esta función está vinculada al tipo de entidad systemuser que representa la propiedad RetrieveUserPrivilegesRequest.UserId. En lugar de devolver una instancia de la clase RetrieveUserPrivilegesResponse, esta función devuelve un tipo complejo RetrieveUserPrivilegesResponse. 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 CSDL.

Para invocar a una función sin enlazar, anexe el nombre completo de la función a la URL e incluya cualquier parámetro con nombre entre paréntesis tras el 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.

El siguiente ejemplo usa la función RetrieveUserPrivileges, que está ligada a la tabla systemuser.

Solicitud:

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  

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 función WhoAmI no está vinculada a una entidad. Se define en CSDL sin un 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 a la clase WhoAmIRequest y devuelve un tipo complejo WhoAmIResponse que corresponde a la clase WhoAmIResponse utilizada por el SDK para .NET. Esta función no tiene ningún parámetro.

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

Solicitud:

GET [Organization URI]/api/data/v9.0/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.0/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",  
 "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1",  
 "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1",  
 "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1"  
}  

Crear una consulta con funciones

Hay dos formas de utilizar las funciones para controlar los datos devueltos con consultas. Algunas funciones permiten el control de las columnas o condiciones que devuelven y se pueden usar funciones de consulta para evaluar condiciones en una consulta.

Funciones que admiten composición

Algunas funciones que figuran en Web API Function Reference devuelven una colección de entidades. Un subconjunto de estas funciones admite composición, 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 atributo IsComposable en CSDL. Cada una de estas funciones tiene un mensaje de acompañamiento manual en el SDK que acepta un parámetro de tipo ColumnSet o QueryBase. Las opciones de consulta del sistema OData ofrecen la misma funcionalidad, por lo que estas funciones no tienen los mismos parámetros que sus mensajes de acompañamiento en el SDK. La siguiente tabla muestra una lista de esas funciones que admiten composición de esta versión.

Funciones de consulta

Las funciones enumeradas en Web API Query Function Reference se proporcionan para ser utilizadas para crear una consulta. Puede utilizarlas de forma similar a las funciones de consulta OData, pero existen algunas diferencias importantes. Debe usar el nombre completo de la función e incluir los nombres de los parámetros.

El siguiente ejemplo usa la función de consulta LastXHours para devolver todas las entidades de cuenta modificadas en las últimas 12 horas.

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

Limitaciones de las funciones de consulta

Una de las limitaciones de funciones de consulta es que no puede usar el operador not para negar funciones de consulta.

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

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

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

Otras funciones de consulta se pueden negar de distintas formas. Por ejemplo, en lugar de intentar negar una función de consulta Last7Days como esta (que produce un error con el mismo mensaje anteriormente indicado):

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

Utilizar una función de consulta OlderThanXDays como esta:

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

Consulte también

Ejemplo de funciones y acciones de la API web (C#)
Ejemplo de funciones y acciones de la API web (JavaScript del lado del cliente)
Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar errores
Consultar datos mediante la API web
Crear una fila de tabla usando la API web
Recuperar una fila de tabla usando la API web
Actualizar y eliminar filas de tablas usando la API web
Asociar y anular la asociación de filas de tabla mediante la API web
Usar acciones de la API web
Ejecute las operaciones por lotes mediante API web
Suplantar a otro usuario utilizando la API web
Realizar operaciones condicionales mediante la API web