カスタム Dataverse ロジックのバイパス

Dataverse でカスタム ビジネス ロジックを適用することなくデータ操作を実行したい場合があります。 これらのシナリオには、通常、多数のレコードが作成、更新、または削除される一括データ操作が含まれます。

ビジネス ロジックを呼び出さないように Dataverse に指示する方法がない場合は、ビジネス ロジックを含む個別のカスタム プラグインとワークフローを見つけて無効にする必要があります。 プラグインとワークフローを無効にすると、これらのプラグインとワークフローが無効になっている間、すべてのユーザーに対してロジックが無効になります。 また、適切なプラグインとワークフローのみを無効にし、完了したら忘れずに再度有効にする必要もあります。

この手動プロセスの代わりに、クライアント アプリケーションまたはプラグインの開発者は、リクエストに特別な オプション パラメーター を渡して、次の表に示すように 2 種類のカスタム ビジネス ロジックを制御できます。

オプション パラメーター

Dataverseで実行されるビジネス ロジックを制御するには、次のオプション パラメータを使用します:

BypassBusinessLogicExecution

BypassBusinessLogicExecution オプション パラメーターは、同期ロジック、非同期ロジック、またはその両方をバイパスするかどうかを選択できることを除いて、BypassCustomPluginExecution オプション パラメーターと同様に機能します。

この オプション パラメーター は、組織に適用されているカスタム ビジネス ロジックを対象としています。 カスタム ビジネス ロジックをバイパスする要求を送信すると、以下を除くすべてのカスタム プラグインとワークフローが無効になります:

• コア Microsoft Dataverse システムの一部であるプラグイン、またはマイクロソフトが発行元であるソリューションの一部であるプラグイン。
• Microsoft が発行者であるソリューションに含まれるワークフロー。

システム プラグインは、特定のエンティティのコア動作を定義します。 これらのプラグインがないと、データの不整合が発生し、簡単に修正できない場合があります。

Microsoft Dynamics 365 Customer Service や Dynamics 365 Sales Solutions などの Dataverse を使用するマイクロソフトが提供するソリューションには、このオプションではバイパスできない重要なビジネス ロジックも含まれています。

次の表は、BypassBusinessLogicExecution でパラメーター値を使用する場合について示しています。

BypassBusinessLogicExecution オプション パラメータを使用するための条件

• BypassBusinessLogicExecution オプション パラメーター を使用して要求を送信する必要があります。
• 要求を送信するユーザーは、prvBypassCustomBusinessLogic 特権を持っている必要があります。 既定では、システム管理者のセキュリティ ロールを持つユーザーのみにこの特権が割り当てられます。 別のロールへの prvBypassCustomBusinessLogic 権限の追加方法

BypassBusinessLogicExecution オプション パラメータはどのように使用するのですか？

このオプションは、.NET 用 SDK または Web API のいずれかで使用できます。

static void DemonstrateBypassBusinessLogicExecution(IOrganizationService service)
{
    Entity account = new("account");
    account["name"] = "Sample Account";

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("BypassBusinessLogicExecution", "CustomSync,CustomAsync");
    service.Execute(request);
}

POST [Organization URI]/api/data/v9.2/accounts HTTP/1.1
If-None-Match: null
OData-Version: 4.0
OData-MaxVersion: 4.0
Content-Type: application/json
Accept: application/json
MSCRM.BypassBusinessLogicExecution: CustomSync,CustomAsync

{
  "name":"Sample Account"
}

BypassBusinessLogicExecutionStepIds

BypassBusinessLogicExecutionStepIds オプションパラメータを使用すると、すべての同期および非同期カスタムロジッ クの代わりに、指定された登録済みプラグインステップをバイパスします。 このパラメーターで登録済みプラグイン ステップ登録の GUID 値を渡します。 渡されたステップ ID が指定した要求で実行されない場合、無視されます。

BypassBusinessLogicExecutionStepId オプションを使用するには?

このオプションは、.NET 用 SDK または Web API のいずれかで使用できます。

static void DemonstrateBypassBusinessLogicExecutionStepIds(IOrganizationService service)
{
   Entity account = new("account");
   account["name"] = "Sample Account";

   CreateRequest request = new()
   {
         Target = account
   };
   request.Parameters.Add("BypassBusinessLogicExecutionStepIds", "45e0c603-0d0b-466e-a286-d7fc1cda8361,d5370603-e4b9-4b92-b765-5966492a4fd7");
   service.Execute(request);
}

