Usar funciones de la API web
Publicado: enero de 2017
Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Las acciones y funciones representan operaciones reutilizables que puede realizar mediante 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 capacidades recuperan normalmente datos. Devuelven una colección o un tipo complejo. Cada una de estas funciones 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 una de estas funciones tiene un valor ConditionOperator correspondiente.
En este tema
Paso de parámetros a una función
Pasar referencia a una entidad para una función
Funciones enlazadas y sin enlazar
Crear una consulta con funciones
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 usa la GetTimeZoneCodeByLocalizedName Function, debe incluir los valores de parámetro LocalizedStandardName y LocaleId. Por tanto, puede usar la siguiente sintaxis en línea que se indica a continuación.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)
Sin embargo, hay un problema pendiente con el uso de valores de DateTimeOffset con la sintaxis en línea, como se explica en el artículo siguiente: DateTimeOffset como parámetro de consulta #204.
Por lo tanto, se recomienda pasar los valores como parámetros como se muestra en el siguiente código de ejemplo. Si usa esta recomendación, puede evitar el problema pendiente que se aplica a DateTimeOffset.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033
Los alias de parámetros también permiten reusar valores de parámetro para reducir la longitud total de la URL cuando el valor de parámetro se utiliza varias veces.
Pasar referencia a una entidad para una función
Determinadas funciones requerirán el pase de una referencia a una entidad existente. Por ejemplo, las siguientes funciones tienen un parámetro que requiere un crmbaseentity EntityType:
Al pasar una referencia a una entidad existente, use la anotación @odata.id para el URI para la entidad. Por ejemplo, si usa RetrievePrincipalAccess Function, puede usar el siguiente URI para especificar el acceso de recuperación a un contacto específico:
GET cc_WebAPI_ServiceURI/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, pero un URI relativo también funciona.
Funciones enlazadas y sin enlazar
Únicamente las funciones que se encuentran en Web API Function Reference pueden estar enlazadas. Las funciones de consulta nunca están enlazadas.
Funciones enlazadas
En el d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_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. Por ejemplo, lo siguiente es la definición de la CalculateTotalTimeIncident Function y CalculateTotalTimeIncidentResponse ComplexType en CSDL.
<ComplexType Name="CalculateTotalTimeIncidentResponse">
<Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
<Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
<ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>
Esta función enlazada es equivalente a la CalculateTotalTimeIncidentRequest usada por el servicio de organización. En API web esta función está enlazada a incident EntityType que representa la propiedad CalculateTotalTimeIncidentRequest.IncidentId. En lugar de devolver una CalculateTotalTimeIncidentResponse, esta función devuelve un CalculateTotalTimeIncidentResponse ComplexType. Cuando una función devuelve un tipo complejo, su definición aparece directamente por encima de la definición de la función en 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á enlazadas no deben usar el nombre completo.
Importante
Una función enlazada debe llamarse mediante un URI para establecer el primer valor de parámetro. No puede establecerlo como un valor de parámetro con nombre.
La siguiente ilustración muestra un ejemplo utilizando la CalculateTotalTimeIncident Function, que está enlazada a la entidad de incidente.
Solicitud
GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Respuesta
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context":"cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse","TotalTime":30 }
Funciones sin enlazar
La WhoAmI Function no está enlazado 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 WhoAmIRequest y devuelve un WhoAmIResponse ComplexType que corresponde al WhoAmIResponse usado por el servicio de la organización. Esta función no tiene ningún parámetro.
Al invocar una función sin enlazar, use únicamente el nombre de función que se muestra en el siguiente ejemplo.
Solicitud
GET cc_WebAPI_ServiceURI/WhoAmI() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Respuesta
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context": "cc_WebAPI_ServiceURI/$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 usan funciones de consulta para evaluar condiciones en una consulta.
Funciones que admiten composición
Algunas funciones que figuran en Web API Function Reference devolverán una colección de entidades. Un subconjunto de estas funciones admite composición, lo que significa que puede incluir una opción adicional 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 servicio de la organización 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 servicio de la organización. 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. Estas funciones se pueden usar de forma similar a las Funciones estándar de consulta, aunque hay algunas diferencias importantes.
Debe usar el nombre completo de la función e incluir los nombres de los parámetros. En el siguiente ejemplo se muestra cómo usar la LastXHours Function para devolver todas las entidades de cuenta modificadas durante las últimas 12 horas.
GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12
Ver 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 utilizando la API web
Cree una entidad usando API web
Recuperar una entidad usando API web
Actualizar y eliminar entidades mediante la API web
Asociar y anular la asociación de entidades 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
Microsoft Dynamics 365
© 2017 Microsoft. Todos los derechos reservados. Copyright