Partager via

Activer les tables virtuelles pour prendre en charge des événements Dataverse

  • Article

Vous pouvez autoriser les entités virtuelles à participer à des événements de pipeline de l’infrastructure d’événements Dataverse et dans le déclencheur Lorsqu’une ligne est ajoutée, modifiée ou supprimée du connecteur PowerAutomate Dataverse. Cette capacité est activée dans le cadre des événements commerciaux Dataverse. Plus d’information : Événements d’entreprise Microsoft Dataverse

Sans la configuration décrite dans cet article, la plupart des entités virtuelles ne participent pas au pipeline Event Framework comme les autres entités. Comme les entités virtuelles ne participent pas au pipeline d’événements, vous ne pouvez pas enregistrer les étapes du plug-in dans les événements de création, de mise à jour et de suppression (CUD) qui se produisent, et bien que les événements CUD apparaissent pour ces entités dans le connecteur Power Automate Dataverse, une erreur est générée lorsque les personnes tentent de sauvegarder un flux qui les utilise.

En effet, les entités virtuelles représentent des données stockées dans une source externe. Dataverse a accès à cette source de données en tant que client, mais d’autres systèmes peuvent mettre à jour ces données à tout moment sans passer par l’infrastructure d’événements Dataverse.

Pour ce faire, il existe deux étapes :

  1. Configuration des données dans une table appelée Métadonnées d’entité virtuelle. Lorsque les données de cette table sont configurées pour les activer, un ensemble de nouvelles API permet au système externe de notifier Dataverse lorsque des événements CUD se produisent.

    Lorsqu’une ligne de métadonnées d’entité virtuelle est associée à EntityMetadata.Metadataid pour une table virtuelle, les trois paramètres suivants peuvent contrôler si une source externe peut notifier votre table virtuelle.

    Lorsqu’il est activé individuellement à l’aide des propriétés booléennes IsOnExternalCreatedEnabled, IsOnExternalDeletedEnabled, et IsOnExternalUpdatedEnabled des métadonnées d’entité virtuelle, les actions liées suivantes deviennent disponibles pour être appelées par des services externes.

    Action/Message Description
    OnExternalCreated Contient des données sur un enregistrement qui a été créé dans un système externe exposé en tant que table virtuelle dans Dataverse.
    OnExternalUpdated Contient des données sur un enregistrement qui a été mis à jour dans un système externe exposé en tant que table virtuelle dans Dataverse.
    OnExternalDeleted Contient des données sur un enregistrement qui a été supprimé dans un système externe exposé en tant que table virtuelle dans Dataverse.

  2. Le système externe qui contrôle les données doit envoyer une requête HTTP authentifiée à Dataverse en utilisant les API contenant des données dans les métadonnées de l’entité virtuelle. Un compte principal de service authentifié effectue généralement cet appel. Pour plus d’informations : Créer des applications web en utilisant l’authentification de serveur à serveur (S2S)

    Mais toute application ou tout utilisateur pouvant effectuer un appel vers Dataverse peut envoyer la requête http nécessaire pour notifier Dataverse que l’événement s’est produit.

Notes

Les entités virtuelles utilisant le fournisseur OData et les sources de date non relationnelles peuvent autoriser certains enregistrements d’étapes de plug-in, par exemple uniquement sur des événements extérieurs à la transaction. Mais ces événements ne sont pas disponibles pour une utilisation avec le connecteur Power Automate Dataverse. Vous n’avez pas besoin de modifier ce comportement. Mais pour une notification d’événement plus fiable, l’approche décrite dans ce sujet est recommandée.

Comment activer les API de notification pour les tables virtuelles

Vous pouvez activer les API de notification en les configurant manuellement dans le portail de créateur (make.powerapps.com/) ou à l’aide de code.

Activer manuellement à l’aide du portail maker

Disons que nous avons une table virtuelle de personne avec ces propriétés, la propriété Nom est new_People.

Propriétés de la table virtuelle new_people.

  1. Dans Power Apps (make.powerapps.com), dans votre solution, sélectionnez +Nouveau puis sélectionnez Métadonnées d’entité virtuelle.

    Ajouter de nouvelles métadonnées d′entité virtuelle à votre solution.

    Cela ouvre le formulaire suivant :

    Formulaire virtualentitymetadata.

  2. Remplissez le formulaire en définissant le Valeur ID de l’entité d’extension au nom de votre table virtuelle. Il n’est pas nécessaire d’activer les trois messages. Vous pouvez définir un ou plusieurs d’entre eux et revenir pour activer le reste plus tard.

