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

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 fonctionnalité est activée dans le cadre des événements métier Dataverse. Plus d’informations : Événements professionnels Microsoft Dataverse

Sans la configuration décrite dans cet article, la plupart des entités virtuelles ne participent pas au pipeline Event Framework comme d’autres entités. Étant donné que les entités virtuelles ne participent pas au pipeline d’événements, vous ne pouvez pas inscrire les étapes de plug-in sur les événements Créer, Mettre à jour et Supprimer (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 utilisateurs essaient d’enregistrer un flux qui les utilise.

Cela est dû au fait que 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.

Il existe deux étapes pour activer ceci :

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 fournissent les moyens pour le système externe d’avertir 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'elles sont individuellement activées à l’aide des métadonnées IsOnExternalCreatedEnabled d’entité virtuelle, IsOnExternalDeletedEnabled et des propriétés booléennes IsOnExternalUpdatedEnabled, les actions associées suivantes deviennent disponibles pour être appelées par des services externes.

   Action/Message	Descriptif
   OnExternalCreated	Contient des données sur un enregistrement créé dans un système externe exposé en tant que table virtuelle dans Dataverse.
   OnExternalUpdated	Contient des données sur un enregistrement 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é sous forme de table virtuelle dans Dataverse.

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

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

Comment activer les API de notification pour les tables virtuelles

Vous pouvez activer les API de notification en les configurant manuellement dans le portail maker (make.powerapps.com/) ou en utilisant du code.

Activer manuellement via le portail créateur

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

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

   

   Cela ouvre le formulaire suivant :

   

2. Remplissez le formulaire, en définissant la valeur ID d’entité d’extension sur le nom de votre table virtuelle. Vous n’êtes pas obligé d’activer les trois messages. Vous pouvez définir un ou plusieurs d’entre eux et revenir pour activer le reste ultérieurement.

Lorsque vous avez activé ces messages, vous pouvez observer et confirmer ce qui a été ajouté à l’aide des étapes décrites dans Afficher les messages créés pour prendre en charge votre table virtuelle.

Définir des propriétés gérées à l’aide du portail Maker

Si vous ne souhaitez pas que les personnes qui installent votre solution managée modifient les comportements des métadonnées d’entité virtuelle, vous devez définir la propriété gérée pour l’empêcher d’utiliser les étapes suivantes.

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

   

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

   

   Ce paramètre ne fera rien tant que l’enregistrement de métadonnées d’entité virtuelle n’est pas inclus dans une solution managée.

Activer avec le code

Vous pouvez automatiser la création de métadonnées d’entité virtuelle pour vos entités virtuelles.

Le VirtualEntityMetadata tableau comporte les colonnes suivantes que vous pouvez définir :

Lors de la création de ces types de composants de solution, nous vous recommandons de définir la propriété gérée IsCustomizable à 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 le Solution.UniqueName est passé 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 du tableau virtuel. L’exemple suivant retourne l’entité MetadataId virtuelle nommée new_people.

Requête :

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 et associez-le au type d'entité Entity en utilisant la MetadataId récupérée lors de 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 de métadonnées d’entité virtuelle à la solution lors de sa création. Plus d’informations : en-têtes HTTP

Requête :

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 Kit de développement logiciel (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 à l’aide de CrmServiceClient. Vous pouvez également utiliser la ServiceClient classe.

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 de types à liaison anticipée

Avec les types à liaison anticipée, vous pouvez utiliser la classe générée à l’aide de la VirtualEntityMetadata commande Power Platform CLI pac modelbuilder build. 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 de types à liaison tardive

Il existe deux façons d’instancier l’instance de métadonnées d’entité virtuelle à l’aide de types à liaison tardive, et les deux sont équivalentes :

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 pour inclure le SolutionUniqueName paramètre facultatif qui ajoute l’enregistrement à votre solution lorsque vous le créez. Plus d’informations : Passage de 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 prendre en charge votre table virtuelle

Un moyen simple de vérifier que les messages que vous avez activés existent est d'examiner le document du service $metadata de la Web API.

Vous pouvez le faire dans votre navigateur. À l’aide de l’URL de votre organisation, tapez 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 rechercher la définition de l’action, dans ce cas pour la new_people table virtuelle.

<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 new_people d’entités. 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 l’outil d’enregistrement de plugins

Lorsque vous inscrivez une étape de plug-in à l’aide de l’outil d’inscription de plug-in, vous trouverez ces messages.

Utiliser les messages pour notifier Dataverse des modifications

Pour notifier Dataverse des modifications, vous devez appeler l’API appropriée. Vous pouvez utiliser l’API Web Dataverse ou le Kit de développement logiciel (SDK) pour .NET.

Avant d’utiliser ces messages, vous pouvez utiliser la procédure décrite dans Afficher les messages créés pour prendre en charge votre table virtuelle pour confirmer qu’elles 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 des actions de l'API web> Actions liées> Actions associées à une collection de tables. Voici quelques exemples montrant l’utilisation de la new_people table virtuelle.

Si la valeur d’ID est connue par le système appelant, elle doit toujours être incluse. L’instance d’entité passée à l’aide du paramètre cible doit avoir la propriété d’annotation appropriée @odata.type définie pour définir le type d’entité. Si ce n’est pas inclus, une erreur est retourné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 Kit de développement logiciel (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 CrmServiceClient avec des types à liaison anticipée, mais 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énements
Événements métier Microsoft Dataverse
Prise en main des tables virtuelles (entités)