Consultar datos utilizando la API web

  • Artículo

Cuando utiliza la API web para crear una consulta en una tabla de Dataverse, debe tomar las siguientes decisiones:

Decisión Descripción
Seleccionar columnas Qué columnas de datos devolver
Unir tablas Qué tablas relacionadas incluir en los resultados
Ordenar filas En qué orden devolver los resultados
Filtrar filas Qué filas de datos devolver
Resultados de página Cuántas filas de datos se devuelven
Agregar datos Cómo agrupar y agregar los datos devueltos
Recuento del número de filas Cómo contar el número de filas

Este artículo trata sobre la consulta de datos encontrados en tablas. También puede utilizar la API web para consultar datos sobre definiciones de tablas o metadatos de la entidad. La estructura de los datos es diferente, por lo que muchas de las capacidades descritas aquí no se aplican. Más información: Consultar difiniciones de tabla mediante la API web y Consultar definiciones de esquemas

Colecciones de entidades

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

Recurdos de EntitySet

Para encontrar todos los recursos de EntitySet disponibles en su entorno, envíe una solicitud GET al documento de servicio de 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. Use esta consulta para confirmar que está usando el nombre de recurso EntitySet correcto.

Para recuperar datos del tipo de entidad de cuenta, empieza con el recurso EntitySet de accounts.

GET [Organization URI]/api/data/v9.2/accounts?$select=name

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.

Si desea recuperar datos del tipo de entidad de cuenta, donde un usuario específico es el OwningUser, puede usar el la propiedad de navegación user_accounts con valor de colección del registro especificado de systemuser.

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:

Opciones de consulta de OData

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
$filter Filtre una colección de recursos. Filtrar filas
$orderby Solicite recursos en un orden particular. Ordenar 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. No use $top cuando recupera páginas de datos. Usar la opción de consulta $top
$count Solicite un recuento de los recursos coincidentes incluidos con los recursos en la respuesta. Recuento del número de filas

Puede aplicar varias opciones a una consulta. 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.

La API web de Dataverse no es compatible con estas opciones de consulta de OData: $skip,$search,$format.

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. Más información: Usar funciones web API

Seleccionar columnas

Importante

Cuando consulta datos, es importante limitar la cantidad de datos devueltos para optimizar el rendimiento. Solo seleccione las columnas con datos que necesita.

Utilice la opción de consulta $select para elegir qué columnas devolver con su consulta. En OData, cada columna se representa como una propiedad. Si no incluye una opción de consulta $select, se devuelven todas las propiedades.

El siguiente ejemplo solicita las propiedades name y revenue de una fila del recurso EntitySet de accounts:

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=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": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
        {
            "@odata.etag": "W/\"81052965\"",
            "name": "Litware, Inc. (sample)",
            "revenue": 20000.0000,
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "4624eff7-53d3-ed11-a7c7-000d3a993550"
        }
    ]
}

La propiedad de la clave principal siempre se devuelve, por lo que no necesita incluirla en su $select. En este ejemplo, accountid ees la clave principal.

También se pueden incluir otros valores de propiedad. En este caso, la propiedad de búsqueda _transactioncurrencyid_value para la referencia de entidad/tabla de divisas (TransactionCurrency) relacionada se incluye porque revenue es una propiedad de moneda.

¿Qué propiedades están disponibles?

Todas las propiedades disponibles para una entidad se encuentran en el documento de servicio de $metadatos. Más información: Propiedades de API web

Los tipos de entidad incluidos con Dataverse se describen en Web API Entity Type Reference.

Sugerencia

La forma más fácil de descubrir rápidamente qué propiedades están disponibles es enviar una solicitud mediante la opción de consulta $top con un valor de 1 sin utilizar $select.

Valores con formato

Los valores con formato son valores de cadena generados en el servidor que puede usar en su aplicación. Los valores con formato incluyen:

  • Las etiquetas localizadas para las columnas elección, opciones, sí/no, estado y razón para el estado
  • El valor de nombre principal para las propiedades de búsqueda y propietario
  • Valores de moneda con símbolos de moneda
  • Valores de fecha con formato en la zona horaria del usuario

Para incluir los valores con formato en sus resultados, use este encabezado de solicitud:

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Los valores con formato son una de varias anotaciones que puede solicitar. Utilice Prefer: odata.include-annotations="*" para incluir todas las anotaciones. Más información: Anotaciones de la solicitud

El valor con formato se devuelve con el registro con una anotación que sigue esta convención:

<property name>@OData.Community.Display.V1.FormattedValue

Por ejemplo:

Solicitud:

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

La siguiente tabla describe los valores y los valores con formato que se devuelven para las propiedades solicitadas.