Lorsque vous avez activé ces messages, vous pouvez observer et confirmer ce qui a été ajouté en suivant les étapes dans Afficher les messages créés pour soutenir votre table virtuelle.

Définir les propriétés gérées à l’aide du créateur de portail

Si vous ne souhaitez pas que les personnes qui installent votre solution gérée modifient les comportements des métadonnées de l’entité virtuelle, vous devez définir la propriété gérée pour l’empêcher en procédant comme suit.

  1. Dans votre solution, sélectionnez les métadonnées de l’entité virtuelle, sélectionnez les points de suspension (...), puis sélectionnez Propriétés gérées.

    Accéder aux propriétés gérées.

  2. Dans le volet Propriétés gérées, désélectionnez Autoriser les personnalisations et appuyez sur Terminé.

    Désélectionnez Autoriser les personnalisations.

    Ce paramètre ne fait rien tant que l’enregistrement Métadonnées de l’entité virtuelle n’est pas inclus dans un solution gérée.

Activer avec du code

Vous souhaiterez peut-être automatiser la création de métadonnées d’entité virtuelle pour vos entités virtuelles.

La table VirtualEntityMetadata a les colonnes suivantes que vous pouvez définir :

Nom du schéma
Nom logique		 Nom d’affichage Type Description
ExtensionOfRecordId
extensionofrecordid		 Entité virtuelle Rechercher Le nom de l’entité virtuelle à laquelle ces paramètres sont destinés.
IsCustomizable
iscustomiable		 Est personnalisable ManagedProperty Contrôle si les métadonnées de l’entité virtuelle peuvent être modifiées ou supprimées lorsqu’elles sont incluses dans un solution gérée.
IsOnExternalCreatedEnabled
isonexternalcreatedenabled		 Activer le message de création externe Boolean Permet à un message d’envoyer des informations sur les enregistrements créés dans la source de données externe.
IsOnExternalDeletedEnabled
isonexternaldeletedenabled		 Activer le message de suppression externe Boolean Permet à un message d’envoyer des informations sur les enregistrements supprimés dans la source de données externe.
IsOnExternalUpdatedEnabled
isonexternalupdatedenabled		 Activer le message de mise à jour externe Boolean Permet à un message d’envoyer des informations sur les enregistrements mis à jour dans la source de données externe.
Name
name		 Nom String Nom des paramètres.
VirtualEntityMetadataId
virtualentitymetadataid		 VirtualEntityMetadata Uniqueidentifier Identificateur unique des instances d’entité

Lors de la création de ces types de composants de solution, nous vous recommandons de définir la propriété gérée Est Personnalisable à false à moins que vous ne vouliez autoriser les personnes qui installent votre solution gérée à pouvoir modifier ces paramètres.

Nous vous recommandons également d’ajouter l’enregistrement Métadonnées d’entité virtuelle** à une solution spécifique lorsque vous la créez. Dans les deux exemples ci-dessous, vous verrez comment Solution.UniqueName est transmis avec la requête qui crée l’enregistrement.

Utilisation de l’API Web

Lorsque vous utilisez l’API Web, la première tâche consiste à obtenir le MetadataId de la table virtuelle. L’exemple suivant renvoie le MetadataId pour une entité virtuelle nommée new_people.

Demande :

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]

Réponse :

HTTP/1.1 200 OK

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

Ensuite, créez l’enregistrement de métadonnées d’entité virtuelle en l’associant au type d’entité Entity à l’aide du MetadataId récupéré dans la première étape.

Notez l’utilisation de l’en-tête MSCRM.SolutionUniqueName défini sur la valeur Solution.UniqueName. Cela ajoute l’enregistrement des métadonnées de l’entité virtuelle à la solution lors de sa création. Pour plus d’informations, voir : En-têtes HTTP

Demande :

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

Réponse :

HTTP/1.1 204 No Content

Utilisation du SDK pour .NET

