Dataverse の拡張性

5 分

このトピックでは、開発者が利用できる Dataverse の拡張性ポイントについて説明します。この Dataverse のアーキテクチャでは、要求を処理するメッセージ駆動型アーキテクチャが設定されています。各要求メッセージは、プラグインによって実装されるカスタムビジネスロジックを実行するための拡張ポイントを持つイベントパイプラインを介して処理されます。標準でメッセージが多数提供され、新しいテーブルを作成するたびに、そのテーブルをサポートする新しいメッセージが追加されます。カスタム API を作成することで、新しいメッセージも作成されます。

重要な概念は、データのアクセス方法に関係なく、常にイベントパイプラインを介してメッセージとして処理され、カスタムのビジネスロジックが実行されるというものです。これは、アプリのユーザーインターフェイスを使用する場合でも、API を使用する場合でも、データのインポートのような管理操作を実行する場合でも当てはまります。システムロジックまたは登録済みのカスタムロジックの実行をバイパスする Dataverse データを直接変更する方法はありません。

Dataverse API の使用

Dataverse には、開発者がデータ操作に使用できる 2 種類のAPI (Web API と組織サービス) が提供されています。各 API の概要を次に説明します。

Dataverse Web API

Web API は、OData v4 RESTful エンドポイントで利用できます。この API は、OAuth 2.0 を使った HTTP 要求および認証をサポートするプログラミング言語で使用します。詳細については、サンプルを参照してください。

Dataverse Organization サービス

組織サービスは、Microsoft によって提供される .NET アセンブリと、テーブルクラス用のタイプが指定されたクラスジェネレーターを含む .NET SDK です。

組織サービスが Dataverse プラグインからのものである場合、このサービスはインスタンス化され、認証なしでプラグインコードに使用できます。プラグインロジックからインスタンスを取得するには、プラグインに渡される serviceProvider を使用して、組織サービスファクトリのインスタンス (IOrganizationService) を取得します。このファクトリを使用すると、組織サービスのインスタンスを取得できます。インスタンスを取得し、そのインスタンスを使用してアカウントテーブルの行を作成するシンプルなプラグインの例を次に示します。

public void Execute(IServiceProvider serviceProvider)
{
    IPluginExecutionContext pluginContext = serviceProvider.Get<IPluginExecutionContext>();
    IOrganizationServiceFactory factory = serviceProvider.Get<IOrganizationServiceFactory>();
    IOrganizationService orgService = serviceProvider.GetOrganizationService(pluginContext.UserId);

    Entity newAccount = new Entity("account");                  
    newAccount["name"] = "Fourth Coffee";
    Guid accountid = orgService.Create(newAccount);
}

また、プラグインの外部で組織サービスを使用することもできます。たとえば、ASP.NET カスタムポータル、Azure Function、またはコンソールアプリケーションからも使用できます。これらのタイプのアプリケーションでは、.NET Full Framework 4.6.2、4.7.2、4.8、および .NET Core 3.0、3.1、5.0、6.0 使用するアプリケーションに対応した Dataverse ServiceClient からの組織サービスを使用します。 ServiceClient クラスは、IOrganizationService インターフェイスを実装します。また、ServiceClient は IOrganizationServiceAsync2 も実装し、これにより非同期バージョンのメソッドも使用可能になります。

次の例では、ServiceClient のインスタンスを取得し、新しいアカウントテーブルの行を作成します。

ServiceClient serviceClient =
    new ServiceClient("Url=https://yourenv.crm.dynamics.com;AuthType=OAuth;AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;RedirectUri=http://localhost ;LoginPrompt=Always");

    Entity newAccount = new Entity("account");                  
    newAccount["name"] = "Fourth Coffee";
    Guid accountid = serviceClient.Create(newAccount);

組織サービスの使用例は他にもあります。接続文字列や利用可能なオプションの詳細も参照してください。

API では、FetchXML のサポートだけでなく、データクエリを構築するための独自のアプローチもサポートしています。 FetchXML は、Dataverse で使用される独自のクエリ言語です。 FetchXML 言語を使用すると、複雑なクエリを関連するテーブル全体で作成し、Dataverse に特定の条件と演算子を使用できます。 Power Automate Dataverse コネクタは、FetchXML もサポートします。

イベントパイプライン

