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

Munu


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


Column
Link
用語集

Coppell

Technologies

5. NGSI v2のAPI



5.1.エンドポイントとhttp動詞
2022-04-11/2023-11-11
　NGSIのAPIは、Web APIと呼ばれるAPIの一種です。前節まで" localhost:1026/v2/entities/"のentitiesをWindowsの用語に合わせてフォルダと呼んでいましたが、ここからはWeb APIの用語に合わせてエンドポイントと表現します。
　ここまでの説明で、例えば" curl -X GET http://localhost:1026/v2/entities/urn:ngsi-ld:Store:002"というコマンドがありましたが、この"GET"の部分を"http動詞 (http verv)"と呼びます。本書でもこれに倣ってなるべくhttp動詞と記載しますが、一般的なWeb APIの説明ではメソッドまたはhttpメソッドと呼ぶ場合が多い様です。本書でも一部両方の記載が混ざっていますが、ご容赦下さい。http動詞にはGET、PUT、POST、PATCH、DELETEのなどの種類があります。
　エンドポイントとhttp動詞の組み合わせで操作の内容が決まります。以下、操作可能な組み合わせの一覧です。パスの構造は都市OSによって異なるので、それぞれの都市らと毎に確認する必要があります。下記のパスは本書で動かす環境のものだと理解してください。また、下記のhttp動詞の他に、HEAD (GETと同じだか本文を返さない) 、CONNECT、OPTIONS、TRACEがありますが、ここでは省略します (参考1, 2)。
エンドポイント http動詞 説明
v2 entities
GET 全てのEntityを対象に読み出します

POST 新たなEntityを追加します
<id>
GET 特定のEntityを指定して読み出します

POST 特定のEntityを指定してAttributeを追加、または更新します

DELETE 特定のEntityを削除します
attrs

PATCH 特定のEntityのAttributeを更新します
<Attribute>
DELETE 特定のEntityの特定のAttributeを削除します
value GET 特定のEntityの特定のAttributeのValueを読みだします
PUT 特定のEntityの特定のAttributeのValueを更新します
types
GET typeの一覧の取得
<EntityTuype> GET 特定EntityのAttributeの一覧
op/update POST 複数ENtityを一括登録、一括更新します
version GET バージョン情報を読み出します

ちょっとコムズカシイ話になりますが、「場所」は一意に識別できないと、何かと不都合があります。ISOでは場所識別子の概念を定義 していて、仮想世界の場所も含んでいます。仮想世界の場所識別子のひとつとしてはURLがあります。URLを指定するとパスが決まるので、対象となるオブジェクト (EntityやAttribute)を一意に決めることができます。このため、NGSI v2のインタフェースでは、URLに対してhttp動詞で動作を定義するという形式を採用しています。

5.2.http
2022年4月11日
　"http"や"https"はWebブラウザを使ったときにurlの先頭に記述しますが、これはhttpというプロトコルで通信をするという記号です。httpは" Hypertext Transfer Protocol"の事で、ブラウザは"http:~"と指定されると、httpプロトコルを使用してWebサーバと通信を行っています。Fiware/OrionはWebサーバと同様にhttpでアプリケーションと通信を行います。httpは、アプリケーションが「リクエスト」を発行し、サーバが「レスポンス」を返すというリクエスト・レスポンス型のプロトコルです。リクエストには、urlやメソッド、バージョンなどの情報が含まれています。メッセージボディを含む場合もあります。メソッドとはhttp動詞のことで、既に記載したように8種類あります。レスポンスには、ステータス、メッセージヘッド、メッセージボディが含まれています。urlには既に記述している様に"?"を挟んでオプションを指定する事ができます。Web APIとは、一般的にはこの様にhttpを使って情報をやりとりするAPIを指します。つまり、FiwareはWeb APIで情報をやとりします。
　"https"もWebブラウザでよく見かけますが、これはセキュリティを強化したhttpの事で、プロトコルはhttpと同じと考えて差し支えありません。
　httpのリクエストのプロトコルは以下の形式になってます

<メソッド>　<url> <httpバージョン>　#必ず最初に書かれている
[<ヘッダフィールド>]　#複数のヘッダフィールドが改行をを挟んで並んでいる
(改行)　　　　　　　　#<body>との境目の印
<Body>　　　　　　　　#データ本体
ヘッダーフィールドには多種のものがありますが、例えば以下のものがあります。

ヘッダフィールドのキーワード データの内容
Accept 受信可能なデータの形式。text, HTML, XMLなど
Content-Type 送受信されるコンテンツの種類。"application/json"、"text/plain"などと指定する

本書のここまでの記述で、"-H"や"-header"で指定していたのは、このヘッダーフィールドの指定でした。
　httpのレスポンスは以下の形式になっています。ヘッダーフィールドの定義はリクエストと共通です。

<httpバージョン>　<ステータス>　<説明>  #必ず最初に書かれている
[<ヘッダフィールド>]  #複数のヘッダフィールドが改行をを挟んで並んでいる
(改行)                #<body>との境目の印
<Body>                #htmlなどの本文
ステータスとしては、主なものに以下のものがあります。

ステータス 説明 補足
100 Continue
200 OK 正常終了したという意味です
202 Accepted 要求は受理された
400 Bad Request 不正な要求
404 Page Not Found urlが間違っている
この様にWeb APIは文字列の行が並んでいる構造をしています。ここまで、curlを利用してきましたが、curlとは、これらの文字列を生成して指定のurlにリクエストとして送り込み、その結果として返却されたレスポンスの文字列を表示するツールだったというわけです。後の章では、Pythonを使ったプログラムを作りますが、やはり同じように文字列をくみ上げたり、返却したりするものです。
　データの受け渡しの方法には、GETの際にurlに続くオプション文字列で渡す方法と、PUTの際にBodyとして渡す方法があります。urlは長さに制限があり、その諸元(最大長)はソフトウェアに依存しますが、一般的には数キロバイト程度と言われています。また、通信を傍受された場合、urlは裸で見えてしまうため、あまり情報を多量に乗せることはこの点からも望ましくはありません。