長期データ保持に関する概要

長期的なデータ保持は、Microsoft Dataverse トランザクションデータベースから管理されたデータレイクへのデータ転送を自動化し、コスト効率の高いアーカイブストレージを実現します。テーブルを長期保存するように構成することから始めましょう。次に、アーカイブするデータを定義する保持ポリシーを作成します。スケジュールされた保持処理では、条件に一致する行が転送されます。

重要

すべての長期データ保持機能を使用するには、「 Dataverse 長期データ保持の概要」で説明されている両方の要件を満たす必要があります。

保持データの取得

FetchXml と QueryExpression を使用して、保持されているデータを取得できます。

FetchXml を使用して、 fetch 要素datasource 属性値を "retained"に設定します。

<fetch datasource="retained">
   <entity name="account">
      <attribute name="accountId" />
   </entity>
</fetch>

QueryExpression を使用して、QueryExpression.DataSource プロパティを retained に設定します。

ヒント

現在、 Dataverse Web API と OData スタイルのクエリを使用して、保持されているデータを取得する方法はありません。 Dataverse Web API で FetchXml を使用できます。

保持ポリシーを設定する

保持ポリシーを作成するには、API、Maker Portal、またはソリューションのインストールを使用します。次のコードサンプルは、API を使用して保持ポリシーを作成する例を示しています。

.NET 用 SDK
ウェブAPI

次のコードでは、Organization サービスと IOrganizationService.Create(Entity) メソッドを使用して、クローズした営業案件をすべて保持し、1 年ごとに実行する保持ポリシーを作成します。有効な繰り返しパラメータは DAILY、WEEKLY、MONTHLY、YEARLY です。保持を 1 回だけ実行するには、繰り返し値を空に設定します。

public void CreateRetentionConfig(IOrganizationService orgService)
{
    Entity retentionConfig = new Entity("retentionconfig");
    retentionConfig["retentionconfigid"] = Guid.NewGuid();
    retentionConfig["entitylogicalname"] = "incident";
    retentionConfig["name"] = "Retain all closed opportunities";
    retentionConfig["uniquename"] = "ui_RetainAllClosedOpportunities";
    retentionConfig["statecode"] = new OptionSetValue(0);
    retentionConfig["statuscode"] = new OptionSetValue(10);
    retentionConfig["criteria"] = "<fetch> " +
        "<entity name=\"opportunity\"> " +
            "<attribute name=\"name\" /> " +
            "<attribute name=\"statecode\" />" +
            "<attribute name=\"actualvalue\" />" +
            "<attribute name=\"actualclosedate\" />" +
            "<attribute name=\"customerid\" />" +
            "<attribute name=\"opportunityid\" />" +
            "<order attribute=\"actualclosedate\" descending=\"true\" />" +
            "<filter type=\"and\">" +
                "<filter type=\"or\">" +
                    "<condition attribute=\"statecode\" operator=\"eq\" value=\"1\" />" +
                    "<condition attribute=\"statecode\" operator=\"eq\" value=\"2\" />" +
                "</filter>" +
            "</filter>" +
        "</entity></fetch>";
    retentionConfig["starttime"] = DateTime.Parse("2024-05-01T00:00:00");
    retentionConfig["recurrence"] = "FREQ=YEARLY;INTERVAL=1";
    try
    {
        var retentionConfigId = orgService.Create(retentionConfig);
        Console.WriteLine($"Retention policy created with Id : {retentionConfigId}");
    }
    catch (Exception ex)
    {
        throw new Exception($"Create retention policy failed: {ex.Message})", ex);
    }
}

このコードの出力は、「ID : c1a9e932-89f6-4f17-859c-bd2101683263 で作成された保持ポリシー」です。

次の Web API の例では、すべてのクローズされた商談を保持し、毎年実行される保持ポリシーを作成します。有効な繰り返しパラメータは DAILY、WEEKLY、MONTHLY、YEARLY です。保持を 1 回だけ実行するには、繰り返し値を空に設定します。この例では、retentionconfig エンティティタイプを使用します。

