Recuperar y ejecutar consultas predefinidas

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Microsoft Dynamics 365 proporciona una forma de que los administradores creen vistas del sistema que están disponibles para todos los usuarios. Los usuarios individuales pueden guardar consultas de búsqueda avanzada para su reutilización en la aplicación. Ambas representan consultas predefinidas que puede recuperar y ejecutar utilizando la API web. También puede redactar una consulta utilizando FetchXml y usarla para recuperar datos.

En este tema

Consultas predefinidas

Usar FetchXML personalizado

Consultas predefinidas

Microsoft Dynamics 365 permite definir, guardar, y ejecutar dos tipos de consultas que se muestran aquí.

Los registros para ambos tipos de entidades contienen la definición FetchXML para que se devuelvan los datos. Puede buscar el tipo de entidad respectivo para recuperar el valor de clave principal. Con el valor de clave principal, puede ejecutar la consulta pasando el valor de clave principal. Por ejemplo, para ejecutar la consulta guardada Cuentas activas, primero debe obtener la clave principal mediante una consulta como ésta.

GET cc_WebAPI_ServiceURI/savedqueries?$select=name,savedqueryid&$filter=name eq 'Active Accounts'

Luego puede usar el valor de savedqueryid y pasarlo como el valor al parámetro savedQuery al conjunto de entidades accounts.

GET cc_WebAPI_ServiceURI/accounts?savedQuery=00000000-0000-0000-00aa-000010001002

Use el mismo método para obtener el userqueryid y pasarlo como el valor al parámetro userQuery al conjunto de entidades que coincida con el returnedtypecode correspondiente de la consulta guardada.

GET cc_WebAPI_ServiceURI/accounts?userQuery=121c6fd8-1975-e511-80d4-00155d2a68d1

Aplicar una consulta a cualquier colección del tipo adecuado

Además de simplemente aplicar la consulta guardada a la colección principal del conjunto de entidades, también puede usar una consulta guardada o consulta de usuario para aplicar el mismo filtrado a cualquier colección del tipo adecuado de entidades. Por ejemplo, si desea aplicar una consulta solo a entidades relacionadas con una entidad específica, puede aplicar el mismo patrón. Por ejemplo, la siguiente URL aplicará la consulta Oportunidades abiertas a las oportunidades relacionadas con una cuenta específica a través de la propiedad de navegación valorada como colección opportunity_parent_account.

GET cc_WebAPI_ServiceURI/accounts(8f390c24-9c72-e511-80d4-00155d2a68d1)/opportunity_parent_account/?savedQuery=00000000-0000-0000-00aa-000010003001

Usar FetchXML personalizado

FetchXML es un lenguaje de consultas propietario que proporciona capacidades para realizar agregación. Las consultas guardadas y consultas de usuario almacenadas en savedquery EntityType y userquery EntityType respectivamente incluyen una propiedad fetchxml que define la consulta. Puede usar FetchXML directamente con el método IOrganizationService.RetrieveMultiple o con RetrieveMultipleRequest.Más información:Crear consultas con FetchXML

Puede pasar FetchXML codificado de dirección URL como consulta al conjunto de entidades correspondiente a la entidad raíz de la consulta con el parámetro FetchXML para devolver los resultados de la API web. Por ejemplo, puede tener el siguiente FetchXML que tiene cuenta como entidad.

<fetch mapping='logical'> 
   <entity name='account'>
      <attribute name='accountid'/> 
      <attribute name='name'/> 
</entity>
</fetch>

El valor codificado de dirección URL de este FetchXML es como se indica a continuación.

%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E

La mayoría de los lenguaje de programación incluyen una función para codificar como dirección URL una cadena. Por ejemplo, en JavaScript use la función encodeURI. Debe codificar como dirección URL cualquier solicitud que envíe a cualquier servicio web RESTful. Si pega una dirección URL en la barra de direcciones del explorador debe codificar como dirección URL la dirección automáticamente. El siguiente ejemplo muestra una solicitud GET mediante el FetchXML indicado anteriormente con la ruta del conjunto de entidades para cuentas.

• Solicitud

  GET cc_WebAPI_ServiceURI/accounts?fetchXml=%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E 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":"cc_WebAPI_ServiceURI/$metadata#accounts(accountid,name)","value":[
      {
        "@odata.etag":"W/\"506678\"","accountid":"89390c24-9c72-e511-80d4-00155d2a68d1","name":"Fourth Coffee (sample)"
      },{
        "@odata.etag":"W/\"502172\"","accountid":"8b390c24-9c72-e511-80d4-00155d2a68d1","name":"Litware, Inc. (sample)"
      },{
        "@odata.etag":"W/\"502174\"","accountid":"8d390c24-9c72-e511-80d4-00155d2a68d1","name":"Adventure Works (sample)"
      },{
        "@odata.etag":"W/\"506705\"","accountid":"8f390c24-9c72-e511-80d4-00155d2a68d1","name":"Fabrikam, Inc. (sample)"
      },{
        "@odata.etag":"W/\"506701\"","accountid":"91390c24-9c72-e511-80d4-00155d2a68d1","name":"Blue Yonder Airlines (sample)"
      },{
        "@odata.etag":"W/\"502180\"","accountid":"93390c24-9c72-e511-80d4-00155d2a68d1","name":"City Power & Light (sample)"
      },{
        "@odata.etag":"W/\"502182\"","accountid":"95390c24-9c72-e511-80d4-00155d2a68d1","name":"Contoso Pharmaceuticals (sample)"
      },{
        "@odata.etag":"W/\"506704\"","accountid":"97390c24-9c72-e511-80d4-00155d2a68d1","name":"Alpine Ski House (sample)"
      },{
        "@odata.etag":"W/\"502186\"","accountid":"99390c24-9c72-e511-80d4-00155d2a68d1","name":"A. Datum Corporation (sample)"
      },{
        "@odata.etag":"W/\"502188\"","accountid":"9b390c24-9c72-e511-80d4-00155d2a68d1","name":"Coho Winery (sample)"
      },{
        "@odata.etag":"W/\"504177\"","accountid":"0a3238d4-f973-e511-80d4-00155d2a68d1","name":"Litware, Inc."
      }
    ]
  }
  

  Nota

  La respuesta de las consultas en FetchXML que contengan entidades de vínculo y sus atributos contiene caracteres Unicode especiales, por ejemplo '.' se convierte en '_x002e_' y '@' se convierte en '_x0040_'.

Paginación con FetchXML

Con fetchXML puede aplicar paginación estableciendo los atributos page y count del elemento fetch. Por ejemplo, para establecer una consulta para cuentas y limitar el número de entidades a 2 y devolver solamente la primera página, el fetchXML siguiente:

<fetch mapping="logical" page="1" count="2">
 <entity name="account">
  <attribute name="accountid" />
  <attribute name="name" />
  <attribute name="industrycode" />
 <order attribute="name" />
 </entity>
</fetch>

Con una solicitud con fetchXML también puede solicitar una cookie de paginación e incluirla con su consulta.Más información:Páginar grandes conjuntos de resultados con FetchXML

Una cookie de paginación debe solicitarse como anotación. Establezca la preferencia odata.include-annotations para usar (o incluir) Microsoft.Dynamics.CRM.fetchxmlpagingcookie y una propiedad @Microsoft.Dynamics.CRM.fetchxmlpagingcookie será devuelta con el resultado.

Ver también

Ejemplo de datos de consulta API (C#)
Ejemplo de datos de consulta 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 funciones de 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