次の方法で共有

バックグラウンド操作 (プレビュー)

  • [アーティクル]

[この記事はプレリリース ドキュメントであり、変更されることがあります]

バックグラウンド オペレーションを使用して、 Dataverse 非同期に処理します。 バックグラウンド操作は、リクエストの実行中に接続を維持したくない場合に役立ちます。

バックグラウンド操作が完了すると、次の 2 つの方法のいずれかで通知を受け取ることができます:

バックグラウンド操作の結果は、次の 2 つの方法のいずれかで取得できます:

要求をバックグラウンドで実行するには、操作をカスタム API として定義する必要があります。 カスタム API を作成して使用する方法、およびカスタム API に関するデータを取得する方法について説明します。

カスタム API はプラグインを使用してデータ操作を実行します。 すべての Dataverse プラグインと同様、これらのプラグインには 2 分間の実行タイムアウトがあります。要求を非同期に送信しても、実行時間は長くなりません。

必要な権限

バックグラウンド操作を実行するには、開始ユーザーは backgroundoperations テーブルへの読み取りおよび書き込みアクセス権が必要です。 prvReadbackgroundoperation と prvWritebackgroundoperation 権限を割り当ててこのアクセスを許可します。

セキュリティ ロールの編集方法について。

非同期処理の要求

.NET 用 SDK または Dataverse Web API を使用して、バックグラウンドで非同期要求を実行できます。

この記事の例では、sample_ExportDataUsingFetchXmlToAnnotation という名前のカスタムAPIを使用しています。 このカスタム API については、サンプル: ExportDataUsingFetchXmlToAnnotation カスタム API で説明しています。

ExecuteBackgroundOperation メッセージを使用します。

SDK には、ExecuteBackgroundOperation 要求クラスと応答クラスがありません。 これらのクラスが追加されるまでは、.NET 用 SDK でメッセージを利用するの説明に従って、基本の OrganizationRequest クラスおよび OrganizationResponse クラスを使用してください。

次の表で、ExecuteBackgroundOperation メッセージの入力パラメーターについて説明します。

件名 タイプ Description
Request OrganizationRequest (必須) 非同期に処理する要求が含まれます。 要求の Dataverse メッセージはカスタム API として実装する必要があります。
CallbackUri string (オプション) Dataverse は、操作が完了すると POST HTTP 要求をこの URL に送信します。

次の表で、ExecuteBackgroundOperation メッセージの出力パラメーターについて説明します。

件名 タイプ Description
BackgroundOperationId GUID 要求の処理を監視またはキャンセルするために使用できるバックグラウンド操作テーブルの行を識別します。
Location string 要求のステータスを取得したり、キャンセルしたりするために使用できるステータス監視リソースの URL を識別します。

次の静的メソッドは、sample_ExportDataUsingFetchXmlToAnnotation カスタム API で ExecuteBackgroundOperation を使用します。