要求:

POST [Organization Uri]/api/data/v9.1/retentionconfigs
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
"statecode": 0,
 "name": "Retain all closed opportunities",
 "uniquename": "ui_RetainAllClosedOpportunities",
 "statuscode": 10,
 "criteria": 
      "<fetch>
          <entity name=\"opportunity\">
              <attribute name=\"name\" />
              <attribute name=\"statecode\" />
              <attribute name=\"actualvalue\" />
              <attribute name=\"actualclosedate\" />
              <attribute name=\"customerid\" />
              <attribute name=\"opportunityid\" />
              <order attribute=\"actualclosedate\" descending=\"true\" />
              <filter type=\"and\">
                  <filter type=\"or\">
                      <condition attribute=\"statecode\" operator=\"eq\" value=\"1\" />
                      <condition attribute=\"statecode\" operator=\"eq\" value=\"2\" />
                  </filter>
              </filter>
          </entity>
      </fetch>",
 "starttime": "2023-05-01T00:00:00",
 "recurrence": "FREQ=YEARLY;INTERVAL=1",
 "retentionconfigid": "35cc1317-20b7-4f4f-829d-5d9d5d77f712",
 "entitylogicalname": "incident"
}

保持ポリシーを検証する

長期保存プロセスにより、データは Dataverse のトランザクションストレージから管理されたデータレイクに移動します。データがデータレイクに移動された後は、そのデータに対してトランザクション操作を実行できなくなります。保持ポリシーが正しいことを確認することが重要です。オプションでカスタムプラグインを ValidateRetentionConfig メッセージに登録することで、独自の検証を追加できます。

.NET 用 SDK
ウェブAPI

class SampleValidateRetentionConfigPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var pluginContext = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var entityName = pluginContext.PrimaryEntityName;
        if( pluginContext.InputParameters.TryGetValue("FetchXml", out var fetchXml) )
        {
            // Add custom validation against the Fetch XML. 
        }
        else
        {
            throw new Exception("No critiera provided.");
        }
    }
}

リテンション実行時のカスタムロジック

長期保持は、アイテム保持ポリシーを設定するたびに実行される非同期プロセスです。以下の操作を行います:

保持対象の行 (レコード) をマークします。
マークされた行をデータレイクにコピーします。
ソースデータベースから行を消去します。
パージが失敗した場合は、マークされた行をロールバックします。

オプションで、行が保持対象としてマークされているとき、行がソースで消去されているとき、または保持対象としてマークされている行がロールバックされているときに実行するカスタムプラグインを登録できます。プラグインコードの作成は、SDK for .NET プログラミングにのみ適用されます。 Web API はプラグイン開発をサポートしていません。

行が保持対象としてマークされている場合のカスタムロジック

行を保持対象としてマークする一環として、Dataverse は BulkRetain と Retain メッセージを呼び出します。これらのメッセージの実行時にプラグインを登録することで、カスタムロジックを追加できます。カスタムロジックの例としては、保持のためにより多くの行をマークしたり、行を保持用にマークする前に検証を実行したりするなどがあります。

このコードサンプルは、単一のテーブル行の保持中に実行されるカスタムプラグインを示しています。

class SampleRetainPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var pluginContext = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var entityName = pluginContext.PrimaryEntityName;
        if( pluginContext.InputParameters.TryGetValue("Target", out var _target) )
        {
            EntityReference target = (EntityReference)_target;
            Console.WriteLine($"Request came for table : {target.Name} with id : {target.Id}");
            // Add your logic for validation or additional operation. 
            // For example - you can call Retain on Additional row of another table. 
        }
        else
        {
            throw new Exception("No target present.");
        }
    }
}

ロールバック保持操作の場合は、 RollbackRetain メッセージに登録する以外は、前の例のようなプラグインを記述します。

一括保持に対するカスタムロジック

このコードサンプルでは、 BulkRetain メッセージ操作の最後のページ実行に関するカスタムロジックを示します。

