Włącz tabele wirtualne do obsługi zdarzeń usługi Dataverse

Możesz pozwolić jednostkom wirtualnym na uczestnictwo w asynchronicznych zdarzeniach struktury opartej na zdarzeniach potoku usługi Dataverse oraz w wyzwalaczu PowerAutomate Dataverse Po dodaniu, modyfikacji lub usunięciu wiersza. Ta funkcja jest włączona w ramach zdarzeń biznesowych usługi Dataverse. Więcej informacji: Microsoft Dataverse business events

Bez konfiguracji opisanej w tym artykule większość jednostek wirtualnych nie uczestniczy w mechanizmie zdarzeń tak jak inne jednostki. Ponieważ encje wirtualne nie uczestniczą w potoku zdarzeń, nie można rejestrować kroków wtyczki dla zdarzeń tworzenia, aktualizowania i usuwania (CUD), które mają miejsce; mimo że zdarzenia CUD są widoczne dla tych jednostek w łączniku Power Automate Dataverse, podczas próby zapisania przepływu korzystającego z nich zostanie wygenerowany błąd.

Dzieje się tak, ponieważ jednostki wirtualne reprezentują dane przechowywane w źródle zewnętrznym. Usługa Dataverse ma dostęp do tego źródła danych jako klienta, ale inne systemy mogą aktualizować te dane w dowolnym momencie bez przechodzenia przez strukturę zdarzeń Usługi Dataverse.

Aby to włączyć, należy wykonać dwa kroki:

1. Konfigurowanie danych w tabeli o nazwie Metadane jednostki wirtualnej. Gdy dane w tej tabeli są skonfigurowane do ich włączania, zestaw nowych interfejsów API udostępnia środki dla systemu zewnętrznego w celu powiadamiania usługi Dataverse o wystąpieniu zdarzeń CUD.

   Jeśli istnieje wiersz metadanych encji wirtualnej skojarzony z EntityMetadata.Metadataid dla tabeli wirtualnej, następujące trzy ustawienia mogą kontrolować, czy źródło zewnętrzne może przesyłać powiadomienia do tej tabeli wirtualnej.

   W przypadku indywidualnego włączenia właściwości jednostki logicznej w metadanych encji wirtualnej IsOnExternalCreatedEnabled, IsOnExternalDeletedEnabled i IsOnExternalUpdatedEnabled, następujące powiązane akcje stają się dostępne do wywoływania przez usługi zewnętrzne.

   Akcja/komunikat	Description
   OnExternalCreated	Zawiera dane dotyczące rekordu utworzonego w systemie zewnętrznym uwidocznionego jako tabela wirtualna w usłudze Dataverse.
   OnExternalUpdated	Zawiera dane dotyczące rekordu, który został zaktualizowany w systemie zewnętrznym uwidoczniony jako tabela wirtualna w usłudze Dataverse.
   OnExternalDeleted	Zawiera dane dotyczące rekordu, który został usunięty w systemie zewnętrznym uwidoczniony jako tabela wirtualna w usłudze Dataverse.

2. System zewnętrzny, który kontroluje dane, musi wysyłać uwierzytelnione żądanie HTTP do usługi Dataverse przy użyciu interfejsów API, które zawierają dane w metadanych jednostki wirtualnej. Uwierzytelnione konto jednostki usługi zwykle wykonuje to wywołanie. Więcej informacji na temat S2S: MSDN: Tworzenie aplikacji sieci Web przy użyciu uwierzytelniania serwer do serwera (S2S)

   Jednak każda aplikacja lub użytkownik, który może wykonać wywołanie usługi Dataverse, może wysłać żądanie HTTP wymagane do powiadomienia usługi Dataverse o wystąpieniu zdarzenia.

Jak włączyć API powiadomień dla wirtualnych tabel

Można włączyć API powiadomień, ręcznie konfigurując je w portalu twórcy (make.powerapps.com/) lub przy użyciu kodu.

Ręczne włączanie przy użyciu portalu twórcy

Załóżmy, że mamy tabelę wirtualną osoby z tymi właściwościami, a właściwość Name to new_People.