static void SendRequestAsynchronously(IOrganizationService service)
{
    //Create a request for message defined as a custom API to run in the background
    var asyncRequest = new OrganizationRequest("sample_ExportDataUsingFetchXmlToAnnotation")
    {
        Parameters =
        {
            {"FetchXml",  @"<fetch version='1.0'  
                                    output-format='xml-platform' 
                                    mapping='logical'>
                                <entity name='account'>
                                    <attribute name='accountid'/>
                                    <attribute name='name'/>  
                                </entity>
                            </fetch>" }
        }
    };

    //Create a request to execute the message in the background
    var request = new OrganizationRequest("ExecuteBackgroundOperation")
    {
        Parameters =
        {
            {"Request", asyncRequest }
        }
    };

    //Execute the background operation request
    var response = service.Execute(request);

    Console.WriteLine($"BackgroundOperationId: {response["BackgroundOperationId"]}");
    Console.WriteLine($"Location: {response["Location"]}");
}

出力:

BackgroundOperationId: <backgroundoperationid value>
Location: [Organization URI]/api/backgroundoperation/<backgroundoperationid value>

IOrganizationService インターフェイスおよび .NET 用 SDK でメッセージを使用する方法の詳細をご覧ください。

バックグラウンド操作を管理する

バックグラウンドで処理する要求を送信すると、応答にはバックグラウンド操作を監視またはキャンセルするために使用できる方法を示す 2 つの値が含まれます。

バックグラウンド操作テーブルまたはステータス監視リソースをクエリして確認する動作は、一般にステータス ポーリングと呼ばれています。 過剰なポーリングはパフォーマンスに悪影響を及ぼす可能性があるため、避けることをお勧めします。 必要に応じて、1 分以上の間隔でポーリングすることをお勧めします。

バックグラウンド操作テーブル

バックグラウンド操作テーブルには、非同期で処理する要求に関する情報が含まれています。 このテーブルには、論理名 backgroundoperation とエンティティ セット名 backgroundoperations があります。 backgroundoperation EntityType について。

次の表では、バックグラウンド操作のステータス管理に使用できる列について説明します。

表示名称
スキーマ名
論理名		 タイプ Description
バックグラウンド操作
BackgroundOperationId
backgroundoperationid		 Uniqueidentifier 主キー
ステータス
StateCode
backgroundoperationstatecode		 Picklist バックグラウンド操作のステータス

オプション:
- 値: 0、ラベル: 準備完了
- 値: 2、ラベル: ロック
- 値: 3、ラベル: 完了
ステータスの理由
StatusCode
backgroundoperationstatuscode		 Picklist バックグラウンド操作のステータス

オプション:
- 値: 0、ラベル: リソースを待機中 (状態:準備完了)
- 値: 20、ラベル: 進行中 (状態:ロック)
- 値: 22、ラベル: キャンセル中 (状態:ロック)
- 値: 30、ラベル: 成功 (状態:完了)
- 値: 31、ラベル: 失敗 (状態:完了)
- 値: 32、ラベル: キャンセル (状態:完了)
件名
Name
name		 String バックグラウンド操作に使用されるカスタム API の UniqueName
表示名
DisplayName
displayname		 String バックグラウンド操作に使用されるカスタム API の DisplayName
パラメーターの入力
InputParameters
inputparameters		 メモ バックグラウンド操作を開始するために指定された入力パラメーター

この文字列は、 Key と Value の JSON シリアル化配列です。
出力パラメーター
OutputParameters
outputparameters		 メモ バックグラウンド操作の応答

この文字列は、 Key と Value の JSON シリアル化配列です。
Start Time
StartTime
starttime		 DateTime バックグラウンド操作が開始実行した時
End Time
EndTime
endtime		 DateTime バックグラウンド操作が終了実行した時
再試行回数
RetryCount
retrycount		 整数 バックグラウンド操作が再試行された回数
エラー コード
ErrorCode
errorcode		 整数 バックグラウンド操作が失敗した場合のエラー コード

エラーが Dataverse から発生した場合、Webサービス エラー コード にリストされているコードのいずれかに対応する整数値を持ちます。 エラーの原因が Dataverse から発生したものではない場合、値はゼロに設定されます。
エラー メッセージ
ErrorMessage
errormessage		 メモ バックグラウンド操作が失敗した場合のエラー メッセージ
実行するユーザー
RunAs
runas		 String バックグラウンド操作の実行に使用される systemuserid の systemuser
作成日
CreatedOn
createdon		 DateTime レコードが作成された時
有効期限
TTLInSeconds
ttlinseconds		 整数 秒単位の有効期限; デフォルト値は 90 日で、その後レコードは自動的に削除されます

バックグラウンド操作テーブルのポーリング

次の列をクエリに必ず含めてください。

  • name
  • backgroundoperationstatecode
  • backgroundoperationstatuscode
  • outputparameters
  • errorcode
  • errormessage

テーブルをポーリングする方法は、SDK を使用しているか Web API を使用しているかによって異なります。

static void PollBackgroundOperationRequest(IOrganizationService service, Guid backgroundOperationId)
{
    // List of columns that will help to get status, output and error details if any
    var columnSet = new ColumnSet(
        "name",
        "backgroundoperationstatecode",
        "backgroundoperationstatuscode",
        "outputparameters",
        "errorcode",
        "errormessage");

    try
    {
        // Get the entity with all the required columns
        var backgroundOperation = service.Retrieve("backgroundoperation", backgroundOperationId, columnSet);

        Console.WriteLine($"Name: {backgroundOperation["name"]}");
        Console.WriteLine($"State Code: {backgroundOperation.FormattedValues["backgroundoperationstatecode"]}");
        Console.WriteLine($"Status Code: {backgroundOperation.FormattedValues["backgroundoperationstatuscode"]}");
        Console.WriteLine($"Output Parameters:");

        // Deserialize the Output Parameters into KeyValuePair<string, string>
        List<KeyValuePair<string, string>>? output = 
            System.Text.Json.JsonSerializer
            .Deserialize<List<KeyValuePair<string, string>>>((string)backgroundOperation["outputparameters"]);

        output.ForEach(x => {
            Console.WriteLine($"\t{x.Key}: {x.Value}");
        });

        Console.WriteLine($"Error Code: {backgroundOperation.GetAttributeValue<string>("errorcode")}");
        Console.WriteLine($"Error Message: {backgroundOperation.GetAttributeValue<string>("errormessage")}");
    }
    // Catch Dataverse errors
    catch (FaultException<OrganizationServiceFault> ex)
    {
        Console.WriteLine($"ErrorCode:{ex.Detail.ErrorCode}");
        Console.WriteLine($"Message:{ex.Detail.Message}");
    }
    // Catch other errors
    catch (Exception error)
    {
        Console.WriteLine($"Some other error occurred: '{error.Message}'");
    }
}

出力待ち:

Name: sample_ExportDataUsingFetchXmlToAnnotation
State Code: Locked
Status Code:  In Progress
Output Parameters:  
Error Code:  
Error Message:

出力完了:

Name: sample_ExportDataUsingFetchXmlToAnnotation
State Code: Completed
Status Code:  Succeeded
Output Parameters:
        AnnotationId: {value}
Error Code:  
Error Message:

エラー出力:

Name: sample_ExportDataUsingFetchXmlToAnnotation
State Code: Completed
Status Code:  Failed
Output Parameters: 
Error Code:  -2147187707
Error Message:  Access is denied.

プラットフォームでエラーが発生した場合、そのエラーには、Web サービスのエラー コード リストにあるコードのいずれかに対応する整数値が含まれます。 プラットフォームからエラーが発生しない場合、値はゼロに設定されます。

ID が見つかりません:

ErrorCode:-2147185406
Message:The HTTP status code of the response was not expected (404).

Status: 404
Response:
{"error":{"message":"Could not find item '110eaa68-db17-4115-ad74-d185823fc089'.","details":[{"message":"\r\nErrors : [\r\n  \"Resource Not Found. Learn more: https://aka.ms/cosmosdb-tsg-not-found\"\r\n]\r\n"}]}}

ステータス監視リソースのポーリング

GET 要求を使用してステータス監視リソースをポーリングすると、バックグラウンド操作のステータスが返されます。 操作が完了すると、カスタム API の出力が提供されます。 実行中にエラーが発生した場合は、エラー メッセージとコードが表示されます。

元のリクエストの Location レスポンス ヘッダーで返されたステータス監視リソースの URL にリクエストを送信します。

要求:

GET [Organization URI]/api/backgroundoperation/{backgroundoperationid}
Content-Type: application/json

応答:

HTTP/1.1 200 OK
Content-Type: application/json

{
  backgroundOperationErrorCode: {INT},
  backgroundOperationErrorMessage: {string},
  backgroundOperationStateCode: {INT},
  backgroundOperationStatusCode: {INT},
  outputParam1: {value},
  outputParam2: {value},
  outputParam3: {value},
}

backgroundOperationErrorCode および backgroundOperationErrorMessage 値は、エラーが発生した場合にのみ含まれます。 出力パラメーターは、操作が正常に完了した場合にのみ含まれます。

ラベルはステータス監視リソースでは使用できません。

結果の通知を受信する

バックグラウンド操作の完了時に通知を受け取るには、次のいずれかを実行できます: 要求にコールバック URL を含めるまたは OnBackgroundOperationComplete イベントに登録する。

コールバックの要求

リクエストに URL を指定して、操作が完了したときにコールバックを受け取ることができます。 Dataverse はこの URL を使用して、次のペイロードで POST 要求を送信します:

{
    "location": "< status monitor resource URL >",
    "backgroundOperationId": "{GUID}",
    "backgroundOperationStateCode": {INT},
    "backgroundOperationStatusCode": {INT},
    "backgroundOperationErrorCode": {INT},
    "backgroundOperationErrorMessage": {string},
}

backgroundOperationErrorCode および backgroundOperationErrorMessage は、エラーが発生した場合にのみ含まれます。

コールバック ペイロードには、出力パラメーターは含まれません。 コールバックを受信するサイトは、結果を取得するために、ステータス監視リソースの URL を使用して認証された GET 要求を送信する必要があります。

認証が必要な URL の場合は、自己完結型の共有アクセス署名 (SAS) URL である必要があります。 認証用の API キーまたはトークンを含めるヘッダーをこれ以上含めることはできません。

webhook.site のようなサイトを使用して、コールバック URL をテストすることをお勧めします。

コールバックを要求する方法は、SDK を使用しているか Web API を使用しているかによって異なります。 次の例では、テストのために Webhook を使用して要求を webhook.site に送信します。

SDK を使用して、ExecuteBackgroundOperation.CallbackUri パラメータを URL に追加してリクエストを送信します。

static void SendRequestAsynchronouslyWithCallback(IOrganizationService service)
{
    //Create a request for message defined as a custom API to run in the background
    var asyncRequest = new OrganizationRequest("sample_ExportDataUsingFetchXmlToAnnotation")
    {
        Parameters =
        {
            {"FetchXml",  @"<fetch version='1.0'  
                                    output-format='xml-platform' 
                                    mapping='logical'>
                                <entity name='account'>
                                    <attribute name='accountid'/>
                                    <attribute name='name'/>  
                                </entity>
                            </fetch>" }
        }
    };

    //Create a request to execute the message in the background
    var request = new OrganizationRequest("ExecuteBackgroundOperation")
    {
        Parameters =
        {
            {"Request", asyncRequest },
            // Request a callback
            {"CallbackUri", "https://webhook.site/<id>" }
        }
    };

    //Execute the background operation request
    var response = service.Execute(request);

    Console.WriteLine($"BackgroundOperationId: {response["BackgroundOperationId"]}");
    Console.WriteLine($"Location: {response["Location"]}");
}

OnBackgroundOperationComplete イベントに登録する

バックグラウンド操作の完了時に通知を受け取るもう 1 つの方法は、OnBackgroundOperationComplete メッセージにステップを登録することです。 このメッセージは、非同期ステップ登録のみを許可するカスタム API です。 これは、ビジネス イベントを表すためにカスタム API を使用して作成されたメッセージ タイプの例です。

名前が示すように、OnBackgroundOperationComplete イベントは、バックグラウンド操作が完了するたびに発生します。 このイベントに非同期ステップを登録すると、プラグインで任意のロジック タイプを実行したり、データを Azure サービスや Webhook に転送したりできます。 詳細情報:

次の表では、OnBackgroundOperationComplete メッセージの入力パラメーターおよび出力パラメーターについて説明します。

入力パラメーター:

件名 タイプ Description
PayloadType 整数 バックグラウンド操作が完了したときにコールバック URI に送信される応答タイプは、バックグラウンド操作の場合は常にゼロです

このフィールドは内部のみで使用するものであるため、更新しないでください。
LocationUrl String 場所の URL
BackgroundOperationId GUID バックグラウンド操作の ID

出力パラメーター:

件名 タイプ Description
OperationName String 操作名
BackgroundOperationStateCode 整数 バックグラウンド操作ステータス コード
BackgroundOperationStatusCode 整数 バックグラウンド操作ステータス コード

プラグインを登録するの手順に従って、OnBackgroundOperationComplete メッセージを構成します。 メッセージ名を OnBackgroundOperationComplete に設定してください。 自動削除を true に設定すると、システム ジョブ (AsyncOperation) レコードが自動的に削除されます。

バックグラウンド操作のキャンセル

自身が始めたバックグラウンド操作がまだ開始されていない場合、キャンセルすることができます。

  • 操作が開始されていない場合、Dataverse はそれを実行しません。
  • 操作が開始された場合、Dataverse はそれを停止しません。
  • キャンセルしたバックグラウンド操作の実行中にエラーが発生した場合、Dataverse は再試行しません。
  • 操作が既に完了している場合、次のエラーが表示されます: Canceling background operation is not allowed after it is in terminal state.

次の 2 つの方法のいずれかでバックグラウンド操作をキャンセルできます:

backgroundoperations を更新してバックグラウンド操作をキャンセルする

backgroundoperations テーブルの行を更新して、backgroundoperationstatecode を 2 (ロック) に、backgroundoperationstatuscode を 22 (キャンセル中) に設定します。

backgroundoperations テーブルを更新する方法は、SDK を使用しているか Web API を使用しているかによって異なります。

static void CancelBackgroundOperationRequest(
    IOrganizationService service, 
    Guid backgroundOperationId)
{
    var backgroundOperation = new Entity(
        entityName: "backgroundoperation", 
        id: backgroundOperationId)
    { 
        Attributes =
        {
            //Set state as Locked
            {"backgroundoperationstatecode", new OptionSetValue(2) },
            //Set status as Cancelling
            {"backgroundoperationstatuscode", new OptionSetValue(22) }
        }            
    }; 

    service.Update(backgroundOperation);
}

ステータス監視リソースに DELETE リクエストを送る

ステータス監視リソースに DELETE 要求を送信して、バックグラウンド操作をキャンセルすることもできます。

要求:

DELETE [Organization URI]/api/backgroundoperation/{backgroundoperationid}

応答:

HTTP/1.1 200 Ok

{
    backgroundOperationStateCode: 2,
    backgroundOperationStatusCode: 22
}

Retries

リクエストの実行中にエラーが発生した場合、最大 3 回まで再試行されます。 これらの再試行では、エクスポネンシャル バックオフ戦略が使用されます。