Recuperar e executar consultas predefinidas

Microsoft Dataverse fornece uma maneira para os administradores criarem exibições do sistema disponíveis para todos os usuários. Usuários individuais podem salvar as consultas do Advanced Find para reutilização no aplicativo. Ambas representam consultas predefinidas que você pode recuperar e executar usando a API Web.

Note

Ao contrário das consultas que usam a sintaxe OData, os dados retornados de consultas predefinidas ou fetchXml não retornarão propriedades com valores null. Quando o valor for null, a propriedade não será incluída nos resultados.

Quando uma consulta é retornada usando a sintaxe OData, um registro incluirá uma propriedade com um valor null como este:

{
    "@odata.etag": "W/\"46849433\"",
    "name": "Contoso, Ltd. (sample)",
    "accountnumber": null,
    "accountid": "7a4814f9-b0b8-ea11-a812-000d3a122b89"
}

Quando recuperado usando uma consulta predefinida ou com FetchXml, o mesmo registro não incluirá a accountnumber propriedade porque ela é null, assim:

{
    "@odata.etag": "W/\"46849433\"",
    "name": "Contoso, Ltd. (sample)",
    "accountid": "7a4814f9-b0b8-ea11-a812-000d3a122b89"
}

Consultas predefinidas

O Dataverse permite que você defina, salve e execute dois tipos de consultas, conforme listado aqui.

Tipo de consulta	Description
Consulta salva	Exibições definidas pelo sistema para uma tabela (entidade). Essas exibições são armazenadas no EntityType savedquery. Mais informações: Personalizar exibições de tabela
Consulta do usuário	A Pesquisa Avançada pesquisa buscas salvas pelos usuários para uma tabela (entidade). Essas exibições são armazenadas no EntityType userquery. Mais informações: tabela UserQuery (modo de exibição salvo)

Os registros desses dois tipos de entidades contêm a definição FetchXML para os dados a serem retornados. Você pode consultar o respectivo tipo de entidade para recuperar o valor da chave primária. Com o valor da chave primária, você pode executar a consulta passando o valor da chave primária. Por exemplo, para executar a consulta salva de Contas Ativas , primeiro você deve obter a chave primária usando uma consulta como esta.

GET [Organization URI]/api/data/v9.2/savedqueries?$select=name,savedqueryid&$filter=name eq 'Active Accounts'

Em seguida, você pode usar o savedqueryid valor e passá-lo como o valor para o parâmetro savedQuery para o conjunto de entidades de contas.

GET [Organization URI]/api/data/v9.2/accounts?savedQuery=00000000-0000-0000-00aa-000010001002

Use a mesma abordagem para obter o userqueryid e passá-lo como o valor para o parâmetro userQuery para o conjunto de entidades que corresponde ao returnedtypecode correspondente da consulta salva.

GET [Organization URI]/api/data/v9.2/accounts?userQuery=121c6fd8-1975-e511-80d4-00155d2a68d1

Aplicar uma consulta a qualquer coleção do tipo apropriado

Além de simplesmente aplicar a consulta salva à coleção de conjuntos de entidades principal, você também pode usar uma consulta salva ou consulta de usuário para aplicar a mesma filtragem em qualquer coleção do tipo apropriado de entidades. Por exemplo, se você quiser aplicar uma consulta apenas às entidades relacionadas a uma entidade específica, poderá aplicar o mesmo padrão. Por exemplo, a URL a seguir aplicará a consulta Open Opportunities às oportunidades relacionadas a uma conta específica por meio da opportunity_parent_account propriedade de navegação com valor de coleção.

GET [Organization URI]/api/data/v9.2/accounts(8f390c24-9c72-e511-80d4-00155d2a68d1)/opportunity_parent_account/?savedQuery=00000000-0000-0000-00aa-000010003001

Consulte também

Exemplo de dados de consulta da API Web (C#)
Exemplo de dados de consulta da API Web (JavaScript do lado do cliente)
Executar operações usando a API Web
Redigir solicitações Http e manipular erros
Consultar dados usando a API Web
Criar uma linha de tabela usando a API Web
Recuperar uma linha de tabela usando a API Web
Atualizar e excluir linhas de tabela usando a API Web
Associar e desassociar linhas de tabela usando a API Web
Usar funções de API Web
Use ações da API Web
Executar operações em lote usando a API Web
Representar outro usuário usando a API Web
Executar operações condicionais usando a API Web