アプリでレコードを作成する、または API を使用してレコードを作成するなどのアクションを実行する場合、[メッセージの作成] は Dataverse によって処理されます。メッセージは、メッセージが通過する一貫性のある一連のステージを提供するイベントパイプライン内で処理されます。メインの操作を除く各ステージには、カスタムロジックを実行するプラグインを関連付けることができます。サポートされているステージで、メッセージが最上位のステージで開始され、パイプラインの各ステージを経過していく様子を次に示します。

メッセージの処理方法を深く理解すると、動作、およびカスタムロジックを実装する方法と実装に最適な場所を理解するのに役立ちます。パイプラインを理解することも、プラグインとカスタム API がどのように機能するのかを認識するのに不可欠です。イベントフレームワークの詳細をご覧ください。

プラグインの作成

プラグインは、Dataverse SDK アセンブリによって提供される IPlugin インターフェイスを実装する .NET クラスです。そのインターフェイスを使用するには、Execute という名前のメソッドを 1 つだけ実装する必要があります。最小実装の例を次に示します。

    public sealed class MyFirstPlugin : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
               //Business Logic 
         }
    }

Execute メソッドには、タイプが IServicePro のパラメータが 1 つあります。このインターフェイスには、プラグインに使用できるサービスの取得に使用できる GetService メソッドが 1 つあります。使用できるサービスの例は次のとおりです。

IPluginExecutionContext - これにより、処理されるメッセージおよび要求者に関する情報へのアクセスが許可されます。
ITracingService - これにより、診断を目的としてトレースログに書き込むためのアクセスが許可されます。
IOrganizationServiceFactory - これにより、プラグインからデータにアクセスする場合に使用する OrganizationService を取得するためのアクセスが許可されます。

GetService を使用して実行コンテキストを取得する例を次に示します。

IPluginExecutionContext context = (IPluginExecutionContext)                        serviceProvider.GetService(typeof(IPluginExecutionContext));

context.InputParameters を使用する場合、元のメッセージへのアクセスが許可され、context.OutputParameters を使用する場合は、呼び出し元に返されるオブジェクトへのアクセスが許可されます。

実行コンテキストを深く理解することは、プラグイン開発者にとっての基本です。実行コンテキストの詳細をご覧ください。

プラグインを実行するには、特定のメッセージに対して実行するプラグインを登録する必要があります。これは、Plugin Registration Tool を使用して実行できます。

カスタム API

Dataverse 内の操作はメッセージとして定義されます。カスタム API は、Dataverse Web サービスを拡張できる新しいメッセージを定義するコードファーストの方法を提供します。これらのメッセージは、システムメッセージと同様、カスタムのビジネスロジックを実行するために呼び出すことができます。たとえば、事前に定義された API 呼び出しのシーケンスを使用して顧客を検索する固有の要件がある場合、各 API 呼び出しでそのシーケンスを実装するのではなく、findcustomer カスタム API を実装できます。 Findcustomer API で必要なロジックを実装して顧客を検索し、結果を返すようになりました。これにより、各アプリで顧客を検索する方法を見出して一貫性のない方法で行う必要がなくなり、カスタム API を呼び出して、各状況で同様の方法で検索要求を処理することができます。また、変更が必要な場合、1 か所でのみ実装する必要があります。

新しいカスタム API を定義するには、最初にカスタム API レコードを作成します。これは、Maker Portal からコードを使用するか、Dataverse ソリューションを使用して実行できます。レコードを作成する際に、カスタム API 名、および要求と応答パラメーターを識別します。

カスタム API のロジックを実装するには、プラグインを作成してパイプラインのメインオペレーションステージに登録します。カスタム API の実装は、メイン操作ステージにプラグインを登録できる唯一のシナリオです。この例については、後の演習で説明します。

実装されると、Dataverse API、Power Apps、Power Automate からカスタムメッセージを使用することが可能になります。 C# から findcustomer カスタム API を使用する例を次に示します。

var req = new OrganizationRequest("fabrikam_findcustomer")
{
    ["CustomerName"] = "Contoso",
    ["CustomerAddress"] = "1 Redmond Way"
};

var resp = serviceClient.Execute(req);

また、プラグインを実装し、カスタム API を使用して他の自動化をトリガーすることはできません。たとえば、別のシステムで発生したイベントに関するデータを含むカスタム API を作成すると、Dataverse でその API を呼び出すことができます。この場合、Azure、Web Hook、Power Automate、または API の非同期プラグインとの多くの異なる統合ポイントで他の自動化を開始できます。

続行