Coppell Technologies

スマートシティの標準規格

Menu

Coppell Technologies (Top)
Fiwareで都市OSを動かしてみよう
NGSI-LDにも挑戦
データ仕様の現状と課題

スマートシティの標準規格

データモデルのユースケース

Column
Link集
用語集

Coppell

Technologies

 4. 呼出し方式 5.3節


5.3 暗号化
2022年7月25日
 既に記載してきたように、httpプロトコルは、文字列などで情報を送ります。このため、データの中身を盗み見る事が可能です。そこで、スマートシティなどでは暗号化の仕組みを取り入れる必要があり、"https"という方式の採用が必要です。
 httpsはhttp Secureの事ですが、http over SSL/TLSまたはhttp over TLSとも言います。通信経路の暗号化の方式にSSLと言うものがあります。この方式は進化し、バージョン3の次のバージョンでは名前が変わりTLSとなりました。つまり、SSLもTLSも同じもので、バージョンが違うだけです。SSLと呼ばれた古いバージョンは今となってはセキュリティーが弱く、廃止された規格です。NGSI-LDでは、TLSの1.2を指定しています。
 httpsとは、このTLSによりセキュアな暗号化された通信経路を作ってから、その中をhttpプロトコルで通信する方式の事です。つまり、httpの中身については、httpsもhttpも変わりはありません。

(愚痴)本ホームページはhttp
 httpsにすべきと記載しながら、本ホームページはhttpです。これは、Biglobeの個人ホームページサービスがhttpsをサポートしていないためです。今更、他のプロバイダに移行するのも面倒ですし。。。


5.4 リソースURI (NGSI V2)
2022年9月19日
 WebAPiは、ターゲットに対してhttp動詞を実行する形をとると書きましたが、このターゲットをNGS v2の規格上はリソースURIと呼びます。リソースURIは以下の構造を持ちます。
 <apiRoot>/v2/<それ以下の構造>
apiRootは、実装により変わります。例えば本サイトの「Fiwareを使って都市OSを動かしてみよう」では、何も説明していませんがapiRootは"http://localhost:1026"でした。
NGSI v2の"v2/<それ以下の構造>"は以下の通りとなっています。
エンドポイント http動詞 説明 利用可能なパラメータ
v2   GET API リソースを取得します。具体的には以下のレスポンスを返します。
{
 "entities_url": "/v2/entities",
 "types_url": "/v2/types",
 "subscriptions_url": "/v2/subscriptions",
 "registrations_url": "/v2/registrations"
}
なし
entities
GET 全てのEntityを対象に読み出します id, type, idPattern, typePattern, q, mq, georel, geometrycoords, limit, offset, attrs, metadata, orderBy, options (count, keyValues, values, unique)

POST 新たなEntityを追加します。格納した位置はLocationヘッダに返却されます。 options (keyValues , upsert)
<id>
GET 特定のEntityを指定して読み出します entityId, type, attrs, options (keyValues, values, unique).

POST 特定のEntityを指定してAttributeを追加、または更新します type, options (append , keyValues)

DELETE 特定のEntityを削除します type
attrs
GET 特定のEntityを指定してAttributeの一覧を読み出します type, attrs, metadata, options (keyValues, values, unique)

POST 特定のEntityを指定してAttributeを追加する、または更新します。Attributeの指定はBODYのJSON文内で行います type, options (append , keyValues, overrideMetadata)

PATCH 特定のEntityのAttributeを更新します。Attributeの指定はBODYのJSON文内で行います options (keyValues)

PUT 特定のEntityを指定して、そのEntityの全てのAttributeを書き換えます type, options (keyValues)
<Attribute>
DELETE 特定のEntityの特定のAttributeを削除します type

GET 特定のEntityの特定のAttributeのValueを読みだします。返却値はJSONオブジェクトです type

