Comparteix via

Usar OData para consultar datos

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

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

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

Por ejemplo, comience con el recurso EntitySet de accounts 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 de valor de colección para un registro especificado. Por ejemplo, si desea recuperar datos del tipo de entidad de cuenta donde un usuario específico es OwningUser, use la user_accounts propiedad de navegación con valores de colección del registro systemuser especificado.

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

Para buscar el nombre de la propiedad de navegación con valores de colección:

Recuperar datos

Para recuperar datos de una colección, envíe una solicitud de GET al recurso de colección. El siguiente ejemplo muestra la recuperación de datos del tipo de entidad 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 para iniciar la consulta, afina la consulta para obtener los datos que necesita. Los siguientes artículos explican cómo completar su consulta.

Artículo Tarea
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 Optimización del 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 van a incluir 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á en el resultado. Liminar el número de filas
$count Solicite un recuento de los recursos coincidentes para incluirlos con los recursos de 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 el alias no tiene un valor asignado, es null.

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 API web

Opciones de consulta OData no compatibles

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

Limitaciones de longitud de URL

La longitud de una URL en una solicitud GETestá 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 mediante una solicitud POST como una manera de mover las opciones de consulta de OData fuera de la URL y al cuerpo de la solicitud, donde el límite es el doble de largo. Al enviar una solicitud de GET dentro de un $batch, puede usar direcciones URL de una longitud de 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 de tabla estándar y 500 filas de tabla elástica.

Como alternativa, especifique una serie de registros que se devolverán mediante paginación. No utilice $top cuando solicite páginas de datos. Obtenga información sobre cómo solicitar resultados paginados.

Limitaciones

Hay algunas cosas que puede hacer mediante FetchXml que OData no admite.

Herramientas de la Comunidad

Nota

Microsoft no admite herramientas creadas por la comunidad. Si tiene preguntas o problemas con las herramientas de la comunidad, póngase en contacto con el publicador de la herramienta.

Dataverse REST Builder es un proyecto de código abierto que proporciona una interfaz de usuario que le ayuda a realizar muchas cosas mediante la API web de Dataverse, incluidas las consultas de redacción.

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

Características de OData versión 4.0

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

En este artículo y los demás artículos de esta sección se describen las partes de la especificación de OData 4.0 que implementa la API web de Dataverse y cómo se puede usar para recuperar datos empresariales de Dataverse.

Nota

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

Pasos siguientes

Aprender a seleccionar columnas.

Seleccionar columnas

  • Last updated on