Filtrar filas usando OData

Utilice la $filter opción de consulta 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.

Operadores de comparación

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

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.

Agrupación de operadores

Utilice 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.

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

Debe utilizar el nombre completo de la función y agregar el espacio de nombres de 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:

• Todos los filtros que usen valores de cadena distinguen mayúsculas de minúsculas.
• Debe codificar como URL los caracteres especiales en los criterios de filtro. Más información: codificar caracteres especiales de URL
• Puedes utilizar caracteres comodín, pero evita utilizarlos incorrectamente. Más información: Uso de caracteres comodín
• Puede utilizar las funciones de consulta de OData: contains, startswith y endswith. Más información: Usar las funciones de consulta de OData
• Debe administrar comillas simples cuando use filtros que acepten una matriz de valores de cadena. Más información: Administrar comillas simples

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.

Usar caracteres comodín

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

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

No se admiten comodines iniciales

Es importante no utilizar el comodín inicial Tarjetas porque no son compatibles. Las consultas que utilizan estos antipatrones presentan problemas de rendimiento porque las consultas no se pueden optimizar. A continuación se muestran algunos ejemplos de comodines principales:

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

Obtenga más información sobre los errores que se devuelven cuando se utilizan comodines iniciales

Usar funciones de consulta de OData

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

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''.

Filtrar en función de los valores de datos relacionados

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 por propiedad de búsqueda

Para Relaciones de uno a muchos, una colección filtrada devuelve los mismos resultados que usar una eq $filter en la propiedad de búsqueda para la relación. Por ejemplo, esta colección filtrada:

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

Es lo mismo que este filtro en una propiedad de búsqueda.

GET [Organization URI]/api/data/v9.2/accounts?$filter=_owninguser_value eq <systemuserid value>&$select=name

Filtrar usando valores de propiedad de columna de búsqueda

Puede filtrar según los valores de las propiedades de navegación de valor único que representan 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 valor único.

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"
                }
            }
        }
    ]
}

Filtrar usando valores de colecciones relacionadas

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 siguiente ejemplo recupera todos los registros de cuentas 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 siguiente ejemplo recupera todos los registros de cuentas 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 siguiente ejemplo recupera todos los registros de cuentas que tienen al menos un correo electrónico con "sometext" en el asunto y cuyo código de estado está 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

Límites de las condiciones

No puede incluir más de 500 condiciones en total en una consulta. De lo contrario, verá este error:

Nombre: TooManyConditionsInQuery
Código: 0x8004430C
Número: -2147204340
Mensaje: Number of conditions in query exceeded maximum limit.

Debe reducir la cantidad de condiciones para ejecutar la consulta. Es posible reducir la cantidad de condiciones utilizando las funciones de consulta In o NotIn , que se pueden usar con números, identificadores únicos y cadenas de hasta 850 caracteres.

Pasos siguientes

Aprenda a paginar resultados.