変更の追跡を使用してデータを外部システムに同期

[アーティクル]
06/23/2023

Microsoft Dataverse の新しい変更追跡機能は、データが最初に抽出されてから、または最後に同期されてからどのデータが変更されたかを検出することによって、データの同期を効率の良い方法で維持する方法を提供します。この記事では、テーブルの変更を有効にして取得する方法について説明します。

テーブルの変更追跡の有効化

テーブルの変更を検索するには、その前に、Change Tracking がこのテーブルに対して有効になっていることを確認します。

この機能が有効になっているかどうかを確認したり、Power Apps を使用して有効にしたりできます。 データ > テーブル そして特定のテーブルを選択します。 詳細オプション の下に、 変更を追跡する プロパティがあります。

これをプログラムで設定するには、 EntityMetadata.ChangeTrackingEnabled プロパティを True に設定します。

注意

テーブルに対して Change Tracking を有効にすると、無効にすることはできません。

Power Apps の使用方法の詳細については: Power Apps を使用してテーブルを作成および編集する

Dataverse Web API を使用してテーブルの変更追跡が有効になっているかどうかを確認するには 2 つの方法があります。

次の GET 要求を使用して、EntityDefinitions をクエリすることができます。
```
GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$filter=ChangeTrackingEnabled eq true
```
変更追跡が有効になっているシステムテーブルがあります (監査 (Audit) など)。次のクエリを使用して、詳細リストを表示できます。
```
GET [Organization URI]/api/data/v9.2/EntityDefinitions?$filter=ChangeTrackingEnabled eq true and IsCustomEntity eq false&$select=LogicalName
```
詳細: Web API を使用してテーブル定義をクエリ
この情報は Web API $metadata サービスのドキュメントに記載されています。コメント Org.OData.Capabilities.V1.ChangeTracking が、変更追跡機能が有効にされたエンティティセットに設定されます。

Web API CDSL サービスドキュメントのコメントを表示するには、この Web API クエリを使用します。
```
GET [Organization URI]/api/data/v9.2/$metadata?annotations=true
```
変更追跡が有効になっているテーブルを表すエンティティセットには、次の注釈が付いています。
```
<Annotation Term="Org.OData.Capabilities.V1.ChangeTracking">
   <Record>
         <PropertyValue Property="Supported" Bool="true" />
   </Record>
</Annotation>
```
詳細: メタデータの注釈。

変更追跡の条件を満たしていないテーブル

テーブルによっては、変更の追跡を有効にできません。 EntityMetadata.CanChangeTrackingBeEnabled 管理プロパティの値を確認することで、テーブルが変更追跡の条件を満たしているかどうかを確認できます。変更追跡を有効にできないテーブルを確認するには、次の Web API クエリを使用します。

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName,ChangeTrackingEnabled&$filter=ChangeTrackingEnabled eq false and CanChangeTrackingBeEnabled/Value eq false

詳細情報:

Web API を使用してテーブルの変更を取得する

テーブルの変更は、Prefer: odata.track-changes ヘッダーを追加することにより、Web API 要求を使用して追跡することができます。このヘッダーは、後にテーブル変更を取得するために使用される、_デルタリンク_を返すことを要求します。

差分リンクは、クライアントが結果に対する後続の変更を取得するために使用する、不透明なサービス生成リンクです。これらは、変更が追跡される一連の結果を記述する定義クエリに基づいています。たとえば、差分リンクを含む結果を生成した要求です。差分リンクは、変更が追跡されているテーブルのコレクションと、変更を追跡するための開始点をエンコードします。詳細: OASIS OData バージョン 4.0 - 差分リンク

Web API 例を使用してテーブルの変更を取得します

この例では、Web API を使用して取引先企業テーブルに加えられた変更を取得する方法を示しています。

要求:

GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax HTTP/1.1
Prefer: odata.track-changes
OData-Version: 4.0
Content-Type: application/json

応答:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.track-changes

