履歴の集約された時系列コンテキスト情報の取得

STH コンポーネントは HTTP REST API を公開して、外部クライアントが格納された履歴の集約された時系列コンテキスト情報を照会できるようにします。

GET リクエスト を使用してこの情報を照会する一般的な URL は次のとおりです :

http://<sth-host>:<sth-port>/STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>?aggrMethod=sum&aggrPeriod=second&dateFrom=2016-02101T00:00:00.000Z&dateTo=2016-01-01T23:59:59.999Z

前の URL では、<> の間にいくつかのテンプレートを使用していますが、これは対応する実際の値で置き換えてください。

また、2016-02101T00:00:00.000Z から 2016-01-01T23:59:59.999Z にかけて2番目の解像度で、以前のリクエストsumの中で 集約されたコンテキスト情報がどのようにリクエストされているかに注目してください。

集約された時系列コンテキスト情報のリクエストには、次のクエリパラメータを使用できます :

  • aggrMethod : 集約メソッド。STH コンポーネントは、次の集約メソッドをサポートしています : 数値属性値および文字列型の属性値 occur に対して、max (最大値)、min (最小値)、sum (すべてのサンプルの合計)、および sum2 (すべてのサンプルの2乗値の合計) です。これらの集約された方法によって提供された情報をサンプル数と組み合わせることで、平均値、分散、標準偏差などの確率的な値を計算することができます。必須パラメータです。
  • aggrPeriod : 集約期間または解像度。固定解像度では、起点時刻形式と可能なオフセットが決まります。必須パラメータです。
  • dateFrom : 集計された時系列情報が必要な開始日時。オプション・パラメータです。
  • dateTo : 集計された時系列情報が必要となる最終日時。オプション・パラメータです。

前のもの(数値属性値のためのもの)のような要求に STH コンポーネントによって提供されるレスポンスの例は、次のようになります :

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "attrName",
                        "values": [
                            {
                                "_id": {
                                    "origin": "2016-01-01T02:46:00.000Z",
                                    "resolution": "second"
                                },
                                "points": [
                                    {
                                        "offset": 13,
                                        "samples": 1,
                                        "sum": 34.59
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "id": "entityId",
                "isPattern": false
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

前の例の応答では、second の解像度の集約時系列コンテキスト情報が返されます。この情報は、2016年1月1日2時46分を起点としています。また、13秒のデータが含まれています。これにはサンプルがあり、その合計(およびそのサンプルの値)は 34.59 です。

一方、属性値が文字列型の場合、次のような(occuer として aggrMethodをもつ)クエリを STH コンポーネントに送信できます。<> の間のテンプレートを適切に置き換えてください :

http://<sth-host>:<sth-port>/STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attrName>?aggrMethod=occur&aggrPeriod=second&dateFrom=2016-01-22T00:00:00.000Z&dateTo=2016-01-22T23:59:59.999Z

An example response for the previous request could be:

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "attrName",
                        "values": [
                            {
                                "_id": {
                                    "origin": "2016-01-22T02:46:00.000Z",
                                    "resolution": "second"
                                },
                                "points": [
                                    {
                                        "offset": 35,
                                        "samples": 34,
                                        "occur": {
                                            "string01": 7,
                                            "string02": 4,
                                            "string03": 5,
                                            "string04": 6,
                                            "string05": 12
                                        }
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "id": "entityId",
                "isPattern": false
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}
有効なクエリが作成されてもデータが返されない場合(たとえば、指定された時間枠に集約されたデータがないなど)、有効なクエリであるため、空の values プロパティ配列を含む、コード 200 のレスポンスが返されます。

もう一つの非常に重要な側面は、生成された集約データの文字列がプロパティとして使用されるため、MongoDB によって課せられたこのような制限が尊重されなければならないことです。より具体的には : "場合によっては、ユーザ提供のキーを使用してBSONオブジェクトを構築することもできます。これらの状況では、キーは予約された $ と . 文字を置換する必要があります。任意の文字で十分ですが、Unicode 全角相当語を使用することを検討してください : U+FF04 (すなわち、“$”)および U+FF0E (すなわち、“.”)

以前の MongoDB 制限により、集約されたコンテキスト情報が生成されている属性に格納されたテキスト値が $ また . 文字を含んでいる場合、それらは Javascript の Unicode 全角相当語と置換され、これは : $ の代わりに \uFF04、および.の代わりに \uFF0E です。