POST [Organization URI]/api/data/v9.2/accounts HTTP/1.1
If-None-Match: null
OData-Version: 4.0
OData-MaxVersion: 4.0
Content-Type: application/json
Accept: application/json
MSCRM.BypassBusinessLogicExecutionStepIds: "45e0c603-0d0b-466e-a286-d7fc1cda8361, d5370603-e4b9-4b92-b765-5966492a4fd7"
{
  "name":"Sample Account"
}

バイパスするステップを特定する

プラグイン ステップ登録の GUID 値を見つける方法はいくつかあります。

プラグイン登録ツールを使用する

1. 表示 メニューから、 エンティティ別に表示 を選択します。

2. エンティティとメッセージを選択します

3. ステップを選択します。

   詳細ペインの プロパティ タブに StepId が表示されます。 そこから値をコピーします。

   

プラグイン登録ツールについて

Web API を使用して環境のクエリを実行する

次のようなクエリを使用して、特定のテーブルとメッセージに設定されたプラグイン ステップ登録を取得します。 次の例では、テーブル論理名を使用して、account テーブルを指定します。 Create はメッセージの名前です。 これらの値を必要なテーブルとメッセージに置き換えます。

Request

GET [Organization URI]/api/data/v9.2/sdkmessagefilters?$select=sdkmessagefilterid
&$filter=primaryobjecttypecode eq 'account' 
and sdkmessageid/name eq 'Create'
&$expand=sdkmessagefilterid_sdkmessageprocessingstep($select=name;
$filter=statecode eq 0 
and customizationlevel eq 1 
and iscustomizable/Value eq true)
Accept: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0 

回答

応答で sdkmessageprocessingstepid 値を探します。 name 値を使用して、バイパスするプラグインを識別します。

この場合、1 つしかありません: 4ab978b0-1d77-ec11-8d21-000d3a554d57

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#sdkmessagefilters(sdkmessagefilterid,sdkmessagefilterid_sdkmessageprocessingstep(name))",
   "value": [
      {
         "@odata.etag": "W/\"31434372\"",
         "sdkmessagefilterid": "c2c5bb1b-ea3e-db11-86a7-000a3a5473e8",
         "sdkmessagefilterid_sdkmessageprocessingstep": [
            {
               "@odata.etag": "W/\"115803276\"",
               "name": "BasicPlugin.FollowupPlugin: Create of account",
               "_sdkmessagefilterid_value": "c2c5bb1b-ea3e-db11-86a7-000a3a5473e8",
               "sdkmessageprocessingstepid": "4ab978b0-1d77-ec11-8d21-000d3a554d57"
            }
         ],
         "sdkmessagefilterid_sdkmessageprocessingstep@odata.nextLink": "[Organization URI]/api/data/v9.2/sdkmessagefilters(c2c5bb1b-ea3e-db11-86a7-000a3a5473e8)/sdkmessagefilterid_sdkmessageprocessingstep?$select=name&$filter=statecode%20eq%200%20and%20customizationlevel%20eq%201%20and%20iscustomizable/Value%20eq%20true"
      }
   ]
}

Web APIを使用したデータのクエリの詳細

FetchXml を使用して環境のクエリを実行する

次のようなクエリを使用して、特定のテーブルとメッセージに設定されたプラグイン ステップ登録を取得します。 次の例では、テーブル オブジェクト型コード を使用して、account テーブルを表す 1 を指定します。

Create はメッセージの名前です。 これらの値を必要なテーブルとメッセージに置き換えます。

この FetchXml クエリを使用して、BypassBusinessLogicExecutionStepIds オプション パラメーターで使用できる step.sdkmessageprocessingstepid 値を返します。

<fetch>
  <entity name='sdkmessagefilter'>
    <filter>
      <condition attribute='primaryobjecttypecode'
        operator='eq'
        value='1' />
    </filter>
    <link-entity name='sdkmessage'
      from='sdkmessageid'
      to='sdkmessageid'
      link-type='inner'
      alias='message'>
      <filter>
        <condition attribute='name'
          operator='eq'
          value='Create' />
      </filter>
    </link-entity>
    <link-entity name='sdkmessageprocessingstep'
      from='sdkmessagefilterid'
      to='sdkmessagefilterid'
      link-type='inner'
      alias='step'>
      <attribute name='name' />
      <filter>
        <condition attribute='statecode'
          operator='eq'
          value='0' />
        <condition attribute='customizationlevel'
          operator='eq'
          value='1' />
        <condition attribute='iscustomizable'
          operator='eq'
          value='1' />
      </filter>
    </link-entity>
  </entity>