PUT 特定のEntityの特定のAttributeのValueを更新します type, options (overrideMetadata)
value GET 特定のEntityの特定のAttributeのValueを読みだします。リクエストヘッダのAcceptの指定で"text/plain"の場合は返却値は文字列で値だけ返却します。application/jsonの場合はAttribute名を含むJSONオブジェクトです type
PUT 特定のEntityの特定のAttributeのValueを書き換えます。リクエストヘッダのContent-Typeの指定で"text/plain"の場合は新しい値はテキストで与えます。文字列の場合はダブルクオートで囲みます。application/jsonの場合はAttribute名を含むJSONオブジェクトで与えます type
types
GET 指定したtypeのEntityの一覧の取得
options=valuesを指定すると、Entity typeの一覧だけが取得でき、それ以外の場合はEntityのAttributeの一覧も取得できます。Attributeの一覧の形式は次項の通りです。
limit, offset, options (count, values)
<EntityType> GET 特定EntityのAttributeの一覧がJSON形式で返却されます。また、そのEntityTypeのEntityの数も返却します。例えば、「Fiwareを使って都市OSを動かしてみよう」のStoreをしているすると、以下の様な返却値があります。
{
   "attrs": {
       "address": {
           "types": [
               "PostalAddress"
           ]
       },
       "category": {
           "types": [
               "Text"
           ]
       },
       "description": {
           "types": [
               "Text"
           ]
       },
       "location": {
           "types": [
               "geo:json"
           ]
       },
       "name": {
           "types": [
               "Text"
           ]
       },
       "openingHoursSpecification": {
           "types": [
               "StructuredValue"
           ]
       },
       "telephone": {
           "types": [
               "Text"
           ]
       }
   },
   "count": 3
}
なし
subscriptions
GET サブスクリプションを一括して返却します。 limit, offset, options (count)

POST サブスクリプションを作成します。 なし
<subscriptionId> GET 特定のサブスクリプションを指定して、返却します。 なし
PATCH 特定のサブスクリプションを指定して、サブスクリプションに含まれるフィールド(expiresなど)を更新します。 なし
DELETE 特定のサブスクリプションを指定して削除します。 なし
registrations
GET レジストレーションを一括して返却します。 limit, offset, options (count)

POST レジストレーションを作成します。 なし
<registrationId> GET 特定のレジストレーションを指定して、返却します。 なし
PATCH 特定のレジストレーションを指定して、サブスクリプションに含まれるフィールド(expiresなど)を更新します。 なし
DELETE 特定のレジストレーションを指定して削除します。 なし
op update POST 更新をバッチ処理します。 options (keyValues)
query POST 検索処理をバッチ処理します。 limit, offset, options (count, keyValues, values, unique)
notify POST レジストレーションの初期値を与えます options (keyValues)
version GET バージョン情報を読み出します なし


[参考] リソースURI (NGSI-LD)
2022年7月25日

 NGSO v2と同様に「ターゲット」をNGSI-LDの規格上はリソースURIと呼びます。リソースURIは以下の構造を持ちます。
 <apiRoot>/ngsi-ld/v1/<それ以下の構造>
apiRootは、実装により変わります。例えば本サイトの「Fiwareを使って都市OSを動かしてみよう」では、何も説明していませんがapiRootは"http://localhost:1026"でした。
NGSI-LDの<それ以下の構造>は以下の通りとなっています。

entities  
/<emtityID>  
/attrs  
/<attrID>
subscriptions  
/<subscriptionID>
types  
/<typeID>
attributes  
/<attrID>
csourceResistrations  
/<resistrationID>
csourceSubscriptions  
/<subscriptionID>
entityOperaioons  
/create
/upsert
/upddate
/delete
/query
temporal  
/entities  
/<emtityID>  
/attrs  
/<attrID>
/<instancsID>
/entityOperaioons  
/query
jsonldContext  
/<contextID>