{
  "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts(name,accountnumber,telephone1,fax)",
"@odata.deltaLink": "[Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44",
"value":[
           {
              "@odata.etag":"W/\"915244\"",
              "name":"Monte Orton",
              "accountnumber":null,
              "telephone1":"555000",
              "fax":"10101",
              "accountid":"60c4e274-0d87-e711-80e5-00155db19e6d"
           }
       ]
}

上記の例から返された @odata.deltaLink URI は、テーブルの変更をフェッチするために使用できます。この例では新しい取引先企業が作成され、既存の取引先企業が削除されました。以下の例に示すように、以前の要求返された差分リンクはこれらの変更を取得します。

要求:

GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44
OData-Version: 4.0
Content-Type: application/json

応答:

HTTP/1.1 200 OK
OData-Version: 4.0

{
          "@odata.context":"[Organization URI]/data/v9.0/$metadata#accounts(name,telephone1,fax)/$delta",
          "@odata.deltaLink":"[Organization URI]/api/data/v9.0/accounts?$select=name,telephone1,fax&$deltatoken=919058%2108%2f22%2f2017%2008%3a21%3a20",
"value":
    [
        {
            "@odata.etag":"W/\"915244\"",
            "name":"Monte Orton",
            "telephone1":"555000",
            "fax":"10101",
            "accountid":"60c4e274-0d87-e711-80e5-00155db19e6d"
        },
        {
            "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts/$deletedEntity",
            "id":"2e451703-c686-e711-80e5-00155db19e6d",
            "reason":"deleted"
        }
    ]
}

最初の変更追跡要求で返された差分リンクの応答には、別の差分リンクが含まれています。この差分リンクは、テーブルにそれ以降に行われたすべての変更を取得するのに役立ちます。最初の変更追跡要求が呼び出された後にテーブルの変更が発生しなかった場合は、空の JSON 応答が返されます。

Web API を使用してテーブルで行われた変更の数を取得します

以下の例に示すように、最初の変更追跡要求から返された差分リンクに $count を追加して変更回数を取得することができます。

要求:

GET [Organization URI]/api/data/v9.0/accounts/$count?$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44
OData-Version: 4.0
Content-Type: application/json

変更追跡 Web API 要求でサポートされていないクエリオプション

Web API 要求で Prefer: odata.track-changes をヘッダーとして使用する場合は、システムクエリオプション $filter、$orderby、$expand および $top はサポートされません。エラーメッセージ: The \"${filter|orderby|expand|top}\" query parameter isn't supported when Change Tracking is enabled. は、Web API 要求でこれらのクエリオプションを使用する場合に返されます。

.NET SDK を使用してテーブルの変更を取得する

テーブルに対する変更の追跡を有効にすると、RetrieveEntityChanges メッセージを RetrieveEntityChangesRequest Class に使用して、そのテーブルの変更を取得できます。

このメッセージは、最初に使用されるときは、テーブルのすべてのレコードを返し、そのデータは外部の記憶域に入力するために使用できます。また、このメッセージは、次の RetrieveEntityChanges メッセージの使用で返されるバージョン番号を返します。これによって、このバージョン番号が返された以降に発生した変更に対するデータのみが返されます。

テーブルの変更の取得に際しては、以下の制限に注意ください。