1. W usłudze Power Apps (make.powerapps.com) w rozwiązaniu wybierz pozycję +Nowy , a następnie wybierz pozycję Metadane jednostki wirtualnej.

   

   Spowoduje to otwarcie następującego formularza:

   

2. Wypełnij formularz, ustawiając wartość Identyfikator jednostki rozszerzenia na nazwę tabeli wirtualnej. Nie musisz włączać wszystkich trzech komunikatów. Można ustawić co najmniej jeden z nich i wrócić, aby włączyć resztę później.

Po włączeniu tych komunikatów możesz obserwować i potwierdzać, co zostało dodane, wykonując kroki opisane w temacie Wyświetlanie komunikatów utworzonych w celu obsługi tabeli wirtualnej.

Ustawianie właściwości zarządzanych przy użyciu portalu twórcy

Jeśli nie chcesz, aby osoby instalujące rozwiązanie zarządzane mogły zmieniać zachowanie metadanych jednostki wirtualnej, powinieneś ustawić właściwość zarządzaną, aby uniemożliwić ich zmianę, korzystając z poniższych kroków.

1. W rozwiązaniu wybierz metadane jednostki wirtualnej i wybierz wielokropek (...) , a następnie wybierz pozycję Właściwości zarządzane.

   

2. W okienku Właściwości zarządzane usuń zaznaczenie pozycji Zezwalaj na dostosowania i naciśnij przycisk Gotowe.

   

   To ustawienie nie będzie działać, dopóki rekord metadanych jednostki wirtualnej nie zostanie uwzględniony w rozwiązaniu zarządzanym.

Włączanie za pomocą kodu

Możesz zautomatyzować tworzenie metadanych jednostki wirtualnej dla jednostek wirtualnych.

Tabela VirtualEntityMetadata zawiera następujące kolumny, które można ustawić:

Podczas tworzenia tych typów składników rozwiązania zalecamy ustawienie właściwości zarządzanej IsCustomizable na false, chyba że chcesz zezwolić osobom, które instalują zarządzane rozwiązanie, na możliwość zmiany tych ustawień.

Zalecamy również dodanie rekordu Metadane jednostki wirtualnej** do określonego rozwiązania podczas jego tworzenia. W obu poniższych przykładach zobaczysz, jak Solution.UniqueName jest przesyłany z żądaniem, które tworzy rekord.

Korzystanie z internetowego interfejsu API

W przypadku korzystania z internetowego interfejsu API pierwszym zadaniem jest pobranie MetadataId tabeli wirtualnej. Poniższy przykład zwraca wartość MetadataId dla jednostki wirtualnej o nazwie new_people.

Prosić:

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]

Odpowiedź:

HTTP/1.1 200 OK

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

Następnie utwórz rekord metadanych jednostki wirtualnej, kojarząc go z jednostką typu Entity, przy użyciu MetadataId pobranego w pierwszym kroku.

Zwróć uwagę na użycie nagłówka MSCRM.SolutionUniqueName ustawionego na wartość Solution.UniqueName. Spowoduje to dodanie rekordu metadanych jednostki wirtualnej do rozwiązania podczas jego tworzenia. Więcej informacji: Nagłówki HTTP

Prosić:

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

Odpowiedź:

HTTP/1.1 204 No Content

Korzystanie z zestawu SDK dla platformy .NET

Niezależnie od tego, czy używasz typów wczesnego lub późnego wiązania, pierwszym zadaniem jest pobranie MetadataId tabeli, co odbywa się w taki sam sposób w obu przypadkach. W tym przypadku dla tabeli wirtualnej o nazwie new_people, używając CrmServiceClient. Alternatywnie, można użyć klasy ServiceClient.

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;

Stosowanie typów z wczesnym wiązaniem

W przypadku wcześniej powiązanych typów można użyć VirtualEntityMetadata klasy wygenerowanej za pomocą polecenia „pac modelbuilder build” z interfejsu wiersza polecenia Power Platform. Więcej informacji: Programowanie z późnym i wczesnym wiązaniem przy użyciu zestawu SDK dla platformy .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,
};

