dataPARC.Store SDK

概要

dataPARC Historian SDKは、サードパーティ・アプリケーションの開発者に、dataPARC Historianに接続し、データの読み取り/書き込み/操作を行う機能を提供します。

特定のデータソース接続(OPCサーバー、フラットファイルなど)は、インターフェイスで表されます。インターフェース・セットは、単一の dataPARC ソース内で使用するために複数のインターフェースを組み合わせることができます。ソースのグループは、通常、物理的なプラントの場所を表し、インターフェイスグループと呼ばれます。接続は、個々のインターフェイス、インターフェイス セット、およびインターフェイス グループに行うことができます。

各インターフェイス内のタグは、構成された各ヒストリアンタグのすべての属性を公開します。dataPARC Historian SDKでは、データを取得時に読み取るためのタグをサブスクリプションできます。

データポイントは、各タグの個々のデータレコードを表します。値に加えて、タイムスタンプと品質はデータポイント内で使用できます。これらは、個別に、時間範囲にわたって読み取るか、ストリーミングすることができます。

以下のドキュメントでは、dataPARC Historian SDKの使用方法とコード例について説明します。

はじめ

前提 条件

サードパーティ アプリケーションには、Visual Studio に dataPARC Historian SDK Nuget パッケージ (dataPARC.Store.Public.SDK) を追加する必要があります。追加されると、この Nuget ソースはパブリック フィードにある場合は最新の状態に保たれます。 または、開発システム上でローカルにホストすることもできます。

Historian SDK は、.NET 4.8、.NET Standard 2.0、および .NET 8.0 との互換性を考慮して設計されています。

dataPARC Historian 側では、追加のものは必要ありません。

詳細情報:

dataPARC Historian GitHub コードリファレンス

資格

クライアント

ヒストリアン関数を呼び出すためのメソッドを持つクライアントを作成します。クライアント クラスには、ReadClient、WriteClient、ConfigurationClient、PublishingClient の 4 つがあります。

各クライアントは個別に作成することも、ClientFactory を使用して作成することもできます。 ClientFactory を使用して複数のクライアントを作成すると、クライアントを遅延作成するプロパティとして、使用可能なクライアントにアクセスできます。クライアント ファクトリがクライアントを所有し、それ自体が使用コンテキストで使用されているため、これらのクライアントを参照するときにコンテキストを使用する必要はありません。ClientFactoryのクライアントプロパティへの後続の参照は、同じインスタンスを返します。

フェールオーバー

読み取り呼び出しは、プライマリ サーバーが使用できなくなった場合のバックアップ サーバーへのフェールオーバーをサポートします。ホスト名とポートを参照するサーバーの配列を作成し、ReadClient を作成するときにこれを "Server" 引数として使用します。 プライマリ・サーバーは、サーバーの配列で指定された最初のサーバーです。読み取り呼び出しには、読み取り構成、データ、および発行が含まれます。読み取り呼び出しは、バックアップ サーバーで自動的に再試行されます。バックアップ サーバーに切り替えると、クライアントは約 3 分間待ってからプライマリ サーバーへの再接続を試みます。必要な数のバックアップ サーバーを追加できます。

認証

クライアントを作成するときは、サーバーの証明書の検証に使用される ICertificateValidation を渡す必要があります。これは、ICertificateValidation を実装している限り、カスタム検証ツールにすることができます。

クライアントが持つ他の認証関連パラメーターは、トークン プロバイダーからアクセス トークンを取得するために使用されるオプションの IAuthProvider です。これは、IAuthProvider を実装している限り、カスタム プロバイダーにすることもできます。ヒストリアンはセキュリティをオフにしている可能性があるため、これはオプションですが、セキュリティで保護されたヒストリアンと話す必要があります。

コネ

読み取り、書き込み、および構成クライアントには、ヒストリアン サーバーへの接続を試みることで ping のように動作する CheckConnectionAsync メソッドがあります。

代わりに、発行クライアントには、タグの発行が開始されたかどうかを示す Publishing プロパティがあります。タグの発行などの実行時間の長い操作の場合、ネットワーク状態の変化により接続が一時的になる可能性がありますが、発行クライアントは回復して動作を続行します。

歴史家の道