class SampleBulkRetainPlugin : IPlugin
{
    // Send notification when bulk retain execution is done. 
    public void Execute(IServiceProvider serviceProvider)
    {
        var pluginContext = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var entityName = pluginContext.PrimaryEntityName;
        if(pluginContext.OutputParameters != null 
            && pluginContext.OutputParameters.TryGetValue("HasMoreRecords", out var _hasMoreRecords) )
        {    
            if(!(bool)_hasMoreRecords)
            {
                Console.WriteLine("This is a last execution of this request.");
                // SendNotifcation that retention for an entity is completed. 
            }
        }
    }
}

保持により行が削除された場合のカスタムロジック

Dataverse は、 PurgeRetainedContent メッセージを実行して、データレイクに正常に移動したトランザクションデータ行を削除します。 PurgeRetainedContent メッセージは、正常に移動されたテーブル行を削除するDelete メッセージ操作を内部的に実行します。

テーブルレベルでのパージ操作中にカスタムロジックが必要な場合は、PurgeRetainedContent メッセージにカスタムプラグインを登録できます。必要に応じて、保持のために行が削除されたときにコードを呼び出す必要がある場合は、Delete メッセージにカスタムプラグインを登録できます。プラグインの ParentContext プロパティを調べて、リテンション期間が原因で削除が発生したかどうかを確認できます。保持による ParentContext メッセージ操作の Delete プロパティ値は「PurgeRetainedContent」です。

このコードサンプルでは、行を削除する準備ができていない場合に、テーブルの消去をブロックします。

class SamplePurgeRetainedContentPlugin : IPlugin
{
    // Block purge if all the rows are not validatd. 
    public void Execute(IServiceProvider serviceProvider)
    {
        var pluginContext = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var entityName = pluginContext.PrimaryEntityName;
        if( pluginContext.InputParameters.TryGetValue("MaxVersionToPurge", out var _maxVersiontoPurge) )
        {
            long MaxVersionToPurge = (long)_maxVersiontoPurge;
            var rowsToBePurged = GetToBePurgedRows(entityName, MaxVersionToPurge);
            // Add custom validation to process rowsToBePurged.
        }
    }

    public EntityCollection GetToBePurgedRows(string  entityName, long maxVersionToPurge)
    {
        IOrganizationService organizationService; // Create OrgService. 
        QueryExpression queryExpression = new QueryExpression()
        {
            EntityName = entityName,
            ColumnSet = new ColumnSet(new string[] { "versionnumber", "msft_datastate" })
        };
        queryExpression.Criteria.AddCondition("msft_datastate", ConditionOperator.Equal, 1);
        queryExpression.Criteria.AddCondition("versionnumber", ConditionOperator.LessEqual, maxVersionToPurge);
        var response = organizationService.RetrieveMultiple(queryExpression);
        return response;
    }
}

このコードサンプルは、保持のために削除操作に適用されます。

class SampleDeletePlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        if (IsDeleteDueToRetention(serviceProvider))
        {
            // Write your code to handle delete during retention
        }
        else
        {
            // Write your code to handle normal delete without retention
        }
    }

    private bool IsDeleteDueToRetention(IServiceProvider serviceProvider)
    {
        var currentContext = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        while (currentContext != null)
        {
            if (string.Equals(currentContext.MessageName, "PurgeRetainedContent"))
            {
                return true;
            }
            else
            {
                currentContext = currentContext.ParentContext;
            }
        }
        return false;
    }
}

クエリの保持ポリシーと実行の詳細

システムは、アイテム保持ポリシーの詳細を RetentionConfig テーブルに格納します。保持処理の実行詳細は、RetentionOperation テーブルと RetentionOperationDetail テーブルに格納されます。これらのテーブルをクエリして、保持ポリシーと実行の詳細を取得できます。

次のコードでは、日付保持の詳細テーブル行のクエリに使用できる FetchXML の例をいくつか示します。 FetchXML 独自の XML ベースのクエリ言語です。 FetchExpressionを使用して SDK ベースのクエリで使用したり、fetchXmlクエリ文字列を使用して Web API で使用したりできます。

