Criar ou editar uma entidade virtual com dados de uma fonte externa

Este tópico se aplica a Dynamics 365 Customer Engagement (on-premises). Para a versão Power Apps deste tópico, consulte: Criar e editar entidades virtuais que contenham dados de uma fonte de dados externa

Uma entidade virtual é uma entidade personalizada no Dynamics 365 Customer Engagement (on-premises) que tem campos com dados de uma fonte de dados externa. As entidades virtuais aparecem no seu aplicativo para usuários como registros de entidade regulares, mas contêm dados originários de um banco de dados externo, como um banco de dados SQL do Azure. Registros baseados em entidades virtuais estão disponíveis em todos os clientes, incluindo os clientes personalizados desenvolvidos usando os serviços Web do Dynamics 365 Customer Engagement.

No passado, para integrar as fontes de dados díspares, você precisaria criar um conector para mover os dados ou desenvolver um plug-in personalizado, no cliente ou no servidor. Entretanto, com as entidades virtuais, você pode se conectar diretamente a uma fonte de dados externa em tempo de execução de forma que os dados específicos da fonte de dados externa fiquem disponíveis em um ambiente, sem a necessidade de replicação de dados.

As entidades virtuais são compostas de até três componentes principais, um provedor de dados, um registro de fonte de dados e uma entidade virtual. O provedor de dados consiste em plug-ins e em uma entidade de fonte de dados. A fonte de dados é um registro da entidade no Dynamics 365 Customer Engagement (on-premises) que inclui metadados que representam o esquema dos parâmetros de conexão. Cada entidade virtual faz referência a uma fonte de dados na definição da entidade.

O Dynamics 365 Customer Engagement (on-premises) inclui um Provedor de Dados OData que pode ser usado para a conexão com o serviço Web OData v4 que acessa os dados externos.

Como alternativa, os desenvolvedores podem criar seus próprios provedores de dados. Os provedores de dados são instalados em um ambiente como uma solução. Mais informações: Introdução às entidades virtuais

Benefícios de entidade virtual

• Os desenvolvedores podem implementar plug-ins para ler dados externos usando os serviços Web do Dynamics 365 Customer Engagemente e a ferramenta de Registro de Plug-ins do Customer Engagement.

• Os personalizadores de sistema usam o Dynamics 365 Customer Engagement (on-premises) para configurar o registro da fonte de dados e criar entidades virtuais usadas para acessar dados externos sem escrever código.

• Usuários finais trabalham com registros criados pela entidade virtual para exibir os dados em campos, grades, resultados de pesquisa, e em relatórios e painéis baseados em Fetch XML.

Adicionar uma fonte de dados a ser usada com entidades virtuais

Os desenvolvedores criam um plug-in personalizado a ser usado como o provedor de dados para uma entidade virtual. Como alternativa, você pode usar o Provedor de Dados OData v4 fornecido. Mais informações: Configuração, requisitos e práticas recomendadas do Provedor de Dados OData v4

1. Vá para Configurações>Administração>Fontes de Dados da Entidade Virtual.

2. Na barra de ferramentas de ações, selecione Novo.

3. Na caixa de diálogo Selecionar Provedor de Dados, selecione uma das fontes de dados a seguir e OK.

   • Provedor de dados personalizado. Se você tiver importado um plug-in de provedor de dados, o provedor de dados aparecerá aqui. Mais informações: Introdução às entidades virtuais

   • Provedor de Dados OData v4. O Dynamics 365 Customer Engagement (on-premises) inclui um Provedor de Dados OData que pode ser usado com serviços Web do OData v4. Mais informações: Configuração, requisitos e práticas recomendadas do Provedor de Dados OData v4

Adicione um campo protegido a uma Fonte de Dados

Você cria campos para uma Fonte de Dados como faz para qualquer outra entidade. Para os dados criptografados ou confidenciais, habilite o atributo Segredo da Fonte de Dados no campo personalizado da Fonte de Dados. Por exemplo, para proteger um campo contendo uma cadeia de conexão do banco de dados.

Criar uma entidade virtual

Você cria uma entidade virtual da mesma forma que qualquer outra entidade no Customer Engagement, com a adição de mais alguns atributos descritos aqui.

1. Acesse Configurações>Personalizações>Personalizar o Sistema.

2. No gerenciador de soluções, crie uma nova entidade. Para fazer isso, selecione Entidades no painel de navegação esquerdo e, depois, Novo.

3. Na guia Geral da Definição de Entidade, selecione Entidade Virtual e, na lista suspensa Fonte de Dados, selecione a fonte de dados desejada.

   

4. Na Definição da Entidade, preencha os campos necessários a seguir.

   • Nome Externo. Insira o nome da tabela na fonte de dados externa à qual essa entidade é mapeada.

   • Nome da Coleção Externa. Insira o nome plural da tabela na fonte de dados externa à qual essa entidade é mapeada.

     Veja um exemplo de uma entidade virtual chamada Filme que usa um provedor de dados do Azure Cosmos DB para acessar arquivos de documentos.

   

   Importante

   Várias opções, como Equipes de Acesso, Filas e Criação Rápida, não estão disponíveis com entidades virtuais. Mais informações: Considerações ao usar as entidades virtuais

   Preencha as propriedades opcionais e obrigatórias adicionais, como os nomes de exibição e no plural, conforme o necessário. Para obter mais informações sobre estas propriedades, consulte Criar e editar entidades.

