次の方法で共有

スキーマ データのキャッシュ

Dataverse 組織のスキーマ定義の永続的なキャッシュを維持すると、一部のアプリケーションにメリットがあります。 例:

  • Dataverse サーバーからの切断中に動作する必要があるアプリケーション。
  • モバイル アプリケーションなど、制限されたネットワーク帯域幅に敏感なアプリケーション。

Dataverse は多くのスキーマ定義データを含みますが、ほとんどのアプリケーションはそのすべてを追跡する必要がありません。 キャッシュするデータ量の制限は不可欠です。

RetrieveMetadataChanges メッセージには次の 2 つの機能があります。

  1. クエリ: 単一のクエリを作成して、必要なスキーマ データのみを取得します。 クエリの作成については、クエリのスキーマ定義 で解説しています。
  2. キャッシュ管理: アプリでスキーマ定義データをキャッシュする場合は、RetrieveMetadataChanges を使用して最後のクエリ以降の変更のみを効率的に取得します。 これらの変更に関する情報を使用して、キャッシュ内のアイテムを追加または削除します。 スキーマ データをキャッシュすると、アプリケーションの起動時間が大幅に短縮される可能性があり、この記事ではそこに焦点をあてています。

キャッシュするスキーマ データのクエリを定義したら、 RetrieveMetadataChanges メッセージの他の機能を使用して、Dataverse スキーマ データのキャッシュを作成および管理します。

キャッシュを作成する

クエリのスキーマ定義に記載の通り、最初のステップは、関心のあるスキーマ情報の種類を定義するクエリを作成することです。 次に、RetrieveMetadataChanges メッセージを使用して、そのクエリを実行し、返されたスキーマ定義をアプリケーションでキャッシュします。 アプリのニーズに適したこのデータを保持する方法を見つけます。 アプリケーションが起動時に読み取るファイルとして、それを保存します。 クエリを最後に実行したときのデータも保存する必要があります。 そのアプリケーションに合わせた適切な方法でキャッシュの構造を決めます。 削除された品目の削除を管理するには、キャッシュが一意の識別子として MetadataId を使用することが重要です。 詳細については、「 削除済みアイテムの削除」を参照してください。

変更を検出する

スキーマ定義の変更がいつ発生するかを検出するイベントは存在しません。 アプリケーションのニーズに基づいてキャッシュを更新します。 通常、アプリケーションの起動時に変更を取得します。 ただし、時間の経過にともなう変化を検出するべき場合は、システムを定期的にポーリングできます。 戦略に関係なく、前の要求を送信した時間を追跡します。

RetrieveMetadataChangesResponse.ServerVersionStamp プロパティは、RetrieveMetadataChanges への要求が発生した時点に関する情報を含みます。 前の応答の ServerVersionStamp 値を取得し、同じクエリを使用して再度送信するときに、 RetrieveMetadataChangesRequest.ClientVersionStamp の値として使用します。

リクエストに ClientVersionStamp プロパティを含めると、返される RetrieveMetadataChangesResponse.EntityMetadata プロパティには、前回のリクエスト以降に変更または追加されたスキーマ データのみが含まれます。 それらを独自のキャッシュに追加できます。

DeletedMetadataFilters パラメータも含めると、前回のリクエスト以降に削除されたスキーマ項目が RetrieveMetadataChangesResponse.DeletedMetadata プロパティに含まれます。 それらを独自のキャッシュから削除できます。

この結果は、元のクエリをもう一度実行するよりも小さく、高速です。

期限切れのキャッシュを管理する

Dataverse には、既定で 90 日間の変更に関する情報が格納されます。 この値は Organization.ExpireSubscriptionsInDays プロパティに格納されます。 ClientVersionStamp値が設定値より古い要求を送信すると、Dataverse はExpiredVersionStamp エラー (0x80044352) を返します。 この特定のエラーを処理し、発生したときにキャッシュを再初期化する準備をしてください。

注意

