Habilitar Tabelas Virtuais para oferecer suporte a eventos Dataverse

Pode permitir que entidades Virtuais participem em eventos de pipeline assíncronos do Dataverse Event Framework e no acionador Quando uma linha é adicionada, modificada ou eliminada do conector do Dataverse do PowerAutomate. Esse recurso é habilitado como parte dos eventos de negócios do Dataverse. Para obter mais informações: Eventos de negócios do Microsoft Dataverse

Sem a configuração descrita neste artigo, a maioria das entidades virtuais não participa do pipeline da Estrutura de Eventos como outras entidades. Como as entidades virtuais não participam no pipeline de eventos, não pode registar passos de plug-in em relação a eventos Criar, Atualizar e Eliminar (CAE) que ocorrem, e, embora os eventos CAE apareçam para estas entidades no conector do Dataverse do Power Automate, é apresentado um erro quando se tenta guardar um fluxo que as utiliza.

Isso ocorre porque as entidades virtuais representam dados armazenados em uma fonte externa. O Dataverse tem acesso a essa fonte de dados como um cliente, mas outros sistemas podem atualizar esses dados a qualquer momento sem passar pela estrutura de eventos do Dataverso.

Há duas etapas para habilitar isso:

1. Configuração de dados em uma tabela chamada Metadados de Entidade Virtual. Quando os dados nesta tabela são configurados para habilitá-los, um conjunto de novas APIs fornece os meios para que o sistema externo notifique o Dataverse quando ocorrerem eventos CUD.

   Quando há uma linha de Metadados de Entidade Virtual associada a EntityMetadata.Metadataid para uma tabela virtual, as três configurações a seguir podem controlar se uma fonte externa pode notificar a sua tabela virtual.

   Quando habilitadas individualmente usando as propriedades booleanas de Metadados de Entidade Virtual IsOnExternalCreatedEnabled, IsOnExternalDeletedEnabled e IsOnExternalUpdatedEnabled, as seguintes ações associadas tornam-se disponíveis para serem invocadas por serviços externos.

   Ação/Mensagem	Description
   OnExternalCreated	Contém dados sobre um registro que foi criado em um sistema externo exposto como uma tabela virtual no Dataverse.
   OnExternalUpdated	Contém dados sobre um registro que foi atualizado em um sistema externo exposto como uma tabela virtual no Dataverse.
   OnExternalDeleted	Contém dados sobre um registro que foi excluído em um sistema externo exposto como uma tabela virtual no Dataverse.

2. O sistema externo que controla os dados deve enviar uma solicitação HTTP autenticada para o Dataverse usando as APIs que têm dados em Metadados de Entidade Virtual. Uma conta de principal de serviço autenticada, normalmente, efetua esta chamada. Mais informações: Criar aplicações Web através da autenticação servidor a servidor (S2S)

   Mas qualquer aplicativo ou usuário que possa realizar uma chamada para o Dataverse pode enviar a solicitação http necessária para notificar o Dataverse de que o evento ocorreu.

Como habilitar APIs de notificação para tabelas virtuais

Você pode habilitar APIs de notificação configurando-as manualmente no portal do criador (make.powerapps.com/) ou usando código.

Ativar manualmente usando o portal do criador

Digamos que temos uma Tabela Virtual de Pessoa com essas propriedades, a propriedade Name é new_People.

1. No Power Apps (make.powerapps.com), na sua solução, selecione +Novo e, em seguida, selecione Metadados de Entidade Virtual.

   

   Isso abre o seguinte formulário:

   

2. Preencha o formulário, definindo o valor Extension Entity Id como o nome da sua tabela virtual. Não é necessário ativar as três mensagens. Você pode definir um ou mais deles e voltar para habilitar o restante mais tarde.

Depois de habilitar essas mensagens, você poderá observar e confirmar o que foi adicionado usando as etapas em Exibir as mensagens criadas para dar suporte à sua tabela virtual.

Definir propriedades gerenciadas usando o portal do criador

Se você não quiser que as pessoas que instalam sua solução gerenciada alterem os comportamentos de Metadados de Entidade Virtual, defina a propriedade gerenciada para impedi-la usando as etapas a seguir.

1. Na sua solução, selecione os Metadados da Entidade Virtual, selecione as reticências (...) e, em seguida, selecione Propriedades Geridas.

   

2. No painel Propriedades gerenciadas, desmarque Permitir personalizações e pressione Concluído.

   

   Essa configuração não fará nada até que o registro de Metadados de Entidade Virtual seja incluído em uma solução gerenciada.

