Consultar dados

Concluído

O conector do Dataverse tem duas ações concentradas na leitura de dados de uma tabela do Dataverse. A ação Obter uma linha por ID recupera uma única linha com a ID exclusiva que você fornece. Quando não sabe a ID exclusiva, você pode usar a ação Listar linhas, que retorna zero para muitas linhas que correspondem a seus critérios de filtro.

Ambas as ações ajudam a configurar colunas selecionadas e a expandir as opções de consulta.

Selecionar colunas

A opção Selecionar colunas limita as colunas retornadas da ação. Você deve configurar a lista de colunas com base nos dados necessários nas etapas subsequentes do fluxo. Fornecer uma lista de colunas ajuda o fluxo a ser mais eficiente. Use o nome lógico da coluna da tabela, que pode ser encontrado na seção Opções avançadas das propriedades da coluna. Por exemplo, se quiser incluir as colunas Nome e Sobrenome da tabela Contato, você precisará fornecer a seguinte lista de colunas separadas por vírgula:

firstname,lastname

A especificação de uma lista de colunas limita as colunas exibidas no conteúdo dinâmico quando você configura etapas subsequentes no fluxo. Se as colunas que você espera não estiverem visíveis, verifique a opção Selecionar colunas na ação que está recuperando os dados.

Expandir consulta

Por padrão, quando as ações de recuperação de dados são executadas, recuperam apenas dados da tabela primária especificada na ação. Você pode usar a opção Expandir Consulta para fornecer uma expressão no estilo OData para incluir dados de tabelas relacionadas. Por exemplo, a tabela Conta tem um relacionamento com a tabela Contato para indicar o contato principal da conta. O exemplo a seguir mostra a expressão OData para incluir a coluna de nome completo e a ID do contato principal na saída da ação.

primarycontactid($select=contactid,fullname)

Embora essa expressão inclua dados na saída das ações, ela não inclui as colunas de dados no painel Conteúdo dinâmico para seleção. Para usar os dados relacionados, você precisa usar uma expressão de fluxo de trabalho para acessar os dados.

Usar a ação Obter uma linha por ID

Normalmente, você usaria a ação Obter uma linha por ID para recuperar dados extras da tabela do Dataverse como parte de uma lógica de fluxo. Por exemplo, se a adição de uma nova linha da tabela Conta disparar seu fluxo, você poderá usar uma ação Obter uma linha por ID para recuperar o email do contato principal relacionado. Nesse exemplo, não é necessário usar uma ação Obter uma linha por ID para recuperar a conta, pois os dados da linha são fornecidos como saída do gatilho.

Ocasionalmente, talvez você queira usar a ação Obter uma linha por ID novamente em sua lógica de fluxo para garantir que tenha os dados mais recentes. Por exemplo, se o fluxo for pausado para uma etapa de aprovação, poderão se passar alguns dias desde a última vez que você recuperou dados. Convém usar a ação Obter uma linha por ID para obter os dados mais recentes após a aprovação. Essa abordagem impediria que o fluxo agisse com base em dados obsoletos.

Se a ID da linha que você planeja criar na etapa for nula, a melhor ação será concluir uma verificação condicional do valor antes de executar a etapa Obter uma linha por ID. A etapa falhará se a ID da linha for nula. Outro erro comum é se você não tiver permissão para ler os dados da linha.

Usar a ação Listar linhas

A ação Listar linhas é poderosa, pois você pode fornecer critérios simples ou complexos para determinar quais linhas de dados ela retorna. A ação dá suporte a dois estilos de especificação desses critérios: expressões de estilo OData ou FetchXML do Dataverse. Você pode usar ambos os estilos de critérios para compor critérios simples e complexos. Em geral, sua preferência determina qual estilo usar. No entanto, FetchXML tem algum suporte de ferramentas da comunidade que pode facilitar a criação de critérios mais complexos.

Recuperar mais de 5.000 linhas