Property valor Valor con formato
name Litware, Inc. (sample) None
revenue 20000.0000 $20,000.00
_primarycontactid_value 70bf4d48-34cb-ed11-b596-0022481d68cd Susanna Stubberod (sample)
customertypecode 1 Competitor
modifiedon 2023-04-07T21:59:01Z 4/7/2023 2:59 PM
_transactioncurrencyid_value 228f42f8-e646-e111-8eb7-78e7d162ced1 US Dollar
accountid 78914942-34cb-ed11-b596-0022481d68cd None

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,revenue)",
    "value": [
{
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "revenue@OData.Community.Display.V1.FormattedValue": "$20,000.00",
            "revenue": 20000.0000,
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "Competitor",
            "customertypecode": 1,
            "modifiedon@OData.Community.Display.V1.FormattedValue": "4/7/2023 2:59 PM",
            "modifiedon": "2023-04-07T21:59:01Z",
            "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

Datos de propiedades de búsqueda

Cuando una propiedad de búsqueda representa una relación de varias tablas o polimórfica, debe solicitar anotaciones específicas para determinar qué tabla contiene los datos relacionados.

Por ejemplo, muchas tablas tienen registros que pueden ser propiedad de usuarios o equipos. Los datos de propiedad se almacenan en una columna de búsqueda denominada ownerid. Esta columna es una propiedad de navegación de un solo valor en OData. Podría usar $expand para crear una combinación para obtener este valor, pero no puede usar $select. Sin embargo, puede usar la propiedad de búsqueda _ownerid_value correspondiente con $select.

Cuando incluyes la propiedad de búsqueda _ownerid_value con su $select, devuelve un valor GUID. Este valor no indica si el propietario del registro es un usuario o un equipo. Debe solicitar anotaciones para obtener estos datos.

Para incluir estas anotaciones en sus resultados, use este encabezado de solicitud:

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

Sugerencia

O puede usar Prefer: odata.include-annotations="*" para incluir todas las anotaciones. Más información: Anotaciones de la solicitud

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,_ownerid_value&$top=2
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

La siguiente respuesta devuelve dos registros de cuenta diferentes. team posee el primero, y systemuser posee el segundo. La anotación _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname proporciona esta información.

Respuesta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_ownerid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81550512\"",
            "name": "Adventure Works (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
            "_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e",
            "accountid": "1adef0b8-54d3-ed11-a7c7-000d3a993550"
        },
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
            "_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}
  • <lookup property name>@Microsoft.Dynamics.CRM.lookuplogicalname es el nombre lógico de la tabla relacionada.
  • <lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty es el nombre de la propiedad de navegación de un solo valor correspondiente. Puede utilizar $expand utilizando este valor en otra solicitud para obtener más datos del registro relacionado.

Unir tablas

Para controlar qué datos se devuelven se los registros de tabla relacionados, use la opción de consulta $expand con propiedades de navegación.

  • Puedes incluir hasta 15 opciones $expand en una consulta. Cada una de las opciones $expand crea una unión que puede afectar al rendimiento.
  • Las consultas que expanden propiedades de navegación valorada como colección pueden devolver datos en caché para las propiedades que no reflejan cambios recientes. Se recomienda usar el encabezado If-None-Match con valor null para reemplazar el almacenamiento en la memoria caché del explorador. Más información: Encabezados HTTP para obtener más detalles.

La siguiente tabla describe las opciones de consulta qu epuede aplicar en ciertass opciones $expand:

Opción Descripción
$select Seleccione qué propiedades se devuelven. Más información: Seleccionar columnas
$filter Para las propiedades de navegación con valor de colección, limite los registros devueltos. Más información: Filtrar filas
$orderby Para las propiedades de navegación con valor de colección, controle el orden de los registros devueltos. No es compatible con $expand anidado. Más información: $expand anidado en propiedades de navegación valorada en una colección
$top Para las propiedades de navegación con valor de colección, limite el número de registros devueltos. No es compatible con $expand anidado. Más información: $expand anidado en propiedades de navegación valorada en una colección
$expand Expanda las propiedades de navegación en el conjunto de entidades relacionadas. El uso de $expand en $expand se llama $expand anidado. Más información: Expansión anidada de propiedades de navegación de un único valor y $expand anidado en propiedades de navegación con valor de colección

Estas opciones son un subconjunto de las opciones de consulta descritas en la sección 11.2.4.2.1 Opciones de ampliación de OData versión 4.0 parte 1, Protocol Plus Errata 02. Las opciones $skip, $count, $search y $levels no se admiten para la API web de Dataverse.

Use estas opciones con $expand agregándolas entre paréntesis después del nombre de la propiedad de navegación. Separe cada opción con punto y coma (;).

Por ejemplo, la siguiente consulta:

  • Solicita la propiedad account.name

  • Une la solicitud de propiedad de navegación con valor de colección AccountTasks:

    • La propiedad task.subject
    • Donde task.subject contiene la cadena "Task"
    • Ordenado por la fecha task.createdon de forma descendente
/accounts?$select=name&$expand=Account_Tasks($select=subject;$filter=contains(subject,'Task');$orderby=createdon desc)

Limitar columnas con $select

Como con cualquier consulta, siempre limite las columnas devueltas usando $select cuando use $expand. Por ejemplo, la siguiente solicitud devuelve los valores contact.fullname y task.subject en los resultados expandidos del tipo de entidad account:

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)
Prefer: odata.maxpagesize=1
If-None-Match: null
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Respuesta:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=1

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
            },
            "Account_Tasks": [
                {
                    "@odata.etag": "W/\"80649460\"",
                    "subject": "Task 1 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "f68393c1-34cb-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Es importante recordar que hay dos tipos de propiedades de navegación. Más información: Propiedades de navegación de la API web

  • Las propiedades de navegación de un solo valor corresponden a atributos de búsqueda que admiten relaciones de varios a uno y permiten establecer una referencia a otro registro.

  • Las propiedades de navegación valoradas como colección corresponden a relaciones de uno a varios o de varios a varios.

Expandir una propiedad de navegación con valor de colección puede hacer que el tamaño de la respuesta sea grande en formas difíciles de anticipar. Es importante que incluya límites para controlar la cantidad de datos que se devuelven. Puede limitar el número de registros utilizando la paginación. Más información: Página de resultados

Hay una diferencia significativa en cómo se aplica la paginación a las opciones $expand anidadas que se aplican a las propiedades de navegación con valor de colección. Más información: Expandir propiedades de navegación con valor de colección

Expandir propiedades de navegación de un solo valor

El siguiente ejemplo demuestra cómo recuperar registros de contacto, incluido el contacto principal y el usuario que creó los registros.

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)  
Prefer: odata.maxpagesize=2
If-None-Match: null
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Respuesta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0  
  
{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(contactid,fullname),createdby(fullname))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "fullname": "Susanna Stubberod (sample)"
            },
            "createdby": {
                "fullname": "System Administrator",
                "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
            }
        },
        {
            "@odata.etag": "W/\"80649580\"",
            "name": "Adventure Works (sample)",
            "accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd",
                "fullname": "Nancy Anderson (sample)"
            },
            "createdby": {
                "fullname": "System Administrator",
                "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

La propiedad de navegación de valor único createdby devuelve una instancia de systemuser EntityType. Se devuelven las propiedades systemuserid y ownerid. Esto se debe a que systemuser hereda de EntityType principal y comparte la clave principal ownerid con EntityType de equipo a través de esta herencia.

Sin embargo, la tabla Usuario (SystemUser) tiene la clave principal de SystemUserId. Ambas propiedades systemuserid y ownerid tienen el mismo valor. Más información: Herencia EntityType

Devolver referencias

En lugar de devolver datos, también puede devolver referencias o vínculos a los registros relacionados expandiendo la propiedad de navegación de un solo valor con la opción /$ref. El siguiente ejemplo devuelve objetos JSON con una propiedad @odata.id que tiene una URL para cada contacto principal.

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid/$ref  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Respuesta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0  
  
{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid,primarycontactid/$ref())",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "@odata.id": "[Organization URI]/api/data/v9.2/contacts(70bf4d48-34cb-ed11-b596-0022481d68cd)"
            }
        },
        {
            "@odata.etag": "W/\"80649580\"",
            "name": "Adventure Works (sample)",
            "_primarycontactid_value": "72bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "@odata.id": "[Organization URI]/api/data/v9.2/contacts(72bf4d48-34cb-ed11-b596-0022481d68cd)"
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid/$ref&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Solo puede usar la opción /$ref con propiedades de navegación de un único valor. Si la usa con una propiedad de navegación con valor de colección, obtiene el error siguiente:

{
    "error": {
        "code": "0x80060888",
        "message": "Expand with $ref is only supported on lookup type navigation property."
    }
}

Expansión anidada de propiedades de navegación de un único valor

Puede expandir las propiedades de navegación de un único valor a varios niveles, anidando una opción $expand en otra opción $expand.

La siguiente consulta devuelve registros de task y expande el contact relacionado, la account relacionada con el contact y el systemuser que creó el registro account:

Solicitud:

GET [Organization URI]/api/data/v9.2/tasks?$select=subject
&$expand=regardingobjectid_contact_task($select=fullname;
 $expand=parentcustomerid_account($select=name;
  $expand=createdby($select=fullname)))  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Respuesta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0 

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#tasks(subject,regardingobjectid_contact_task(fullname,parentcustomerid_account(name,createdby(fullname))))",
    "value": [
        {
            "@odata.etag": "W/\"80730855\"",
            "subject": "Task 1 for Susanna Stubberod",
            "activityid": "e9a8c72c-dbcc-ed11-b597-000d3a993550",
            "regardingobjectid_contact_task": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "parentcustomerid_account": {
                    "name": "Litware, Inc. (sample)",
                    "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
                    "createdby": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            }
        },
        {
            "@odata.etag": "W/\"80730861\"",
            "subject": "Task 2 for Susanna Stubberod",
            "activityid": "c206f534-dbcc-ed11-b597-000d3a993550",
            "regardingobjectid_contact_task": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "parentcustomerid_account": {
                    "name": "Litware, Inc. (sample)",
                    "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
                    "createdby": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/tasks?$select=subject&$expand=regardingobjectid_contact_task($select=fullname;$expand=parentcustomerid_account($select=name;$expand=createdby($select=fullname)))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bC206F534-DBCC-ED11-B597-000D3A993550%257d%2522%2520first%253d%2522%257bE9A8C72C-DBCC-ED11-B597-000D3A993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Expandir propiedades de navegación valoradas como colección

Hay algunas diferencias importantes en la respuesta que dependen de si usa anidado $expand con una propiedad de navegación con valor de colección en cualquier parte de su consulta.

$expand anidado $expand único
Paging Paginación en filas expandidas. Paginación solo en recurso de EntitySet. Las direcciones URL <property name>@odata.nextLink de las filas expandidas no incluyen información de paginación.
Se admiten $top o $orderby No Sí

$expand único en propiedades de navegación valoradas como colección

Si usa solo un nivel $expand, no se aplica paginación a las filas expandidas. Si incluye el encabezado de solicitud Prefer: odata.maxpagesize, la paginación solo se aplica al recurso de EntitySet de la consulta.

Cada propiedad de navegación expandida con valor de colección devuelve una URL <property>@odata.nextLink que no incluye información de paginación. Es una URL que representa la colección filtrada para la relación con las opciones de consulta adjuntas. Puede usar esa URL para enviar una solicitud GET por separado y devuelve las mismas filas que se devolvieron en su solicitud original. Puede aplicar paginación a esa solicitud.

Debido a que no se aplica paginación a los registros expandidos, se pueden devolver hasta 5000 registros relacionados por cada propiedad de navegacion con valor de colección expandida. Dependiendo de sus datos y la consulta, podría ser una gran cantidad de datos. Devolver esa cantidad de datos podría afectar el rendimiento y posiblemente provocar que se agote el tiempo de espera de su solicitud. Tenga cuidado con las consultas que redacta. Puede usar las opciones $top, $filter y $orderby para controlar el número total de registros devueltos.

El siguiente ejemplo incluye una sola expansión de Account_Tasks y contact_customer_accounts mientras recupera registros de cuenta. El encabezado de solicitud Prefer: odata.maxpagesize=1 garantiza que solo se devuelva un registro de cuenta en la primera página.

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)
Prefer: odata.maxpagesize=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
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0 

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "Account_Tasks": [
                {
                    "@odata.etag": "W/\"80730894\"",
                    "subject": "Task 1 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
                },
                {
                    "@odata.etag": "W/\"80730903\"",
                    "subject": "Task 2 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "605dbd65-e2cc-ed11-b597-000d3a993550"
                },
                {
                    "@odata.etag": "W/\"80730909\"",
                    "subject": "Task 3 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "a718856c-e2cc-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject",
            "contact_customer_accounts": [
                {
                    "@odata.etag": "W/\"80648695\"",
                    "fullname": "Susanna Stubberod (sample)",
                    "_parentcustomerid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
                }
            ],
            "contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Compare esta respuesta con el siguiente ejemplo, que incluye un anidado $expand. Desplace la respuesta de ejemplo horizontalmente para ver que solo la URL @odata.nextLink del resultado de la cuenta contiene información de paginación.

$expand anidado en propiedades de navegación valoradas como colección

Si usa un $expand anidado en cualquier parte de su consulta y ha incluido el encabezado de solicitud Prefer: odata.maxpagesize, la paginación se aplica a cada una de las colecciones expandidas.

Cada propiedad de navegación expandida con valor de colección devuelve una URL <property>@odata.nextLink que incluye información de paginación. Puede usar esa URL para enviar una solicitud GET por separado y devolverá el siguiente conjunto de registros que no se incluyeron en su solicitud original.

No puede usar las opciones $top o $orderby para limitar la cantidad total de registros devueltos con un $expand anidado. Se devuelve el siguiente error si utiliza estas opciones:

{
    "error": {
        "code": "0x80060888",
        "message": "Only $select and $filter clause can be provided while doing $expand on many-to-one relationship or nested one-to-many relationship."
    }
}

El siguiente ejemplo se basa en el ejemplo anterior y utiliza los mismos datos. La única diferencia es la adición en la URL de este $expand anidado en una propiedad de navegación de un solo valor para devolver el usuario propietario del contacto: ;$expand=owninguser($select=fullname).

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname;
$expand=owninguser($select=fullname))
Prefer: odata.maxpagesize=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
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0 

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname,owninguser(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "Account_Tasks": [
                {
                    "subject": "Task 1 for Litware",
                    "activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject,description&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520first%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E",
            "contact_customer_accounts": [
                {
                    "fullname": "Susanna Stubberod (sample)",
                    "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                    "owninguser": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            ],
            "contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname&$expand=owninguser($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject,description),contact_customer_accounts($select=fullname;$expand=owninguser($select=fullname))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Compare esta respuesta con el ejemplo anterior, que no incluye un anidado $expand. En esta respuesta, el encabezado de solicitud Prefer: odata.maxpagesize=1 se aplica a lo sregistros task devueltos con Account_Tasks. Solo se devuelve una tarea en lugar de tres. La URL Account_Tasks@odata.nextLink devuelve las siguientes dos tareas. Desplace la respuesta de ejemplo horizontalmente para ver que las direcciones URL Account_Tasks@odata.nextLink, contact_customer_accounts@odata.nextLink y@odata.nextLink contienen información de paginación.

Ordenar filas

Use la opción de consulta $orderby para especificar el orden en el que se devuelven los elementos. Use el sufijo asc o desc para especificar orden ascendente o descendente, respectivamente. El predeterminado es ascendente. El ejemplo siguiente recupera las propiedades name y revenue de las cuentas, ordenadas por orden de revenue ascendente y por name descendente:

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

Filtrar filas

Utilice la opción de consulta $filter para filtrar una colección de recursos.

Dataverse evalúa cada recurso de la colección mediante el conjunto de expresiones para $filter. Solo se devuelven en la respuesta los registros en los que la expresión se evalúa como true. Los registros no se devuelven si la expresión se evalúa como false o null, o si el usuario no tiene acceso de lectura al registro.

La siguiente tabla describe los operadores y funciones que puede usar en expresiones $filter.

Descripción Más información
Operadores de comparación Use los operadores eq,ne,gt,ge,lt, y le para comparar una propiedad y un valor. Operadores de comparación
Operadores lógicos Use and, or y not para crear expresiones más complejas. Operadores lógicos
Agrupación de operadores Use paréntesis: (), para especificar la precedencia para evaluar una expresión compleja. Agrupación de operadores
Funciones de consulta de OData Evaluar valores de cadena usando las funciones contains, endswith y startswith Usar funciones de consulta de OData
Funciones de consulta de Dataverse Utilice más de 60 funciones especializadas diseñadas para aplicaciones comerciales. Funciones de consulta de Dataverse
Expresiones Lambda Cree expresiones basadas en valores de colecciones relacionadas. Filtrar usando valores de colecciones relacionadas

Si usa una propiedad de búsqueda en un $filter, también puede usar una colección filtrada con la propiedad de navegación con valor de colección correspondiente. Por ejemplo, estas dos consultas devuelven los mismos resultados:

accounts?$filter=_owninguser_value eq '<systemuserid value>'&$select=name

systemusers(<systemuserid value>)/user_accounts?$select=name

Operadores de comparación

La siguiente tabla describe los operadores que puede usar para comparar una propiedad y un valor.

Operator Descripción Ejemplo
eq Es igual a $filter=revenue eq 100000
ne No es igual a $filter=revenue ne 100000
gt Mayor que $filter=revenue gt 100000
ge Mayor o igual que $filter=revenue ge 100000
lt Menor que $filter=revenue lt 100000
le Menor o igual que $filter=revenue le 100000

Comparación de columnas

Puede utilizar operadores de comparación para comparar valores de propiedad en la misma fila. Solo se pueden usar operadores de comparación para comparar valores en la misma fila, y los tipos de columna deben coincidir. Por ejemplo, la siguiente consulta devuelve todos los contactos donde firstname es igual a lastname:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$filter=firstname eq lastname

Operadores lógicos

La siguiente tabla describe los operadores lógicos que puede usar para crear expresiones más complejas.

Operator Descripción Ejemplo
and Lógico y $filter=revenue lt 100000 and revenue gt 2000
or Disyunción lógica $filter=contains(name,'(sample)') or contains(name,'test')
not Negación lógica $filter=not contains(name,'sample')

Agrupación de operadores

Use paréntesis: () con operadores lógicos para especificar la precedencia para evaluar una expresión compleja; por ejemplo:

$filter=(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Funciones de consulta de Dataverse

Utilice más de 60 funciones especializadas diseñadas para aplicaciones comerciales. Estas funciones proporcionan capacidades especiales, como se describe en la siguiente tabla.

Grupo Funciones
Fechas InFiscalPeriod, InFiscalPeriodAndYear, InFiscalYear, InOrAfterFiscalPeriodAndYear, InOrBeforeFiscalPeriodAndYear,
Last7Days, LastFiscalPeriod, LastFiscalYear, LastMonth, LastWeek, LastXDays, LastXFiscalPeriods, LastXFiscalYears,
LastXHours, LastXMonths, LastXWeeks, LastXYears, LastYear, Next7Days, NextFiscalPeriod, NextFiscalYear,
NextMonth, NextWeek, NextXDays, NextXFiscalPeriods, NextXFiscalYears, NextXHours, NextXMonths,
NextXWeeks, NextXYears, NextYear, OlderThanXDays, OlderThanXHours, OlderThanXMinutes, OlderThanXMonths,
OlderThanXWeeks, OlderThanXYears, On, OnOrAfter, OnOrBefore, ThisFiscalPeriod, ThisFiscalYear, ThisMonth, ThisWeek, ThisYear, Today, Tomorrow, Yesterday
Valores de id. EqualBusinessId, EqualUserId, NotEqualBusinessId, NotEqualUserId
Jerarquía Above, AboveOrEqual, EqualUserOrUserHierarchy, EqualUserOrUserHierarchyAndTeams, EqualUserOrUserTeams,
EqualUserTeams, NotUnder, Under, UnderOrEqual
Más información: Consultar datos jerárquicos
Columnas de elecciones ContainValues, DoesNotContainValues
Más información: Consultar datos a partir de opciones
Entre Between, NotBetween
En In, NotIn
Lenguaje EqualUserLanguage

Nota

La funcioń Contains es para usar con columnas que tienen indexación de texto completo. Solo la tabla Dynamics 365 KBArticle (artículo) tiene columnas que tienen indexación de texto completo. Use en su lugar la función contains de OData.

Web API Query Function Reference tiene la lista completa. Cada artículo proporciona un ejemplo de sintaxis que puede copiar.

Debe usar el nombre completo de la función y agregar el espacio de nombres del servicio (Microsoft.Dynamics.CRM) al nombre de la función.

Cada función tiene un parámetro PropertyName que especifica la propiedad a evaluar. La función puede tener más parámetros, como PropertyValue, PropertyValues o PropertyValue1 y PropertyValue2. Cuando existen estos parámetros, debe proporcionar un valor o valores para comparar con el parámetro PropertyName.

El siguiente ejemplo muestra los usos de la función Between para buscar cuentas con entre 5 y 2000 empleados.

GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

Filtrar usando valores de cadena

Tenga en cuenta los siguientes puntos cuando filtre valores de cadena:

URL codifica los caracteres especiales

Si la cadena que está utilizando como valor en una función de filtro incluye un carácter especial, debe codificarlo como URL. Por ejemplo, si usa esta función: contains(name,'+123'), no funcionará porque + es un carácter que no se puede incluir en una URL. Si codifica la cadena como URL, se convertirá en contains(name,'%2B123') y obtendrá resultados donde el valor de la columna contiene +123.

La siguiente tabla muestra los valores codificados de URL para caracteres especiales comunes.

Especial
carácter		 URL de codificación
carácter
$ %24
& %26
+ %2B
, %2C
/ %2F
: %3A
; %3B
= %3D
? %3F
@ %40

Usar caracteres comodín

Al componer filtros usando cadenas, puede aplicar los siguientes caracteres comodín:

Caracteres Descripción Documentación y ejemplos de T-SQL
% Coincide con cualquier cadena de cero o más caracteres. Este carácter comodín se puede utilizar como prefijo o como sufijo. Carácter de porcentaje (Comodín - Caracteres que deben coincidir) (Transact-SQL)
_ Utilice el carácter de subrayado para hacer coincidir cualquier carácter único en una operación de comparación de cadenas que implique la coincidencia de patrones. _ (Comodín - Coincidir con un carácter) (Transact-SQL)
[] Hace que coincida con cualquier carácter único dentro del rango o conjunto especificado que se especifica entre paréntesis. [ ] (Comodín - Coincidir con caracteres) (Transact-SQL)
[^] Hace que coincida con cualquier carácter único que no esté dentro del rango o conjunto especificado que se especifica entre paréntesis cuadrados. [^] (Comodín - Los caracteres no coinciden) (Transact-SQL)

Más información: Usar caracteres comodín en condiciones para valores de cadena

No se admiten comodines finales

Es importante no utilizar comodines finales porque no se admiten. Las consultas que utilizan estos antipatrones presentan problemas de rendimiento porque las consultas no se pueden optimizar. Estos son algunos ejemplos de comodines finales:

startswith(name,'%value')
endswith(name,'value%')

Usar funciones de consulta de OData

La siguiente tabla describe las funciones de consulta de OData que puede usar para filtrar valores de cadena:

Function Ejemplo
contains $filter=contains(name,'(sample)')
endswith $filter=endswith(name,'Inc.')
startswith $filter=startswith(name,'a')

Puede usar estas funciones con el operador lógico not para negar el resultado.

Administrar comillas simples

Algunos filtros aceptan una matriz de valores de cadena, como la función In Query. Al especificar valores en estos filitros que contienen una comilla o apóstrofo, como O'Brian o Men's clothes, debe usar comillas dobles alrededor de los valores, por ejemplo:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=Microsoft.Dynamics.CRM.In(PropertyName=@p1,PropertyValues=@p2)
&@p1='lastname'
&@p2=["OBrian","OBryan","O'Brian","O'Bryan"]

Si no lo hace, obtiene el siguiente error:Invalid JSON. A comma character ',' was expected in scope 'Array'. Every two elements in an array and properties of an object must be separated by commas.

Si el filtro es para un solo valor, reemplace el carácter de comilla simple con dos caracteres de comilla simple consecutivos; por ejemplo:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=lastname eq 'O''Bryan'

Si no lo hace, obtiene un error como este: There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.

Puede filtrar las filas devueltas en función de los valores de las tablas relacionadas. La forma de filtrar depende del tipo de relación.

Filtrar usando valores de propiedad de columna de búsqueda

Puede filtrar en función de los valores en las propiedades de navegación de un solo valor que representan las columnas de búsqueda. Use este patrón:

<single-valued navigation property>/<property name>

El siguiente ejemplo devuelve registros de cuentas en función del valor de la columna primarycontactid/fullname:

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/fullname eq 'Susanna Stubberod (sample)'
&$select=name,_primarycontactid_value
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,_primarycontactid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

También puede comparar valores más arriba en la jerarquía de propiedades de navegación de un solo valor.

El siguiente ejemplo devuelve la primera cuenta donde el registro de contacto representa primarycontactid, donde 'System Administrador' creó el registro, usando primarycontactid/createdby/fullname en el $filter.

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/createdby/fullname eq 'System Administrator'
&$select=name,_primarycontactid_value
&$expand=primarycontactid(
$select=fullname,_createdby_value;
$expand=createdby($select=fullname))
&$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,_primarycontactid_value,primarycontactid(fullname,_createdby_value,createdby(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "_createdby_value@OData.Community.Display.V1.FormattedValue": "System Administrator",
                "_createdby_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "createdby": {
                    "fullname": "System Administrator",
                    "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                    "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                }
            }
        }
    ]
}

Utilice los operadores Lambda any y all para evaluar valores en una colección para filtrar los resultados.

  • any: devuelve true si la expresión booleana aplicada es true para cualquier miembro de la colección; si no, devuelve false. El operador any sin un argumento devuelve true si la colección no está vacía.
  • all: devuelve true se la expresión booleana aplicada es true todos los miembros de la colección; si no, devuelve false.

La sintaxis tiene el siguiente aspecto:

<collection>/[any | all](o:<expression to evaluate>)

En este caso, o es la variable que representa los elementos de la colección. La convención es usar la primera letra del tipo. En la expresión, utilice o/<property or collection name> para hacer referencia a una propiedad o colección de un elemento determinado.

Puede incluir condiciones en varias propiedades de navegación con valores de colección y colecciones anidadas. No puede incluir condiciones en las propiedades de navegación con valores de colección que están anidadas en una propiedad de navegación de búsqueda. Por ejemplo, $filter=primarycontactid/new_contact_account/any(a:a/accountid eq '{GUID}') no se admite.

Más información: Usar operadores Lambda en odata.org

Ejemplos de operadores Lambda

El ejemplo siguiente recupera todos los registros de cuenta de cuenta que tienen al menos un correo electrónico con “sometext” en el asunto:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext'))
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

El ejemplo a continuación recupera todos los registros de entidad de cuenta que tienen todas las tareas asociadas cerradas:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(t:t/statecode eq 1)
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

El ejemplo a continuación recupera todos los registros de entidad de cuenta que tienen al menos un correo electrónico con “sometext” en el asunto y cuyo código de estado es activo:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext') and 
e/statecode eq 0)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

El siguiente ejemplo crea una consulta anidada usando los operadores any y all:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=(contact_customer_accounts/any(c:c/jobtitle eq 'jobtitle' and 
c/opportunity_customer_contacts/any(o:o/description ne 'N/A'))) and 
endswith(name,'Inc.')
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Resultados de página

Utilice el encabezado de solicitud Prefer: odata.maxpagesize para controlar la cantidad de registros devueltos. Si no especifica un número, se pueden devolver hasta 5000 registros por cada solicitud. No puede solicitar un tamaño de página superior a 5000.

Nota

Dataverse no admite la opción de consulta $skip, por lo que no puede usar la combinación de $top y $skip para la paginación. Para obtener más información: Usar la opción de consulta $top

El siguiente ejemplo devuelve solo los dos primeros registros de contacto:

Solicitud:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2

Respuesta:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
    "value": [
        {
            "@odata.etag": "W/\"72201545\"",
            "fullname": "Yvonne McKay (sample)",
            "contactid": "49b0be2e-d01c-ed11-b83e-000d3a572421"
        },
        {
            "@odata.etag": "W/\"80648695\"",
            "fullname": "Susanna Stubberod (sample)",
            "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Cuando hay más registros de los solicitados, la anotación @odata.nextLink proporciona una URL que puede usar con GET para devolver la siguiente página de datos, como se muestra en el siguiente ejemplo:

Solicitud:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2

Respuesta:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
    "value": [
        {
            "@odata.etag": "W/\"80648710\"",
            "fullname": "Nancy Anderson (sample)",
            "contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd"
        },
        {
            "@odata.etag": "W/\"80648724\"",
            "fullname": "Maria Campbell (sample)",
            "contactid": "74bf4d48-34cb-ed11-b596-0022481d68cd"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%223%22%20pagingcookie=%22%253ccookie%2520page%253d%25222%2522%253e%253ccontactid%2520last%253d%2522%257bF2318099-171F-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257bBB55F942-161F-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Debe almacenar en caché los resultados devueltos o el valor de URL @odata.nextLink y utilizarlos para volver a las páginas anteriores.

No cambie el valor de la URL @odata.nextLink ni le anexe opciones de consulta. Para cada solicitud posterior de páginas adicionales, debe usar el mismo valor de preferencia de odata.maxpagesize que usó en la solicitud original. Puede continuar paginando los datos hasta que no se incluya ninguna anotación @odata.nextLink en los resultados.

En los ejemplos anteriores, la información codificada se estableció como el valor del parámetro $skiptoken en el valor de URL @odata.nextLink. El servidor establece esta información codificada para controlar la paginación. No debe modificar la información codificada ni codificarla más. Utilice el valor de URL proporcionado para recuperar la página siguiente.

Usar la opción de consulta $top

Use la opción de consulta $top para limitar el número de resultados devueltos. No use $top con el encabezado de solicitud Prefer: odata.maxpagesize. Si incluye ambos, $top se ignora.

El siguiente ejemplo solo devuelve las primeras tres filas de cuenta:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=3

Agregar datos

Use la opción $apply para agregar y agrupar los datos dinámicamente.

Las funciones agregadas están limitados a una colección de 50.000 registros. La información adicional acerca de usar la funcionalidad agregada con Dataverse se puede encontrar aquí: Agregar datos mediante FetchXml.

Puede encontrar más información sobre la agregación de datos de OData aquí: Extensión de OData para la versión 4.0 de agregación de datos. Dataverse solo admite un subconjunto de estos métodos agregados.

Nota

  • No se admite groupby con los valores datetime.

  • No se admite $orderby con valores agregados. Esto devolverá el error: The query node SingleValueOpenPropertyAccess is not supported.

Estos son algunos ejemplos:

Estos ejemplos no muestran la solicitud y la respuesta completas por motivos de brevedad.

Lista de estados únicos en la consulta

GET accounts?$apply=groupby((statuscode))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Cuerpo de respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2
        }
    ]
}

Recuento por valores de estado

GET accounts?$apply=groupby((statuscode),aggregate($count as count))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Cuerpo de respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "count@OData.Community.Display.V1.FormattedValue": "8",
            "count": 8
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "count@OData.Community.Display.V1.FormattedValue": "1",
            "count": 1
        }
    ]
}

Suma agregada de ingresos

GET accounts?$apply=aggregate(revenue with sum as total)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Cuerpo de respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "total@OData.Community.Display.V1.FormattedValue": "$440,000.00",
            "total": 440000.000000000
        }
    ]
}

Ingresos medios basados en el estado

GET accounts?$apply=groupby((statuscode),aggregate(revenue with average as averagevalue))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Cuerpo de respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "averagevalue@OData.Community.Display.V1.FormattedValue": "$53,750.00",
            "averagevalue": 53750.000000000
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "averagevalue@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "averagevalue": 10000.000000000
        }
    ]
}