変更の取得では、1 つのテーブルのみが追跡されます。バージョンまたはトークンなしで RetrieveEntityChanges が実行された場合、サーバーは、それをシステムの最小バージョンとして処理して、すべてのレコードを新規として返します。削除済みのオブジェクトは返されません。
最後のトークンが既定値の 7 日以内である場合、変更は返されます。この期間は、組織テーブル ExpireChangeTrackingInDays 列の値によって制御され、変更できます。構成された値よりも古い未処理の変更がある場合、システムは例外をスローします。
クライアントにテーブルに対する変更のセット、たとえば、バージョン 1 が存在し、次の変更のクエリの前にレコードが作成され、そのレコードが削除された場合、初めに削除されたアイテムがクライアントに存在しない場合でも、そのアイテムを取得します。
レコードは、サーバー側ロジックによって決定される順序で取得されます。通常、呼び出し元は、最初に新規のまたは更新されたすべてのレコード (バージョン番号で並べ替え) と、それに続く削除されたレコードを取得します。 3000 レコードが作成または更新され、2000 レコードが削除された場合は、Dataverse は 5000 レコードのコレクションを返します。これは、最初の 3000 エントリが新規または更新されたレコードで構成され、後の 2000 エントリが削除されたレコードの分です。
新規または更新されたアイテムのコレクションが 5000 を超える場合、コレクションを複数ページで表示できます。
呼び出し元のユーザーは、テーブルに対する組織レベルの読み取りアクセス権を持っている必要があります。ユーザーの読み取りアクセスが制限されている場合、システムは権限チェックエラーをスローします。

.NET SDK サンプルコード

次のコードスニペットは、RetrieveEntityChanges メッセージを使用してテーブルの変更を取得する方法を示しています。完全なサンプルについては、「変更の追跡を使用して外部システムにデータを同期」を参照してください。

string token;

// Initialize page number.
int pageNumber = 1;
List<Entity> initialrecords = new List<Entity>();

// Retrieve records by using Change Tracking feature.
RetrieveEntityChangesRequest request = new RetrieveEntityChangesRequest();
request.EntityName = _customBooksEntityName.ToLower();
request.Columns = new ColumnSet("sample_bookcode", "sample_name", "sample_author");
request.PageInfo = new PagingInfo() { Count = 5000, PageNumber = 1, ReturnTotalRecordCount = false };


// Initial Synchronization. Retrieves all records as well as token value.
Console.WriteLine("Initial synchronization....retrieving all records.");
while (true)
{
    RetrieveEntityChangesResponse response = (RetrieveEntityChangesResponse)_serviceProxy.Execute(request);

    initialrecords.AddRange(response.EntityChanges.Changes.Select(x => (x as NewOrUpdatedItem).NewOrUpdatedEntity).ToArray());
    initialrecords.ForEach(x => Console.WriteLine("initial record id:{0}", x.Id));
    if (!response.EntityChanges.MoreRecords)
    {
        // Store token for later query
        token = response.EntityChanges.DataToken;
        break;

    }
    // Increment the page number to retrieve the next page.
    request.PageInfo.PageNumber++;
    // Set the paging cookie to the paging cookie returned from current results.
    request.PageInfo.PagingCookie = response.EntityChanges.PagingCookie;
}

参照

テーブルの代替キーを定義する
 代替キーを使用してレコードを参照
 Upsert を使用して Dynamics 365 を外部データで更新
 Web API を使用してテーブル定義をクエリ

注意

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

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

変更の追跡を使用してデータを外部システムに同期

テーブルの変更追跡の有効化

変更追跡の条件を満たしていないテーブル

Web API を使用してテーブルの変更を取得する

Web API 例を使用してテーブルの変更を取得します

Web API を使用してテーブルで行われた変更の数を取得します

変更追跡 Web API 要求でサポートされていないクエリオプション

.NET SDK を使用してテーブルの変更を取得する

.NET SDK サンプルコード

参照

フィードバック

その他のリソース

変更の追跡を使用してデータを外部システムに同期

テーブルの変更追跡の有効化

変更追跡の条件を満たしていないテーブル

Web API を使用してテーブルの変更を取得する

Web API 例を使用してテーブルの変更を取得します

Web API を使用してテーブルで行われた変更の数を取得します

変更追跡 Web API 要求でサポートされていないクエリ オプション

.NET SDK を使用してテーブルの変更を取得する

.NET SDK サンプル コード

参照

フィードバック

その他のリソース

変更追跡 Web API 要求でサポートされていないクエリオプション

.NET SDK サンプルコード