Używanie typów z dynamicznym wiązaniem

Istnieją dwa sposoby zainicjalizowania wystąpienia metadanych jednostki wirtualnej przy użyciu typów późnego wiązania, oba są równoważne:

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;

Lub:

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

Tworzenie rekordu

Podczas tworzenia rekordu użyj klasy CreateRequest , a nie metody IOrganizationService.Create , aby dołączyć SolutionUniqueName opcjonalny parametr, który dodaje rekord do rozwiązania podczas jego tworzenia. Więcej informacji: Przekazywanie opcjonalnych parametrów za pomocą żądania

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

service.Execute(createRequest);

Wyświetlanie komunikatów utworzonych w celu obsługi tabeli wirtualnej

Łatwy sposób na sprawdzenie, czy włączone przez Ciebie komunikaty istnieją, to analiza dokumentu usługi $metadata Web API.

Możesz to zrobić w przeglądarce. Używając adresu URL organizacji, wpisz następujące polecenie w przeglądarce:

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

Jest to duży dokument XML, ale możesz wyszukać ciąg "OnExternalCreated" i znaleźć definicję akcji dla tabeli wirtualnej new_people w tym przypadku.

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

Widać, że jest to akcja OData powiązana z zestawem new_people jednostek. Znajdziesz podobne akcje dla OnExternalDeleted i 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>

Wyświetlanie komunikatów przy użyciu narzędzia rejestracji wtyczek

Podczas rejestrowania kroku wtyczki przy użyciu narzędzia do rejestracji wtyczek znajdziesz te komunikaty.

Używanie komunikatów do powiadamiania usługi Dataverse o zmianach

Aby powiadomić usługę Dataverse o zmianach, należy wywołać odpowiedni interfejs API. Możesz użyć internetowego interfejsu API usługi Dataverse lub zestawu SDK dla platformy .NET.

Przed użyciem tych komunikatów możesz użyć procedury opisanej w temacie Wyświetlanie komunikatów utworzonych w celu obsługi tabeli wirtualnej w celu potwierdzenia ich istnienia.

Korzystanie z internetowego interfejsu API

Ponieważ te interfejsy API są akcjami OData powiązanymi z kolekcją tabel, możesz postępować zgodnie ze wzorcem opisanym tutaj: Używanie akcji internetowego interfejsu API> Powiązane akcje> Akcje związane z kolekcją tabel. Poniżej przedstawiono kilka przykładów pokazujących użycie tabeli wirtualnej new_people.

Jeśli wartość identyfikatora jest znana przez system wywołujący, zawsze należy ją uwzględnić. Wystąpienie jednostki przekazane przy użyciu parametru docelowego musi mieć odpowiednią @odata.type właściwość adnotacji ustawioną w celu zdefiniowania typu jednostki. Jeśli nie zostanie to uwzględnione, zostanie zwrócony błąd.

Te wywołania powinny zawsze zwracać wartość 204: No Content.

OnExternalCreated

W przypadku tej akcji wartości powinny zawierać wszystkie właściwości ustawione podczas tworzenia rekordu.

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

W przypadku tej akcji należy uwzględnić tylko te właściwości, które uległy zmianie.

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

W przypadku tej akcji wymagany jest tylko unikatowy identyfikator rekordu.

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

Korzystanie z zestawu SDK dla platformy .NET

W przypadku korzystania z .NET SDK można użyć wczesnych lub późnych typów powiązań. Więcej informacji: Programowanie z późnym i wczesnym wiązaniem przy użyciu zestawu SDK dla platformy .NET

Typy z wczesnym wiązaniem

W tym przykładzie użyto klasy CrmServiceClient z typami wczesnego wiązania, ale można również użyć ServiceClient.

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

Typy z późnym wiązaniem

W tym przykładzie użyto klasy CrmServiceClient z typami późnego wiązania, ale można również użyć ServiceClient.

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

Zobacz też

Struktura zdarzeń
Wydarzenia biznesowe Microsoft Dataverse
Wprowadzenie do tabel wirtualnych (encji)