5. Criar e adicionar um ou mais campos para a entidade virtual. Além das propriedades de campo padrão necessárias para criar um campo personalizado, essas propriedades opcionais estão disponíveis para cada campo personalizado que você cria para uma entidade virtual.

   • Nome Externo. Esse é geralmente o nome exclusivo para identificar os dados que você deseja exibir no campo.

   Nota

   Se o tipo de campo a ser criado for OptionSet, os campos adicionais a seguir estarão disponíveis.

   • Nome de Tipo Externo. Essa propriedade é mapeada para o nome externo do conjunto de valores no serviço externo para o conjunto de opções. Normalmente, isso pode ser uma enumeração ou um nome de uma classe de valor de cadeia de caracteres. O Nome do Tipo Externo pode ser usado quando o nome totalmente qualificado for necessário. Por exemplo, como o Nome do Tipo com OData onde os parâmetros em uma consulta precisam do nome totalmente qualificado,como [Nome do Tipo].[Valor].
   • Valor Externo. Essa propriedade é mapeada para o valor correspondente na fonte de dados externa para o item do conjunto de opções. O valor inserido é usado para determinar qual item do conjunto de opções será exibido no aplicativo.

   Preencha as propriedades adicionais como necessário. Para obter mais informações sobre estas propriedades, consulte Criar e editar campos.

6. Selecione Salvar e Fechar na página de propriedades Campo.

7. Na barra de ferramentas do gerenciador de soluções, selecione Salvar.

8. Na barra de ferramentas do gerenciador de soluções, selecione Publicar.

9. Feche o gerenciador de soluções.

Considerações ao usar as entidades virtuais

As entidades virtuais têm estas restrições.

• Todas as entidades virtuais são somente leitura.

• As entidades existentes não podem ser convertidas em entidades virtuais.

• Por padrão, as entidades virtuais contém somente um campo Nome e Id. Nenhum outro campo gerenciado pelo sistema, como Status ou Criado em/Modificado em é suportado.

• As entidades virtuais não suportam campos personalizados com os tipos de dados de Moeda, Imagem ou Cliente.  

• As entidades virtuais não oferecem suporte à auditoria.

• Os campos da entidade virtual não podem ser usados em valores acumulados ou em campos calculados.  

• Uma entidade virtual não pode ser um tipo de atividade de entidade.

• Muitos recursos que afetem linhas da tabela de entidade não podem ser habilitados com entidades virtuais. Os exemplos incluem filas, gerenciamento de conhecimento, SLAs, detecção de duplicidades, controle de alterações, recurso mobile offline, segurança do campo, Pesquisa de Relevância, Portais de soluções do portal da Web do Dynamics 365 Customer Engagement (on-premises) e relacionamento N:N entre entidades virtuais.

• As entidades virtuais são propriedade da organização e não dão suporte aos conceitos de segurança do Common Data Service for Apps em nível de linha. É recomendável que você implemente o seu próprio modelo de segurança para a fonte de dados externa.

• É recomendável ter como destino uma única fonte de dados quando as entidades virtuais são usadas em Localizações Avançadas. Por exemplo, não é permitido criar uma Localização Avançada que cria basicamente uma junção entre os dados nativos do Dataverse e os dados externos da entidade virtual.

• As propriedades de metadados de campo que validam a atualização não se aplicam a entidades virtuais. Por exemplo, um campo Número Inteiro em um campo entidade virtual pode ser definido com um valor mínimo de zero. No entanto, como o valor é obtido de uma fonte de dados externa, uma consulta retornará valores menores que zero quando recuperados de uma entidade virtual. A propriedade de valor mínimo não é implícita na consulta. Se desejar, você ainda poderá filtrar os valores como maiores que 0.

• As entidades virtuais não dão suporte ao controle de alterações e não podem ser sincronizadas usando um recurso do Customer Engagement, como o Serviço de Exportação de Dados.

• Os fluxos do processo empresarial não têm suporte com entidades virtuais. Mais informações: Erro inesperado recebido quando um usuário ativa um fluxo do processo empresarial

Erro inesperado recebido quando um usuário ativa um fluxo do processo empresarial

Quando um usuário tenta ativar um fluxo do processo empresarial, ele pode receber uma mensagem de "erro inesperado". Visualizando o arquivo de log, a seguinte entrada de log é exibida.

ErrorCode: 0x80040216 Message: System.Web.HttpUnhandledException: Exceção do tipo 'System.Web.HttpUnhandledException' foi gerada. ---> Microsoft.Crm.CrmException: o fluxo do processo empresarial não pode ser habilitado para a Entidade Virtual

Esse problema ocorre porque as entidades virtuais não oferecem suporte a fluxos do processo empresarial.

Confira também

Requisitos e práticas recomendadas do provedor de dados OData v4
Criar e editar entidades
Criar e editar campos