Nota
L'accés a aquesta pàgina requereix autorització. Pots provar d'iniciar sessió o canviar de directori.
L'accés a aquesta pàgina requereix autorització. Pots provar de canviar directoris.
Use la $filteropción de consulta OData para filtrar una colección de recursos.
Dataverse evalúa cada recurso de la colección mediante el conjunto de expresiones para $filter. La respuesta solo incluye registros en los que la expresión se evalúa como true. Los registros no se incluyen 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 | Evalúe los valores de cadena utilizando 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 |
Operadores de comparación
La siguiente tabla describe los operadores que puede usar para comparar una propiedad y un valor.
| Operador | 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 puede usar operadores de comparación para comparar valores de 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.
| Operador | 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 prioridad 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.
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 PropertyName parámetro que especifica la propiedad que se va a evaluar. La función puede tener más parámetros, como PropertyValue, PropertyValueso PropertyValue1 y PropertyValue2. Cuando existan estos parámetros, proporcione un valor o valores para compararlos con el PropertyName parámetro .
En el ejemplo siguiente se muestra cómo usar 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 mediante valores de cadena
Tenga en cuenta los siguientes puntos al filtrar mediante valores de cadena:
- Todos los filtros que usan valores de cadena no distinguen mayúsculas de minúsculas.
- Debe codificar como URL los caracteres especiales en los criterios de filtro. Para obtener más información, consulte Codificación url de caracteres especiales.
- Puede usar caracteres comodín, pero evite usarlos de manera incorrecta. Para obtener más información, consulte Uso de caracteres comodín.
- Puede utilizar las funciones de consulta de OData:
contains,startswithyendswith. Para obtener más información, consulte Uso de funciones de consulta de OData. - Debe administrar comillas simples cuando use filtros que acepten una matriz de valores de cadena. Para obtener más información, consulte Gestión de comillas simples.
URL codifica los caracteres especiales
Si la cadena que usa como valor en una función de filtro incluye un carácter especial, debe codificarlo por url. Por ejemplo, si usa esta función: contains(name,'+123'), no funciona porque + es un carácter que no se puede incluir en una dirección URL. Si codifica la cadena en la URL, se convierte en contains(name,'%2B123') y obtiene 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 crear filtros mediante cadenas, puede usar 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. Utilice este carácter comodín como prefijo o 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) |
[] |
Coincide con cualquier carácter único dentro del intervalo o conjunto especificado que especifique entre corchetes. | [ ] (Comodín - Coincidir con caracteres) (Transact-SQL) |
[^] |
Coincide con cualquier carácter único que no esté dentro del rango o conjunto que se especifique entre los corchetes. | [^] (Comodín - Los caracteres no coinciden) (Transact-SQL) |
Para obtener más información, consulte Usar caracteres comodín en condiciones para valores de cadena.
No se admiten caracteres comodín iniciales
No use caracteres comodín iniciales porque no se admiten. Las consultas que utilizan estos antipatrones presentan problemas de rendimiento porque las consultas no se pueden optimizar. He aquí algunos ejemplos de comodines iniciales:
startswith(name,'%value')
endswith(name,'value%')
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:
| Function | Ejemplo |
|---|---|
contains |
$filter=contains(name,'(sample)') |
endswith |
$filter=endswith(name,'Inc.') |
startswith |
$filter=startswith(name,'a') |
Use estas funciones con el operador not lógico para negar el resultado.
Administrar comillas simples
Algunos filtros aceptan una matriz de valores de cadena, como la función In Query. Cuando se especifican valores en estos filtros que contienen comillas simples, o apóstrofo, caracteres, como O'Brian o Men's clothes, se usan 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.
Filtro sobre la propiedad de búsqueda
En el caso de las relaciones uno a varios, una colección filtrada devuelve los mismos resultados que el uso de una eq$filter propiedad Lookup 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 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.
En el ejemplo siguiente se devuelve la primera cuenta donde el registro de contacto representa el primarycontactid, donde "Administrador del sistema" creó el registro, mediante primarycontactid/createdby/fullname en $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 Lambdaany y all para evaluar valores en una colección para filtrar los resultados.
any: devuelvetruesi la expresión booleana aplicada es true para cualquier miembro de la colección; si no, devuelve false.- El operador
anysin un argumento devuelvetruesi la colección no está vacía.
- El operador
all: devuelve true si 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 cuenta que tengan 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 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 siguiente ejemplo recupera todos los registros de cuenta que tengan al menos un correo electrónico con "algúntexto" en el asunto y cuyo código de estado sea 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
Puede incluir hasta 500 condiciones totales en una consulta. De lo contrario, verá este mensaje de 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 que pueda reducir el número de condiciones mediante 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.