ヒストリアンパスは、ヒストリアンがデータを格納する場所へのパス、つまりディレクトリパス、ネットワークパスです。等。これらは HistorianPathConfig オブジェクトとして保存されます。これらは、個々の ConfigurationClient に適用できます。 

構成を保存すると、保存された構成は SaveResult<T> にラップされて返されます。これにより、保存操作、保存された値などのステータスが表示されます。構成を読み取ると、構成は GetResult<T> にラップされて返されます。これにより、読み取り操作のステータス、成功した場合の読み取り値などが表示されます。

インターフェイス グループ

インターフェイス グループは、ヒストリアンの最上位エンティティです。すべてのインターフェイス、インターフェイス セット、およびタグは、インターフェイス グループに属している必要があります。

複数のインターフェイス グループを保存でき、1 つのグループまたはすべてのグループの読み取りをサポートします。

インターフェイス

インターフェイスはタグのグループであり、多くの場合、特定のデータ ソースに関連付けられています。すべてのタグは 1 つのインターフェイスに属している必要があります。各インターフェイスは、インターフェイス グループに属している必要があります。

複数のインターフェイスを保存でき、単一のインターフェイス、グループ内のすべてのインターフェイス、またはすべてのグループ内のすべてのインターフェイスの読み取りをサポートします。

インタフェース・セット

インターフェイス セットは、同じインターフェイス グループ内のインターフェイスのグループです。各インターフェイス セットは、インターフェイス グループに属している必要があります。

同じインターフェイス グループ内のインターフェイスをインターフェイス セットに追加できます。1 つのインターフェイス グループに複数のインターフェイス セットを含めることができますが、各インターフェイスは 1 つのインターフェイス セットにのみ属できます。

複数のインターフェイス セットを保存でき、単一のインターフェイス セット、グループ内のすべてのインターフェイス セット、またはすべてのグループ内のすべてのインターフェイス セットの読み取りをサポートします。

タグ

タグとは、センサー、計算などのデータストリームを持つもののことです。Client オブジェクトには、タグを保存するためのメソッドが含まれています。

複数のタグを保存でき、単一のタグ、インターフェイス内のすべてのタグ、またはインターフェイス セット内のすべてのタグの読み取りをサポートします。 タグは、完全修飾タグ名または GUID でクエリできます。

データの書き込み

Client オブジェクトは、WriteDataPointAsync メソッドまたは WriteDataPointsAsync メソッドを使用して、もう 1 つのタグにデータを書き込むことをサポートします。

異なる型の複数のデータ ポイントを TagDataPointSet オブジェクトに組み合わせて、1 つのメソッド (WriteDataPointSetAsync) で複数の型のデータを書き込むことを容易にすることができます。

現在の値の読み取り

ReadClient オブジェクトの ReadCurrentValueAsync メソッドを使用すると、1 つのタグの現在の値を取得できます。 タグ名または GUID を指定するには、ReadCurrentValueParameters オブジェクトが必要です。

ReadCurrentValueParameters オブジェクトの配列を ReadCurrentValuesAsync メソッドに渡すことで、複数のタグ値を読み取ることができます。

特定のタイムスタンプの読み取り

ReadClient オブジェクトの ReadAtTimeAsync メソッドを使用すると、履歴の特定の時点から 1 つのタグの値を取得できます。 タグ名または GUID とタイムスタンプを指定するには、ReadAtTimeParameters オブジェクトが必要です。

このメソッドは、1 つのタグの複数のタイムスタンプの読み取りをサポートします。データポイントを含む配列が返されます。

生データの読み取り

ReadClient オブジェクトの ReadRawAsync メソッドを使用すると、一定期間の 1 つのタグの値を取得できます。タグ名または GUID、開始タイムスタンプ、終了タイムスタンプを指定するには、ReadRawParameters オブジェクトが必要です。データポイントの配列が返されます。

この ReadRawBulkAsync メソッドは、一定期間にわたる複数のタグ値の読み取りをサポートします。

一定期間のデータ ポイントの数は、ReadRawCountAsync メソッドを使用して読み取ることができます。

