Conectar-se ao Microsoft Dataverse a partir de fluxos de trabalho nos Aplicativos Lógicos do Azure

Aplica-se a: Aplicativos Lógicos do Azure (Consumo + Padrão)

Importante

Em 30 de agosto de 2022, as operações do conector do Common Data Service 2.0, também conhecido como Microsoft Dataverse (Herdado), migraram para o conector atual do Microsoft Dataverse. As operações herdadas têm o rótulo "herdado", enquanto as operações atuais carregam o rótulo de "versão prévia". Você pode usar o conector do Dataverse atual em qualquer fluxo de trabalho de aplicativo lógico existente ou novo. Para compatibilidade com versões anteriores, os fluxos de trabalho existentes continuam a funcionar com o conector do Dataverse herdado. No entanto, certifique-se de examinar esses fluxos de trabalho e atualizá-los prontamente.

Desde outubro de 2023, a versão herdada ficou indisponível para novos fluxos de trabalho. Os fluxos de trabalho existentes continuam funcionando, mas você deve usar as operações atuais do conector do Dataverse para novos fluxos de trabalho. Será anunciado uma linha do tempo para a data de desligamento das ações e gatilhos herdados. Para obter mais informações, confira O conector do Microsoft Dataverse (herdado) para Aplicativos Lógicos do Azure será preterido e substituído por outro conector.

Para criar e executar fluxos de trabalho automatizados que criam e gerenciam linhas no banco de dados do Microsoft Dataverse, você pode usar os Aplicativos Lógicos do Azure e o conector do Microsoft Dataverse. Esses fluxos de trabalho podem criar registros, atualizar registros e executar outras operações. Você também pode obter informações do banco de dados do Dataverse e disponibilizar a saída para outras ações a serem usadas em seus fluxos de trabalho. Por exemplo, quando um registro é adicionado, atualizado e excluído no banco de dados do Dataverse, você pode enviar um email usando o conector do Outlook do Office 365.

Este guia mostra como criar um fluxo de trabalho que cria uma linha de tarefa sempre que uma nova linha de cliente potencial é criada.

Referência do conector

Para obter informações técnicas com base na descrição do Swagger do conector, como operações, limites e outros detalhes, confira a página de referência do conector gerenciado.

Pré-requisitos

• Uma conta e uma assinatura do Azure. Se você não tiver uma assinatura do Azure, inscreva-se em uma conta gratuita do Azure.

• Um ambiente e banco de dados do Dataverse Data Service, que é um espaço onde sua organização armazena, gerencia e compartilha dados corporativos e um banco de dados do Dataverse. Para saber mais, consulte os recursos a seguir:

  • Learn: Criar e gerenciar ambientes no Dataverse

  • Power Platform – Visão geral dos ambientes

• Conhecimento básico sobre como criar fluxos de trabalho de aplicativo lógico Standard ou de Consumo e o aplicativo lógico de onde você deseja acessar os registros em seu banco de dados do Dataverse. Para usar um gatilho do Dataverse, você precisa começar com um fluxo de trabalho em branco. Para saber mais, consulte os recursos a seguir:

  • Crie um exemplo de fluxo de trabalho de aplicativo lógico de Consumo

  • Criar um exemplo de fluxo de trabalho de aplicativo lógico Standard

Adicionar um gatilho do Dataverse

Quando você adiciona um gatilho ou uma ação que conecta um serviço ou um sistema e não tem uma conexão existente ou ativa, os Aplicativos Lógicos do Azure solicitam que forneça as informações de conexão, que variam de acordo com o tipo, por exemplo:

• Suas credenciais de conta
• Um nome a ser usado para a conexão
• O nome do sistema ou do servidor
• O tipo de autenticação a ser usado
• Uma cadeia de conexão

Este exemplo usa o gatilho Dataverse que inicia seu fluxo de trabalho quando uma linha é adicionada, atualizada ou excluída.

Observação

O conector do Dataverse tem parâmetros específicos da operação e parâmetros específicos do banco de dados. Por exemplo, quando você seleciona uma tabela, os parâmetros disponíveis para essa tabela variam e diferem de outras tabelas.

Standard

1. No portal do Azure, abra o recurso de aplicativo lógico Standard e o fluxo de trabalho em branco no designer.

2. No designer, siga estas etapas gerais para adicionar o gatilho do Microsoft Dataverse chamado Quando uma linha é adicionada, modificada ou excluída.

3. Se solicitado, entre no seu ambiente ou banco de dados do Dataverse.

