Aktivieren von virtuellen 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 an der Event Framework-Pipeline wie anderen Entitäten teil. Da virtuelle Entitäten nicht an der Ereignispipeline teilnehmen, können Sie keine Plug-In-Schritte für Ereignisse zum Erstellen, Aktualisieren und Löschen (CUD) registrieren, und obwohl CUD-Ereignisse für diese Entitäten im Power Automate Dataverse-Connector angezeigt werden, wird ein Fehler ausgelöst, wenn Benutzer versuchen, einen Fluss zu speichern, der sie verwendet.

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

Es gibt zwei Schritte, um dies zu aktivieren:

1. Konfigurieren von Daten in einer Tabelle mit dem Namen "Virtuelle Entitätsmetadaten". Wenn Daten in dieser Tabelle so konfiguriert sind, dass sie aktiviert werden, stellen eine Reihe neuer APIs die Mittel bereit, mit denen das externe System Dataverse benachrichtigen kann, wenn CUD-Ereignisse auftreten.

   Wenn eine Metadatenzeile der virtuellen Entität EntityMetadata.Metadaten-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	Description
   OnExternalCreated	Enthält Daten zu einem Datensatz, der in einem externen System erstellt wurde, das als virtuelle Tabelle in Dataverse verfügbar gemacht wurde.
   OnExternalUpdated	Enthält Daten zu einem Datensatz, der in einem externen System aktualisiert wurde, das als virtuelle Tabelle in Dataverse verfügbar gemacht wurde.
   OnExternalDeleted	Enthält Daten zu einem Datensatz, der in einem externen System gelöscht wurde, das als virtuelle Tabelle in Dataverse verfügbar gemacht wurde.

2. Das externe System, das die Daten steuert, muss eine authentifizierte HTTP-Anforderung mithilfe der APIs mit Daten in Virtual Entity Metadata an Dataverse senden. Ein authentifiziertes Dienstprinzipalkonto führt diesen Aufruf in der Regel aus. Weitere Informationen: Erstellen von Webanwendungen mit der Server-zu-Server-(S2S)-Authentifizierung

   Aber jede Anwendung oder ein Benutzer, die einen Aufruf von Dataverse ausführen können, kann die http-Anforderung senden, die erforderlich ist, um Dataverse darüber zu benachrichtigen, dass das Ereignis aufgetreten ist.

So aktivieren Sie Benachrichtigungs-APIs für virtuelle Tabellen

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

Manuelles Aktivieren über das Maker Portal

Angenommen, wir haben eine virtuelle Person-Tabelle mit diesen Eigenschaften, die Name-Eigenschaft ist new_People.

1. Wählen Sie in Power Apps (make.powerapps.com) in Ihrer Lösung +Neu und dann virtuelle Entitätsmetadaten aus.

   

   Dadurch wird das folgende Formular geöffnet:

   

2. Füllen Sie das Formular aus, und geben Sie als Wert der Erweiterungsentitäts-ID den Namen Ihrer virtuellen Tabelle an. Sie müssen nicht alle drei Nachrichten aktivieren. Sie können eine oder mehrere davon festlegen und zurückkehren, um den Rest später zu aktivieren.

Wenn Sie diese Nachrichten aktiviert haben, können Sie feststellen und bestätigen, was mithilfe der Schritte in der Ansicht der erstellten Nachrichten zur Unterstützung Ihrer virtuellen Tabelle hinzugefügt wurde.

Festlegen verwalteter Eigenschaften mithilfe des Maker-Portals

Wenn Sie nicht möchten, dass Personen, die Ihre verwaltete Lösung installieren, das Verhalten der Metadaten für virtuelle Entitäten ändern, sollten Sie die verwaltete Eigenschaft festlegen, um dies mithilfe der folgenden Schritte zu verhindern.

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 drücken Sie "Fertig".

   

   Diese Einstellung hat keine Wirkung, bis der Datensatz für Virtuelle Entitätsmetadaten in einer verwalteten Lösung enthalten ist.