Suma de los ingresos basados en el estado

GET accounts?$apply=groupby((statuscode),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Cuerpo de respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "total@OData.Community.Display.V1.FormattedValue": "$430,000.00",
            "total": 430000.000000000
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "total": 10000.000000000
        }
    ]
}

Recuento total de ingresos por nombre de contacto principal

GET accounts?$apply=groupby((primarycontactid/fullname),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Cuerpo de respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "total": 10000.000000000,
            "contact_fullname": "Jim Glynn (sample)"
        },
        {
            "total@OData.Community.Display.V1.FormattedValue": "$80,000.00",
            "total": 80000.000000000,
            "contact_fullname": "Maria Campbell (sample)"
        },
      ... <truncated for brevity>
      
    ]
}

Nombres de contacto primario para cuentas de “WA”

GET accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))

Cuerpo de respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "contact_fullname": "Rene Valdes (sample)"
        },
        {
            "contact_fullname": "Robert Lyon (sample)"
        },
        {
            "contact_fullname": "Scott Konersmann (sample)"
        }
    ]
}

Fecha y hora de registro creado por última vez

GET accounts?$apply=aggregate(createdon with max as lastCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Cuerpo de respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "lastCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
            "lastCreate": "2023-03-25T17:42:47Z"
        }
    ]
}

