Aktivér virtuelle tabeller for at understøtte Dataverse-hændelser

Du kan tillade, at virtuelle objekter deltager i asynkrone Dataverse Event Framework-pipelinehændelser og i PowerAutomate Dataverse-connectoren Når en række tilføjes, ændres eller slettes . Denne funktion er aktiveret som en del af Dataverse-forretningshændelser. Flere oplysninger: Microsoft Dataverse-forretningshændelser

Uden den konfiguration, der er beskrevet i denne artikel, deltager de fleste virtuelle objekter ikke i Event Framework-pipelinen på samme måde som andre enheder. Da virtuelle objekter ikke deltager i hændelsespipelinen, kan du ikke registrere plug-in-trin i forbindelse med CUD-hændelser (Create, Update og Delete), og selvom CUD-hændelser vises for disse enheder i Power Automate Dataverse-connectoren, udløses der en fejl, når andre forsøger at gemme et flow, der bruger dem.

Dette skyldes, at virtuelle objekter repræsenterer data, der er gemt i en ekstern kilde. Dataverse har adgang til datakilden som en klient, men andre systemer kan opdatere disse data når som helst uden at gå gennem Dataverse-hændelsesstrukturen.

Der er to trin til at aktivere dette:

1. Konfiguration af data i en tabel kaldet Metadata for virtuelt objekt. Når data i denne tabel er konfigureret til at aktivere dem, giver et sæt nye API'er det eksterne system mulighed for at give Dataverse besked, når der opstår CUD-hændelser.

   Når der er knyttet en række med virtuelle objektmetadata til EntityMetadata. Metadataid for en virtuel tabel kan følgende tre indstillinger styre, om en ekstern kilde kan give din virtuelle tabel besked.

   Når individuelt aktiveret ved hjælp af de virtuelle objektmetadata IsOnExternalCreatedEnabled, IsOnExternalDeletedEnabledog IsOnExternalUpdatedEnabled booleske egenskaber, bliver følgende bundne handlinger tilgængelige, så de kan kaldes af eksterne tjenester.

   Handling/meddelelse	Beskrivelse
   OnExternalCreated	Indeholder data om en post, der blev oprettet i et eksternt system, der vises som en virtuel tabel i Dataverse.
   OnExternalUpdated	Indeholder data om en post, der blev opdateret i et eksternt system, der vises som en virtuel tabel i Dataverse.
   OnExternalDeleted	Indeholder data om en post, der er slettet i et eksternt system, der vises som en virtuel tabel i Dataverse.

2. Det eksterne system, der styrer dataene, skal sende en godkendt HTTP-anmodning til Dataverse ved hjælp af de API'er, der har data i metadata for virtuelle objekter. En godkendt tjenesteprincipalkonto udfører typisk dette opkald. Flere oplysninger: Opbygge webprogrammer ved hjælp af server til server-godkendelse (S2S)

   Men alle programmer eller brugere, der kan udføre et kald til Dataverse, kan sende den http-anmodning, der er nødvendig for at give Dataverse besked om, at hændelsen fandt sted.

Sådan aktiverer du meddelelses-API'er for virtuelle tabeller

Du kan aktivere meddelelses-API'er ved manuelt at konfigurere dem på udviklerportalen (make.powerapps.com/) eller ved hjælp af kode.

Aktivér manuelt ved hjælp af udviklerportalen

Lad os antage, at vi har en virtuel persontabel med disse egenskaber. Egenskaben Name er new_People.

Egenskaberne for den virtuelle tabel new_people.

1. I Power Apps (make.powerapps.com) i din løsning skal du vælge +Ny og derefter vælge Metadata for virtuelle objekter.

   

   Dette åbner følgende formular:

   

2. Udfyld formularen, og angiv værdien for udvidelsesobjekt-id'et til navnet på den virtuelle tabel. Du behøver ikke at aktivere alle tre meddelelser. Du kan angive en eller flere af dem og vende tilbage for at aktivere resten senere.

Når du har aktiveret disse meddelelser, kan du se og bekræfte, hvad der er tilføjet, ved hjælp af trinnene i Få vist de meddelelser, der er oprettet for at understøtte den virtuelle tabel.

Angiv administrerede egenskaber ved hjælp af udviklerportalen

Hvis du ikke ønsker, at personer, der installerer din administrerede løsning, skal ændre funktionsmåden for virtuelle objektmetadata, skal du angive den administrerede egenskab for at forhindre den ved hjælp af følgende trin.

1. I din løsning skal du vælge Metadata for virtuelle objekter og vælge ellipsen (...) og derefter vælge Administrerede egenskaber.

   

2. Fjern markeringen af Tillad tilpasninger i ruden Administrerede egenskaber, og tryk på Udført.

   

   Denne indstilling gør ikke noget, før posten Virtuelle objektmetadata er inkluderet i en administreret løsning.

Aktivér med kode

Det kan være en god idé at automatisere oprettelsen af virtuelle objektmetadata for dine virtuelle objekter.

Tabellen VirtualEntityMetadata indeholder følgende kolonner, som du kan angive:

Når du opretter disse typer løsningskomponenter, anbefaler vi, at du angiver den administrerede egenskab IsCustomizable , false medmindre du vil tillade, at personer, der installerer din administrerede løsning, kan ændre disse indstillinger.

