変更追跡と Web API を使用して、エンティティ データの変更を追跡する

  • 15 分

一般的に、組織では複数のシステム間でデータを同期する必要があります。 Microsoft Dataverse にはこのシナリオを効率的に管理するための機能が搭載されており、変更追跡 と呼ばれます。 変更追跡を有効にすると、変更を照会するアプリケーションを作成できます。

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

テーブルで変更の追跡を有効にするには、Power Apps Maker Portal の詳細オプション > このテーブル用セクションにあるテーブル設定で変更を追跡するフラグを設定します。

OData 4.0 のドキュメントによれば、差分リンクは、「結果に後から加えられた変更を取得するためにクライアントが使用する、不透明なサービス生成リンク」です。Microsoft は、この標準を Dataverse の変更追跡に組み込み、長期的に発生する変更データとの整合性をとるための共通の標準的な方法を提供します。 差分リンクの詳細については、「OData バージョン 4.0 - 差分リンク」を参照してください。

変更追跡要求を実行すると、応答には差分リンクが含まれます。これを次の要求に渡すことで、最初の要求後に発生した変更を取得することができます。 日付スタンプおよびタイムスタンプでの追跡の経験があればそのときと同様に、差分リンクを維持するかどうかはアプリケーションによって異なります。

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

テーブルで変更追跡を有効にした後、Web 要求の基本設定ヘッダーとして odata.track-changes を追加すると、Web API を使用して変更を取得できます。 次の例では、特定のフィールドのセット (name、account number、telephone1、fax) について、アカウント テーブルに対する変更を要求します。

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

最初の要求では差分が適用されていないため、クエリに適用されるデータ セット全体が返されます。 ただし、応答には @odata.deltaLink 値が含まれます。 このリンクには、今回のクエリが実行された後に適用された変更内容を確認する必要がある場合に、後続の要求に渡すための deltatoken パラメーターが含まれています。 このプロセスは、OData でのページングの処理方法と同じように捉えることができます。

次の例は、先行するアカウント要求に対する応答です。

{
          "@odata.context":"[Organization URI]/data/v9.2/$metadata#accounts(name,telephone1,fax)/$delta",
          "@odata.deltaLink":"[Organization URI]/api/data/v9.2/accounts?$select=name,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44",
"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.2/$metadata#accounts/$deletedEntity",
            "id":"2e451703-c686-e711-80e5-00155db19e6d",
            "reason":"deleted"
        }
    ]
}

このシナリオでは、少し時間が経過したため、他の変更が適用されているかどうかを確認すると仮定します。 この @odata.deltaLink パラメーターを使用してクエリを実行すると (接続文字列の管理が異なる場合は、この値から deltatoken を抽出)、前回の要求以降に加えられた変更を確認できます。

次の例では、返された @odata.deltaLink を実行して、前回の要求以降の変更を取得する方法を示します。

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44

このシナリオでは、新しいアカウントが作成され、既存のアカウントが削除されたと仮定します。 応答は、次の例のようになります。

{
          "@odata.context":"[Organization URI]/data/v9.2/$metadata#accounts(name,telephone1,fax)/$delta",
          "@odata.deltaLink":"[Organization URI]/api/data/v9.2/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.1/$metadata#accounts/$deletedEntity",
            "id":"2e451703-c686-e711-80e5-00155db19e6d",
            "reason":"deleted"
        }
    ]
}

この例のように指定されている別の差分リンクを、次に変更の確認が必要になったときに使用できます。

差分の変更数を取得する

要求に $count パラメーターを追加すると、特定の差分で加えられた変更の数を取得することもできます。

GET [Organization URI]/api/data/v9.2/accounts/$count?$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44