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

  • [アーティクル]

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

  • Dataverse サーバーから切断された期間にも動作する必要があるアプリケーション
  • モバイル アプリケーションなど、ネットワーク帯域幅の制限に影響を受けるアプリケーション

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

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

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

キャッシュしたいスキーマ データのクエリを定義した後、RetrieveMetadataChanges メッセージの他の機能を使用して、Dataverse スキーマ データのキャッシュを作成し、維持することができます。

キャッシュを作成する

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

変更を検出する

スキーマ定義の変更を検出するイベントはありません。 アプリケーションのニーズに応じてキャッシュを更新する必要があります。 通常、変更はアプリケーションの起動時に取得されます。 ただし、時間の経過にともなう変化を検出するべき場合は、システムを定期的にポーリングできます。 戦略に関係なく、前回のリクエストを送信した時間を追跡することが重要です。

RetrieveMetadataChangesResponse.ServerVersionStamp プロパティは、RetrieveMetadataChanges への要求が発生した時点に関する情報を含みます。 同じクエリでもう一度送信する場合は、前の応答から ServerVersionStamp の値を取得して、それを RetrieveMetadataChangesRequest.ClientVersionStamp の値として使用する必要があります。

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

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

この結果は、元のクエリを再度実行するよりも小規模かつ速くなるはずです。

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

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

注意

値が常に 90 日未満になると考えられる場合でも、このエラーを処理する準備が必要です。 このエラーがスローされるのは、削除したスキーマ データの正確な追跡に、サーバー上の何らかの変更が影響を与える場合です。 たとえば Organization.ExpireSubscriptionsInDays プロパティを変更すると、以前の VersionStamp 値がすべて無効化されます。 これらの変更の一部は、ユーザーの操作で発生せず、システム メンテナンスによってトリガーされる場合があります。

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

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

階層が含む各項目は、null を指定できるブール値 HasChanged 値を含みます。 この値が false の場合、現在の項目は変更されておらず、階層で下位に存在する項目が変更されたことを意味します。 HasChanged 値が true の場合、階層の現在の項目が変更されたことを意味します。

注意

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

オプションを追跡する

直感的ではないと思われる領域のひとつは、選択列のオプションがどのように追跡されるかです。 このエリアは、HasChanged プロパティを理解するための良い例です。

新しいオプションが選択肢列に追加された場合、階層が含む次のデータが RetrieveMetadataChangesResponse.EntityMetadata プロパティと共に返されます。

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

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

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

RetrieveMetadataChanges メッセージに ClientVersionStamp と DeletedMetadataFilters の両方のパラメーターを含めると、RetrieveMetadataChangesResponse.DeletedMetadata プロパティに削除された品目 に関するデータが含まれます。 このプロパティは Keys と Values のセットを含む DeletedMetadataCollection です。 キーは 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#)
クエリ スキーマ定義

注意

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

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