カスタム仮想エンティティ データ プロバイダー
Dynamics 365 for Customer Engagement (on-premises) Data SDK の使用により、.NET Developers には、既存のデータ プロバイダーがサポートしていない外部データ ソースの種類を統合するために役立つ、カスタム仮想エンティティ データ プロバイダーを作成するオプションがあります。 各データ プロバイダーは、サポートされる CRUD 操作を実装する一連の再利用可能な Dynamics 365 for Customer Engagement (on-premises) プラグインで構成されます。 (初期リリースは Retrieve および RetrieveMultiple 読み取り命令に制限されます。) このセクションには、データ プロバイダー、およびコード例を含むカスタム プロバイダーを開発するためのアプローチに関する基本情報が用意されています。
Note
カスタム データ ソース プロバイダー作成の代替策として、既存のデータ データ プロバイダー対するデータ ソースの調整を検討する必要があります。 たとえば、外部データ ソースに対して OData v4 インターフェイスを作成する場合、用意された標準 OData v4 データ プロバイダーを使用して直接アクセスすることができます。 この REST インターフェイスを追加するメカニズムは、基盤となるデータ サービス テクノロジにより異なります。たとえば、WCF Data Services 4.5 を参照してください。 OData は広範囲に及ぶ専用ツールおよび互換性技術を持ち、業界からの広い支持を得ています。
前提条件
カスタム データ プロバイダーには、作成および管理のための実質的開発リソースが必要です。 次の領域の基本的な知識が必要です。
- 外部データ ソース スキーマおよび関連するデータ アクセスの技術。 このドメインに関する知識は、外部データ ソースの種類特有です。
- Dynamics 365 for Customer Engagement (on-premises) メタデータ スキーマ; 詳細については、 Microsoft Dynamics 365 Customer Engagement (on-premises) のメタデータおよびデータ モデルを参照してください。
- Dynamics 365 for Customer Engagement (on-premises) イベント システム; 詳細については、イベント フレームワークを参照してください。
- Dynamics 365 for Customer Engagement (on-premises) プラグイン アーキテクチャおよび開発; 詳細については、プラグインの開発を参照してください。
また、Dynamics 365 for Customer Engagement (on-premises) Data SDK を手動でダウンロード、または対応する NuGet パッケージをプロジェクト内に含める必要があります。 この SDK は Visual Studio 2015 または 2017 と互換性があります。
プロバイダのカテゴリ
仮想データ SDK アセンブリを使用して作成することができるデータ プロバイダーには、汎用または対象の 2 つの全般カテゴリがあります。 以下の表はこれらのアプローチを説明し、そのアプローチに最適なデータ プロバイダー開発モデルを照合します。
| カテゴリ | Dev モデル | 説明 |
|---|---|---|
| 汎用 | 「地金」プロバイダ | このプロバイダーは、関連要求に対する FetchXML クエリ式を外部データ ソースに柔軟に変換して、結果のエンティティ インスタンスを返すことができます。 このようなプロバイダーは、このデータ ソースの種類のすべてのインスタンスで再使用することができます。 このアプローチは最も一般的ですが、開発はより複雑になります。 データ ソースのスキーマを変更する場合、影響を受ける仮想エンティティは再マッピングのみが必要です。 |
| 対象 | 既知のスキーマの LINQ プロバイダー | このようなプロバイダーは、関連する LINQ コールに対するクエリのみを、既知の、既存データ ソースのインスタンスに変換します。 LINQ 照会に対してデータ ソースを有効にする のトピックスで説明されているように、データ ソースは LINQ プロバイダーである必要があります。 このアプローチは特定のデータ ソースのインスタンスに制限されますが、コーディングの必要が少なくなります。 データ ソースのスキーマを変更する場合、プロバイダーを更新および再作成する必要があります。 |
汎用プロバイダの例として、標準 Odata v4 データプロバイダと、 Cosmos DB データプロバイダ が挙げられます。
カスタム データ プロバイダーを使用する手順
Dynamics 365 for Customer Engagement (on-premises) にインポートできる仮想エンティティ データ プロバイダー ソリューションを作成するために必要な、いくつかの手順があります。
- カスタム データ プロバイダー プラグイン DLL (または一連の DLL) を開発します。
- プラグイン登録ツール (PRT) を使用して、Dynamics 365 for Customer Engagement (on-premises) サービスを持つカスタム データ プロバイダーを登録します。
- データ プロバイダー ソリューションを作成します。
- データの種類または特定のインスタンスを反映するデータ ソース エンティティをカスタマイズします。
- カスタム データ プロバイダー ソリューションをエクスポートします。
プラグインの開発
このリリースのバーチャル エンティティは読み取り専用であるため、取得および RetrieveMultiple イベントに登録されたプラグインの形式でデータ プロバイダーを記述します。 各イベントには、戻すデータの種類を説明する実行コンテキスト内の情報が含まれます。
| イベント | 実行コンテキスト |
|---|---|
| 取得 | 取得するエンティティと共に、含める属性および関連エンティティについて説明します。 |
| RetrieveMultiple | クエリを定義する QueryExpression オブジェクトを含めます。 フレームワークには、クエリ式ツリーの異なる部分を参照するように設計された QueryExpressionVisitor クラスが含まれます。 |
両方のイベントで、以下の内容が必要です。
- 実行コンテキスト内のそれぞれの情報を、外部データ ソースに対して機能するクエリに変換します。
- データを外部システムから取得します。
- 取得の場合、データを エンティティ に変換します。それ以外の場合、RetrieveMultiple は EntityCollection に変換します。 この結果は、 Dynamics 365 Customer Engagement (on-premises) プラットフォームを介してクエリを実行するユーザに返されます。
Microsoft.Xrm.Sdk.Data 名前空間内のクラスには、実行コンテキストからの Dynamics 365 Customer Engagement (on-premises) クエリ情報を、外部データ ソースに適した形式のクエリにマッピングするために役立つフレームワークが用意されています。 このフレームワークは、返されるデータを Dynamics 365 Customer Engagement (on-premises) プラットフォームが予期する適切な Entity または EntityCollection タイプに変換するために役立ちます。
データ プロバイダーの例外
何らかの理由で期待した結果をコードが実現できない場合、適切なエラーをスローする必要があります。 Microsoft.Xrm.Sdk.Data.Exceptions 名前空間には、この目的のために使用することができる、 SdkExceptionBase から派生した次の例外クラスが含まれます。
| 例外クラス | 説明 |
|---|---|
| AttributeNotFoundException | クエリは関連する外部データ レコードにある属性を指定します。 通常、不完全な種類のマッピングまたは外部データ ソース スキーマの変更の結果として発生します。 |
| AuthenticationException | エラーは外部データ ソース サービスに対するセキュリティ認証中に発生します。たとえば、外部データ サービスから受け取る HTTP ステータス 401 です。 通常、現在のユーザーが適切な特権を持たない場合、または関連付けられた EntityDataSource の接続情報が不正確であるために発生します。 |
| EndpointException | データ ソース エンティティ内のエンドポイント構成が無効、またはエンドポイントが存在しません。 |
| EntityNotFoundException | クエリは存在しないエンティティを対象としています。 通常、不完全な種類のマッピングまたは外部データ ソース スキーマの変更の結果として発生します。 |
| GenericDataAccessException | 一般的なデータ 悪性 エラーで、エラーがより具体的な例外に対してマッピングされない時に使用します。 |
| InvalidMetadataException | |
| InvalidQueryException | 指定されたクエリが無効です。たとえば無効な句の組み合わせ、またはサポートされていない比較演算子です。 |
| ObjectNotFoundException | 外部データ ソースで指定されたレコードが存在しません。 |
| TimeoutException | 許容時間内に外部オペレーションが完了しませんでした。たとえば、外部データ サービスからの HTTP ステータス 408 の結果です。 |
プラグイン登録
通常のプラグインとは異なり、プラグイン登録ツール (PRT) のみを使用して各イベントのためのアセンブリおよびプラグインを登録します。 特定のステップは登録しません。 プラグインは、通常のプラグイン ステップでは利用可能でないオペレーションのコア トランザクション ステージである、ステージ 30 で実行します。 ステップを登録する代わりに、Microsoft.Dynamics.CRM.EntityDataProvider および Microsoft.Dynamics.CRM.EntityDataSource エンティティを使用して、データ プロバイダーを構成します。
| エンティティ | 説明 |
|---|---|
| EntityDataProvider | 各イベントで使用するプラグインおよびデータ ソースの論理名を定義します。 |
| EntityDataSource | 認証に必要な秘密情報を含め、外部データ ソースに必要なエンティティ コンテキストと接続情報を提供します。 |
仮想エンティティのメタデータが構成されると、プラグインは PRT を使用して登録されて、正確な構成データが EntityDataProvider および EntityDataSource エンティティのにセットされ、仮想エンティティは要求に対する応答を開始します。