Fiwareを使って都市OSを動かしてみよう

Munu


データ仕様の現状と課題
スマートシティの標準規格(案)
データモデルのユースケース
ツール


Column
Link
用語集

Coppell

Technologies

3. Entityの作成



3.1.標準形式のEntityの作成
2022-12-13/2023-11-11
　Entityを表現する規約は、「スマートシティの標準規定(案)」の第8章を参照してください。Entityの形式(データモデル)の標準化されているものは、FIWAREの場合はSmart Data ModelとしてGitHub やSmart Data Modelsのホームページ に公開されています。GitHubのSmart Data Modelsプロジェクトは、Fiware Foundationだけでなく、IUDX 、TM Forum、OASC 、およびその他の協力者が共同で運営しています。Smart Data ModelsはNGSI-V2とNGSI-LDの二種類があり、NGSI-LDが最新ですが、日本ではV2がまだ主流であるため、本書ではV2を中心に話を進めます。　NGSI v2のEntityの情報モデルは下図のように三層構造になっています。



つまり、Entityには複数のAttribute (属性)を付加する事ができ、Attributeには複数のMetadataを付加する事ができます。
この三階層の意味は次の通りです。Entityは「モノ」や「コト」に対応すると説明しました。例えば、Entityを人のデータだとすると、人には年齢、身長、体重、性別の様な属性があります。この属性がAttributeです。体重というAttributeが「60kg」だとすると、その体重はいつ計測したのか、どんな機器で測定したのかを知りたい場合があります。これが、Attributeに対するMetadataです。たとえば、体重のAttributeには計測日時というMetadataがあるという感じになります。
Attributeが無いEntityはあり得ませんが、Metadataはあっても無くても構いません。尚、Attributeの中には座標や住所の様に値に構造や数列を持つものがあります。住所では、住所というAttributeが国・都道府県・市区町村・町字以下という構造をもった値を持っているイメージです。一見、階層構造になっている様にも感じますが、住所の場合は値が階層構造になっている訳ではなく、Attributeが構造を持っているだけです。従って、値は最大でEntityから3階層という考え方になります。

まずは、サンプルとしてStoreのEntityを考えます。今回は簡単のためにMetadataが無いケースを考えます。
リアルな店の属性情報は以下とします。
属性 値
店名 セブンイレブン呉市吉浦店
住所 〒737-0843 広島県呉市吉浦潭鼓町１-１
営業時間 24時間営業
URL https://www.sej.co.jp/
電話番号 +81823311458
場所 (座標) 北緯34.256781,東経132.5304138

GitHubでStoreの形式を見ると、登録可能なプロパティは以下となっています (大半省略)。因みに、Storeは、Smart Data Modelsの中のSmartCitiesの中のdataModel.PointOfInterestの中に公開されています。一見しても良く分かりませんが、コロンの前がAttribute名で、コロンの後ろがその説明です。Enumとは、Enummerationの略で、日本語では列挙型項目とか、列挙型メンバと言います。プルダウンメニューの様にあらかじめ決められた選択肢から選ぶ形式の項目です。一番下に、Required propertiesと言う業がありますが、これは必須項目を指しています。


 address: The mailing address
category: Category of the store. Enum:'AutoPartsStore,
BikeStore,BookStore,ClothingStore,ComputerStore,
ConvenienceStore,DepartmentStore,ElectronicsStore,Florist,
FurnitureStore,GardenStore,GroceryStore,HardwareStore,
HobbyShop,HomeGoodsStore,JewelryStore,LiquorStore,
MensClothingStore,MobilePhoneStore,MovieRentalStore,
MusicStore,OfficeEquipmentStore,OutletStore,PawnShop,PetStore,
ShoeStore,SportingGoodsStore,TireShop,ToyStore,WholesaleStore'
description: A description of this item
email: The email address of this store.
id: Unique identifier of the entity
location: Geojson reference to the item. It can be Point,
LineString, Polygon, MultiPoint, MultiLineString or
MultiPolygon
name: The name of this item.
openingHoursSpecification: A structured value providing
information about the opening hours of a place or a certain
service inside a place
telephone: The telephone number of this store.
type: NGSI Entity type. It has to be Store
Required properties  escription, id, name, type

それを見ると、登録が必須となっている値は、description, id, name, typeです。そこで、足りない属性情報としてidとtypeとdescriptionを追加しましょう。typeは"Store"です。
属性 Property 値
ID id ??
type type type
店名 name セブンイレブン呉市吉浦店
住所 address 〒737-0843 広島県呉市吉浦潭鼓町１?１
営業時間 openingHoursSpecification 24時間営業
URL url https://www.sej.co.jp/
電話番号 telephone +81823311458
場所 (座標) location 北緯34.256781,東経132.5304138

category "ConvenienceStore"

description ??

idとdescriptionが判らないので、さらに「スマートシティの標準規定(案)」の第8章を確認します。そうすると、使える文字は以下でした。


 半角英数字, "-", ".", "~","_"

日本語は使えないことがわかります。
また、idの形式は以下であることが分かります。因みに、この形式は、NGSI-LDというNGSI V2の後継規格であるNGSI-LDとしてESTIの標準規格になっています 。今回はNGSI v2ですが、後継であるNGSI-LDのパターンに合わせておくことがFiwareの開発元であるFiware Foundationの推奨です。


 urn:ngsi-ld:<Entity type>:<entity-id>