Vi anbefaler også, at du føjer posten Virtuelle objektmetadata** til en bestemt løsning, når du opretter den. I begge eksempler nedenfor kan du se, hvordan Solution.UniqueName overføres med den anmodning, der opretter posten.

Bruger Web API

Når du bruger web-API'en, er den første opgave at hente den MetadataId virtuelle tabel. I følgende eksempel returneres MetadataId for et virtuelt objekt med navnet new_people.

Bøn:

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]

Svar:

HTTP/1.1 200 OK

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

Opret derefter den virtuelle objektmetadatapost, mens du knytter den til Entity objekttypen ved hjælp af den MetadataId , der blev hentet i det første trin.

Bemærk brugen af overskriften MSCRM.SolutionUniqueName , der er angivet til værdien Solution.UniqueName . Dette føjer den virtuelle objektmetadatapost til løsningen, efterhånden som den oprettes. Flere oplysninger: HTTP-headere

Bøn:

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

Svar:

HTTP/1.1 204 No Content

Brug af SDK til .NET

Uanset om du bruger tidligt eller sent bundne typer, er den første opgave at hente MetadataId tabellen , som hentes på samme måde i begge tilfælde. I dette tilfælde for en virtuel tabel med navnet new_people ved hjælp af CrmServiceClient. Alternativt kan klassen ServiceClient bruges.

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;

Brug af tidligt bundne typer

Med tidligt bundne typer kan du bruge den VirtualEntityMetadata klasse, der er genereret ved hjælp af power Platform CLI pac modelbuilder build-kommando. Flere oplysninger: Sen og tidlig bundet programmering ved hjælp af SDK'et til .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,
};

Brug af senbundne typer

Der er to måder at instantiere den virtuelle objektmetadataforekomst ved hjælp af senbundne typer på:

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;

Eller:

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

Oprettelse af record

Når du opretter posten, skal du bruge metoden CreateRequest Class i stedet for metoden IOrganizationService.Create , så du kan inkludere den SolutionUniqueName valgfri parameter, der føjer posten til din løsning, når du opretter den. Flere oplysninger: Overførsel af valgfrie parametre med en anmodning

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

service.Execute(createRequest);

Få vist de meddelelser, der er oprettet for at understøtte den virtuelle tabel

Du kan nemt kontrollere, at de meddelelser, du har aktiveret, findes ved at undersøge web-API'en $metadata tjenestedokument.

Det kan du gøre i din browser. Skriv følgende i din browser ved hjælp af URL-adressen til din organisation:

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

Dette er et stort XML-dokument, men du kan søge efter 'OnExternalCreated' og finde definitionen af handlingen, i dette tilfælde for den new_people virtuelle tabel.

<Action Name="OnExternalCreated" IsBound="true">
 <Parameter Name="entityset" Type="Collection(mscrm.new_people)" Nullable="false"/>
 <Parameter Name="Target" Type="mscrm.crmbaseentity" Nullable="false"/>
</Action>

Du kan se, at dette er en OData-handling, der er bundet til new_people objektsættet. Du kan finde lignende handlinger for OnExternalDeleted, og 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>

Få vist meddelelserne ved hjælp af plug-in-registreringsværktøjet

Når du registrerer et plug-in-trin ved hjælp af plug-in-registreringsværktøjet, finder du disse meddelelser.

Brug meddelelserne til at give Dataverse besked om ændringer

Hvis du vil give Dataverse besked om ændringer, skal du kalde den relevante API. Du kan bruge enten Dataverse Web-API'en eller SDK'et til .NET.

Før du bruger disse meddelelser, kan det være en god idé at bruge proceduren i Få vist de meddelelser, der er oprettet til at understøtte den virtuelle tabel , for at bekræfte, at de findes.

Brug af web-API'en

Da disse API'er er OData-handlinger, der er bundet til en tabelsamling, kan du følge det mønster, der er dokumenteret her: Brug handlinger bundet til web-API-handlinger>>, der er bundet til en tabelsamling. Følgende er nogle eksempler, der viser brugen af den new_people virtuelle tabel.

Hvis id-værdien er kendt af det kaldende system, skal den altid inkluderes. Den enhedsforekomst, der overføres ved hjælp af destinationsparameteren , skal have den relevante @odata.type anmærkningsegenskab angivet for at definere objekttypen. Hvis dette ikke er inkluderet, returneres der en fejl.

Disse kald skal altid returnere 204: No Content.

OnExternalCreated

For denne handling skal værdierne indeholde alle de egenskaber, der blev angivet, da posten blev oprettet.

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

For denne handling er det kun de egenskaber, der er ændret, der skal medtages.

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

For denne handling er kun det entydige id for dataposten nødvendigt.

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

Brug af SDK til .NET

Når du bruger SDK til .NET, kan du bruge enten tidlige eller sene bindingstyper. Flere oplysninger: Sen og tidlig bundet programmering ved hjælp af SDK'et til .NET

Typer, der er bundet tidligt

I dette eksempel bruges CrmServiceClient med tidligt bundne typer, men kan også ServiceClient bruges.

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

Senbundne typer

I dette eksempel bruges CrmServiceClient med senbundne typer, men kan også ServiceClient bruges.

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

Se også

Hændelsesstruktur
Microsoft Dataverse-forretningshændelser
Kom i gang med virtuelle tabeller (objekter)