Fecha y hora de registro creado por primera vez

GET accounts?$apply=aggregate(createdon with min as firstCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Cuerpo de respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "firstCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
            "firstCreate": "2023-03-25T17:42:46Z"
        }
    ]
}

Recuento del número de filas

Use la opción de consulta $count=true para incluir un recuento de entidades que coincidan con los criterios de filtro, hasta 5000.

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=accountid&$count=true
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Respuesta:

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(accountid)",
    "@odata.count": 9,
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        },
        ... <Truncated for brevity>
    ]
}

La anotación de respuesta @odata.count contiene el número de filas, hasta 5000, que coinciden con los criterios de filtro con independencia del tamaño de página seleccionado.

Nota

Si desea recuperar una instantánea de las últimas 24 horas del número total de filas de una tabla más allá de 5000, use la función RetrieveTotalRecordCount.

Si el valor del recuento es 5000 y quiere saber si el recuento es exactamente 5000 o mayor que 5000, puede agregar el siguiente encabezado:

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.totalrecordcount,Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded"

Este encabezado agrega las siguientes anotaciones al resultado:

  • @Microsoft.Dynamics.CRM.totalrecordcount
  • @Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded

Cuando se use con la opción de consulta $count=true y haya más de 5000 registros, se devuelven los siguientes valores:

