Compartir a través de

Uso de funciones de API web

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

  • 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

Para esas funciones que requieren parámetros, el procedimiento recomendado es pasar 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 [Organization URI]/api/data/v9.2/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

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

Evite estos problemas pasando los valores con alias de parámetro, como se muestra en el ejemplo de código siguiente.

GET [Organization URI]/api/data/v9.2/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:

Functions    
CalculateRollupField IncrementKnowledgeArticleViewCount InitializeFrom
IsValidStateTransition RetrieveDuplicates RetrieveLocLabels
RetrievePrincipalAccess RetrieveRecordWall ValidateRecurrenceRule

Al pasar una referencia a un registro existente, use la @odata.id anotación en el 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 [Organization URI]/api/data/v9.2/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 se pueden enlazar las funciones encontradas en Web API Function Referenceo creadas como UNA 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 a la RetrieveUserPrivilegesRequest clase que usa el SDK para .NET. En el Web API, esta función está enlazada al systemuser tipo de entidad que representa la propiedad RetrieveUserPrivilegesRequest.UserId. En lugar de devolver una instancia de la RetrieveUserPrivilegesResponse clase , 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 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.

Importante

Invoque una función enlazada mediante un URI para establecer el primer valor de parámetro. No se puede establecer como un valor de parámetro con nombre.

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 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 WhoAmI función no está enlazada a una entidad. Se define en el CSDL sin un IsBound atributo .

<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 clase y devuelve un WhoAmIResponse tipo complejo que corresponde a la WhoAmIResponse clase usada por el SDK para .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

Hay dos maneras de usar las funciones para controlar los datos devueltos con consultas. Algunas funciones permiten controlar las columnas o condiciones que devuelven y 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 ColumnSet o QueryBase. Las opciones de consulta del sistema OData proporcionan la misma funcionalidad para que estas funciones no tengan los mismos parámetros que sus mensajes complementarios en el SDK. En la tabla siguiente se muestra una lista de esas funciones que se pueden componer en esta versión.

Functions    
RetrieveAllChildUsersSystemUser RetrieveBusinessHierarchyBusinessUnit RetrieveUnpublishedMultiple
SearchByBodyKbArticle SearchByKeywordsKbArticle SearchByTitleKbArticle

Funciones de consulta

Las funciones enumeradas en Web API Query Function Reference están diseñadas para usarse para formular 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 [Organization URI]/api/data/v9.2/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 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 [Organization URI]/api/data/v9.2/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 [Organization URI]/api/data/v9.2/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 negar la Last7Days función de consulta como esta (que produce el mismo error que se mencionó anteriormente):

GET [Organization URI]/api/data/v9.2/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 [Organization URI]/api/data/v9.2/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)
Realización de operaciones mediante la API web
Redacción de solicitudes HTTP y control de errores
Consultar datos utilizando 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
Ejecución de operaciones por lotes mediante la API web
Suplantar a otro usuario mediante la API web
Realización de operaciones condicionales mediante la API web

  • Last updated on