Compartir a través de

Usar OData para consultar datos

  • Artículo

Cada consulta comienza con una colección de entidades. Las colecciones de entidades pueden ser:

EntitySet recursos

Para encontrar todos los recursos disponibles en su ambiente, envíe una solicitud al documento de servicio de la API web: EntitySet GET ...

Solicitud:

GET [Organization URI]/api/data/v9.2/
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",
    "value": [
        {
            "name": "aadusers",
            "kind": "EntitySet",
            "url": "aadusers"
        },
        {
            "name": "accountleadscollection",
            "kind": "EntitySet",
            "url": "accountleadscollection"
        },
        {
            "name": "accounts",
            "kind": "EntitySet",
            "url": "accounts"
        },
      ... <Truncated for brevity>
   [
}

Sugerencia

Estos valores suelen ser el nombre plural de la tabla, pero pueden ser diferentes. Utilice los resultados de esta solicitud para confirmar que está utilizando el nombre de recurso EntitySet correcto.

Por ejemplo, comience con el recurso accounts EntitySet para recuperar datos del tipo de entidad de cuenta.

GET [Organization URI]/api/data/v9.2/accounts

Colecciones filtradas

Puede consultar cualquier colección de entidades representadas por una propiedad de navegación con valor de colección de un registro específico. Por ejemplo, si desea recuperar datos del tipo de entidad de cuenta donde un usuario específico es el OwningUser , puede usar la propiedad de navegación con valor de colección del registro user_accounts systemuser especificado.

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

Para localizar el nombre de la colección de navegación de un solo valor:

Recuperar datos

Para recuperar datos de una colección, envíe una GET solicitud al recurso de la colección. El siguiente ejemplo muestra cómo recuperar datos del tipo de entidad de cuenta.

Este ejemplo también demuestra:

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,statecode,statuscode&$orderby=name&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Respuesta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,statecode,statuscode)",
   "value": [
      {
         "@odata.etag": "W/\"112430907\"",
         "name": "A. Datum Corporation (sample)",
         "statecode@OData.Community.Display.V1.FormattedValue": "Active",
         "statecode": 0,
         "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
         "statuscode": 1,
         "accountid": "4b757ff7-9c85-ee11-8179-000d3a9933c9"
      }
   ]
}

Refinar la consulta

Después de seleccionar la tabla con la que comenzar la consulta, refine la consulta para obtener los datos que necesita. Los siguientes artículos explican cómo completar su consulta.

Artículo Task
Seleccionar columnas Especifique qué columnas de datos se deben devolver.
Unir tablas Especificar el número de tablas relacionada para devolver en los resultados.
Ordenar filas Especifique el orden de clasificación de las filas que se deben devolver.
Filtrar filas Especifique qué filas de datos se deben devolver.
Resultados de página Especifique cuántas filas de datos se devolverán con cada solicitud.
Agregar datos Cómo agrupar y agregar los datos devueltos.
Recuento del número de filas Cómo obtener un recuento del número de filas devueltas.
Optimizaciones del rendimiento Cómo optimizar el rendimiento

Opciones de consulta de OData

Utilice estas opciones para cambiar los resultados devueltos de una colección. La siguiente tabla describe las opciones de consulta de OData que admite la API web de Dataverse.

Opción Usar para Más información
$select Solicite un conjunto específico de propiedades para cada entidad o tipo de complejo. Seleccionar columnas
$expand Especifique los recursos relacionados que se incluirán en línea con los recursos recuperados. Unir tablas
$orderby Solicite recursos en un orden particular. Ordenar filas
$filter Filtre una colección de recursos. Filtrar filas
$apply Agregue y agrupe sus datos. Agregar datos
$top Especifique el número de elementos de la colección consultada que se incluirán en el resultado. Limitar el número de filas
$count Solicite un recuento de los recursos coincidentes incluidos con los recursos en la respuesta. Recuento del número de filas

Para aplicar múltiples opciones, separe las opciones de consulta de la ruta del recurso con un signo de interrogación (?). Separe cada opción después de la primera con un ampersand (&). Los nombres de opción distinguen entre mayúsculas y minúsculas.

Uso de alias de parámetro con opciones de consulta

Puede utilizar alias de parámetros para las opciones de consulta $filter y$orderby, pero actualmente no dentro de la opción $expand. Los alias de parámetro permiten usar el mismo valor varias veces en una solicitud. Si al alias no se asigna un valor se da por hecho que es nulo.

Sin alias de parámetros:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

Con alias de parámetros:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=@p1 asc,@p2 desc
&$filter=@p1 ne @p3&@p1=revenue&@p2=name

También puede usar alias de parámetro al usar funciones. Aprenda a utilizar las funciones de la API web

Opciones de consulta OData no admitidas

La API web no admite las siguientes opciones de consulta OData: Dataverse , ,. $skip``$search``$format

Limitaciones de longitud de URL

La longitud de una URL en una GET solicitud está limitada a 32 KB (32,768 caracteres). Incluir muchas opciones de consulta OData complejas como parámetro en la URL puede llegar al límite. Puede ejecutar una operación utilizando una solicitud como una forma de mover las opciones de consulta de OData fuera de la URL y hacia el cuerpo de la solicitud, donde el límite es el doble de largo. $batch POST Enviar una solicitud de GET dentro de un $batch permite que las tengan hasta 64 KB (65 536 caracteres). Obtenga más información sobre las operaciones por lotes utilizando la API web.

Liminar el número de filas

Para limitar la cantidad de filas devueltas, utilice la opción de consulta OData. $top Sin este límite, Dataverse devuelve hasta 5000 filas.

Alternativamente, especifique una cantidad de registros para devolver usando la paginación. No utilice $top cuando solicite páginas de datos. Aprenda a solicitar resultados paginados

Limitaciones

Hay algunas cosas que puedes hacer usando FetchXml que OData no admite.

Herramientas de la Comunidad

Nota

Las herramientas creadas por la comunidad no reciben soporte de Microsoft. Si tiene preguntas o problemas con las herramientas de la comunidad, comuníquese con el creador de la herramienta.

El Dataverse REST Builder es un proyecto de código abierto que proporciona una interfaz de usuario que le ayuda a hacer muchas cosas utilizando la Dataverse API web, incluida la composición de consultas.

XrmToolBox FetchXMLBuilder es una herramienta gratuita para componer y probar solicitudes FetchXml, pero también genera código para consultas OData utilizando la misma experiencia de diseño.

Características de la versión 4.0 de OData

La API web es un servicio de OData versión 4.0. Dataverse Estas secciones de la especificación OData 4.0 describen cómo recuperar datos:

Este artículo y los demás artículos de esta sección describen las partes de la especificación OData 4.0 implementadas por la API web y cómo puede usarla para recuperar datos comerciales de Dataverse . Dataverse

Nota

La versión 4.01 de OData es la última versión. Incluye mejoras y funciones adicionales que no están disponibles en la versión 4.0 y, por lo tanto, actualmente no están disponibles en la API web. Dataverse

Pasos siguientes

Aprender a seleccionar columnas.

Seleccionar columnas

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).