Que vous utilisiez des types à liaison précoce ou tardive, la première tâche consiste à récupérer le MetadataId du tableau, qui est récupéré de la même manière dans les deux cas. Dans ce cas pour une table virtuelle nommée new_people utilisant CrmServiceClient. Sinon, la classe ServiceClient peut aussi être utilisée.

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;

Utilisation des types à liaison anticipée

Avec les types à liaison anticipée, vous pouvez utiliser la classe VirtualEntityMetadata générée à l’aide de la commande pac modelbuilder build de Power Platform CLI. Pour plus d’informations, voir : Programmation avec liaison tardive et anticipée à l’aide du SDK pour .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,
};

Utilisation des types à liaison tardive

Il existe deux manières d’instancier l’instance de métadonnées d’entité virtuelle à l’aide de types à liaison tardive, l’une ou l’autre étant équivalente :

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

Création de l’enregistrement

Lors de la création de l’enregistrement, utilisez la Classe CreateRequest plutôt que la Méthode IOrganizationService.Create afin de pouvoir inclure le paramètre facultatif SolutionUniqueName qui ajoute l’enregistrement à votre solution lorsque vous le créez. Plus d’informations : Transmettre des paramètres facultatifs avec une requête

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

service.Execute(createRequest);

Afficher les messages créés pour soutenir votre table virtuelle

Un moyen simple de vérifier que les messages que vous avez activés existent consiste à examiner le document de l’API web du service $metadata.

Vous pouvez le faire dans votre navigateur. À l’aide de l’URL de votre organisation, saisissez ce qui suit dans votre navigateur :

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

Il s’agit d’un document XML volumineux, mais vous pouvez rechercher « OnExternalCreated » et retrouvez la définition de l’action, en l’occurrence pour la table virtuelle 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>

Vous pouvez voir qu’il s’agit d’une action OData liée à l’ensemble d’entités new_people. Vous trouverez des actions similaires pour OnExternalDeleted et 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>

Afficher les messages à l’aide de Plugin Registration Tool

Lorsque vous enregistrez une étape du plug-in à l’aide de Plugin Registration Tool, vous trouverez ces messages.

Enregistrement d’une étape de plug-in sur le message OnExternalCreated pour l’entité new_people.

Utilisez les messages pour notifier Dataverse des changements

Pour prévenir Dataverse des modifications, vous devez appeler l’API appropriée. Vous pouvez utiliser l’API web Dataverse ou le SDK pour .NET.

Avant d’utiliser ces messages, vous pouvez utiliser la procédure décrite dans Afficher les messages créés pour soutenir votre table virtuelle pour confirmer qu’ils existent.

Utilisation de l’API Web

Étant donné que ces API sont des actions OData liées à une collection de tables, vous pouvez suivre le modèle documenté ici : Utiliser les actions de l’API Web > Actions liées > Actions liées à une collection de tables. Voici quelques exemples illustrant l’utilisation de la table virtuelle new_people.

Si la valeur ID est connue du système appelant, elle doit toujours être incluse. L’instance d’entité transmise à l’aide du paramètre Cible doit avoir le jeu de propriétés d’annotation @odata.type appropriée pour définir le type d’entité. Si elle n’est pas incluse, une erreur est renvoyée.

Ces appels doivent toujours retourner 204: No Content.

OnExternalCreated

Pour cette action, les valeurs doivent inclure toutes les propriétés définies lors de la création de l’enregistrement.

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

Pour cette action, seules les propriétés qui ont changé doivent être incluses.

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

Pour cette action, seul l’Identificateur unique de l’enregistrement est nécessaire.

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

Utilisation du Kit de développement logiciel (SDK) pour .NET

Lorsque vous utilisez le SDK pour .NET, vous pouvez utiliser des types de liaison anticipée ou tardive. Pour plus d’informations, voir : Programmation avec liaison tardive et anticipée à l’aide du SDK pour .NET

Types à liaison anticipée

Cet exemple utilise le CrmServiceClient avec des types à liaison anticipée, même si ServiceClient peut également être utilisé.

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

Types à liaison tardive

Cet exemple utilise le CrmServiceClient avec des types à liaison tardive, même si ServiceClient peut également être utilisé.

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

Voir aussi

Infrastructure d’événement
Événements métiers Microsoft Dataverse
Se familiariser avec les tables virtuelles (entités)