各エンドポイントに対するオペレーションは以下の通りです。
Resource Name Resource URI HTTPMethod Meaning
Entity List /entities/ POST Entity creation
GET Query entities
Entity by id /entities/{entityId} GET Entity retrieval by id
DELETE Entity deletion by id
Entity Attribute List /entities/{entityId}/attrs/ POST Append entity Attributes
PATCH Update entity Attributes
Attribute by id /entities/{entityId}/attrs/{attrId} PATCH Attribute partial update
DELETE Attribute delete
Subscriptions List /subscriptions/ POST Subscription creation
GET Subscription list retrieval
Subscription by Id /subscriptions/{subscriptionId} GET Subscription retrieval by id
PATCH Subscription update by id
DELETE Subscription deletion by id
Entity Types /types/ GET Available entity types
Entity Type /types/{type} GET Details about available entity type
Attributes /attributes/ GET Available attributes
Attribute /attributes/{attrId} GET Details about available attribute
Context source registration list /csourceRegistrations/ POST Csource registration creation
GET Discover Csource registrations
Context source registration by Id /csourceRegistrations/{registrationId} GET Csource registration retrieval by id
PATCH Csource registration update by id
DELETE Csource registration deletion by id
Context source registration subscription list /csourceSubscriptions/ POST Csource registration subscription
GET Csource registration subscription list retrieval
Context source registration subscription by Id /csourceSubscriptions/{subscriptionId} GET Csource registration subscription retrieval by id
PATCH Csource registration subscription update by id
DELETE Csource registration subscription deletion by id
Entity Operations. Create /entityOperations/create POST Batch Entity creation
Entity Operations. Upsert /entityOperations/upsert POST Batch Entity create or update (upsert)
Entity Operations. Update /entityOperations/update POST Batch Entity update
Entity Operations. Delete /entityOperations/delete POST Batch Entity deletion
Entity Operations. Query /entityOperations/query POST Entity Query based on POST
Entity Temporal Evolution /temporal/entities/ POST Temporal Representation of Entity creation
GET Query temporal evolution of Entities
Temporal Representation of Entity by id /temporal/entities/{entityId} GET Temporal Representation of Entity retrieval by id
DELETE Temporal Representation of Entity deletion by id
Temporal Representation of Entity Attribute List /temporal/entities/{entityId}/attrs/ POST Temporal Representation of Entity Attribute instance addition
Temporal Representation of Entity Attribute by id /temporal/entities/{entityId}/attrs/{attrId} DELETE Attribute from Temporal Representation of Entity deletion
Temporal Representation of Entity Attribute Instance by id /temporal/entities/{entityId}/attrs/{attrId} /{instanceId} PATCH Attribute Instance update
DELETE Attribute Instance deletion by instance id
Temporal Query Operation /temporal/entityOperations/query POST Temporal Representation of Entity Query based on POST
Add @context /jsonldContexts POST Add a user @context to the internal cache
List @contexts /jsonldContexts GET List all cached @contexts
Serve @context /jsonldContexts/{contextId} GET Serve one specific user @context
Delete and Reload @context     /jsonldContexts/{contextId} DELETE Delete one specific @context from internal cache, possibly reinserting a freshly downloaded copy of it


5.6 パラメータ
2022-09-19/2023-02-10

 URLにパラメータ文字列を追加してパラメータを指定する事も可能です。例えば、"http://aaa.bbb/ccc?ddd=eee&fff=ggg"と書けば、ddd=eeeとfff=gggの二つのパラメータを指定したことになります。尚、curlコマンドの様に、オプションをurl中に書かず、他の方法で指定する機能をもっているツールもあります。