Por padrão, a ação não retorna mais de 5.000 linhas. Você poderá ativar o recurso Paginação na guia Configurações se precisar retornar mais dados. Ao ativar a paginação, você pode especificar um tamanho de página com até 100.000 linhas. Quando mais de uma página de dados for possível, você precisará manipular manualmente as páginas em seu fluxo obtendo o token de paginação e repassando a recuperação das páginas subsequentes. Para obter mais informações, confira Ativar paginação.

Considere suas necessidades futuras, pois atingir 5.000 linhas não produz erro. Além disso, você não receberá todos os dados. Quando possível, elabore seus critérios para produzir os menores resultados possíveis para seu fluxo processar.

Usar critérios de estilo OData

Na propriedade Filtrar linhas na ação, você pode fornecer um filtro de estilo OData para limitar as linhas que são retornadas às linhas que correspondem aos critérios. Ao compor a expressão para a propriedade Filtrar linhas, é necessário usar o nome lógico da coluna, que pode ser encontrado na seção Opções avançadas da propriedade da coluna. A lógica a seguir é um exemplo simples que filtra Contatos para retornar todas as linhas com o nome John.

firstname eq 'John'

Além disso, você pode usar operadores de filtro de consulta padrão e funções de consulta. Por exemplo, a lógica a seguir alteraria o filtro para usar a função contain.

contains(firstname,'John')

Para obter mais informações, consulte os exemplos em operadores de filtro padrão e funções de consulta.

Você pode usar operadores lógicos como e, ou e não. Por exemplo, a lógica a seguir verifica se a coluna de receita está em um intervalo de 2001-99999.

revenue lt 100000 and revenue gt 2000

Você pode usar parênteses () com operadores lógicos para especificar a precedência a fim de avaliar uma expressão complexa:

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

Você também pode filtrar dados relacionados. Por exemplo, a expressão a seguir retornaria linhas da tabela de contas que têm um contato principal chamado Susanna.

primarycontactid/fullname eq 'Susanna (sample)'

Junto com a expressão Filtrar linhas, a propriedade Classificar por ajuda a determinar a ordem da saída das linhas da ação. Os nomes devem ser uma lista separada por vírgulas de nomes de colunas lógicas. Se apenas o nome da coluna for especificado, a coluna será classificada em ordem crescente. Você pode especificar um sufixo asc ou desc para indicar ordem crescente ou decrescente.

A propriedade Row count pode indicar quantas linhas retornar. Por exemplo, se você quiser verificar se há linhas correspondentes, não será necessário retornar mais de uma única linha.

Usar critérios de estilo FetchXML

FetchXML é uma linguagem de consulta proprietária com base em XML do Dataverse que você pode usar para consultar dados. Você pode compor FetchXML e usá-lo como critério de filtro para a saída das linhas da ação Listar linhas. Você pode compor manualmente o XML ou usar a Localização avançada de um aplicativo baseado em modelo do Power Apps para criar seu filtro e baixar o FetchXML.

FetchXML contém o equivalente aos recursos Selecionar colunas, Classificar por, Expandir consulta e Filtrar linhas para os critérios de estilo OData.

A expressão a seguir é um exemplo de FetchXML para filtrar a tabela Conta em linhas com status ativo e um nome que contém Contoso. Esse exemplo também retorna o email do contato principal relacionado à linha da conta.

<fetch>
  <entity name="account">
    <attribute name="name"/>
    <attribute name="address1_city"/>
    <attribute name="primarycontactid"/>
    <attribute name="telephone1"/>
    <attribute name="accountid"/>
    <order attribute="name" descending="false"/>
    <filter type="and">
      <condition attribute="statecode" operator="eq" value="0"/>
      <condition attribute="name" operator="like" value="%Contoso%"/>
    </filter>
    <link-entity alias="accountprimarycontactidcontactcontactid" name="contact" from="contactid" to="primarycontactid" link-type="outer" visible="false">
      <attribute name="emailaddress1"/>
    </link-entity>
  </entity>
</fetch>

Para obter mais informações, consulte Usar FetchXML para criar uma consulta.

No momento, as consultas de agregação não têm suporte quando você usa a ação Listar linhas com critérios FetchXML.