4. Na caixa de informações do gatilho, forneça os valores necessários.

   Para o gatilho de exemplo, confira Quando uma linha é adicionada, modificada ou excluída.

   

5. Quando terminar, salve o fluxo de trabalho de aplicativo lógico. Selecione Salvar na barra de ferramentas do designer.

6. Agora, adicione pelo menos uma ação para o fluxo de trabalho a ser executado quando o gatilho for acionado. Por exemplo, você pode adicionar uma ação do Dataverse ou uma ação que envia emails com base nas saídas do gatilho.

Consumo

1. No portal do Azure, abra o recurso do aplicativo lógico de Consumo e o fluxo de trabalho em branco no designer.

2. No designer, siga estas etapas gerais para adicionar o gatilho do Microsoft Dataverse chamado Quando uma linha é adicionada, modificada ou excluída.

3. Se solicitado, entre no seu ambiente ou banco de dados do Dataverse.

4. Na caixa de informações do gatilho, forneça os valores necessários.

   Para o gatilho de exemplo, confira Quando uma linha é adicionada, modificada ou excluída.

   

5. Quando terminar, salve o fluxo de trabalho de aplicativo lógico. Selecione Salvar na barra de ferramentas do designer.

6. Agora, adicione pelo menos uma ação para o fluxo de trabalho a ser executado quando o gatilho for acionado. Por exemplo, você pode adicionar uma ação do Dataverse ou uma ação que envia emails com base nas saídas do gatilho.

Adicionar uma ação do Dataverse

Quando você adiciona um gatilho ou uma ação que conecta um serviço ou um sistema e não tem uma conexão existente ou ativa, os Aplicativos Lógicos do Azure solicitam que forneça as informações de conexão, que variam de acordo com o tipo, por exemplo:

• Suas credenciais de conta
• Um nome a ser usado para a conexão
• O nome do sistema ou do servidor
• O tipo de autenticação a ser usado
• Uma cadeia de conexão

Este exemplo usa a ação Dataverse que adiciona uma nova linha ao banco de dados.

Observação

O conector do Dataverse tem parâmetros específicos da operação e parâmetros específicos do banco de dados. Por exemplo, quando você seleciona uma tabela, os parâmetros disponíveis para essa tabela variam e diferem de outras tabelas.

Standard

1. No portal do Azure, abra o recurso de aplicativo lógico Standard e o fluxo de trabalho no designer.

2. No designer, siga estas etapas gerais para adicionar a ação do Microsoft Dataverse chamada Adicionar uma nova linha.

3. Se solicitado, entre no seu ambiente ou banco de dados do Dataverse.

4. Na caixa de informações de ação, forneça os valores necessários.

   Para a ação de exemplo, confira Adicionar uma nova linha.

   

5. Quando terminar, salve o fluxo de trabalho de aplicativo lógico. Selecione Salvar na barra de ferramentas do designer.

6. Continue adicionando mais ações, se desejar.

Consumo

1. No portal do Azure, abra o recurso do aplicativo lógico de consumo e o fluxo de trabalho no designer.

2. No designer, siga estas etapas gerais para adicionar a ação do Microsoft Dataverse chamada Adicionar uma nova linha.

3. Se solicitado, entre no seu ambiente ou banco de dados do Dataverse.

4. Na caixa de informações de ação, forneça os valores necessários.

   Para a ação de exemplo, confira Adicionar uma nova linha.

   

5. Quando terminar, salve o fluxo de trabalho de aplicativo lógico. Selecione Salvar na barra de ferramentas do designer.

6. Continue adicionando mais ações, se desejar.

Testar seu fluxo de trabalho

Para testar e disparar o fluxo de trabalho, siga estas etapas:

Standard

1. No menu de fluxo de trabalho, selecione Visão geral.

2. Na barra de ferramentas Visão geral, selecione Executar>Executar.

3. Reproduza as condições necessárias para que o fluxo de trabalho seja executado.

Consumo

1. Na barra de ferramentas do designer, escolha Executar gatilho>Executar.

2. Reproduza as condições necessárias para que o fluxo de trabalho seja executado.

Retornar linhas com base em um filtro

Para ações que retornam linhas, como a ação Listar linhas, você pode usar uma consulta ODATA que retorna linhas com base no filtro especificado. Por exemplo, você pode configurar a ação para retornar apenas linhas para contas ativas. Para obter mais informações sobre a ação de exemplo, confira Listar linhas.

Standard

1. No designer, na ação, abra a lista Parâmetros avançados e selecione a propriedade Filtrar linhas.

   

