Aktivieren virtueller Tabellen zur Unterstützung von Dataverse-Ereignissen

Sie können virtuellen Entitäten die Teilnahme an asynchronen Pipeline-Ereignissen im Dataverse-Ereignisframework und im Trigger Wenn eine Zeile hinzugefügt, geändert oder gelöscht wird des PowerAutomate Dataverse-Konnektors gestatten. Diese Funktion ist als Teil von Dataverse-Geschäftsereignissen aktiviert. Weitere Informationen: Microsoft Dataverse-Geschäftsereignisse

Ohne die in diesem Artikel beschriebene Konfiguration nehmen die meisten virtuellen Entitäten nicht wie andere Entitäten an der Pipeline des Ereignisframeworks teil. Da virtuelle Entitäten nicht an der Ereignispipeline teilnehmen, können Sie keine Plug-In-Schritte für auftretende Ereignisse zum Erstellen, Aktualisieren und Löschen registrieren. Und obwohl solche Ereignisse für diese Entitäten im Power Automate Dataverse-Konnektor auftreten, wird ein Fehler ausgegeben, wenn Benutzer versuchen, einen Flow zu speichern, der sie verwendet.

Das liegt daran, dass virtuelle Entitäten Daten darstellen, die in einer externen Quelle gespeichert sind. Dataverse hat als Client Zugriff auf dieses Datenquelle, aber andere Systeme können diese Daten jederzeit aktualisieren, ohne das Dataverse-Ereignisframework zu durchlaufen.

Zwei Schritte sind erforderlich, um dies zu aktivieren:

1. In einer Tabelle mit dem Namen Metadaten der virtuellen Entität müssen Daten konfiguriert werden. Wenn Daten in dieser Tabelle so konfiguriert sind, dass sie aktiviert werden, macht es eine Reihe neuer APIs möglich, dass Dataverse vom externen System beim Auftreten von Ereignissen zum Erstellen, Aktualisieren und Löschen benachrichtit wird.

   Wenn eine Metadatenzeile der virtuellen Entität EntityMetadata.Metadat-ID für eine virtuelle Tabelle zugeordnet ist, können die folgenden drei Einstellungen steuern, ob Ihre virtuelle Tabelle die Benachrichtigung durch eine externe Quelle unterstützen kann.

   Bei einzelner Aktivierung mit den booleschen Eigenschaften IsOnExternalCreatedEnabled, IsOnExternalDeletedEnabled und IsOnExternalUpdatedEnabled der Metadaten der virtuellen Entität stehen die folgenden gebundenen Aktionen für den Aufruf durch externe Dienste zur Verfügung.

   Aktion/Nachricht	Beschreibung
   OnExternalCreated	Enthält Daten zu einem Datensatz, der in einem externen System erstellt wurde und in Dataverse als virtuelle Tabelle verfügbar ist.
   OnExternalUpdated	Enthält Daten zu einem Datensatz, der in einem externen System aktualisiert wurde und in Dataverse als virtuelle Tabelle verfügbar ist.
   OnExternalDeleted	Enthält Daten zu einem Datensatz, der in einem externen System gelöscht wurde und in Dataverse als virtuelle Tabelle verfügbar ist.

2. Das externe System, das die Daten kontrolliert, muss eine authentifizierte HTTP-Anforderung an Dataverse senden und dazu die APIs verwenden, die durch Daten in den Metadaten der virtuellen Entität aktiviert wurden. Ein authentifiziertes Serviceprinzipalkonto fürht in der regel diesen Aufruf durch. Weitere Informationen: Erstellen von Webanwendungen mit der Server-zu-Server-(S2S)-Authentifizierung

   Aber jede Anwendung oder jeder Benutzer, der einen Aufruf an Dataverse durchführen kann, kann die zur Benachrichtigung erforderliche HTTP-Anforderung senden, um Dataverse über das Auftreten des Ereignisses zu benachrichtigen.

So aktivieren Sie Benachrichtigungs-APIs für virtuelle Tabellen

Sie können Benachrichtigungs-APIs aktivieren, indem Sie sie manuell im Entwicklerportal konfigurieren (make.powerapps.com/) oder Code verwenden.

Manuelles Aktivieren über das Entwicklerportal

Nehmen wir an, wir haben eine virtuelle Personentabelle mit diesen Eigenschaften, die Eigenschaft Name Eigentum ist auf new_People festgelegt.

