Compartir vía

Usar OData para consultar datos

  • Artículo

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

Recursos de EntitySet

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

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>
   [
}

Propina

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 de EntitySet correcto.

Por ejemplo, comience con el accounts recurso 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 cuenta donde un usuario específico es el OwningUser, puede utilizar la propiedad de navegación con valor de colección user_accounts del registro 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 colección. En el ejemplo siguiente se muestra la recuperación de 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 modificar 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. Liminar 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 varias 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 signo de 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. Aprender a usar las funciones de la Web API

Opciones de consulta OData no compatibles

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

Limitaciones de longitud de URL

La longitud de una URL en una solicitud GET 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 $batch con una solicitud POST como método para mover las opciones de consulta OData de la dirección URL al cuerpo de la solicitud donde el límite es el doble de largo. Enviar una solicitud de GET dentro de un $batch permite que las tengan hasta 64 KB (65 536 caracteres). Más información sobre las operaciones por lotes mediante la API web.

Liminar el número de filas

Para limitar el número de filas devueltas utilice la opción QueryExpression de $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 puede 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.

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

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

Características de OData versión 4.0

La API web de Dataverse es un servicio OData versión 4.0. En estas secciones de la especificación OData 4.0 se describe cómo recuperar datos:

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

Nota

La versión 4.01 de OData es la más reciente. Incluye mejoras y características adicionales que no están disponibles en la versión 4.0 y, por lo tanto, no están disponibles actualmente en la Dataverse API web.

Pasos siguientes

Aprender a seleccionar columnas.

Seleccionar columnas