オプションのパラメーターを使用する

  • [アーティクル]

Dataverse は、クライアント アプリケーションの開発者が個々の要求の動作を変更するために使用できる一連のオプション パラメータまたは要求ヘッダー値を提供します。 この記事では、必要な動作を取得するために使用できるパラメーター値と要求ヘッダーについて説明します。

注意

この記事では、これらのパラメーターについて紹介しますが、詳しくは説明しません。 これらのパラメーターを使用するシナリオを完全に理解するには、リンクをクリックして詳細を確認してください。

使用方法

これらのオプション パラメータの使用方法は、Dataverse SDK for .NET と Web API のどちらを使用しているかによって異なります。

通常、名前付きリクエスト クラスの OrganizationRequest.Parameters Collection にパラメータを追加します。

注意

IOrganizationServiceで公開されている 7 つのショートカット メソッドを使用してこれらのパラメーターを指定することはできません。 IOrganizationService.Execute メソッド で名前付きリクエスト クラスを使用する必要があります。

1 つの例外は、partitionid を設定する場合です。これは、エンティティ インスタンスの属性として設定されます。 詳細: 指定されたパーティションでデータ操作を実行する

詳細情報:

ソリューション コンポーネントをソリューションに関連付ける

ソリューション コンポーネントでデータ操作を実行する場合、SolutionUniqueName パラメータでソリューションの一意の名前を指定することにより、ソリューションに関連付けることができます。

このパラメーターは、次のメッセージで使用できます。

  • AddPrivilegesRole
  • Create (POST)
  • Delete (DELETE)
  • MakeAvailableToOrganizationTemplate
  • Update (PATCH)

次の例では、Web リソース ソリューション コンポーネントを作成し、ExampleSolution という一意の名前でソリューションに追加します。

static void CreateWebResourceInSolution(IOrganizationService service)
{
    Entity webResource = new("webresource");

    webResource["displayname"] = "Simple HTML web resource";
    webResource["content"] = "PCFET0NUWVBFIGh0bWw+CjxodG1sPgogIDxib2R5PgogICAgPGgxPkhlbGxvIFdvcmxkPC9oMT4KICA8L2JvZHk+CjwvaHRtbD4=";
    webResource["webresourcetype"] = new OptionSetValue(1);
    webResource["name"] = "sample_SimpleHTMLWebResource.htm";
    webResource["description"] = "An example HTML web resource";

    CreateRequest request = new();
    request.Target = webResource;
    request["SolutionUniqueName"] = "ExampleSolution";

    service.Execute(request);
}

詳細情報:

詳細情報:

重複データ検出の抑制

作成した新しいレコードが重複レコードであると判断された場合、または重複データ検出ルールが評価されるように既存のレコードを更新するときに Dataverse がエラーをスローするようにするには、間違った値を持つ SuppressDuplicateDetection パラメータを使用してその行を作成または更新する必要があります。

次の例は、次の条件が当てはまる場合にエラーを返します。

  • 重複データ検出が、行が作成または更新されるときに環境に対して有効です。
  • account テーブルで重複データ検出が有効です
  • アカウント name の値が既存の行と完全に一致するかどうかを確認する重複データ検出ルールが公開されています
  • Sample Account という名前の既存の取引先企業があります。
static void DemonstrateSuppressDuplicateDetection(IOrganizationService service)
{
    Entity account = new("account");
    account["name"] = "Sample Account";

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("SuppressDuplicateDetection", false);

    try
    {
        service.Execute(request);
    }
    catch (FaultException<OrganizationServiceFault> ex)
    {
        throw ex.Detail.ErrorCode switch
        {
            -2147220685 => new InvalidOperationException(ex.Detail.Message),
            _ => ex,
        };
    }
}

詳細情報:

共有された変数をプラグイン実行コンテキストに追加する

tag パラメータを使用して、プラグイン内でアクセス可能な共有変数値を含めます。 この追加情報により、プラグインはクライアント アプリケーションに依存するロジックを適用できます。

注意