値が常に 90 日未満であると思われる場合でも、このエラーを管理する準備をしてください。 このエラーは、サーバー上の変更が削除されたスキーマ データの正確な追跡に影響する場合に発生します。 たとえば、 Organization.ExpireSubscriptionsInDays プロパティを変更すると、以前のすべての VersionStamp 値が無効になります。 これらの変更の一部は、実行したアクションによって発生しない可能性がありますが、システムメンテナンスによってトリガーされる可能性があります。

変更された項目を追加する

キャッシュを初期化するために最初のクエリを実行する場合と同様に、RetrieveMetadataChangesResponse.EntityMetadataを使用して後続の要求に対して返されるRetrieveMetadataChangesRequest.ClientVersionStamp プロパティには、変更された項目の完全な階層が含まれます。

階層内の各項目には、null を許容するブール値の HasChanged 値があります。 この値が false の場合、現在の項目は変更されませんでしたが、階層内のその下の項目が変更されていることを意味します。 HasChanged値が true の場合は、階層内の現在の項目が変更されていることを意味します。

注意

クエリで EntityMetadata.Privileges を要求した場合、権限は変更されたかどうかにかかわらず、常に返されます。 多くの場合、権限は変更されません。

追跡オプション

変更の追跡が直感的に見えない領域の 1 つは、選択列のオプションを追跡する方法です。 このエリアは、HasChanged プロパティを理解するための良い例です。

選択肢列に新しいオプションを追加すると、階層内の次のデータが RetrieveMetadataChangesResponse.EntityMetadata プロパティによって返されます。

EntityMetadata プロパティが false であるため、EnumAttributeMetadataとHasChangedが変更されなかったことがわかります。 OptionSetMetadata.HasChanged プロパティのみが true です。 現在有効なすべてのオプションが返されます。 新しいオプションも含め、すべてのオプションの OptionMetadata.HasChanged プロパティは null です。

新しく作成されたオプションにのみ、Label プロパティのデータが含まれます。 OptionMetadata.HasChanged プロパティは、プロパティの 1 つ (ColorやLabelなど) が変更された場合にのみ true になります。

削除済みアイテムを除去する

ClientVersionStamp メッセージに DeletedMetadataFilters と RetrieveMetadataChanges の両方のパラメーターを含めると、RetrieveMetadataChangesResponse.DeletedMetadata プロパティに削除された品目 に関するデータが含まれます。 このプロパティは DeletedMetadataCollection と Keys のセットを含む Values です。 キーは列挙値 DeletedMetadataFilters であり、これらの値を使用して削除された値のサブセットにアクセスできます。

注意

DeletedMetadataFilters パラメーターは省略可能です。 これを含めると、プロセスが内部キャッシュからではなくデータベースから直接データを取得するため、パフォーマンスに影響する可能性があります。 削除した項目を検出して、返す必要がある最小限のデータにフィルター値を設定する必要がある場合にのみ、これを使用します。

削除した値は Guid 値のコレクションとして返されます。 削除されたアイテムの値は、クエリに基づいてフィルタリングされません。 多くの Guid 値はキャッシュにありませんが、キャッシュされた項目の Guid 値が含まれます。 一致する Guid 値を見つけて、それらの項目を削除する必要があります。 キャッシュにない値は無視してください。

注意

Web API DeletedMetadataFilters EnumType の定義は、SDK DeletedMetadataFilters 列挙型 と多少異なります。

Web API DeletedMetadataFilters EnumType には Entity メンバーがありません。 Default を代わりに使用します。

削除されたオプションの追跡

注意: DeletedMetadataFilters 列挙型は OptionSet のメンバーを含みますが、オプションは含みません。 選択肢列からオプションを削除した場合、削除された特定のオプションへの参照は見つかりません。 キャッシュされたオプションにアクセスし、OptionSet に対して返された現在のオプションと比較する必要があります。

参照

Web API クエリ スキーマ定義と変更の検出のサンプル (C#)
.NET 用 SDK クエリ スキーマ定義と変更の検出のサンプル (C#)
クエリ スキーマ定義

  • Last updated on