</fetch>

FetchXml を使用したデータの取得について

ステップ数の制限

パラメーターのサイズが大きくなりすぎないように、渡すことができるステップ数のデフォルトの制限は 3 です。 制限は、組織テーブルの OrgDbOrgSettings 列 のデータを使用して制御されます。 BypassBusinessLogicExecutionStepIdsLimit 値を変更するには、Microsoft Dynamics CRM 用の OrgDBOrgSettings ツール または OrgDbOrgSettings アプリ を使用します。

この制限の推奨最大サイズは 10 ステップです。

BypassCustomPluginExecution

BypassCustomPluginExecution オプションのパラメータを使用して、カスタム同期ロジックをバイパスします。

このオプション パラメーターは、BypassBusinessLogicExecution と同じように使用します。ただし、別の特権 (prvBypassCustomPlugins) が必要となります

BypassCustomPluginExecution オプションを使用するには?

このオプションは、.NET 用 SDK または Web API のいずれかで使用できます。

static void DemonstrateBypassCustomPluginExecution(IOrganizationService service)
{
    Entity account = new("account");
    account["name"] = "Sample Account";

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("BypassCustomPluginExecution", true);
    service.Execute(request);
}

var service = new CrmServiceClient(connectionString);  

service.BypassPluginExecution = true;

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

service.Create(account);

POST [Organization URI]/api/data/v9.2/accounts HTTP/1.1
If-None-Match: null
OData-Version: 4.0
OData-MaxVersion: 4.0
Content-Type: application/json
Accept: application/json
MSCRM.BypassCustomPluginExecution: true

{
  "name":"Sample Account"
}

必要な権限を別のロールに追加する

この記事で説明するオプションのパラメーターには、システム管理者のセキュリティ ロールにのみ追加される権限が必要です。 これらの権限は、セキュリティ ロール デザイナーで他のセキュリティ ロールに追加することはできません。 この権限を別のセキュリティ ロールに付与する必要がある場合は、API を使用する必要があります。 たとえば、システム カスタマイザー セキュリティ ロールを持つユーザーにこの権限を付与する場合があります。

別のセキュリティ ロールに権限を追加するには、権限の ID が必要です。

これらの ID 値はすべての Dataverse 環境で同じです。

static void AddprvBypassCustomPluginsToRole(IOrganizationService service, Guid roleId)
{
    var request = new AddPrivilegesRoleRequest
    {
        RoleId = roleId,
        Privileges = new[]{
            new RolePrivilege{
                PrivilegeId = new Guid("0ea552b0-a491-4470-9a1b-82068deccf66"),
                Depth = PrivilegeDepth.Global
            }
        }
    };
    service.Execute(request);
}

POST [Organization URI]/api/data/v9.2/roles(<id of role>)/Microsoft.Dynamics.CRM.AddPrivilegesRole HTTP/1.1
Content-Type: application/json   
Accept: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0 

{
  "Privileges": [
    {
      "PrivilegeId": "0ea552b0-a491-4470-9a1b-82068deccf66",
      "Depth": "3"
    }
  ]
}

HTTP/1.1 204 No Content  
OData-Version: 4.0  

ビジネス ロジックのバイパスに関するよくある質問 (FAQ)

以下は、同期ビジネス ロジックをバイパスするためのオプション パラメータの使用に関するよくある質問です。

これらのオプションのパラメータは、マイクロソフトのプラグインによるデータ操作のためにプラグインをバイパスしますか？

いいえ Microsoft ソリューションのプラグインまたはワークフローが、他のレコードに対して操作を実行する場合、それらの操作のロジックはバイパスされません。 特定の操作に適用されるプラグインまたはワークフローのみがバイパスされます。

プラグイン内で実行するデータ操作にこれらのオプション パラメーターを使用できますか?

ただし、必要な権限を持つユーザーのコンテキストでプラグインが実行されている場合に限ります。 プラグインの場合、OrganizationRequest クラス から派生したクラスのオプション パラメーターを設定します。 プラグインでは、CrmServiceClient クラスや ServiceClient クラスを使用することはできません。

参照

Power Automate フローをバイパスする
オプションのパラメーターを使用する