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

Munu


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


Column
Link
用語集

Coppell

Technologies

 5. NGSI v2のAPI 5.3-5.5節




5.3.Orionのオプション
2022年4月11日
 前節でhttp動詞とパスのお話をしましたが、実はそれだけでは不十分です。例えばすでに出てきたように、表示形式をkeyValues形式にしたいなどの指定が必要な場合があるためです。
Key Value 説明
options 指定なし Normalized形式であることを示します。

keyValues キーバリュー形式であることを指定します。GET時にはアトリビュートの指定に関わらず、idとtypeも返却します。

values GET時にValueだけを取り出すときに指定します

count GET時にidとtypeだけを取り出すときに指定します
type Entityのタイプ名 GET時に指定したタイプだけを返却します
attrs __none Attributeを指定しないことを示す。検索すると、idとtypeだけが返却される

Attribute名 指定したAttributeが返却される
q Attribute名==文字列 文字列で指定した値のAttributeを持つEntityを返却する
mq Metadata名==文字列 文字列で指定した値のMetadataを持つEntityを返却する

 オプションは、いつもお使いのブラウザで指定するように、URLの後ろに"?"を置いて書きます。複数のオプションがある場合は&で結びます。例えば、以下の様になります。

curl -X GET 'http://localhost:1026/v2/entities?type=Store&options=keyValues'

この例では、entitiesにぶら下がるすべてのEntityを対象に、GETというhttp動詞により問い合わせを実行しています。その時に、オプションにTypeはStoreだけを限定し、返却形式はkeyValuesと指定しました。また、"&"はcurlがエラーにするので、url全体をシングルクォートで囲みました。
PS C:\Users\owner> curl -X GET 'http://localhost:1026/v2/entities?type=Store&options=keyValues'
[{"id":"urn:ngsi-ld:Store:001","type":"Store","address":{"streetAddress":"長沼町202-5","addressLocality":"八王子市","addressRegion":"東京都","postalCode":"1920907"},"location":{"type":"Point","coordinates":[139.37158,35.64226]},"name":"ローソン八王子長沼町店"},{"id":"urn:ngsi-ld:Store:002","type":"Store","address":{"streetAddress":"吉浦潭鼓町1-1","addressLocality":"呉市","addressRegion":"広島県","postalCode":"7370843"},"category":"ConvenienceStore","description":"呉市吉浦の国道31号線沿いのコンビニエンスストア","location":{"type":"Point","coordinates":[132.5304138,34.2567817]},"name":"セブンイ レブン呉市吉浦店","openingHoursSpecification":{"opens":"00:00:00","closes":"23:59:00"},"refOffStreetParking":"urn:ngsi-ld:OffStreetParking:002","telephone":"+81823311458"}]
PS C:\Users\owner>

 前記の例ではブラウザと同じように、URLにオプションを指定しましたが、もうひとつURLの後ろに"-d 'オプション文字列'"を付ける方法があります。前記の例を書き直してみましょう。この方法を使うときは、curlのオプションに "-G" をつけておきます。

curl -G -X GET 'http://localhost:1026/v2/entities' -d 'type=Store' -d 'options=keyValues'
PS C:\Users\owner> curl -G -X GET 'http://localhost:1026/v2/entities' -d 'type=Store' -d 'options=keyValues'
[{"id":"urn:ngsi-ld:Store:001","type":"Store","address":{"streetAddress":"長沼町202-5","addressLocality":"八王子市","addressRegion":"東京都","postalCode":"1920907"},"location":{"type":"Point","coordinates":[139.37158,35.64226]},"name":"ローソン八王子長沼町店"},{"id":"urn:ngsi-ld:Store:002","type":"Store","address":{"streetAddress":"吉浦潭鼓町1-1","addressLocality":"呉市","addressRegion":"広島県","postalCode":"7370843"},"category":"ConvenienceStore","description":"呉市吉浦の国道31号線沿いのコンビニエンスストア","location":{"type":"Point","coordinates":[132.5304138,34.2567817]},"name":"セブンイ レブン呉市吉浦店","openingHoursSpecification":{"opens":"00:00:00","closes":"23:59:00"},"refOffStreetParking":"urn:ngsi-ld:OffStreetParking:002","telephone":"+81823311458"}]
PS C:\Users\owner>>

全く同じ応答が返されました。このように、複数のオプションがあるときには、"-d"を付けたオプションを、ブランクを挟んで複数書くことにより指定可能です。


