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

Dataverse には、個々の要求の動作を変更するために使用できる一連の省略可能なパラメーターと要求ヘッダー値が用意されています。 この記事では、必要な動作を取得するために使用できるパラメーター値と要求ヘッダーについて説明します。

メモ

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

使用方法

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

通常は、名前付き要求クラスの OrganizationRequest.Parameters コレクション にパラメーターを追加します。

メモ

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

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

詳細情報:

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

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

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

  • AddPrivilegesRole
  • CopySystemForm
  • Create (POST)
  • Delete (DELETE)
  • MakeAvailableToOrganizationTemplate
  • RemovePrivilegeRole
  • ReplacePrivilegesRole
  • Update (PATCH)
  • Upsert

この操作は、 SolutionUniqueName 値が次の場合にエラーを返します。

  • 無効な文字が含まれています。 文字、数字、およびアンダースコア文字のみを使用できます。
  • 空の文字列であるか、制限されたソリューション名を使用しています。
  • ソリューション UniqueName 値と一致しません。

重要

SolutionUniqueName パラメーター値がマネージド ソリューションと一致する場合、エラーは返されません。 値 は無視されます。 ソリューション コンポーネントをマネージド ソリューションに追加することはできません。

次の例では、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);
}

詳細情報:

詳細情報:

重複データ検出の抑制

作成した新しいレコードまたは更新するレコードが別のレコードの重複検出ルールと一致する場合は、 SuppressDuplicateDetection パラメーターを使用して行を作成または更新し、 falseの値を指定する必要があります。

次の例では、次の条件に該当する場合にエラーが返されます。

  • 行を作成または更新するときに、環境に対して重複検出が有効になります。
  • 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 パラメーターで一意の文字列値を渡します。

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

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 値を使用します。

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

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

重要

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

次の例では、SDK for .NET BypassBusinessLogicExecutionを使用して新しいアカウント レコードを作成するときに、同期と非同期の両方のカスタム ロジックのオプション パラメーターを設定します。

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

カスタム Dataverse ロジックをバイパスする方法の詳細を確認する

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 フローのバイパス

マスクされていないデータを返す

マスク ルール プレビュー機能を使用するように列を構成する場合は、オプションのパラメーターUnMaskedData使用して、マスクされていない値を要求します。

RetrieveMultipleRequest request = new()
{
   Query = query,
   ["UnMaskedData"] = true
};

var response = (RetrieveMultipleResponse)service.Execute(request);

マスクされていないデータの取得について詳しくは、こちらをご覧ください。

参照

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