Aktivieren mit Code

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

Die VirtualEntityMetadata Tabelle enthält die folgenden Spalten, die Sie festlegen können:

Beim Erstellen dieser Arten von Lösungskomponenten wird empfohlen, die verwaltete Eigenschaft IsCustomizable auf false festzulegen, es sei denn, Sie möchten Personen, die Ihre verwaltete Lösung installieren, erlauben, diese Einstellungen zu ändern.

Es wird auch empfohlen, den Eintrag "Virtuelle Entität-Metadaten**" einer bestimmten Lösung hinzuzufügen, wenn Sie diesen erstellen. In beiden unten stehenden Beispielen sehen Sie, wie die Solution.UniqueName-Anforderung zusammen mit dem Erstellungsantrag für den Datensatz übergeben wird.

Verwenden von Web-API

Wenn Sie die Web-API verwenden, besteht die erste Aufgabe darin, die MetadataId virtuelle Tabelle abzurufen. Das folgende Beispiel gibt das 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 virtuelle Entitätsmetadatensatz der Lösung hinzugefügt, sobald sie erstellt wird. 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 früh oder spät gebundene Typen verwenden, besteht die erste Aufgabe darin, die MetadataId 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_peopleCrmServiceClient. 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 früh gebundenen Typen

Mit früh gebundenen Typen können Sie die VirtualEntityMetadata Klasse verwenden, die mit dem Power Platform CLI pac modelbuilder build-Befehl generiert wird. Weitere Informationen: Spätgebundene und früh gebundene Programmierung mit dem 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 spät gebundenen Typen

Es gibt zwei Möglichkeiten, die Instanz der virtuellen Entitätsmetadaten mit spät gebundenen Typen zu instanziieren. Beide sind gleichwertig:

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 Eintrags

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

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

service.Execute(createRequest);

Anzeigen der erstellten Nachrichten zur Unterstützung Ihrer virtuellen Tabelle

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

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

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

Dies ist ein großes XML-Dokument, Sie können jedoch nach "OnExternalCreated" suchen und die Definition der Aktion in diesem Fall für die new_people virtuelle Tabelle finden.

<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 new_people Entityset 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 mithilfe des Plug-In-Registrierungstools

Wenn Sie einen Plug-In-Schritt mithilfe des Plug-In-Registrierungstools registrieren, finden Sie diese Nachrichten.

Verwenden der Nachrichten, um Dataverse über Ä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 in der Beschreibung beschriebene Verfahren in der Ansicht der erstellten Nachrichten verwenden, um Ihre virtuelle Tabelle zu unterstützen , um zu bestätigen, dass sie vorhanden sind.

Verwenden der Web-API

Da es sich bei diesen APIs um OData-Aktionen handelt, die an eine Tabellensammlung gebunden sind, können Sie dem hier dokumentierten Muster folgen: Verwenden von Web-API-Aktionen> gebundene Aktionen> Aktionen, die an eine Tabellensammlung gebunden sind. Im Folgenden sind einige Beispiele aufgeführt, die die Verwendung der new_people virtuellen Tabelle zeigen.

Wenn der ID-Wert vom aufrufenden System bekannt ist, sollte er immer einbezogen werden. Die Entitätsinstanz, die mit dem Target-Parameter übergeben wird, muss die entsprechende @odata.type Anmerkungseigenschaft festgelegt haben, um den Entitätstyp zu definieren. Wenn dies nicht enthalten ist, wird ein Fehler zurückgegeben.

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

OnExternalCreated

Bei dieser 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 die Eigenschaften einbezogen werden, die geändert wurden.

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: Spätgebundene und früh gebundene Programmierung mit dem SDK für .NET

Frühgebundene Typen

In diesem Beispiel wird der CrmServiceClient mit früh gebundenen Typen verwendet, obwohl auch ServiceClient verwendet werden könnte.

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

In diesem Beispiel wird der CrmServiceClient mit spät gebundenen Typen verwendet, obwohl auch ServiceClient verwendet werden kann.

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)