Ativar com código

Você pode querer automatizar a criação de metadados de entidade virtual para suas entidades virtuais.

A VirtualEntityMetadata tabela tem as seguintes colunas que você pode definir:

Ao criar esses tipos de componentes de solução, recomendamos que defina a propriedade gerida IsCustomizable como false, a menos que queira permitir que as pessoas que instalam a sua solução gerida possam alterar essas configurações.

Também recomendamos que você adicione o registro Metadados de Entidade Virtual** a uma solução específica ao criá-lo. Em ambos os exemplos abaixo, você verá como o Solution.UniqueName é passado com a solicitação que cria o registro.

Usando a API da Web

Quando você usa a API da Web, a primeira tarefa é obter o MetadataId da tabela virtual. O exemplo a seguir retorna o MetadataId para uma entidade virtual chamada new_people.

Pedido:

GET [Organization Uri]/api/data/v9.1/EntityDefinitions(LogicalName='new_people')?$select=MetadataId HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Authorization: Bearer [REDACTED]

Resposta:

HTTP/1.1 200 OK

{
    "@odata.context": "[Organization Uri]/api/data/v9.1/$metadata#EntityDefinitions(MetadataId)/$entity",
    "MetadataId": "b198e6f3-3dd6-4c0b-9570-702f0c10d577"
}

Em seguida, crie o registo de metadados da entidade virtual associando-o ao entitytype Entity usando o MetadataId obtido no primeiro passo.

Observe a utilização do cabeçalho MSCRM.SolutionUniqueName definido com o valor Solution.UniqueName. Isso adiciona o registro de metadados de entidade virtual à solução à medida que ela é criada. Para obter mais informações: Cabeçalhos HTTP

Pedido:

POST [Organization Uri]/api/data/v9.1/virtualentitymetadatas HTTP/1.1
MSCRM.SolutionUniqueName: YourSolutionUniqueName
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Authorization: Bearer [REDACTED]
Content-Type: application/json; charset=utf-8

{
  "@odata.type": "Microsoft.Dynamics.CRM.virtualentitymetadata",
  "name": "Person Virtual Metadata",
  "iscustomizable": {
    "@odata.type": "Microsoft.Dynamics.CRM.BooleanManagedProperty",
    "Value": false,
    "CanBeChanged": false
  },
  "isonexternalcreatedenabled": true,
  "isonexternaldeletedenabled": true,
  "isonexternalupdatedenabled": true,
  "extensionofrecordid@odata.bind": "entities(b198e6f3-3dd6-4c0b-9570-702f0c10d577)"
}

Resposta:

HTTP/1.1 204 No Content

Usando o SDK para .NET

Independentemente de usar tipos vinculados antecipados ou tardios, a primeira tarefa é obter o MetadataId da tabela, que é obtido da mesma forma para ambos os casos. Neste caso, para uma tabela virtual nomeada new_people usando CrmServiceClient. Alternativamente, a ServiceClient classe pode ser usada.

var service = new CrmServiceClient(conn);
// var service = new ServiceClient(conn);

var retrieveEntityRequest = new RetrieveEntityRequest
{
    LogicalName = "new_people",
    EntityFilters = EntityFilters.Entity
};

var retrieveEntityResponse = (RetrieveEntityResponse)service.Execute(retrieveEntityRequest);

var entityId = retrieveEntityResponse.EntityMetadata.MetadataId;

Utilizar tipos de vínculo antecipado

Com tipos de vínculo antecipado, pode usar a classe VirtualEntityMetadata gerada usando o comando de compilação da pac modelbuilder do Power Platform CLI. Mais informações: Programação de vínculo Tardio e vínculo Antecipado utilizando SDK para .NET

var virtualEntityMetadata = new VirtualEntityMetadata
{
    Name = "Person Virtual Metadata",
    ExtensionOfRecordId = new EntityReference("entity", entityId.Value),
    IsCustomizable = new BooleanManagedProperty(false),
    IsOnExternalCreatedEnabled = true,
    IsOnExternalDeletedEnabled = true,
    IsOnExternalUpdatedEnabled = true,
};

Utilizar tipos de vínculo tardio

Há duas formas de instanciar a instância dos metadados de entidade virtual usando tipos de vínculo tardio, ambas são equivalentes.