5.4.URLエンコード
2022年4月11日
 既に説明している様に、curlコマンドの中に"http://aaa.bbb/ccc?ddd&eee"などと書きますが、実はこの文字列の中に書くことができない文字があります。例えばダブルクォート(")など。それらの文字を書くときには、URLエンコードと呼ばれる回避策があります。空白の場合は空白をタイプする代わりに"%20"と書きます。以下、変換表です。

文字 URLエンコード
空白 (" ") %20
ダブルクオート (""") %22
シャープ ("#") %23
("<") %3c
(">") %3e
シングルクオート ("'") %27
中括弧("{"} %7b
中括弧(")"} %7d

これら以外に制御文字と呼ばれる文字ではない文字もあります。例えばタブや改行などです。それらも使う場合はURLエンコードする必要があります。気を付けなければならないのは、日本語を使うと、知らないうちに制御文字などと同じコードを含んでしまう事があるということです。このため、日本語をパラメータに使うときはエンコードして使う必要があります。例えば、"ローソン八王子長沼町店"はエンコードして、"%e3%83%ad%e3%83
%bc%e3%82%bd%e3%83%b3%e5%85%ab%e7%8e%8b%e5%ad%90%e9%95%b7%e6%b2%bc%e7%94%ba%e5
%ba%97"と書く必要があります。

curl -G -X GET 'http://localhost:1026/v2/entities' -d 'type=Store' -d 'q=name==ローソン八王子長沼町店' -d 'options=keyValues'
curl -G -X GET 'http://localhost:1026/v2/entities' -d 'type=Store' -d 'q=name==%e3%83%ad%e3%83%bc%e3%82%bd%e3%83%b3%e5%85%ab%e7%8e%8b%e5%ad%90%e9%95%b7%e6%b2%bc%e7%94%ba%e5%ba%97' -d 'options=keyValues'

 実際に使った例が以下です。同じ問い合わせを二回実行しています。一回目は、エンコードしておらず、検索結果がありませんが、二回目はエンコードしてあるので見つかる様になります。
PS C:\Users\owner> curl -G -X GET 'http://localhost:1026/v2/entities' -d 'type=Store' -d 'q=name==ローソン八王子長沼町店' -d 'options=keyValues'
[]
PS C:\Users\owner> curl -G -X GET 'http://localhost:1026/v2/entities' -d 'type=Store' -d 'q=name==%e3%83%ad%e3%83%bc%e3%82%bd%e3%83%b3%e5%85%ab%e7%8e%8b%e5%ad%90%e9%95%b7%e6%b2%bc%e7%94%ba%e5%ba%97' -d 'options=keyValues'
[{"id":"urn:ngsi-ld:Store:001","type":"Store","address":{"streetAddress":"長沼町202-5","addressLocality":"八王子市","addressRegion":"東京都","postalCode":"1920907"},"location":{"type":"Point","coordinates":[139.37158,35.64226]},"name":"ローソン八王子長沼町店"}]
PS C:\Users\owner>

日本語をエンコードする方法はネット上にたくさん紹介されていますが、インタラクティブに変換するのなら、例えばラッコツールズの変換ツール などが便利です。
 なお、前節でurlの後ろに"?"を挟んでオプションを指定する方法について説明しましたが、その場合もエンコードは必要です。念のため。


5.5.curlのオプション
2022年4月11日
 NGSIというわけではありませんが、ついでにcURLのオプションについても説明します。ここでは簡単にしか説明しませんので、全体を知りたい方はこちら をご覧ください。
 改めての説明となりますが、curlは、インタネットのプロトコル(HTTP、HTTPSなど)のいずれかを使用して、サーバーとの間でデータを転送するためのツールです。コマンドの形式は、以下です

curl [オプション] [URL ...]
URLには、複数の指定や範囲の指定も可能ですが、ここでは省略します。URLには、uriの直後に"?"をつけることで、オプション文字列もサーバに渡すことができます。また、サーバに依存しますが、"-d"などのオプションを渡せる場合もあります。繰り返しになりますが、uriの後ろに記述したオプションはサーバに渡すオプションで、uriの前に記述したオプションはcurlコマンドのオプションです (実装依存ですので、これを逸脱しても動く場合もあります)。
主なcurlコマンドのオプションは以下の通りです。

-d <data> データを渡します。(-Gも参照のこと)
-X <commnd> コマンドを渡します。httpの場合はhttp動詞を渡します。
-i 出力にhttpヘッダもつける指定です
-iX <command> -i -Xと同じ意味です
-G GET時に"-d"の<data>を、urlの後ろに"?"セパレータを挟んで付加します。