Habilitación de tablas virtuales para admitir eventos de Dataverse

Puede permitir que las entidades virtuales participen en eventos de canalización de Event Framework de Dataverse asincrónico y en el desencadenador Cuando se agrega, modifica o elimina una fila del conector del conector de Dataverse de Power Automate. Esta funcionalidad está habilitada como parte de los eventos empresariales de Dataverse. Más información: Eventos empresariales de Microsoft Dataverse

Sin la configuración descrita en este artículo, la mayoría de las entidades virtuales no participan en la canalización de Event Framework, como otras entidades. Dado que las entidades virtuales no participan en la canalización de eventos, no es posible registrar pasos de complemento para los eventos de crear, actualizar y eliminar (CAE) que se producen. Aunque estos eventos CAE aparecen para estas entidades en el conector de Dataverse de Power Automate, se genera un error cuando los usuarios intentan guardar un flujo que los utiliza.

Esto se debe a que las entidades virtuales representan los datos almacenados en un origen externo. Dataverse tiene acceso a ese origen de datos como cliente, pero otros sistemas pueden actualizar esos datos en cualquier momento sin pasar por el marco de eventos de Dataverse.

Hay dos pasos para habilitar esto:

1. Configuración de datos en una tabla denominada Metadatos de entidad virtual. Cuando los datos de esta tabla están configurados para habilitarlos, un conjunto de nuevas API proporciona los medios para que el sistema externo notifique a Dataverse cuando se produzcan eventos CUD.

   Cuando hay una fila de metadatos de entidad virtual asociada a EntityMetadata. Metadataid para una tabla virtual, las tres opciones siguientes pueden controlar si un origen externo puede notificar a la tabla virtual.

   Cuando se habilitan individualmente usando las propiedades booleanas IsOnExternalCreatedEnabled, IsOnExternalDeletedEnabled y IsOnExternalUpdatedEnabled de los metadatos de la entidad virtual, las siguientes acciones enlazadas estarán disponibles para ser llamadas por servicios externos.

   Acción o mensaje	Description
   OnExternalCreated	Contiene datos sobre un registro que se creó en un sistema externo expuesto como una tabla virtual en Dataverse.
   OnExternalUpdated	Contiene datos sobre un registro que se actualizó en un sistema externo expuesto como una tabla virtual en Dataverse.
   OnExternalDeleted	Contiene datos sobre un registro que se eliminó en un sistema externo expuesto como una tabla virtual en Dataverse.

2. El sistema externo que controla los datos debe enviar una solicitud HTTP autenticada a Dataverse mediante las API que tienen datos en metadatos de entidad virtual. Normalmente, una cuenta de entidad de servicio autenticada realiza esta llamada. Más información: Crear aplicaciones web mediante la autenticación de servidor a servidor (S2S)

   Pero cualquier aplicación o usuario que pueda realizar una llamada a Dataverse puede enviar la solicitud http necesaria para notificar a Dataverse que se produjo el evento.

Habilitación de las API de notificación para tablas virtuales

Puede habilitar las API de notificación configurándolas manualmente en el portal de creador (make.powerapps.com/) o mediante código.

Habilitar manualmente mediante el portal de creadores

Supongamos que tenemos una tabla virtual de persona con estas propiedades, la propiedad Name es new_People.

1. En Power Apps (make.powerapps.com), en la solución, seleccione +Nuevo y, a continuación, seleccione Metadatos de entidad virtual.

   

   Se abrirá el siguiente formulario:

   

2. Complete el formulario y establezca el valor de Id. de entidad de extensión en el nombre de la tabla virtual. No es necesario habilitar los tres mensajes. Puede establecer uno o varios de ellos y volver para habilitar el resto más adelante.

Cuando haya habilitado estos mensajes, puede observar y confirmar lo que se agregó mediante los pasos descritos en Visualización de los mensajes creados para admitir la tabla virtual.

Configure propiedades administradas usando el portal del creador

Si no desea que las personas que instalen la solución administrada cambien los comportamientos de metadatos de la entidad virtual, debe establecer la propiedad administrada para evitarlo mediante los pasos siguientes.

1. En la solución, seleccione los metadatos de la entidad virtual y seleccione los puntos suspensivos (...) y, a continuación, seleccione Propiedades administradas.

   

2. En el panel Propiedades administradas, anule la selección de Permitir personalizaciones y presione Listo.

   

   Esta configuración no hará nada hasta que el registro de metadatos de entidad virtual se incluya en una solución administrada.

Habilitar con código

Es posible que quiera automatizar la creación de metadatos de entidad virtual para las entidades virtuales.

La VirtualEntityMetadata tabla tiene las columnas siguientes que puede establecer:

Al crear estos tipos de componentes de solución, se recomienda establecer la propiedad administrada IsCustomizable para que sea false a menos que quiera permitir que las personas que instalen la solución administrada puedan cambiar esta configuración.