var virtualEntityMetadata = new Entity("virtualentitymetadata");
virtualEntityMetadata["name"] = "Person Virtual Metadata";
virtualEntityMetadata["extensionofrecordid"] = new EntityReference("entity", entityId.Value);
virtualEntityMetadata["iscustomizable"] = new BooleanManagedProperty(false);
virtualEntityMetadata["isonexternalcreatedenabled"] = true;
virtualEntityMetadata["isonexternaldeletedenabled"] = true;
virtualEntityMetadata["isonexternalupdatedenabled"] = true;

Ou:

  var virtualEntityMetadata = new Entity("virtualentitymetadata") { 
      Attributes = new AttributeCollection {
          { "name","Person Virtual Metadata" },
          { "extensionofrecordid", new EntityReference("entity", entityId.Value)},
          { "iscustomizable",new BooleanManagedProperty(false)},
          { "isonexternalcreatedenabled",true },
          { "isonexternaldeletedenabled",true },
          { "isonexternalupdatedenabled",true}
      }            
  };

Criando o registro

Ao criar o registro, use a classe CreateRequest em vez do método IOrganizationService.Create para que você possa incluir o SolutionUniqueName parâmetro opcional que adiciona o registro à sua solução ao criá-lo. Para obter mais informações: Passando parâmetros opcionais com uma solicitação

var createRequest = new CreateRequest
{
    Target = virtualEntityMetadata
};
createRequest["SolutionUniqueName"] = "YourSolutionUniqueName";

service.Execute(createRequest);

Ver as mensagens criadas para suportar a sua tabela virtual

Uma maneira fácil de verificar se as mensagens que ativou existem é examinar o documento de serviço $metadata da Web API.

Você pode fazer isso no seu navegador. Usando a URL da sua organização, digite o seguinte no navegador:

[Organization Uri]/api/data/v9.2/$metadata

Este é um documento XML grande, mas você pode procurar por 'OnExternalCreated' e encontrar a definição da ação, neste caso para a new_people tabela virtual.

<Action Name="OnExternalCreated" IsBound="true">
 <Parameter Name="entityset" Type="Collection(mscrm.new_people)" Nullable="false"/>
 <Parameter Name="Target" Type="mscrm.crmbaseentity" Nullable="false"/>
</Action>

Você pode ver que esta é uma Ação OData vinculada ao new_people conjunto de entidades. Você encontrará ações semelhantes para OnExternalDeleted, e OnExternalUpdated:

<Action Name="OnExternalDeleted" IsBound="true">
 <Parameter Name="entityset" Type="Collection(mscrm.new_people)" Nullable="false"/>
<Parameter Name="Target" Type="mscrm.crmbaseentity" Nullable="false"/>
</Action>
<Action Name="OnExternalUpdated" IsBound="true">
 <Parameter Name="entityset" Type="Collection(mscrm.new_people)" Nullable="false"/>
 <Parameter Name="Target" Type="mscrm.crmbaseentity" Nullable="false"/>
</Action>

Visualizar as mensagens usando a ferramenta de registro para plug-ins

Ao registrar uma etapa de plug-in usando a ferramenta de registro de plug-in, você encontrará essas mensagens.

Use as mensagens para notificar o Dataverse sobre as alterações

Para notificar o Dataverse sobre alterações, você deve chamar a API apropriada. Você pode usar a API Web Dataverse ou o SDK para .NET.

Antes de usar essas mensagens, convém usar o procedimento descrito em Exibir as mensagens criadas para dar suporte à sua tabela virtual para confirmar que elas existem.

Usando a API da Web

Como estas APIs são ações OData vinculadas a uma coleção de tabelas, pode seguir o padrão documentado aqui: Usar ações da API da Web> Ações vinculadas> Ações vinculadas a uma coleção de tabelas. A seguir estão alguns exemplos mostrando o uso da new_people tabela virtual.

Se o valor de ID for conhecido pelo sistema chamador, ele deve sempre ser incluído. A instância de entidade passada usando o parâmetro de destino deve ter a propriedade de anotação apropriada @odata.type definida para definir o tipo de entidade. Se isso não estiver incluído, um erro será retornado.

Estas chamadas devem sempre retornar 204: No Content.

OnExternalCreated

Para essa ação, os valores devem incluir todas as propriedades definidas quando o registro foi criado.

POST [Organization Uri]/api/data/v9.1/new_peoples/Microsoft.Dynamics.CRM.OnExternalCreated HTTP/1.1
Authorization: Bearer [REDACTED]
Content-Type: application/json
 
