Dataverse イベントに対応した仮想テーブルを有効化する

[アーティクル]
04/19/2023

仮想エンティティを、非同期 Dataverse イベントフレームワークパイプラインイベントおよび PowerAutomate Dataverse コネクタの行が追加、変更、または削除された場合のトリガーに参加させることができます。この機能は、Dataverse ビジネスイベントの一部として有効になります。詳細: Microsoft Dataverse ビジネスイベント

この記事で説明されている構成がない場合、ほとんどの仮想エンティティは他のエンティティのようにイベントフレームワークパイプラインに参加しません。仮想円ティtぇ位はイベントパイプラインに参加しないので、発生する作成、更新、および削除 (CUD) イベントに対してプラグインステップを登録することができず、これらのエンティティに対する CUD イベントは Power Automate Dataverse コネクタに表示されますが、それらを使用するフローを保存しようとするとエラーが発生します。

これは、仮想エンティティが外部ソースに保存されたデータを表すためです。 Dataverse は、クライアントとしてそのデータソースにアクセスしますが、他のシステムは、Dataverse イベントフレームワークを経由せずに、いつでもそのデータを更新できます。

これを有効にするには、次の 2 つの手順があります:

仮想エンティティメタデータ と呼ばれるテーブルでデータを構成します。このテーブルのデータが有効になるように構成されている場合、新しい API のセットは、CUD イベントが発生したときに、外部システムが Dataverse に通知する手段を提供します。

仮想テーブルの EntityMetadata.Metadataid に関連付けられた仮想エンティティメタデータ行がある場合、次の 3 つの設定は、仮想テーブルの通知をサポートできるかどうかを制御できます。

仮想エンティティメタデータの IsOnExternalCreatedEnabled、IsOnExternalDeletedEnabled、および IsOnExternalUpdatedEnabled ブール値プロパティを使用して個別に有効にした場合、次のバインド済みアクションは、外部サービスからの呼び出しが可能になります。

アクション/メッセージ	内容
`OnExternalCreated`	Dataverse の仮想テーブルとして公開されている外部システムで作成されたレコードに関するデータを含みます。
`OnExternalUpdated`	Dataverse の仮想テーブルとして公開されている外部システムで更新されたレコードに関するデータを含みます。
`OnExternalDeleted`	Dataverse の仮想テーブルとして公開されている外部システムで削除されたレコードに関するデータを含みます。

データを制御する外部システムは、仮想エンティティメタデータのデータによって有効化された API を使用して、認証済み HTTP 要求を Dataverse に送信する必要があります。認証済みサービスプリンシパルアカウントは通常この呼び出しを実行します。詳細情報: サーバー間 (S2S) 認証を使用して Web アプリケーションを作成する

ただし、Dataverse への呼び出しを実行できるアプリケーションまたはユーザーは、イベントが発生したことを Dataverse に通知するために必要な HTTP 要求を送信できます。

注意

OData プロバイダーと非リレーショナルデータソースを使用する仮想エンティティは、たとえばトランザクション外のイベントでのみ、特定のプラグインステップ登録を許可する場合があります。ただし、これらのイベントは、Power Automate Dataverse コネクタでは使用できません。この動作に変更はありません。ただし、より信頼性の高いイベント通知を行うには、このトピックで説明されているアプローチをお勧めします。

仮想テーブルの通知 API を有効にする方法

通知 API を有効にするには、メーカーポータル (make.powerapps.com/) で手動で構成するか、コードを使用します。

メーカーポータルを使用して手動で有効にする

これらのプロパティを持つ Person 仮想テーブルがあり、名前プロパティが new_People であるとします。

new_people 仮想テーブルのプロパティ。

Power Apps ( make.powerapps.com) のソリューション内で +新規、仮想エンティティメタデータ の順に選択します。

これにより、次のフォームが開きます:
フォームに入力して、拡張エンティティ ID 値を仮想テーブルの名前に設定します。 3 つのメッセージすべてを有効にする必要はありません。 1 つまたは複数を設定し、後で戻って残りを有効にすることができます。

これらのメッセージを有効にすると、仮想テーブルをサポートするために作成されたメッセージの表示の手順を使用して、追加された内容を確認できます。

メーカーポータルを使用した管理プロパティの設定

