Habilitar tabelas virtuais para dar suporte a eventos do Dataverse

Você pode permitir que entidades virtuais participem de eventos de pipeline assíncronos da estrutura de eventos do Dataverse e no conector do PowerAutomate Dataverse Quando uma linha é adicionada, modificada ou excluída. Essa funcionalidade está habilitada como parte de eventos de negócios do Dataverse. 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 do pipeline de eventos, você não pode registrar etapas de plug-in em eventos CUD (Criar, Atualizar, Excluir) que ocorrem, mas, embora os eventos CUD apareçam para essas entidades no conector do Power Automate Dataverse, um erro é exibido quando as pessoas tentam salvar 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 Dataverse.

Há duas etapas para habilitar isso:

1. Configurando dados em uma tabela chamada Metadados de Entidade Virtual. Quando os dados nesta tabela são configurados para habilitar eventos CUD, um conjunto de novas APIs fornece os meios para o sistema externo notificar o Dataverse quando esses eventos ocorrerem.

   Quando há uma entrada de metadados de entidade virtual associada ao EntityMetadata.Metadataid de uma tabela virtual, as seguintes três configurações podem controlar se uma fonte externa pode notificar a sua tabela virtual.

   Quando habilitadas individualmente usando os metadados de entidade virtual IsOnExternalCreatedEnabled, IsOnExternalDeletedEnabled e IsOnExternalUpdatedEnabled, as propriedades boolianas, as ações vinculadas a seguir ficam disponíveis para serem chamadas por serviços externos.

   Ação/mensagem	Description
   OnExternalCreated	Contém dados sobre um registro 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 realiza essa chamada. Mais informações: Criar aplicativos Web usando a autenticação de servidor para servidor (S2S)

   Mas qualquer aplicativo ou usuário que possa executar 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 AS APIs de notificação configurando-as manualmente no portal do criador (make.powerapps.com/) ou usando código.

Habilitar manualmente usando o portal do Maker

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

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

   

   Isso abre o seguinte formulário:

   

2. Conclua o formulário, definindo o valor da ID da Entidade de Extensão como o nome da tabela virtual. Você não precisa habilitar as três mensagens. Você pode definir um ou mais deles e voltar para habilitar o restante mais tarde.

Quando você tiver habilitado essas mensagens, poderá observar e confirmar o que foi adicionado usando as etapas em Exibir as mensagens criadas para dar suporte à 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 de usar as etapas a seguir.

1. Em sua solução, selecione os metadados de entidade virtual, clique nas reticências (...) e escolha Propriedades Gerenciadas.

   

2. No painel Propriedades Gerenciadas, desmarque Permitir Personalizações e pressione Done.

   

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

Habilitar com código

Talvez você queira 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 você defina a propriedade gerenciada IsCustomizable como sendo false , a menos que você queira permitir que as pessoas que instalam sua solução gerenciada possam alterar essas configurações.

Também recomendamos que você adicione o registro de 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 Web

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

Pedir:

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 registro de metadados de entidade virtual ao associá-lo ao Entity tipo de entidade usando o MetadataId recuperado na primeira etapa.

Observe o uso do cabeçalho MSCRM.SolutionUniqueName definido para o valor Solution.UniqueName. Isso adiciona o registro de metadados de entidade virtual à solução à medida que é criada. Mais informações: cabeçalhos HTTP

Pedir:

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 você usar tipos antecipados ou tardios, a primeira tarefa é recuperar o MetadataId da tabela, que é recuperada da mesma forma para ambos os casos. Nesse caso, para uma tabela virtual chamada new_people usando CrmServiceClient. Como alternativa, 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;

Usar tipos vinculados antecipadamente

Com tipos de associação inicial, você pode usar a VirtualEntityMetadata classe gerada usando o comando pac modelbuilder build da CLI do Power Platform. Mais informações: programação com associação tardia e associação antecipada usando o 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,
};

Uso dos tipos de associação tardia

Há duas maneiras de instanciar os metadados de entidade virtual usando tipos de associação tardia, e 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. Mais informações: Passando parâmetros opcionais com uma solicitação

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

service.Execute(createRequest);

Exibir as mensagens criadas para dar suporte à tabela virtual

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

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

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

Este é um documento XML grande, mas você pode pesquisar 'OnExternalCreated' e encontrar a definição da ação, nesse 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 associada 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 de plug-ins

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

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

Para notificar o Dataverse sobre as alterações, você deve chamar a API apropriada. Você pode usar a API Web do 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 à tabela virtual para confirmar se elas existem.

Usando a API Web

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

Se o valor da ID for conhecido pelo sistema de chamada, ele sempre deverá 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 especificar o tipo de entidade. Se isso não estiver incluído, um erro será retornado.

Essas chamadas sempre devem 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 essa ação, somente 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 essa ação, somente o identificador exclusivo para o registro é necessário.

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 associação iniciais ou tardios. Mais informações: programação com associação tardia e associação antecipada usando o SDK para .NET

Tipos de associação antecipada

Este exemplo usa o CrmServiceClient com tipos de associação antecipada, 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 associação tardia

Este exemplo usa o CrmServiceClient com tipos de associação tardia, 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);

Consulte Também

Estrutura de eventos
Eventos empresariais do Microsoft Dataverse
Introdução às tabelas virtuais (entidades)