"@odata.count": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,

Si hay menos de 5000 registros, se devuelve el recuento real.

"@odata.count": 58,
"@Microsoft.Dynamics.CRM.totalrecordcount": 58,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,

Si no incluye la opción $count=true, el valor @Microsoft.Dynamics.CRM.totalrecordcount total será -1.

El siguiente ejemplo muestra que hay 10 cuentas que coinciden con $filter, pero solo se devuelven las tres primeras cuentas:

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name?
&$filter=contains(name,'sample')
&$count=true  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Prefer: odata.maxpagesize=3
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.*"

Respuesta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.maxpagesize=3
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.*"
  
{  
   "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name)",
   "@odata.count":10,
   "@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
   "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,
   "value":[  
      {  
         "@odata.etag":"W/\"502482\"",
         "name":"Fourth Coffee (sample)",
         "accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {  
         "@odata.etag":"W/\"502483\"",
         "name":"Litware, Inc. (sample)",
         "accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {  
         "@odata.etag":"W/\"502484\"",
         "name":"Adventure Works (sample)",
         "accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
      }
   ],
   "@odata.nextLink":"[Organization URI]/api/data/v9.2/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Para obtener solo un número que represente el conteo de una colección, agregue /$count, como en el siguiente ejemplo:

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts/$count  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Respuesta:

HTTP/1.1 200 OK  
Content-Type: text/plain  
OData-Version: 4.0  
  
10

Consulte también

Buscar registros de Dataverse
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