{
    "Target": {
        "@odata.type": "Microsoft.Dynamics.CRM.new_people",
        "new_name": "John",
        "new_age": 23,
        "new_lastname": "Doe",
        "new_peopleid": "f6f5896b-bf08-455c-9bd3-526760cb3685"
    }
}

OnExternalUpdated

Para esta ação, apenas as propriedades que foram alteradas devem ser incluídas.

POST [Organization Uri]/api/data/v9.1/new_peoples/Microsoft.Dynamics.CRM.OnExternalUpdated HTTP/1.1
Authorization: Bearer [REDACTED]
Content-Type: application/json
 
{
    "Target": {
        "@odata.type": "Microsoft.Dynamics.CRM.new_people",
        "new_age": 24,
        "new_peopleid": "f6f5896b-bf08-455c-9bd3-526760cb3685"
        }
}

OnExternalDeleted

Para esta ação, apenas é necessário o identificador exclusivo do registo.

POST [Organization Uri]/api/data/v9.1/new_peoples/Microsoft.Dynamics.CRM.OnExternalDeleted HTTP/1.1
Authorization: Bearer [REDACTED]
Content-Type: application/json
{
    "Target": {
        "@odata.type": "Microsoft.Dynamics.CRM.new_people",
        "new_peopleid": "f6f5896b-bf08-455c-9bd3-526760cb3685"
        }
}

Usando o SDK para .NET

Ao usar o SDK para .NET, você pode usar tipos de vinculação antecipada ou tardia. Mais informações: Programação de vínculo Tardio e vínculo Antecipado utilizando SDK para .NET

Tipos de vínculo antecipado

Este exemplo usa o CrmServiceClient com tipos de vínculo antecipado, embora ServiceClient também possa ser usado.

var service = new CrmServiceClient(conn);
// var service = new ServiceClient(conn);

//OnExternalCreated
var createPerson = new new_people
{
    new_peopleId = new Guid("f6f5896b-bf08-455c-9bd3-526760cb3685"),
    new_name = "John",
    new_Age = 23,
    new_LastName = "Doe"
};


var createRequest = new OnExternalCreatedRequest
{
    Target = createPerson
};

service.Execute(createRequest);

//OnExternalUpdated
var updatePerson = new new_people
{
    new_peopleId = new Guid("f6f5896b-bf08-455c-9bd3-526760cb3685"),
    new_Age = 24
};


var updateRequest = new OnExternalUpdatedRequest
{
    Target = updatePerson
};

service.Execute(updateRequest);

//OnExternalDeleted
var deletePerson = new new_people
{
    new_peopleId = new Guid("f6f5896b-bf08-455c-9bd3-526760cb3685")
};


var deleteRequest = new OnExternalDeletedRequest
{
    Target = deletePerson
};

Tipos de ligação tardia

Este exemplo usa o CrmServiceClient com tipos de vínculo tardio, embora ServiceClient também possa ser usado.

var service = new CrmServiceClient(conn);
// var service = new ServiceClient(conn);

  //OnExternalCreated
  Entity createPerson = new Entity("new_people");
  createPerson["new_peopleid"] = new Guid("f6f5896b-bf08-455c-9bd3-526760cb3685");
  createPerson["new_name"] = "John";
  createPerson["new_age"] = 23;
  createPerson["new_lastname"] = "Doe";

  
  var orgCreateRequest = new OrganizationRequest("OnExternalCreated");
  orgCreateRequest["Target"] = createPerson;

  service.Execute(orgCreateRequest);

  //OnExternalUpdated
  Entity updatePerson = new Entity("new_people");
  updatePerson["new_peopleid"] = new Guid("f6f5896b-bf08-455c-9bd3-526760cb3685");
  updatePerson["new_age"] = 24;

  
  var orgUpdateRequest = new OrganizationRequest("OnExternalUpdated");
  orgUpdateRequest["Target"] = updatePerson;

  service.Execute(orgUpdateRequest);

  //OnExternalDeleted
  Entity deletePerson = new Entity("new_people");
  deletePerson["new_peopleid"] = new Guid("f6f5896b-bf08-455c-9bd3-526760cb3685");

  
  var orgDeleteRequest = new OrganizationRequest("OnExternalDeleted");
  orgDeleteRequest["Target"] = deletePerson;

  service.Execute(orgDeleteRequest);

Ver também

Estrutura do evento
Eventos de negócios do Microsoft Dataverse
Introdução às tabelas virtuais (entidades)