管理ソリューションをインストールするユーザーに仮想エンティティメタデータの動作を変更させたくない場合は、次の手順で、管理プロパティを設定して変更されないようにする必要があります。

ソリューションで、仮想エンティティメタデータを選択し、省略記号 (...) をクリックして、管理プロパティ を選択します。
管理プロパティペインで、カスタマイズを許可 の選択を解除し、完了を押します。

この設定は、仮想エンティティメタデータレコードが管理ソリューションに含まれるまで何もしません。

コードで有効にする

仮想エンティティに対して仮想エンティティメタデータの作成を自動化することもできます。

VirtualEntityMetadata テーブルには、設定可能な次の列があります:

スキーマ名論理名	表示名	タイプ	内容
`ExtensionOfRecordId` `extensionofrecordid`	仮想エンティティ	参照	これらの設定の対象となる仮想エンティティの名前。
`IsCustomizable` `iscustomiable`	カスタマイズ可能	ManagedProperty	仮想エンティティメタデータを管理ソリューションに含めるときに、変更または削除できるかどうかを制御します。
`IsOnExternalCreatedEnabled` `isonexternalcreatedenabled`	外部作成メッセージの有効化	Boolean	メッセージを有効にして、外部データソースで作成された新しいレコードに関する情報を送信します。
`IsOnExternalDeletedEnabled` `isonexternaldeletedenabled`	外部削除メッセージの有効化	Boolean	メッセージを有効にして、外部データソースで削除されたレコードに関する情報を送信します。
`IsOnExternalUpdatedEnabled` `isonexternalupdatedenabled`	外部更新メッセージの有効化	Boolean	メッセージを有効にして、外部データソースで更新されたレコードに関する情報を送信します。
`Name` `name`	件名	String	設定の名前。
`VirtualEntityMetadataId` `virtualentitymetadataid`	VirtualEntityMetadata	Uniqueidentifier	エンティティのインスタンスを表す一意識別子

このような種類のソリューションコンポーネントを作成するときは、管理ソリューションをインストールするユーザーがこれらの設定を変更できるようにする場合を除き、IsCustomizable 管理プロパティを false に設定することをお勧めします。

また、仮想エンティティメタデータ** レコードを作成するときに、特定のソリューションに追加することをお勧めします。以下の両方の例で、レコードを作成する要求とともに Solution.UniqueName がどのように渡されるかを確認します。

Web API の使用

Web API を使用する場合、最初のタスクは仮想テーブルの MetadataId を取得することです。次の例では、new_people という名前の仮想エンティティに対して MetadataId を返します。

要求:

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]

応答:

HTTP/1.1 200 OK

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

次に、最初のステップで取得した MetadataId を使用して、Entity entitytype に関連付けながら、仮想エンティティのメタデータレコードを作成します。

Solution.UniqueName 値に設定された MSCRM.SolutionUniqueName ヘッダーの使用を確認します。これにより、仮想エンティティのメタデータレコードが作成時にソリューションに追加されます。詳細: HTTP ヘッダー

要求:

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

応答:

HTTP/1.1 204 No Content

.NET 用 SDK の使用

事前または遅延バインド型のどちらを使用するかに関係なく、最初のタスクはテーブルの MetadataId を取得することであり、どちらの場合も同じ方法で取得されます。この場合、CrmServiceClient を使用した new_people という名前の仮想テーブルです。あるいは、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;

事前バインド型の使用

事前バインド型では、Power Platform CLI pac modelbuilder ビルドコマンドを使用して生成された VirtualEntityMetadata クラスを使用できます。詳細: .NET 用 SDK を使用した遅延バインドおよび事前バインドプログラミング

var virtualEntityMetadata = new VirtualEntityMetadata
{
    Name = "Person Virtual Metadata",
    ExtensionOfRecordId = new EntityReference("entity", entityId.Value),
    IsCustomizable = new BooleanManagedProperty(false),
    IsOnExternalCreatedEnabled = true,
    IsOnExternalDeletedEnabled = true,
    IsOnExternalUpdatedEnabled = true,
};

遅延バインド型の使用

遅延バインド型を使用して仮想エンティティメタデータインスタンスをインスタンス化する方法は 2 つあり、どちらも同等です:

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;