ここでは仮にurnとして"urn:ngsi-ld:Store:002"としておきましょう。Descriptionは適当に" 呉市吉浦の国道31号線沿いのコンビニエンスストア"とでもしておきましょう。
次に、Addressの形式が"PostalAddress"となっていますので、これを調べましょう。Storeの説明に"model.yami"というのがありますので、これを見ます 。yamiというのは、jsonっぽい形式で説明を書いた文書の事です。そうすると、住所はいくつかの項目に分かれていることがわかります。日本の住所のどの部分までをどこに入れるのかについては(当然ながら)書かれていませんが、RegionはCountryにある地域なので都道府県、LocalityはRegionある地域なので市区町村、streetAddressはLocalityにある住所なので、それ以下の住所としましょう。尚、後で記載しますが、自治体の住所表記の番地以下は半角数字なので、そのようにします。郵便番号も自治体にあわせて数字7桁にします。座標はGetPropertyとありますが、説明を読むと、点(Point)か線(Line)か面(Polygon)で表すとなっていますが、例を見ると点なので、ここでは点にしましょう。座標の表し方は二つ以上の数値の列でGeoJsonの形式となっています。GeoJsonは[東経, 北緯]を10進数で表記したもので、西経と南緯はマイナスの10進数で表現します。
この様に各値をpropertyの形式を確認しつつ編集したものが以下となります。
Property データタイプ 値
id Text "urn:ngsi-ld:Store:002"
type Text "Store"
name Text "セブンイレブン呉市吉浦店"
address PostalAddress streetAddress "吉浦潭鼓町１-１"
addressLocality "呉市"
addressRegion "広島県"
addressCountry "日本"
postalCode 7370843
openingHoursSpecification StructuredValue Opens "00:00:00"
Closes "23:59:00"
url Text https://www.sej.co.jp/
telephone Text +81823311458
location geo:json Point [132.530413, 34.25678]
category Text "ConvenienceStore"
description Text "呉市吉浦の国道31号線沿いのコンビニエンスストア"

因みに、locationの形式は、Smart Data Models"の例を見ると"GeoProperty"となっていますが、そうすると(なぜか)緯度や経度を使った距離計算ができないので、明示的に"geo:json"としておきます。頭文字は大文字の約束のはずですが、ここだけは特別と思ってください。さて、これらの表の中身をNGSI V2に準拠したjson形式に変換します。json形式については「スマートシティの標準規定」の第7章をご覧ください。


 {
   "id": "urn:ngsi-ld:Store:002",
   "type": "Store",
   "name": {
       "type": "Text",
       "value": "セブンイレブン呉市吉浦店"
   },
   "address": {
       "type": "PostalAddress",
       "value": {
           "streetAddress": "吉浦潭鼓町1-1",
           "addressLocality": "呉市",
           "addressRegion": "広島県",
           "postalCode": "7370843"
       }
   },
   "openingHoursSpecification": {
       "type": "StructuredValue",
       "value": {
           "opens": "00:00:00",
           "closes": "23:59:00"
       }
   },
   "location": {
       "type": "geo:json",
       "value": {
           "type": "Point",
           "coordinates": [
               132.5304138,
               34.2567817
           ]
       }
   },
   "telephone": {
       "type": "Text",
       "value": "+81823311458"
   },
   "category": {
       "type": "Text",
       "value": "ConvenienceStore"
   },
   "description": {
       "type": "Text",
       "value": "呉市吉浦の国道31号線沿いのコンビニエンスストア"
   }
}

これをpostStore002.json というテキストファイルに格納してPostします。後で説明しますが、Fiwareでは、"v2"というフォルダ配下"entities"というフォルダがあり、その配下に全てのEntityが格納されている構造になっています。このため、" http://localhost:1026/v2/entities"というフォルダに対してPOSTすることでEntityが格納されます。


 curl -iX POST -H "Content-Type: application/json" -d @d:\postStore002.json http://localhost:1026/v2/entities

以下の様な応答があれば、正常です。
PS C:\Users\owner> curl -iX POST -H "Content-Type: application/json" -d @d:\postStore002.json http://localhost:1026/v2/entities
HTTP/1.1 201 Created
Connection: Keep-Alive
Content-Length: 0
Location: /v2/entities/urn:ngsi-ld:Store:002?type=Store
Fiware-Correlator: 6b81bf92-baea-11ec-8943-0242ac120003
Date: Wed, 13 Apr 2022 05:27:33 GMT

PS C:\Users\owner>

試しに読み出してみましょう。


 curl -X GET http://localhost:1026/v2/entities/urn:ngsi-ld:Store:002

"entities"フォルダ配下の"urn:ngsi-ld:Store:002"をGETするコマンドです。そうすると、以下の様にEntityが返却されます。
PS C:\Users\owner> curl -X GET http://localhost:1026/v2/entities/urn:ngsi-ld:Store:002
{"id":"urn:ngsi-ld:Store:002","type":"Store","address":{"type":"PostalAddress","value":{"streetAddress":"吉浦潭鼓町1-1","addressLocality":"呉市","addressRegion":"広島県","postalCode":"7370843"},"metadata":{}},"category":{"type":"Text","value":"ConvenienceStore","metadata":{}},"description":{"type":"Text","value":"呉市吉浦の国道31号線沿いのコンビニエンススト ア","metadata":{}},"location":{"type":"geo:json","value":{"type":"Point","coordinates":[132.5304138,34.2567817]},"metadata":{}},"name":{"type":"Text","value":"セブンイレブン呉市吉浦店","metadata":{}},"openingHoursSpecification":{"type":"StructuredValue","value":{"opens":"00:00:00","closes":"23:59:00"},"metadata":{}},"telephone":{"type":"Text","value":"+81823311458","metadata":{}}}
PS C:\Users\owner>

ちゃんと格納されていますね。