メッセージを組織サービスと共に使用する

注意

エンティティとテーブルの違いがわかりませんか？ Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。

組織サービスのすべてのデータ操作はメッセージとして定義されます。 IOrganizationService はデータ操作を行う次の 7 つのメソッドを提供する。 (Create、 Retrieve、 RetrieveMultiple、 Update、 Delete、 Associate および Disassociate ) これらのメソッドはそれぞれ基になるメッセージまわりの便利なサッパーで、最終的に Execute メソッドを使用して呼び出されます。 基礎となる組織サービスのみが Execute メソッドを 1 つのパラメーターとしてを持ち、それは OrganizationRequest クラスのインスタンスです。 Execute メソッドによって返される値は OrganizationResponse クラスのインスタンスです。

コードを記述する際のエクスペリエンス向上のため、すべての標準システム データ操作には SDK アセンブリで定義されている *Request および *Response クラスのペアがあります。 これらのクラスはそれぞれが OrganizationRequest および OrganizationResponse の各クラスを継承しており、コーディングの際に生産性のより高いエクスペリエンスを提供します。

次の例は、このように定義されたアカウント行を作成する 3 つの異なる方法を示しています。

var account = new Account();
account.Name = "Test account";

IOrganizationService、Createの使用

var id = svc.Create(account);

IOrganizationServiceおよびExecuteと共に CreateRequest を使用する

CreateRequest request = new CreateRequest()
{ Target = account };
var id = ((CreateResponse)svc.Execute(request)).id;

IOrganizationServiceおよびExecuteと共に OrganizationRequest を使用する

ParameterCollection parameters = new ParameterCollection();
parameters.Add("Target", account);

OrganizationRequest request = new OrganizationRequest() {
RequestName = "Create",
Parameters = parameters
};

OrganizationResponse response = svc.Execute(request);

var id = (Guid)response.Results["id"];

このように一般的なデータ操作は IOrganizationService メソッドを使用して効率化され、システム メッセージは SDK アセンブリの *Request および *Response クラスで簡素化されています。 下記のケースを除くほとんどの場合、基になる OrganizationRequest および OrganizationResponse クラスを使用する必要はありません。

プラグインのメッセージの操作

プラグインでの操作を示すデータは次の形式をとります IExecutionContext、InputParameters および IExecutionContext、OutputParameters。 これら ParameterCollection のプロパティは、イベント実行パイプラインの最初 2 つのステージにおいては OrganizationRequest 、メイン操作の後のステージでは OrganizationResponse クラスで使用される値を格納します。

メッセージの構造を知ることはプラグイン内で確認や変更が必要なデータがどこにあるか理解するのに役立ちます。

詳細:

• ビジネス プロセスを拡張するためのプラグインを記述する
• イベント フレームワーク

ユーザー定義アクションを使用する

ユーザー定義のアクションを使用すると SDK アセンブリにこれらの操作に対するクラスはありません。 コード生成ツール CrmSvcUtil.exe でパラメータ generateActions を使用するとこれらのクラスを生成することがでできます。またはクラスを生成せずに使うには OrganizationRequest をインスタンス化して RequestName および Parameters をセットします。 その結果を使用するには OrganizationResponse、Resultsから返される値を解析する必要があります。 プロパティに設定します。

詳細:

• 組織サービスを使用して事前バインド プログラミングのクラスを生成する
• ユーザー定義アクション

要求のオプション パラメーターを渡す

SDK アセンブリのすべての *Request メッセージ クラスに対して公開されているプロパティ Parameters を使用して、メッセージのオプション パラメーターを渡すことができます。 メッセージとともに渡すことができるいくつかのオプションのパラメーターがあります。

パラメーター	内容	メッセージ
SolutionUniqueName	操作が適用されるソリューションの一意の名前を指定する String です。 詳細: ソリューション コンポーネントの依存関係の追跡。	AddPrivilegesRoleRequest CreateRequest DeleteRequest MakeAvailableToOrganizationTemplateRequest UpdateRequest
SuppressDuplicateDetection	作成操作または更新操作で、重複データの検出を無効にするために使用する Boolean です。 詳細: SuppressDuplicateDetection パラメーターを使用して、行の作成または更新時にエラーをスローします。	CreateRequest UpdateRequest
tag	ExecutionContext``SharedVariables コレクション内に含める値。	プラグイン ステップを登録できるメッセージ。 詳細: 組織サービスから共有された変数を追加する
PartitionId	ストレージ パーティション内の NoSql テーブルの非リレーショナル テーブル データにアクセスするために使用される一意の String 値。 Azure 異種ストレージ内のテーブル データにアクセスする際のパフォーマンスを向上させるために使用されます。 詳細: ストレージ パーティションを使用してテーブルデータにアクセスするときのパフォーマンスを向上させる	CreateRequest UpdateRequest RetrieveRequest DeleteRequest
BypassCustomPluginExecution	prvBypassCustomPlugins 特権で送信されたリクエストに含まれている場合、カスタム プラグインを回避します。 詳細: カスタム ビジネス ロジックを回避する	カスタム プラグインを含む可能性のある要求。

次のサンプルは、オプション パラメーターを渡す方法を示しています。

Account account = new Account();  
account.Name = "Fabrikam";  
CreateRequest req = new CreateRequest();  
req.Target = account;  
req["SuppressDuplicateDetection"] = true;  
CreateResponse response = (CreateResponse)svc.Execute(req);  

組織サービスから共有変数を追加する

SharedVariables コレクションの ExecutionContext 内のプラグインが利用できる文字列の値を設定できます。 詳細情報: 変数の共有

var account = new Entity("account");
account["name"] = "Contoso";

var request = new CreateRequest() { Target = account };
request["tag"] = "This is a value passed.";

var response = (CreateResponse)svc.Execute(request);

webhook を使用して送信した場合、SharedVariables コレクション内で次の値になります。

{
"key": "tag",
"value": "This is a value passed."
}

これは、Web API を使用して実行することもできます: Web API から共有変数を追加する

プライベート メッセージ

Microsoft Dataverse には、サードパーティの開発者が使用することを意図していないいくつかのメッセージが含まれています。 これらのメッセージは通常、機能機能を有効にするために Microsoft によって追加されますが、カスタム API 機能を備えたサードパーティ ソリューションによって追加することもできます。 プライベート メッセージは、SdkMessage.IsPrivate プロパティによって示されます。

注意事項

カスタム API として作成した場合を除き、プライベート メッセージを使用しないでください。 メッセージを非公開としてマークすることにより、ソリューションの発行者は、メッセージを使用する他のアプリをサポートしていないことを明示的に呼びかけています。 ソリューション発行者は、いつでもメッセージを削除したり、重大な変更を導入したりする場合があります。 ソリューション発行者以外によるこれらのメッセージの使用はサポートされていません。 プラグインからのプライベート メッセージの呼び出しはサポートされていません。

詳細: カスタム API の作成と使用

関連項目

組織サービスを使用したテーブル操作
メッセージを非同期に実行するために ExecuteAsync を使用します
単一のデータベース トランザクションでメッセージを実行する
組織サービスを使用して複数の要求を実行する

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。