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

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

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

テーブルの変更を取得する前に、そのテーブルに対して変更の追跡が有効になっていることを確認してください。

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

EntityMetadata.ChangeTrackingEnabled プロパティを True に設定することで、プログラムによってこのプロパティを設定します。

ヒント

テーブルの変更の追跡を有効にした後は、無効にすることはできません。

Power Apps の使用方法の詳細については、「 Power Apps を使用してテーブルを作成および編集する」を参照してください。

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

次のEntityDefinitions要求を使用してGETクエリを実行します。
```
GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$filter=ChangeTrackingEnabled eq true
```
一部のシステムテーブルでは、監査 (監査) など、変更の追跡が有効になっています。完全な一覧を表示するには、次のクエリを使用します。
```
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"
           }
       ]
}

例示された前の URI@odata.deltaLink を使用して、テーブルの変更を取得します。この例では、新しいアカウントを作成し、既存のアカウントを削除しました。前の要求から返されたデルタリンクは、次の例に示すように、その変更内容を取得します。

要求:

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

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

テーブルの変更の追跡を有効にする場合は、RetrieveEntityChangesでメッセージを使用して、そのテーブルの変更を取得します。

このメッセージを初めて使用すると、テーブルのすべてのレコードが返されます。そのデータを使用して、外部ストレージを設定できます。また、メッセージは、 RetrieveEntityChanges メッセージの次の使用時に返すバージョン番号も返されるため、そのバージョン以降に発生した変更のデータのみが返されます。

テーブルの変更を取得するときは、次の制約に注意してください。

変更の取得で追跡できるテーブルは 1 つだけです。バージョンまたはトークンなしで RetrieveEntityChanges を実行すると、サーバーはそれをシステムの最小バージョンとして扱い、すべてのレコードを新規として返します。削除されたオブジェクトは返されません。
最後のトークンが既定値の 7 日以内の場合、変更が返されます。 Organization テーブル ExpireChangeTrackingInDays 列の値は、この期間を制御し、変更できます。未処理の変更が構成された値より古い場合、システムは例外をスローします。
クライアントがテーブル (バージョン 1 など) に対して一連の変更を行っている場合、次の変更クエリの前にレコードが作成および削除されると、クライアントは、最初にアイテムを持っていない場合でも削除済みアイテムを取得します。
レコードは、サーバー側ロジックによって決定される順序で取得されます。通常、呼び出し元は、すべての新規または更新されたレコードを最初に取得し (バージョン番号で並べ替え)、その後に削除されたレコードを取得します。作成または更新されたレコードが 3,000 件、削除されたレコードが 2,000 件の場合、Dataverse は標準テーブルの 5,000 件のレコードのコレクションを返します。最初の 3,000 エントリが新規または更新されたレコードで、最後の 2,000 エントリが削除されたレコードです。
新規または更新されたアイテムのコレクションが 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 を使用してテーブル定義をクエリ

フィードバック

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

Last updated on 2026-04-01

次の方法で共有

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

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

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

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

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

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

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

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

.NET SDK のサンプル コード

参照

フィードバック

その他のリソース

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

.NET SDK のサンプルコード