Compartir a través de

Habilitar las tablas virtuales para admitir eventos de Dataverse

  • Artículo

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

Sin la configuración descritas en este artículo, la mayoría de las entidades virtuales no participan en la canalización de Event Framework como otras entidades. Debido a que las entidades virtuales no participan en la canalización del evento, no puede registrar los pasos del complemento en los eventos de creación, actualización y eliminación (CUD) que se producen, y aunque los eventos de CUD aparecen para estas entidades en el conector de Power Automate Dataverse, se produce un error cuando las personas intentan guardar un flujo que los usa.

Esto se debe a que las entidades virtuales representan datos almacenados en una fuente externa. 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. Configurar datos en una tabla llamada Metadatos de entidad virtual. Cuando los datos de esta tabla se configuran para habilitarlos, un conjunto de nuevas API proporcionan los medios para que el sistema externo notifique a Dataverse cuando ocurren los eventos CUD.

    Cuando hay una fila de metadatos de entidad virtual asociada con EntityMetadata.Metadataid para una tabla virtual, las siguientes tres configuraciones pueden controlar si una fuente externa puede notificar a su tabla virtual.

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

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

  2. El sistema externo que controla los datos debe enviar una solicitud HTTP autenticada a Dataverse utilizando las API que tienen datos en los metadatos de la entidad virtual. Una cuenta principal de servicio autenticada suele realizar 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 el evento ocurrió.

Nota

Las entidades virtuales que utilizan OData Provider y fuentes de fechas no relacionales pueden permitir ciertos registros de pasos de complementos, por ejemplo, solo en eventos fuera de la transacción. Pero estos eventos no están disponibles para su uso con el conector de Power Automate Dataverse. No es necesario cambiar este comportamiento. Pero, para una notificación de eventos más confiable, se recomienda el enfoque descrito en este tema.

Cómo habilitar las API de notificación para tablas virtuales

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

Habilitar manualmente usando el portal de creadores

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

Las propiedades de la tabla virtual new_people.

  1. En Power Apps (make.powerapps.com), dentro de su solución, seleccione +Nuevo y luego seleccione Metadatos de entidad virtual.

    Agregar un nuevo virtualentitymetadata a su solución.

    Esto abre el siguiente formulario:

    formulario virtualentitymetadata.

  2. Complete el formulario, configurando el valor Id. de entidad de extensión con el nombre de su tabla virtual. No es necesario que habilite los tres mensajes. Puede configurar uno o más y volver para habilitar el resto más tarde.

Cuando haya habilitado estos mensajes, puede observar y confirmar lo que se agregó usando los pasos en Ver los mensajes creados para apoyar su mesa virtual.

Establecer propiedades administradas mediante el portal de creadores

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

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

    Navegar a Propiedades administradas.

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

    Anule la selección de Permitir personalizaciones.

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

Habilitar con código

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

La tabla VirtualEntityMetadata tiene las siguientes columnas que puede establecer:

Nombre de esquema
Nombre lógico		 Nombre Tipo Descripción
ExtensionOfRecordId
extensionofrecordid		 Entidad virtual Búsqueda El nombre de la entidad virtual para la que son estas configuraciones.
IsCustomizable
iscustomiable		 Es personalizable ManagedProperty Controla si los metadatos de la entidad virtual se pueden cambiar o eliminar cuando se incluyen en una solución administrada.
IsOnExternalCreatedEnabled
isonexternalcreatedenabled		 Habilitar mensaje de creación externo Booleana Permite que un mensaje envíe información sobre nuevos registros creados en el origen de datos externo.
IsOnExternalDeletedEnabled
isonexternaldeletedenabled		 Habilitar mensaje de elimnación externo Booleana Permite que un mensaje envíe información sobre nuevos registros eliminados en el origen de datos externo.
IsOnExternalUpdatedEnabled
isonexternalupdatedenabled		 Habilitar mensaje de actualización externo Booleana Permite que un mensaje envíe información sobre nuevos registros actualizados en el origen de datos externo.
Name
name		 Name String Nombre de la configuración.
VirtualEntityMetadataId
virtualentitymetadataid		 VirtualEntityMetadata Uniqueidentifier Identificador único de instancias de entidad.

Al crear este tipo de componentes de la solución, le recomendamos que configure la propiedad administrada Es personalizable para que sea false a menos que desee permitir que las personas que instalen su solución administrada puedan cambiar esta configuración.

También recomendamos que agregue el registro de metadatos de entidad virtual** a una solución específica cuando la cree. En los dos ejemplos siguientes, verá cómo se pasa Solution.UniqueName con la solicitud que crea el registro.

Uso de la API web

Al utilizar la API web, la primera tarea es obtener el MetadataId de la tabla virtual. El siguiente ejemplo devuelve el MetadataId para una entidad virtual llamada 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"
}

Luego, cree el registro de metadatos de la entidad virtual mientras lo asocia tipo de entidad Entity usando el MetadataId recuperado en el primer paso.

Tenga en cuenta el uso del encabezado MSCRM.SolutionUniqueName establecido en el valor Solution.UniqueName. Esto agregará el registro de metadatos de la entidad virtual a la solución a medida que se crea. Más información: Ecabezados 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

Usar 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 llamada new_people utilizando CrmServiceClient. Alternativamente, se puede usar la clase ServiceClient.

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;

Usando tipos de enlace de tiempo de compilación

Con tipos de enlace temprano, puede usar la clase VirtualEntityMetadata generada con el comando de Power Platform CLI pac modelbuilder build. 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,
};

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

Creando el registro

Al crear el registro, utilice la clase CreateRequest en lugar del método IOrganizationService.Create para que pueda incluir el parámetro opcional SolutionUniqueName que agregará el registro a su solución cuando lo cree. 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 fácil de verificar que los mensajes que habilitó existen es examinar el documento de servicio de metadatos de la API web $.

Puede hacer esto en su navegador. Con la URL de su organización, escriba lo siguiente en su navegador:

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

Este es un documento XML grande, pero puede buscar 'OnExternalCreated' y 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 vinculada al entityset new_people. Encontrará acciones similares para OnExternalDeleted y 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>

Ver los mensajes usando la herramienta de registro del complemento

Cuando registre un paso de complemento utilizando la herramienta de registro de complemento, encontrará estos mensajes.

Registrar un paso de complemento en el mensaje OnExternalCreated para la entidad new_people.

Usa los mensajes para notificar los cambios a Dataverse

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

Antes de utilizar estos mensajes, es posible que desee utilizar el procedimiento que se describe en Ver los mensajes creados para apoyar su tabla virtual para confirmar que existen.

Uso de la API web

Debido a que estas API son acciones de OData vinculadas a una colección de tablas, puede seguir el patrón documentado aquí: Utilizar acciones de API web> Acciones vinculadas> Acciones vinculadas a una colección de tablas. Los siguientes son algunos ejemplos que muestran el uso de la tabla virtual new_people.

Si el sistema de llamada conoce el valor del id., siempre debe incluirse. La instancia de entidad pasada usando el parámetro Destino debe tener la propiedad de anotación @odata.type apropiada establecida para definir el tipo de entidad. Si no se incluye, se devolverá 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 aquellas 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 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);

Consulte también

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