2. Na propriedade Filtrar linhas, que agora aparece na ação, insira uma expressão de consulta ODATA como, por exemplo:

   statuscode eq 1

   

Para obter mais informações sobre as opções de consulta do sistema $filter, confira Dados de consulta usando a API Web – Filtrar resultados.

Consumo

1. No designer, abra a lista Adicionar novo parâmetro e selecione a propriedade Filtrar listas.

   

2. Na propriedade Filtrar linhas, que agora aparece na ação, insira uma expressão de consulta ODATA como, por exemplo:

   statuscode eq 1

   

Para obter mais informações sobre as opções de consulta do sistema $filter, confira Dados de consulta usando a API Web – Filtrar resultados.

Retornar linhas com base em uma ordem de classificação

Para ações que retornam linhas, como a ação Listar linhas, você pode usar uma consulta ODATA que retorna linhas em uma ordem especificada, que varia de acordo com as linhas que a ação retorna. Por exemplo, você pode configurar a ação para retornar linhas organizadas pelo nome da conta. Para obter mais informações sobre a ação de exemplo, confira Listar linhas.

Standard

1. No designer, na ação, abra a lista Parâmetros avançados e selecione a propriedade Ordenar por.

   

2. Na propriedade Ordenar por, que agora aparece na ação, insira o nome da coluna a ser usado para classificar, por exemplo, o nome:

   

Para obter mais informações sobre as opções de consulta do sistema $orderby, confira Dados de consulta usando a API Web – Ordenar por.

Consumo

1. No designer, abra a lista Adicionar novo parâmetro e selecione a propriedade Ordenar por.

   

2. Na propriedade Ordenar por, que agora aparece na ação, insira o nome da coluna a ser usado para classificar, por exemplo, o nome:

   

Para obter mais informações sobre as opções de consulta do sistema $orderby, confira Dados de consulta usando a API Web – Ordenar por.

Tipos de dados de campo

Em um gatilho ou ação, o tipo de dados de um valor de campo deve corresponder ao tipo de dados necessário do campo. Esse requisito se aplica se você inserir manualmente o valor ou selecionar o valor na lista de conteúdo dinâmico.

Observação

O conector do Dataverse tem parâmetros específicos da operação e parâmetros específicos do banco de dados. Por exemplo, quando você seleciona uma tabela, os parâmetros disponíveis para essa tabela variam e diferem de outras tabelas.

Por exemplo, suponha que você tenha uma tabela chamada Tarefas. Essa tabela tem campos que se aplicam somente a essa tabela, enquanto outras tabelas têm seus próprios campos. Para a tabela Tarefas de exemplo, a tabela a seguir descreve alguns tipos de campo de exemplo e os tipos de dados que esses campos exigem para seus valores.

Campo	Tipo de dados	Descrição
Campo de texto	Linha única de texto	Requer uma única linha de texto ou conteúdo dinâmico que tenha o tipo de dados de texto, por exemplo, estas propriedades: - Descrição - Categoria
Campo de número inteiro	Número inteiro	Requer um Integer ou conteúdo dinâmico que tenha o tipo de dados Integer, por exemplo, essas propriedades: - Porcentagem Concluída - Duration
Campo de data	Data e hora	Requer uma data no formato DD/MM/AAA ou conteúdo dinâmico que tenha o tipo de dados data, por exemplo, essas propriedades: - Data da criação - Data de Início - Início real - Término real - Data de conclusão
Campo que faz referência a outro registro de entidade	Chave primária	Requer uma ID de registro, como um GUID, e um tipo de pesquisa, o que significa que os valores da lista de conteúdo dinâmico não funcionarão, por exemplo, nessas propriedades: - Proprietário: deve ser uma ID de usuário válida ou uma ID de registro de equipe. - Tipo de Proprietário: Deve ser um tipo de pesquisa como systemusers ou teams, respectivamente. - Referente a: precisa ser uma ID de registro válida, como uma ID de conta ou de registro de contato. - Tipo Referente a: Deve ser um tipo de pesquisa como accounts ou contacts, respectivamente. - Cliente: precisa ser uma ID de registro válida, como uma ID de conta ou de registro de contato. - Tipo de Cliente: Deve ser o tipo de pesquisa como accounts ou contacts, respectivamente.

Para a tabela Tarefas de exemplo, suponha que você use a ação Adicionar uma nova linha para criar uma nova linha associada a outras linhas de entidade, especificamente uma linha de usuário e uma linha de conta. Então, nessa ação, especifique as IDs e os tipos de pesquisa para esses registros de entidade usando valores que correspondem aos tipos de dados esperados para as propriedades relevantes.