1. Im Power Apps (make.powerapps.com), wählen Sie in Ihrer Lösung +Neu und dann Metadaten der virtuellen Entität auswählen.

   

   Damit wird das folgende Formular geöffnet:

   

2. Füllen Sie das Formular aus und legen Sie den Wert ID der Erweiterungsentität auf den Namen Ihrer virtuellen Tabelle fest. Sie müssen nicht alle drei Nachrichten aktivieren. Sie können eine oder mehrere von ihnen festlegen und später zurückkehren, um den Rest zu aktivieren.

Wenn Sie diese Nachrichten aktiviert haben, können Sie mit den Schritten in Anzeigen der zur Unterstützung Ihrer virtuellen Tabelle erstellten Nachrichten beobachten und bestätigen, was hinzugefügt wurde.

Verwaltete Eigenschaften über das Entwicklerportal festlegen

Wenn Sie nicht möchten, dass Personen, die Ihre verwaltete Lösung installieren, das Verhalten der Metadaten der virtuellen Entität ändern können, sollten Sie die verwaltete Eigenschaft mithilfe der folgenden Schritte so festlegen, dass dies verhindert wird.

1. Wählen Sie in Ihrer Lösung die Metadaten der virtuellen Entität aus und klicken Sie auf die Auslassungspunkte (...) und wählen Sie dann Verwaltete Eigenschaften aus.

   

2. Deaktivieren Sie im Bereich „Verwaltete Eigenschaften“ die Option Anpassungen zulassen und klicken Sie dann auf Fertig.

   

   Diese Einstellung hat aber keine Auswirkung, bis der Metadatensatz der virtuellen Entität in einer verwalteten Lösung enthalten ist.

Mit Code aktivieren

Möglicherweise möchten Sie die Erstellung von Metadaten für Ihre virtuellen Entitäten automatisieren.

Die Tabelle VirtualEntityMetadata bietet folgende Spalten, die Sie festlegen können:

Beim Erstellen dieser Typen von Lösungskomponenten empfehlen wir, die verwaltete Eigenschaft IsCustomizable auf false festzulegen, außer Sie möchten, dass Personen, die Ihre verwaltete Lösung installieren, diese Einstellungen ändern können.

Wir empfehlen Ihnen außerdem, den Datensatz Virtual Entity Metadata** zu einer bestimmten Lösung hinzuzufügen, wenn Sie diese erstellen. In den beiden folgenden Beispielen sehen Sie, wie Solution.UniqueName mit der Anforderung übergeben wird, die den Datensatz erstellt.

Verwenden von Web-API

Bei der Verwendung der Web-API besteht die erste Aufgabe darin, die MetadataId der virtuellen Tabelle abzurufen. Das folgende Beispiel gibt die MetadataId für eine virtuelle Entität mit dem Namen new_people zurück.

Anforderung:

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]

Antwort:

HTTP/1.1 200 OK

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

Erstellen Sie anschließend den Metadatensatz der virtuellen Entität, während Sie ihn dem Entitätstyp Entity zuweisen, indem Sie die im ersten Schritt abgerufene MetadataId verwenden.

Beachten Sie die Verwendung des Header MSCRM.SolutionUniqueName, der auf den Wert Solution.UniqueName festgelegt ist. Dadurch wird der Metadatensatz der virtuellen Entität bei der Erstellung zur Lösung hinzugefügt. Weitere Informationen: HTTP-Header

Anforderung:

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

Antwort:

HTTP/1.1 204 No Content

Verwenden des SDK für .NET

Unabhängig davon, ob Sie Typen mit früher oder später Bindung verwenden, besteht die erste Aufgabe darin, die MetadataId der Tabelle abzurufen, die für beide Fälle auf die gleiche Weise abgerufen wird. In diesem Fall für eine virtuelle Tabelle mit dem Namen new_people mit CRMServiceClient. Alternativ kann die ServiceClient-Klasse verwendet werden.

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;

Verwenden von Typen mit früher Bindung

Bei Typen mit früher Bindung können Sie die Klasse VirtualEntityMetadata verwenden, die mit Power Platform CLI pac modelbuilder Build-Befehl generiert wird. Weitere Informationen: Programmierung mit später und früher Bindung mithilfe des SDK für .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,
};