このコードサンプルは、電子メールオーダーのすべてのアクティブな保持ポリシーを名前で返す簡単なクエリを示しています。

.NET 用 SDK
ウェブAPI


public EntityCollection GetActivePolicies(IOrganizationService orgService)
{
    string fetchXml = @"
    <fetch>
      <entity name='retentionconfig'>
        <attribute name='retentionconfigid' />
        <attribute name='name' />
        <attribute name='createdon' />
        <attribute name='starttime' />
        <attribute name='recurrence' />
        <attribute name='entitylogicalname' />
        <attribute name='criteria' />
        <order attribute='name' descending='false' />
        <filter type='and'>
          <condition attribute='entitylogicalname' operator='eq' value='email' />
          <condition attribute='statuscode' operator='eq' value='10' />
        </filter>
      </entity>
    </fetch>";

    var query = new FetchExpression(fetchXml);

    EntityCollection results = orgService.RetrieveMultiple(query);

    results.Entities.ToList().ForEach(x => {
      Console.WriteLine(x.Attributes["name"]);
    });

    return(results);
}

FetchXML クエリ文字列のほかの例

このコードサンプルは、FetchXML ステートメントを使用して、電子メールのすべての一時停止された保持ポリシーを取得する方法を示しています。

<fetch>
  <entity name="retentionconfig">
    <attribute name="retentionconfigid" />
    <attribute name="name" />
    <attribute name="createdon" />
    <attribute name="starttime" />
    <attribute name="recurrence" />
    <attribute name="entitylogicalname" />
    <attribute name="criteria" />
    <order attribute="name" descending="false" />
    <filter type="and">
      <condition attribute="entitylogicalname" operator="eq" value="email" />
      <condition attribute="statuscode" operator="eq" value="20" />
    </filter>
  </entity>
</fetch>

このコードサンプルは、FetchXML ステートメントを使用して保持ポリシーのすべての保持操作を取得する方法を示しています。

<fetch>
  <entity name="retentionoperation">
    <attribute name="retentionoperationid" />
    <attribute name="name" />
    <attribute name="statuscode" />
    <attribute name="statecode" />
    <attribute name="starttime" />
    <attribute name="rootentitylogicalname" />
    <attribute name="endtime" />
    <attribute name="criteria" />
    <order attribute="name" descending="false" />
    <filter type="and">
      <condition 
         attribute="retentionconfigid" 
         operator="eq" 
         value="{35CC1317-20B7-4F4F-829D-5D9D5D77F763}" />
    </filter>
  </entity>
</fetch>

このコードサンプルは、保持操作の詳細を取得する FetchXML ステートメントを示しています。

<fetch>
  <entity name="retentionoperationdetail">
    <attribute name="retentionoperationdetailid" />
    <attribute name="name" />
    <attribute name="createdon" />
    <attribute name="retentionoperationid" />
    <attribute name="retentioncount" />
    <attribute name="isrootentity" />
    <attribute name="failedcount" />
    <attribute name="entitylogicalname" />
    <order attribute="name" descending="false" />
    <filter type="and">
      <condition attribute="retentionoperationid" operator="eq" value="{35CC1317-20B7-4F4F-829D-5D9D5D77F763}"/>
    </filter>
  </entity>
</fetch>

このコードサンプルは、保持操作中に発生した不具合/エラーの詳細を取得する FetchXML ステートメントを示しています。

<fetch>
  <entity name="retentionfailuredetail">
    <attribute name="retentionfailuredetailid" />
    <attribute name="name" />
    <attribute name="createdon" />
    <attribute name="recordid" />
    <attribute name="operation" />
    <attribute name="message" />
    <order attribute="name" descending="false" />
    <filter type="and">
      <condition attribute="operationid" operator="eq" value="35CC1317-20B7-4F4F-829D-5D9D5D77F763" />
    </filter>
  </entity>
</fetch>

参照

データ保持ポリシーを管理する
 長期保存されたデータを表示する
 データの一括削除
 Microsoft Dataverse Web API を使用する

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-02