Usar OData para consultar datos
Cada consulta comienza con una colección de entidades. Las colecciones de entidades pueden ser:
- Recursos de EntitySet: una de las colecciones de API web
EntitySet
. - Colecciones filtradas: un conjunto de entidades devueltas por una propiedad de navegación con valor de colección para un registro específico.
- Una propiedad de navegación con valor de colección expandida.
- Una colección devuelta por una función.
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:
- Para cualquier tabla y relación de Dataverse, puede consultar la Web API Entity Type Reference
- Para cualquier tabla personalizada o Relaciones, busque las propiedades de navegación con valores de colección dentro del documento de servicio $metadata ...
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:
- Limitar las columnas devueltas usando
$select
. Más información sobre la selección de columnas - Ordenar resultados utilizando
$orderby
. Obtenga más información sobre cómo ordenar columnas - Limitar las filas devueltas usando
$top
. Obtenga información sobre cómo limitar el número de filas - Mostrar valores formateados utilizando el encabezado de solicitud:
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
. Obtenga más información sobre los valores formateados
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.
No se pueden unir tablas sin ninguna relación. ... OData solo permite usar la opción de consulta
$expand
para unir tablas usando propiedades de navegación que son parte de Relaciones en el modelo de datos.Limitaciones de agregación enumera las siguientes limitaciones para las agregaciones que utilizan OData:
Realizar comparaciones cruzadas de columnas de tablas. OData admite el filtrado de valores de columnas en la misma fila, pero deben estar en la misma tabla. ...
No es necesario anular el orden de clasificación predeterminado para las columnas de opciones. El comportamiento predeterminado al ordenar columnas de opciones es utilizar valores enteros en lugar del valor de etiqueta localizado.
No puede utilizar la optimización del rendimiento de la consulta Materialize tardía.
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:
- OData versión 4.0. Parte 1: Protocolo más erratas 03 11.2 Solicitud de datos
- OData versión 4.0. Parte 2: Convenciones de URL más Erratas 03 5 Opciones de consulta
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.
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).