DirectionalReadRawAsync メソッドを使用すると、1 つのタグの開始タイムスタンプから指定した数のデータポイントを順方向または逆方向に読み取ることができます。 タグ名または GUID、開始タイムスタンプ、方向、およびデータ ポイントの数を指定するには、DirectionalReadRawParameters オブジェクトが必要です。データポイントの配列が返されます。

生データは、StreamRawAsync メソッドを使用してストリーミングできます。 StreamRawParameters オブジェクトを使用して、タグ名または GUID、開始タイムスタンプ、終了タイムスタンプを指定する必要があります。 ストリーミングは、返すことができるデータを読み込むことと同じですが、サーバーは読み込みを開始するとすぐにストリームにデータを送信するため、データの返しが速くなります。また、クライアントのメモリ制約に関する柔軟性も向上します。

DirectionalStreamRawAsync メソッドを使用すると、1 つのタグの開始タイムスタンプから指定した数のデータポイントを順方向または逆方向に読み取ることができます。 タグ名または GUID、開始タイムスタンプ、方向、およびデータ ポイントの数を指定するには、DirectionalStreamRawParameters オブジェクトが必要です。データポイントの配列が返されます。

処理済みデータの読み込み

ReadClient オブジェクトには、集計などの処理されたデータを読み取るためのメソッドも含まれています。

ReadProcessedAsync メソッドを使用すると、1 つのタグの処理された値を一定期間から取得できます。タグ名または GUID、開始タイムスタンプ、終了タイムスタンプ、集計構成を指定するには、ReadProcessParameters オブジェクトが必要です。 集計構成は、タイプと処理間隔を含む AggregateConfig オブジェクトを使用して指定されます。データポイントの配列が返されます。

この ReadProcessedBulkAsync メソッドは、処理された複数のタグ値の読み取りをサポートします。

一定期間に処理されたデータ ポイントの数は、ReadProcessedCountAsync メソッドを使用して読み取ることができます。

メソッドは、生データと同様に、処理済みデータの指向性読み取りや処理済みデータのストリーミングにも使用できます(前述)。

構成による処理済みデータの読み取り

集計構成は、名前を文字列として保存し、ReadClient の ReadProcessedByConfigAsync メソッドに渡すことができます。 上記の「処理済みデータの読み取り」と同じ機能はすべて使用できますが、メソッドの名前に「Async」の前に「ByConfig」が含まれています。

配列データの読み取り

すべての読み取り呼び出しでは、配列タグをスライスするための 2 つの追加パラメーター arrayStartIndex と arrayLength がサポートされています。返されるデータポイントは、シェイプ [arrayStartIndex..arrayLength] を配列データポイントから取得します。

読み取り応答からのデータポイントの使用

すべての読み取り呼び出しは、DataPoints または IDataPoint の 2 種類のうちの 1 つでデータポイントを返します

DataPoints:複数のタイプのデータポイントの1つの配列、つまりDataPointSingle[]、DataPointByte[]などの1つ。

IDataPoint: データポイント型の 1 つ、つまり DataPointSingle、DataPointByte などの 1 つ。

返されるデータポイントのタイプがわかっている場合は、プロパティで取得できます。これはパフォーマンスの点で最良のケースです。

任意のタイプのデータポイントに対して動作する関数など、型がわからない場合は、すべての型の関数を渡すことができます。これは、DataPointsでCountプロパティが実装される方法です。また、すべてのタイプにアクションを渡すこともできます。

最後に、各データポイント型は IDataPoint を実装するため、DataPoints インスタンスに含まれるすべてのデータポイントから IDataPoint の配列を取得できます。これは、含まれるすべてのデータポイントが IDataPoint として参照されるとボックス化されるため、DataPoint を操作する場合には最も理想的ではありません。

タグの公開

PublishingClient オブジェクトを使用すると、最新のデータ ポイントを受信するためのタグのサブスクライブが容易になります。 StartPublishingAsync メソッドは 1 つのタグをサブスクライブし、タグ名または GUID、および時間間隔を指定するには StartTagPublishingParameters オブジェクトが必要です。

公開間隔を変更したり、公開を停止したりする方法も使用できます。

OnReconnected イベントは、クライアントとサーバーの接続ステータスの変化に基づいてアクションを実行するために利用でき、OnPublish イベントは、クライアントがサーバーから新しく公開されたデータポイントを受信したときにアクションを実行するために利用できます。