También se recomienda agregar el registro Metadatos de entidad virtual** a una solución específica al crearlo. En los dos ejemplos siguientes, verá cómo se pasa Solution.UniqueName con la solicitud que crea el registro.

Uso de la API web

Cuando se usa la API web, la primera tarea es obtener la MetadataId de la tabla virtual. En el ejemplo siguiente se devuelve el MetadataId de una entidad virtual denominada new_people.

Solicitud:

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]

Respuesta:

HTTP/1.1 200 OK

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

A continuación, cree el registro de metadatos de la entidad virtual al asociarlo al Entity tipo de entidad mediante el MetadataId recuperado en el primer paso.

Tenga en cuenta el uso del encabezado MSCRM.SolutionUniqueName establecido en el valor Solution.UniqueName. Esto agrega el registro de metadatos de entidad virtual a la solución a medida que se crea. Más información: Encabezados HTTP

Solicitud:

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)"
}

Respuesta:

HTTP/1.1 204 No Content

Uso del SDK para .NET

Independientemente de si utiliza tipos de enlace temprano o tardío, la primera tarea es recuperar el MetadataId de la tabla, que se recupera de la misma forma para ambos casos. En este caso, para una tabla virtual denominada new_people con CrmServiceClient. Como alternativa, se puede usar la ServiceClient clase .

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 de enlace de tiempo de compilación

Con los tipos de enlace de tiempo de compilación, puede usar la clase VirtualEntityMetadata generada usando el comando de compilación pac modelbuilder de Power Platform CLI. Más información: Programación en tiempo de ejecución y en tiempo de compilación con 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,
};

Usar tipos de enlace de tiempo de ejecución

Hay dos formas de crear una instancia de metadatos de la entidad virtual utilizando tipos de enlace tardío, cualquiera de las dos es equivalente:

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;

O:

  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}
      }            
  };

Creación del registro

Al crear el registro, use la clase CreateRequest en lugar del método IOrganizationService.Create para que pueda incluir el SolutionUniqueName parámetro opcional que agrega el registro a la solución al crearlo. Más información: Pasar parámetros opcionales con una solicitud

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

service.Execute(createRequest);

Ver los mensajes creados para apoyar su tabla virtual

Una manera sencilla de comprobar que los mensajes habilitados existen es examinar el documento de servicio de $metadata api web.

Puede hacerlo en el explorador. Con la dirección URL de la organización, escriba lo siguiente en el explorador:

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

Se trata de un documento XML grande, pero puede buscar "OnExternalCreated" para encontrar la definición de la acción, en este caso para la tabla virtual new_people.

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

Puede ver que se trata de una acción de OData enlazada al new_people conjunto de entidades. Encontrará acciones similares para OnExternalDeletedy 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>

Visualización de los mensajes mediante la herramienta de registro del complemento

Al registrar un paso de complemento mediante la herramienta de registro de complementos, encontrará estos mensajes.

Usar los mensajes para notificar a Dataverse los cambios

Para notificar a Dataverse los cambios, debe llamar a la API adecuada. Puede usar la API web de Dataverse o el SDK para .NET.

Antes de usar estos mensajes, quizás desee usar el procedimiento descrito en Ver los mensajes creados para admitir su tabla virtual para confirmar que existen.

Uso de la API web

Dado que estas API son acciones de OData enlazadas a una colección de tablas, puede seguir el patrón documentado aquí: Usar acciones de API web> Acciones enlazadas> a una colección de tablas. A continuación se muestran algunos ejemplos que muestran el uso de la new_people tabla virtual.

Si el sistema que realiza la llamada conoce el valor de identificador, siempre debe incluirse. La instancia de entidad pasada mediante el parámetro Target debe tener establecida la propiedad de anotación adecuada @odata.type para definir el tipo de entidad. Si no se incluye, se devuelve un error.

Estas llamadas siempre deben devolver 204: No Content.

OnExternalCreated

Para esta acción, los valores deben incluir todas las propiedades establecidas cuando se creó el registro.

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 acción, solo se deben incluir las propiedades que han cambiado.

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 acción, solo es necesario el identificador único del registro.

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"
        }
}

Uso del SDK para .NET

Al usar el SDK para .NET, puede usar los tipos de enlace temprano o tardío. Más información: Programación en tiempo de ejecución y en tiempo de compilación con SDK para .NET

Tipos de enlace de tiempo de compilación

Este ejemplo usa CrmServiceClient con tipos de enlace en tiempo de compilación, aunque también se puede usar ServiceClient.

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 enlace de tiempo de ejecución

Este ejemplo usa CrmServiceClient con tipos de enlace en tiempo de ejecución, aunque también se puede usar ServiceClient.

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);

Véase también

Marco de trabajo de eventos
Eventos empresariales de Microsoft Dataverse
Introducción a las tablas virtuales (entidades)