このパラメーターは、クライアント アプリケーションが任意の値を設定できるようにするためのものです。 Microsoft の機能では、異なる動作を有効にするために、クライアント アプリケーション コードに特定の値を設定する必要はありません。

プラグインの値にアクセスするには、IExecutionContext.SharedVariables コレクション を使用してください

if (context.SharedVariables.ContainsKey("tag")){
    string tagValue = context.SharedVariables["tag"];
}

次の例では、取引先企業レコードを作成している間に、この値: A string value をパスします。

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

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("tag", "A string value");
    service.Execute(request);
}

詳細情報: 変数の共有

指定されたパーティションでデータ操作を実行する

パーティション分割戦略でエラスティック テーブルを使用する場合、partitionid パラメーターで一意の文字列値を渡すと、ストレージ パーティション内の非リレーショナル テーブル データにアクセスすることができます。

以下の例では、contoso_sensordata レコードを取得する際に partitionid 値として deviceId を使用しています。

private static Entity RetrieveRecord(
    IOrganizationService service,
    Guid contosoSensorDataId,
    string deviceId,
    string sessionToken)
{
    EntityReference entityReference = new("contoso_sensordata", contosoSensorDataId);

    RetrieveRequest request = new()
    {
        ColumnSet = new ColumnSet("contoso_value"),
        Target = entityReference,
        ["partitionId"] = deviceId, //To identify the record
        ["SessionToken"] = sessionToken //Pass the session token for strong consistency
    };
    var response = (RetrieveResponse)service.Execute(request);
    return response.Entity;

}

また、代替キー スタイルで partitionid の値を使用することも可能です。

カスタム同期ロジックをバイパスする

トランザクション中に同期ロジックを適用する必要があり、個々の操作のパフォーマンスに大きな影響を与える可能性があります。 一括操作を実行する場合、これらの個々の操作にかかる時間が増えると、必要な時間が長くなる可能性があります。 BypassCustomPluginExecution パラメータを一括データ操作の実行中にパフォーマンスを向上させたい場合は、パラメーターを使用します。

重要

通話ユーザーは、prvBypassCustomPlugins 特権を持っている必要があります。

.NET 用 SDK でこのパラメータを使用するには 2 つの方法があります。

値をオプションのパラメータとして設定します

次の例では、CreateRequest クラス を使用して新しい取引先企業レコードを作成するときに、オプションの BypassCustomPluginExecution パラメーターを設定します。

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

CrmServiceClient.BypassPluginExecution プロパティを設定します

次の例では、新しい取引先企業レコードを作成するときに CrmServiceClient.BypassPluginExecution プロパティを設定します。

var service = new CrmServiceClient(connectionString);  

service.BypassPluginExecution = true;

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

service.Create(account);

この設定はサービスに適用されるため、false に設定されるまで、サービスを使用して送信されるすべてのリクエストに対して設定されたままになります。

注意

このプロパティは、Dataverse.Client.ServiceClient では使用できませんが、 Dataverse.Client.Extensions.CRUDExtentions メソッド では使用できます。

詳細: 非同期サービスのバイパス

Power Automate フローのバイパス

フローをトリガーするバルク データ操作が発生すると、Dataverse フローを実行するシステム ジョブを作成します。 システム ジョブの数が非常に多い場合、システムのパフォーマンスの問題が発生する可能性があります。 これが発生した場合は、SuppressCallbackRegistrationExpanderJob オプションのパラメーターを使用してフローがトリガーするのをバイパスすることを選べます。

CallbackRegistration テーブル はフロートリガーを管理し、登録されたフロー トリガーを呼び出す エキスパンダー 呼ばれる内部操作があります。

注意

このオプションを使用すると、フローの所有者は、フロー ロジックがバイパスされたという通知を受け取りません。

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

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

詳細: Power Automate フローのバイパス

参照

.NET 用 SDK でメッセージを使用する
Web API: HTTP 要求の作成とエラーの処理 : その他のヘッダー
カスタム ビジネス ロジックをバイパスする

注意

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

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