Key Value 説明
attrs __none Attributeを指定しないことを示します。検索すると、idとtypeだけが返却されます
Attribute名 指定したAttributeが返却されます
id Entity-id GET時に指定したidのEntityだけ返却されます
limit 整数 GET時に最大何件のペイロードを返却するかの指定です。既定値は20です。
mq Metadata名==文字列 文字列で指定した値のMetadataを持つEntityを返却する
offset 整数 GET時に最初に返却するペイロードが何件目かをを指定します。既定値はゼロです。このパラメータはLimitとと組み合わせて使用します。例えば、一回目の問い合わせでlimit=10,offset=10と指定すると、11件目から20件目までが返却されます。この様に、少しずつ返却されることを「ページネーション」と呼びます。
options 指定なし Normalized形式であることを示します。
keyValues キーバリュー形式であることを指定します。GET時にはアトリビュートの指定に関わらず、idとtypeも返却します。
values GET時にValueだけを取り出すときに指定します
count レスポンスヘッダFiware-Total-Count に条件に合致するペイロードの総件数が格納されます。返却する件数ではなく、総件数です。
unique 値が蔵返されない点を除いてvalueと同じです。
skipForwarding Registrationの設定を無視して、CPrに対する転送要求を行いません
overrideMetadata Metadataを置き換えます。指定したペイロードに含まれていないMetadataは削除されます
orderBy Attribute名 GET時に返却するペイロードの順番を指定します。指定すると指定したAttributeの値で昇順に並びます。既定値は、作成順の昇順です。つまり、dat4eCreated順です。Attribute名は複数指定する事が可能で、カンマで区切って指定します。降順にしたいときは、Attribute名の前に!(ビックリマーク)を付けます。例えば、A,!Bと書くと、上位キーがAの昇順で、次のキーがBの降順になります。
q Attribute名==文字列 文字列で指定した値のAttributeを持つEntityを返却する
type Entityのタイプ名 GET時に指定したタイプだけを返却します。複数のタイプを指定したい場合は、カンマで区切ります。例えば、type=Store,Refrigeratorなどと書きます。

 これらの説明からわかる様に、パラメータ内にAttribute名、Metadata名、Entity id、Entity typeなどの識別子が記載されます。パラメータ内に"="や"&"などの文字が出現すると、セキュリティー上の問題が発生し得ます。そこで、識別子に使って良い文字から、これらの文字を除外する事がのそましいです。この点については、識別子の定義の項で詳しく記載します。

5.7 URLエンコーディング
2022年9月20日

 前節で説明している様に、オプションはURLの文字列の最後に"http://aaa.bbb/ccc?ddd=eee&fff=ggg"などと書きますが、オプションもURLの一部なので使う事ができない文字があります。例えばダブルクォート(")や日本語などです。それらの文字を書くときには、URLエンコードと呼ばれる回避策があります。URLエンコードでは、1バイトずつ分解して"%"と2ケタの16進表現の3文字の文字列にします。例えば空白の場合は空白をタイプする代わりに"%20"と書きます。以下、変換表です
文字 URLエンコード
空白 (" ") %20
ダブルクオート (""") %22
シャープ ("#") %23
パーセント("%") %25
アンド("&") %26
シングルクオート ("'") %27
括弧("(") %28
括弧閉じ(")") %39
セミコロン(";") %3b
("<") %3c
イコール("=") %3d
(">") %3e
クエスチョンマーク("?") %3f
中括弧("{"} %7b
中括弧(")"} %7d

 アンド、括弧、括弧閉じ、セミコロン、イコール、クエスチョンマークは、URLの仕様上は禁止されていませんが、セキュリティーやパラメータの解釈上問題があるので、どうしても使わざるを得ない場合はURLエンコーディングします。勿論、パラメータの"q=abc==def"のイコールは、イコールという記号として認識して欲しいので、URLエンコードしてはいけません。念のため。
 パーセントはURLエンコードの印ですから、%という文字を送りたい場合は、URLエンコードします。
 尚、curlなどの各種コマンド自身も特殊文字に特別な意味を持たせている場合があります。従って、特殊文字は常にURLエンコーディングしておいた方が良いかもしれません。また、それらのツールが"%"に特別な意味を持たせている場合があります。よくあるのが、URLエンコーディングのマークです。そうなると、空白を表現しようとすると、%20を更にURLエンコーディングする事になるので、%2520と書く事になります。そうなると訳が分かりませんので、多くの場合、その様な文字列はファイル内に記述すると避けられます。勿論、そのコマンドがファイルによる入力を許している場合だけですが。
 日本語(正確にはASCII文字以外)については、必ずURLエンコードします。これは、URLはプロトコル上ASCII文字しかないとして処理するため、エラーを発生させたり、間違った結果となる場合があるからです。対応表は膨大になるのでここには掲載しませんが、色なツールやプログラムから呼び出せるクラスが流通していますので、必要に応じて検索エンジンなどで確認してください。