バックグラウンド操作 (プレビュー)
[この記事はプレリリース ドキュメントであり、変更されることがあります]
バックグラウンド オペレーションを使用して、 Dataverse 非同期に処理します。 バックグラウンド操作は、リクエストの実行中に接続を維持したくない場合に役立ちます。
バックグラウンド操作が完了すると、次の 2 つの方法のいずれかで通知を受け取ることができます:
バックグラウンド操作の結果は、次の 2 つの方法のいずれかで取得できます:
要求をバックグラウンドで実行するには、操作をカスタム API として定義する必要があります。 カスタム API を作成して使用する方法、およびカスタム API に関するデータを取得する方法について説明します。
カスタム API はプラグインを使用してデータ操作を実行します。 すべての Dataverse プラグインと同様、これらのプラグインには 2 分間の実行タイムアウトがあります。要求を非同期に送信しても、実行時間は長くなりません。
バックグラウンド操作を実行するには、開始ユーザーは backgroundoperations
テーブルへの読み取りおよび書き込みアクセス権が必要です。 prvReadbackgroundoperation
と prvWritebackgroundoperation
権限を割り当ててこのアクセスを許可します。
- SDK: AddPrivilegesRoleRequest
- Web API: AddPrivilegesRole アクション
.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 つの値が含まれます。
backgroundoperations
テーブル内の行の ID を使用して、テーブル内のデータを取得または更新します:ステータス監視リソースを表す
Location
URL を使用して、バックグラウンド操作をポーリングおよびキャンセルします:重要
ステータス モニタ リソースは、Web API
backgroundoperation
EntityType リソースではありません。[URL] 例 ステータス監視リソース [Organization URI]/api/backgroundoperation/<backgroundoperationid value>
backgroundoperation
EntityType リソース[Organization URI]/api/data/v9.2/backgroundoperations(<backgroundoperationid value>)
ステータス モニター リソースは、 Dataverse Web API の一部ではありません。 URL に
/data/v9.2/
が含まれていないことに注意してください。 ステータス監視リソースは GET 操作および DELETE 操作のみをサポートしており、Web APIbackgroundoperation
EntityType リソースと同じ動作はありません。
バックグラウンド操作テーブルまたはステータス監視リソースをクエリして確認する動作は、一般にステータス ポーリングと呼ばれています。 過剰なポーリングはパフォーマンスに悪影響を及ぼす可能性があるため、避けることをお勧めします。 必要に応じて、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 TimeStartTime starttime |
DateTime | バックグラウンド操作が開始実行した時 |
End TimeEndTime 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"]}");
}
バックグラウンド操作の完了時に通知を受け取るもう 1 つの方法は、OnBackgroundOperationComplete
メッセージにステップを登録することです。 このメッセージは、非同期ステップ登録のみを許可するカスタム API です。 これは、ビジネス イベントを表すためにカスタム API を使用して作成されたメッセージ タイプの例です。
名前が示すように、OnBackgroundOperationComplete イベントは、バックグラウンド操作が完了するたびに発生します。 このイベントに非同期ステップを登録すると、プラグインで任意のロジック タイプを実行したり、データを Azure サービスや Webhook に転送したりできます。 詳細情報:
- プラグインの登録
- Azure 統合
- Azure イベント ハブ ソリューションの Microsoft Dataverse イベント データに関する作業
- Webhooks を使用してサーバー イベント用に外部ハンドラーを作成する
次の表では、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
テーブルの行を更新して、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 [Organization URI]/api/backgroundoperation/{backgroundoperationid}
応答:
HTTP/1.1 200 Ok
{
backgroundOperationStateCode: 2,
backgroundOperationStatusCode: 22
}
リクエストの実行中にエラーが発生した場合、最大 3 回まで再試行されます。 これらの再試行では、エクスポネンシャル バックオフ戦略が使用されます。