　5.3-5.5節 - 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の後ろに"?"セパレータを挟んで付加します。

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

5. NGSI v2のAPI 5.3-5.5節

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

　5. NGSI v2のAPI　5.3-5.5節