• Com base na propriedade Proprietário, que especifica uma ID de usuário e a propriedade de Tipo de Proprietário, que especifica o systemusers tipo de pesquisa, a ação associa o novo registro a um usuário específico.

• Com base na propriedade Referente a, que especifica uma ID de registro e a propriedade de Tipo Referente a, que especifica o accounts tipo de pesquisa, a ação associa o novo registro a uma conta específica.

Standard

Consumo

Solução de problemas

Chamadas de vários ambientes

O conector do Dataverse armazena informações sobre os fluxos de trabalho do aplicativo lógico que obtêm e exigem notificações sobre alterações de entidade de banco de dados usando a callbackregistrations entidade em seu banco de dados do Dataverse. Se você copiar uma organização do Dataverse, todos webhooks também serão copiado. Se você copiar sua organização antes de desabilitar fluxos de trabalho mapeados para sua organização, todos webhooks copiados também apontarão para os mesmos fluxos de trabalho de aplicativos lógicos, que receberão notificações de várias organizações.

Para interromper notificações indesejadas, exclua a entidade callbackregistrations da organização que envia essas notificações seguindo estas etapas:

1. Identifique a organização do Dataverse da qual você deseja remover notificações e entre nessa organização.

2. No navegador Chrome, encontre o registro de retorno de chamada que você deseja excluir.

   1. Revise a lista genérica para todos os registros de retorno de chamada no seguinte URI do OData para que você possa exibir os dados dentro da entidade callbackregistrations:

      https://{organization-name}.crm{instance-number}.dynamics.com/api/data/v9.0/callbackregistrations:

      Observação

      Se nenhum valor for retornado, talvez você não tenha permissões para exibir esse tipo de entidade, ou talvez você não tenha se conectado na organização correta.

   2. Filtre o nome lógico da entidade de disparo entityname e o evento de notificação que corresponda ao fluxo de trabalho do aplicativo lógico (mensagem). Cada tipo de evento é mapeado para o Integer da mensagem da seguinte forma:

      Tipo de evento	Integer da mensagem
      Criar	1
      Excluir	2
      Atualizar	3
      CreateOrUpdate	4
      CreateOrDelete	5
      UpdateOrDelete	6
      CreateOrUpdateOrDelete	7

      Este exemplo mostra como você pode filtrar notificações Create em uma entidade chamada nov_validation usando o seguinte URI do OData para uma organização de exemplo:

      https://fabrikam-preprod.crm1.dynamics.com/api/data/v9.0/callbackregistrations?$filter=entityname eq 'nov_validation' and message eq 1

      

      Observação

      Se existirem vários gatilhos para a mesma entidade ou evento, você poderá filtrar a lista usando filtros adicionais, como os atributos createdon e _owninguser_value. O nome do usuário proprietário aparece em /api/data/v9.0/systemusers({id}).

   3. Depois de encontrar a ID do registro de retorno de chamada que deseja excluir, siga estas etapas:

      1. No navegador Chrome, abra as Ferramentas para Desenvolvedores Chrome (Teclado: F12).

      2. Na janela, na parte superior, selecione a guia Console.

      3. No prompt de linha de comando, insira este comando, que envia uma solicitação para excluir o registro de retorno de chamada especificado:

         fetch('http://{organization-name}.crm{instance-number}.dynamics.com/api/data/v9.0/callbackregistrations({ID-to-delete})', { method: 'DELETE'})

         Importante

         Certifique-se de fazer a solicitação de uma página de UCI (Interface de Cliente Não Unificada), por exemplo, da própria página de resposta do OData ou da API. Caso contrário, a lógica no arquivo app.js pode interferir nessa operação.

   4. Para confirmar que o registro de retorno de chamada não existe mais, verifique a lista de registros de retorno de chamada.

Entidade "callbackregistrations" duplicada

Nos fluxos de trabalho do aplicativo lógico Standard, sob condições específicas, como realocação de instância ou reinicialização do aplicativo, o gatilho do Microsoft Dataverse inicia uma execução duplicada, que cria uma entidade callbackregistrations duplicada no banco de dados do Dataverse. Se você editar um fluxo de trabalho Standard que começa com um gatilho do Dataverse, verifique se essa entidade callbackregistrations está duplicada. Se a duplicata existir, exclua manualmente a entidade callbackregistrations duplicada.

Próximas etapas

• Conectores gerenciados dos Aplicativos Lógicos do Azure
• Conectores internos de Aplicativos Lógicos do Azure
• O que são os conectores nos Aplicativos Lógicos do Azure