または:

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

レコードの作成

レコードを作成するとき、IOrganizationService.Create メソッドではなく、CreateRequest クラスを使用することで、SolutionUniqueName オプションパラメーター含めることができ、作成時にソリューションにレコードを追加します。詳細情報 : リクエストでオプションのパラメータを渡す

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

service.Execute(createRequest);

仮想テーブルをサポートするために作成されたメッセージの表示

有効にしたメッセージが存在することを確認する簡単な方法は、Web API $metadata サービスドキュメントを調べることです。

これはブラウザーで行うことができます。組織の URL を使用して、ブラウザーに次のように入力します:

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

これは大きな XML ドキュメントですが、'OnExternalCreated' を検索して、アクションの定義、この場合は、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>

これが、new_people entityset にバインドされた OData アクションであることがわかります。 OnExternalDeleted と 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>

プラグイン登録ツールを使用したメッセージの表示

プラグイン登録ツールでプラグインステップを登録すると、これらのメッセージが表示されます。

new_people エンティティの OnExternalCreated メッセージにプラグインステップを登録する。

メッセージを使用して Dataverse に変更を通知

Dataverse に変更を通知するには、適切な API を呼び出す必要があります。 Dataverse Web API または、.NET 用 SDK のいずれかを使用できます。

これらのメッセージを使用する前に、仮想テーブルをサポートするために作成されたメッセージの表示で説明されている手順を使用して、メッセージが存在するかどうかを確認します。

Web API の使用

これらの API はテーブルコレクションにバインドされた OData アクションであるため、ここに記載されているパターンに従うことができます: Web API アクションの使用> バインド済みアクション> テーブルコレクションにバインドされたアクション。以下に、new_people 仮想テーブルの使用例をいくつか示します。

呼び出しシステムで ID 値がわかっている場合は、常に含める必要があります。 Target パラメーターを使用して渡されるエンティティインスタンスには、エンティティの種類を定義するための適切な @odata.type 注釈プロパティが設定されている必要があります。これが含まれていない場合、エラーが返されます。

これらの呼び出しは常に 204: No Content を返します。

OnExternalCreated

このアクションでは、値にはレコードの作成時に設定されたすべてのプロパティを含める必要があります。

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

このアクションでは、変更されたプロパティのみを含める必要があります。

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

このアクションでは、レコードの一意の識別子のみが必要です。

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

SDK for .NET の使用

.NET 用 SDK を使用する場合、事前または遅延バインディング型のいずれかを使用できます。詳細: .NET 用 SDK を使用した遅延バインドおよび事前バインドプログラミング

事前バインド型

この例では、アーリーバウンドタイプの CrmServiceClient を使用していますが、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
};

遅延バインド型

この例では、レイトバウンドタイプの CrmServiceClient を使用していますが、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);

次の方法で共有

Dataverse イベントに対応した仮想テーブルを有効化する

仮想テーブルの通知 API を有効にする方法

メーカーポータルを使用して手動で有効にする

メーカーポータルを使用した管理プロパティの設定

コードで有効にする

Web API の使用

.NET 用 SDK の使用

仮想テーブルをサポートするために作成されたメッセージの表示

プラグイン登録ツールを使用したメッセージの表示

メッセージを使用して Dataverse に変更を通知

Web API の使用

OnExternalCreated

OnExternalUpdated

OnExternalDeleted

SDK for .NET の使用

事前バインド型

遅延バインド型

関連情報

その他のリソース

次の方法で共有

Dataverse イベントに対応した仮想テーブルを有効化する

仮想テーブルの通知 API を有効にする方法

メーカー ポータルを使用して手動で有効にする

メーカー ポータルを使用した管理プロパティの設定

コードで有効にする

Web API の使用

.NET 用 SDK の使用

仮想テーブルをサポートするために作成されたメッセージの表示

プラグイン登録ツールを使用したメッセージの表示

メッセージを使用して Dataverse に変更を通知

Web API の使用

OnExternalCreated

OnExternalUpdated

OnExternalDeleted

SDK for .NET の使用

事前バインド型

遅延バインド型

関連情報

その他のリソース

メーカーポータルを使用して手動で有効にする

メーカーポータルを使用した管理プロパティの設定