Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Use a opção $filter de consulta OData para filtrar uma coleção de recursos.
O Dataverse avalia cada recurso na coleção usando o conjunto de expressões para $filter. A resposta inclui apenas registros em que a expressão é avaliada como true. Os registros não serão incluídos se a expressão for avaliada como false ou null, ou se o usuário não tiver acesso de leitura ao registro.
A tabela a seguir descreve os operadores e funções que você pode usar em $filter expressões.
| Description | Mais informações | |
|---|---|---|
| Operadores de comparação | Use os eq,ne,gt,ge,lt, e le operadores para comparar uma propriedade e um valor. |
Operadores de comparação |
| Operadores lógicos | Use and, or e not para criar expressões mais complexas. |
Operadores lógicos |
| Operadores de agrupamento | Use parênteses: (), para especificar a precedência para avaliar uma expressão complexa. |
Operadores de agrupamento |
| Funções de consulta OData | Avalie valores de cadeia de caracteres usando contains, endswithe startswith funções. |
Usar funções de consulta OData |
| Funções de consulta do Dataverse | Use mais de 60 funções especializadas projetadas para aplicativos empresariais. | Funções de consulta do Dataverse |
| Expressões lambda | Crie expressões com base em valores de coleções relacionadas. | Filtrar usando valores de coleções relacionadas |
Operadores de comparação
A tabela a seguir descreve os operadores que você pode usar para comparar uma propriedade e um valor.
| Operator | Description | Example |
|---|---|---|
eq |
Igual | $filter=revenue eq 100000 |
ne |
Não é Igual a | $filter=revenue ne 100000 |
gt |
Maior que | $filter=revenue gt 100000 |
ge |
Maior ou igual | $filter=revenue ge 100000 |
lt |
Menor que | $filter=revenue lt 100000 |
le |
Inferior ou igual | $filter=revenue le 100000 |
Comparação de colunas
Você pode usar operadores de comparação para comparar valores de propriedade na mesma linha. Você só pode usar operadores de comparação para comparar valores na mesma linha e os tipos de coluna devem corresponder. Por exemplo, a consulta a seguir retorna quaisquer contatos em que firstname é igual a lastname:
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$filter=firstname eq lastname
Operadores lógicos
A tabela a seguir descreve os operadores lógicos que você pode usar para criar expressões mais complexas.
| Operator | Description | Example |
|---|---|---|
and |
and lógico | $filter=revenue lt 100000 and revenue gt 2000 |
or |
or lógico | $filter=contains(name,'(sample)') or contains(name,'test') |
not |
Negação lógica | $filter=not contains(name,'sample') |
Operadores de agrupamento
Use parênteses () com operadores lógicos para especificar a precedência para avaliar uma expressão complexa. Por exemplo:
$filter=(contains(name,'sample') or contains(name,'test')) and revenue gt 5000
Funções de consulta do Dataverse
Use mais de 60 funções especializadas projetadas para aplicativos empresariais. Essas funções fornecem recursos especiais, conforme descrito na tabela a seguir.
Observação
A função Contains é usada com colunas que têm indexação de texto completo. Somente a tabela Dynamics 365 KBArticle (artigo) tem colunas que têm indexação de texto completo. Em vez disso, use a função OData contains .
Web API Query Function Reference tem a lista completa. Cada artigo fornece um exemplo de sintaxe que você pode copiar.
Você deve usar o nome totalmente qualificado da função e acrescentar o namespace do Serviço (Microsoft.Dynamics.CRM) ao nome da função.
Cada função tem um PropertyName parâmetro que especifica a propriedade a ser avaliada. A função pode ter mais parâmetros, como PropertyValue, PropertyValuesou .PropertyValue1PropertyValue2 Quando esses parâmetros existirem, forneça um valor ou valores para comparar com o PropertyName parâmetro.
O exemplo a seguir mostra como usar a função Between para pesquisar contas com entre 5 e 2.000 funcionários.
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 cadeia de caracteres
Lembre-se dos seguintes pontos ao filtrar usando valores de cadeia de caracteres:
- Todos os filtros que utilizam valores de texto são insensíveis a maiúsculas e minúsculas.
- Você deve codificar em URL os caracteres especiais nos critérios de filtro. Para obter mais informações, consulte codificar caracteres especiais em URL.
- Você pode usar caracteres curinga, mas evite fazê-lo de forma incorreta. Para obter mais informações, consulte Usar caracteres curinga.
- Você pode usar funções de consulta OData:
contains,startswitheendswith. Para obter mais informações, consulte Usar funções de consulta OData. - Você deve gerenciar aspas únicas ao usar filtros que aceitam uma matriz de valores de cadeia de caracteres. Para obter mais informações, consulte Gerenciar aspas simples.
Codificar caracteres especiais na URL
Se a cadeia de caracteres que você usar como valor em uma função de filtro incluir um caractere especial, será necessário codificar o caractere especial na URL. Por exemplo, se você usar essa função: contains(name,'+123')não funcionará porque + é um caractere que não pode ser incluído em uma URL. Se você codificar a string para a URL, ela se tornará contains(name,'%2B123') e você obterá resultados onde o valor da coluna contém +123.
A tabela a seguir mostra os valores codificados em URL para caracteres especiais comuns.
| Especial caractere |
URL codificada caractere |
|---|---|
$ |
%24 |
& |
%26 |
+ |
%2B |
, |
%2C |
/ |
%2F |
: |
%3A |
; |
%3B |
= |
%3D |
? |
%3F |
@ |
%40 |
Usar caracteres curingas
Ao redigir filtros usando cadeias de caracteres, você pode usar os seguintes caracteres curinga:
| Caracteres | Description | Documentação e exemplos do T-SQL |
|---|---|---|
% |
Corresponde a qualquer cadeia de caracteres de zero ou mais caracteres. Use esse caractere curinga como um prefixo ou sufixo. | Caractere de porcentagem (Curinga – Caracter(es) a Corresponder) (Transact-SQL) |
_ |
Use o caractere de sublinhado para corresponder a qualquer caractere único em uma operação de comparação de cadeia de caracteres que envolva correspondência de padrões. | _ (Curinga - Corresponde a Um Caractere) (Transact-SQL) |
[] |
Corresponde a qualquer caractere único dentro do intervalo ou conjunto especificado que você especificar entre colchetes. | [ ] (Curinga - Caracter(es) a Corresponder) (Transact-SQL) |
[^] |
Corresponde a qualquer caractere único que não esteja dentro do intervalo ou conjunto que você especificar entre os colchetes. | [^] (Curinga - Caracter(es) a Não Corresponder) (Transact-SQL) |
Para obter mais informações, consulte Usar caracteres curinga em condições para valores de cadeia de caracteres.
Não há suporte para caracteres curinga à esquerda
Não use curingas à esquerda porque eles não têm suporte. As consultas que usam esses antipadrões apresentam problemas de desempenho porque as consultas não podem ser otimizadas. Aqui estão alguns exemplos de curingas iniciais:
startswith(name,'%value')
endswith(name,'value%')
Saiba mais sobre os erros retornados quando os caracteres curinga iniciais são usados
Usar funções de consulta OData
A tabela a seguir descreve as funções de consulta OData que você pode usar para filtrar valores de cadeia de caracteres:
| Função | Example |
|---|---|
contains |
$filter=contains(name,'(sample)') |
endswith |
$filter=endswith(name,'Inc.') |
startswith |
$filter=startswith(name,'a') |
Use essas funções com o operador not lógico para negar o resultado.
Gerenciar aspas simples
Alguns filtros aceitam uma matriz de valores de cadeia de caracteres, como a função In Query. Quando você especifica valores nesses filtros que contêm aspas simples ou apóstrofos, como O'Brian ou Men's clothes, use aspas duplas ao redor dos valores: por exemplo:
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"]
Caso contrário, você receberá o seguinte erro: 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.
Se o filtro for para um único valor, substitua o caractere de aspa única por dois caracteres de aspas simples consecutivos; por exemplo:
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=lastname eq 'O''Bryan'
Se você não fizer isso, receberá um erro como este: There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.
Filtrar com base em valores de dados relacionados
Você pode filtrar linhas retornadas com base em valores em tabelas relacionadas. A forma como você filtra depende do tipo de relação.
Filtrar na propriedade de pesquisa
Para relações um para muitos, uma coleção filtrada retorna os mesmos resultados que o uso de eq$filter na propriedade de Pesquisa para o relacionamento. Por exemplo, esta coleção filtrada:
GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name
É o mesmo que esse filtro em uma propriedade de pesquisa.
GET [Organization URI]/api/data/v9.2/accounts?$filter=_owninguser_value eq <systemuserid value>&$select=name
Filtrar usando valores de propriedade de coluna de consulta
Você pode filtrar com base em valores em propriedades de navegação de valor único que representam colunas de pesquisa. Use este padrão:
<single-valued navigation property>/<property name>
O exemplo a seguir primarycontactid/fullname retorna registros de conta com base no valor da coluna:
Pedir:
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"
Resposta:
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"
}
]
}
Você também pode comparar valores mais acima da hierarquia de propriedades de navegação de valor único.
O exemplo a seguir retorna a primeira conta em que o registro de contato representa o primarycontactid, em que 'Administrador do Sistema' criou o registro, usando primarycontactid/createdby/fullname no $filter.
Pedir:
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"
Resposta:
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 coleções relacionadas
Use os Lambda operatorsany e all para avaliar valores em uma coleção e filtrar os resultados.
any: retornatruese a expressão aplicada for verdadeira para qualquer membro da coleção; caso contrário, ela retornará false.- O
anyoperador sem um argumento retornarátruese a coleção não estiver vazia.
- O
all: retorna true se a expressão aplicada for verdadeira para todos os membros da coleção; caso contrário, retornará false.
A sintaxe tem esta aparência:
<collection>/[any | all](o:<expression to evaluate>)
Nesse caso, o é a variável que representa os itens na coleção. A convenção é usar a primeira letra do tipo.
Na expressão, use o/<property or collection name> para fazer referência a uma propriedade ou coleção de um determinado item.
Você pode incluir condições em várias propriedades de navegação com valor de coleção e coleções aninhadas. Você não pode incluir condições em propriedades de navegação com valor de coleção aninhadas em uma propriedade de navegação de pesquisa. Por exemplo, $filter=primarycontactid/new_contact_account/any(a:a/accountid eq '{GUID}') não há suporte.
Mais informações: Operadores Lambda no odata.org
Exemplos de operador Lambda
O exemplo a seguir recupera todos os registros de conta que têm pelo menos um email com "sometext" no assunto:
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
O exemplo a seguir recupera todos os registros de conta que têm todas as tarefas associadas fechadas:
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
O exemplo a seguir recupera todos os registros de conta que têm pelo menos um email com "sometext" no assunto e cujo código de estado está ativo:
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
O exemplo a seguir cria uma consulta aninhada usando any e all operadores:
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
Limites de condição
Você pode incluir até 500 condições totais em uma consulta. Caso contrário, você verá esta mensagem de erro:
Nome:
TooManyConditionsInQuery
Código:0x8004430C
Número:-2147204340
Mensagem:Number of conditions in query exceeded maximum limit.
Você precisa reduzir o número de condições para executar a consulta. Você pode reduzir o número de condições usando as funções de consulta In ou NotIn que podem ser usadas com números, identificadores exclusivos e cadeias de caracteres de até 850 caracteres.
Próximas etapas
Saiba como paginar resultados.