Verwenden von Typen mit später Bindung

Es gibt zwei Möglichkeiten, die Metadateninstanz der virtuellen Entität mithilfe spät gebundener Typen zu instanziieren, von denen beide gleichwertig sind:

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;

Oder:

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

Erstellen des Datensatzes

Verwenden Sie beim Erstellen des Datensatzes die Klasse CreateRequest anstelle der Methode IOrganizationService.Create, damit Sie den optionalen Parameter SolutionUniqueName einschließen können, der den Datensatz zu Ihrer Lösung hinzufügt, wenn Sie sie erstellen. Weitere Informationen: Übergabe optionaler Parameter mit einer Anfrage

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

service.Execute(createRequest);

Anzeigen der Nachrichten, die zur Unterstützung Ihrer virtuellen Tabelle erstellt wurden

Eine einfache Möglichkeit, um zu überprüfen, ob die von Ihnen aktivierten Nachrichten vorhanden sind, besteht darin, das $metadata-Dienstdokument der Web-API zu überprüfen.

Dies können Sie in Ihrem Browser tun. Geben Sie unter Verwendung der URL für Ihre Organisation Folgendes in den Browser ein:

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

Dies ist ein großes XML-Dokument, aber Sie können nach OnExternalCreated suchen und die Definition der Aktion finden, in diesem Fall für die virtuelle Tabelle 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>

Sie können sehen, dass dies eine OData-Aktion ist, die an das entityset new_people gebunden ist. Sie finden ähnliche Aktionen für OnExternalDeleted und 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>

Anzeigen der Nachrichten mit dem Plug-In-Registrierungstool

Wenn Sie einen Plug-In-Schritt mit dem Plug-In-Registrierungstool registrieren, finden Sie diese Meldungen.

Verwenden der Nachrichten, um Dataverse über die Änderungen zu benachrichtigen

Um Dataverse über Änderungen zu benachrichtigen, müssen Sie die entsprechende API aufrufen. Sie können entweder die Dataverse-Web-API oder das SDK für .NET verwenden.

Bevor Sie diese Nachrichten verwenden, sollten Sie das unter Anzeigen der Nachrichten, die zur Unterstützung Ihrer virtuellen Tabelle erstellt wurden beschriebene Verfahren verwenden, um zu bestätigen, dass sie vorhanden sind.

Verwenden der Web-API

Da es sich um APIs und OData-Aktionen handelt, die an eine Tabellensammlung gebunden sind, können Sie dem hier dokumentierten Muster folgen: Verwenden Sie „Web-API-Aktionen > Gebundene Aktionen > An eine Tabellensammlung gebundene Aktionen“. Im Folgenden finden Sie einige Beispiele für die Verwendung der virtuellen Tabelle new_people.

Wenn der ID-Wert dem aufrufenden System bekannt ist, sollte er immer enthalten sein. Für die mit dem Parameter Ziel übergebene Entitätsinstanz muss die entsprechende Anmerkungseigenschaft @odata.type so festgelegt sein, dass sie den Entitätstyp definiert. Wenn dies nicht enthalten ist, wird ein Fehler zurückgegeben.

Diese Anrufe sollten immer 204: No Content zurückgeben.

OnExternalCreated

Für diese Aktion sollten die Werte alle Eigenschaften enthalten, die beim Erstellen des Datensatzes festgelegt wurden.

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

Für diese Aktion sollten nur diejenigen Eigenschaften aufgenommen werden, die sich geändert haben.

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

Für diese Aktion ist nur der eindeutige Bezeichner für den Datensatz erforderlich.

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

Verwenden des SDK für .NET

Wenn Sie das SDK für .NET verwenden, können Sie entweder frühe oder späte Bindungstypen verwenden. Weitere Informationen: Programmierung mit später und früher Bindung mithilfe des SDK für .NET

Typen mit früher Bindung

Dieses Beispiel verwendet CrmServiceClient mit früh gebundenen Typen; ServiceClient könnte allerdings auch verwendet werden.

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

Typen mit später Bindung

Dieses Beispiel verwendet CrmServiceClient mit spät gebundenen Typen; ServiceClient könnte allerdings auch verwendet werden.

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

Siehe auch

Ereignisframework
Microsoft Dataverse Geschäftsereignisse
Erste Schritte mit virtuellen Tabellen (Entitäten)