Coppell Technologies
スマートシティの標準規格
5.2節
|
|
2022年7月24日
HTTPプロトコルは、良く知られている実装事例はWebブラウザとWebサイト間のデータのやりとりです。この様にHTTPプロトコルはクライアントサーバ型の通信を実現します。つまり、クライアントが問い合わせ(以下、リクエスト)、それに応じてサーバがレスポンスを返します。Webブラウザの場合は、Webブラウザ側がクライアントでWebサイト側がサーバとなります。
Webブラウザでは、URLを指定してリクエストをします。URLにはサーバのアドレス、サーバ内の格納場所、およびオプション文字列などが渡されますが。実は、HTTPプロトコルでは、リクエストもレスポンスも、URL以外に文字列を受け渡します。それぞれ、以下の構造をもっています。
■リクエスト
| <http動詞> <ターゲット> <httpバージョン> |
<ヘッダーフィールド>
<ヘッダーフィールド>
・・・・ |
| <空行> |
| 本文 |
<http動詞>に続くターゲット>と<httpバージョン>は一行に書きます。セパレータは空白(ブランク文字)です。
<http動詞>はhttp動詞またはhttpメソッド、或いは単に動詞やメソッドとも呼ばれます。ETSIの規約ではHttp動詞(http verb)と記載されているのに、レスポンスの定義の部分では、例えば"Method Not Allowed"などとなっており"統一されていません。メソッドと呼ぶ場合が一番多い様です。<http動詞>には"GET"、"POST"、"PUT"、"PATCH"、"DELETE"、"HEAD" (GETと同じだか本文を返さない) 、"CONNECT"、"OPTIONS"、"TRACE"という単語が入っています。Webブラウザなら、ここはホームページのデータを取り出すという意味で、通常は"GET"が入っています。
<ターゲット>はhttp動詞が操作を行う対象です。後で、詳しく説明しますが、URLのサーバ名より後ろの文字列が入ります。ルートの場合は"/"が入ります。例えば、ブラウザで、https://www.abc.jp/def/ghi.htmlと記載すれば、"/def/ghi.html"が入ります。
<httpバージョン>は、今は"HTTP/1.1"が主流です。最新は"HTTP/2"ですので、今後はバージョン2が見られるようになるかもしれません。尚、バージョン2は1.1の上位互換でいし、デジタル庁の推奨モジュールも1.1をサポートしてるので、本書でも1.1を前提に記載します。
2行目からはヘッダーフィールドが続きます。ヘッダーフィールドには沢山の種類がありますが、NGSI V2では以下のものがあります。
| Host: |
例えば、本書であれば"www.coppelltech.jp:1028"となります。つまり、サーバとポート番号を指定します。このサーバのURLとすでに述べたターゲットを繋げれば、URL全体が出来上がります。尚、HTTP/1.1ではこのヘッダは必須です |
| Accept: |
クライアントが受信可能なデータ形式です。通常、'Accept: application/json'と記載します。但し、AttributeのValueだけをGETする場合はtextが受信可能ですので、'Accept: text/plain'を指定します。 |
| Content-Length |
本文のバイト長です。必須のヘッダです。指定を忘れると、411 Length Requiredのエラーを返します。尚、curl等で指定していないのは、ツール内で計算して指定してくれているためです。 |
| Content-Type |
本文のデータ形式です。'Content-Type: application/json'を指定します。但し、AttributeのValueを直接書き換える為に値を直接指定する場合は、'Content-Type: text/plain'を指定します。尚、LDでは、'Content-Type: application/json'、'Content-Type: application/ld+json'、または'Content-Type: text/plain'を指定します。 |
| Fiware-Service: |
推奨モジュールであるFiware/Orionでは、 マルチテナンシー機能を使う場合に、テナント名を通知します。 |
| Fiware-Servicepath |
推奨モジュールであるFiware/Orionでは、 サービスパスを通知します。 |
| Link: |
本書関係では、NGSI-LDを使用する際に、@contextの通知に用います |
| Origin: |
推奨モジュールであるFiware/Orionでは、CORSと呼ばれる機能を使うときに使うヘッダです。この機能を使うには、Orion起動時に-corsOrigin でCORSを有効にする必要があります。 |
| User-Agent: |
クライアントの情報です。Windowsなのかスマホなのかなどが分かるため、クライアントに合わせたレスポンスが可能となります。 |
| X-Forwarded-For |
推奨モジュールであるFiware/Orionでは、リクエスト元のIPアドレスをオーバーライドするIPアドレスを指定します。 |
| X-Auth-Token |
PEP Steelskin などの Orion と統合されたセキュリティ・エンフォース・ プロキシによって使用されます。このヘッダは通知やフォアード時に透過的に通知されます。 |
| X-Real-IP |
推奨モジュールであるFiware/Orionでは、リクエスト元のIPアドレスをオーバーライドするIPアドレスを指定します。X-Forwarded-Forよりも優先されます。 |
<空行>は、ヘッダーフィールドと本文との間のセパレーターです。
<本文>には、JSONなどの文字列やバイナリコードが入ります。尚、http動詞がGETの場合は、本文には何も入りません。
■レスポンス
| <httpバージョン> <レスポンスコード> <:結果フレーズ> |
<ヘッダーフィールド>
<ヘッダーフィールド>
・・・・ |
| <空行> |
| 本文 |
返却されるヘッダーフィールドは以下の通りです。
| Access-Control-Allow-Headers |
推奨モジュールであるFiware/Orionでは、CORSと呼ばれる機能を使うときに使うヘッダです。この機能を使うには、Orion起動時に-corsOrigin でCORSを有効にする必要があります。 |
| Access-Control-Allow-Methods |
推奨モジュールであるFiware/Orionでは、CORSと呼ばれる機能を使うときに使うヘッダです。この機能を使うには、Orion起動時に-corsOrigin でCORSを有効にする必要があります。 |
| Access-Control-Allow-Origin |
推奨モジュールであるFiware/Orionでは、CORSと呼ばれる機能を使うときに使うヘッダです。この機能を使うには、Orion起動時に-corsOrigin でCORSを有効にする必要があります。 |
| Access-Control-Expose-Headers |
推奨モジュールであるFiware/Orionでは、CORSと呼ばれる機能を使うときに使うヘッダです。この機能を使うには、Orion起動時に-corsOrigin でCORSを有効にする必要があります。 |
| Access-Control-Max-Age |
推奨モジュールであるFiware/Orionでは、CORSと呼ばれる機能を使うときに使うヘッダです。この機能を使うには、Orion起動時に-corsOrigin でCORSを有効にする必要があります。 |
| Allow: |
クライアントが間違ったhttp動詞を指定した場合、許可しているhttp動詞を通知します |
| Content-Length: |
本文のバイト長です |
| Content-Type: |
本文のデータ形式が入ります。例えば通常のホームページであれば、"text/html"と入ります |
| Expect: |
推奨モジュールであるFiware/Orionでは、空のExpectヘッダを送信します。このヘッダはサーバ(受信側)に特別な動作を要求するヘッダであるため、空のヘッダを送信する仕様となっています。 |
| Fiware-Correlator |
推奨モジュールであるFiware/Orionで使用されます。 |
| Fiware-Service: |
推奨モジュールであるFiware/Orionでは、 マルチ手ナンシー機能を使う場合に、テナント名を通知します。 |
| Fiware-Servicepath |
推奨モジュールであるFiware/Orionでは、 サービスパスを通知します。 |
| Fiware-Total-Count |
推奨モジュールであるFiware/Orionでは、 フィルタ条件に合致するEntityの総件数を返却します。 |
| Last-Modified: |
このページが更新された日時です。キャッシュの制御やクローリングの要否判断などに用います。 |
| Location: |
Entityのurlの後半部分です。3.4節で記載する<APIルート>を除いた、それ以降の文字列が、Entityを格納したときなどに返却されます。つまり、"/v2/"以降が通知されます。 |
| Ngsiv2-AttrsFormat |
送信するペイロードの形式が格納されています。例えば'Ngsiv2-Attrsformat: normalized'などです。 |
| User-Agent: |
推奨モジュールであるFiware/Orionでは、 Orion のバージョン等の情報を記載してあります |
| X-Auth-Token |
PEP Steelskin などの Orion と統合されたセキュリティ・エンフォース・ プロキシによって使用されます。このヘッダは受信したヘッダと透過的に同じものです。 |
<空行>は、ヘッダーフィールドと本文との間のセパレーターです。
<本文>には、htmlやJSONなどの文字列や画像のバイナリコードが入ります。
2022年8月15日
レスポンスコードを以下に示します。
| レスポンスコード |
結果フレーズ |
補足 |
| 100 |
Continue |
|
| 200 |
OK |
正常終了したという意味です |
| 201 |
Created |
Entityの格納が成功した場合に返却されます。 |
| 202 |
Accepted |
要求は受理された |
| 204 |
No Content |
Attributeを正常に追加した場合やEntityを正常に削除した場合などに返却されます |
| 400 |
Bad Request |
不正な要求。シンタックスが間違っているなど |
| ParseError |
JSON構文に誤りがある |
| 404 |
Not Found |
urlが間違っているなど、目標のリソースが見つからない |
| 405 |
Method Not Allowed |
http動詞が間違っている |
| 406 |
Not Acceptable |
不正な要求。例えば、リクエストヘッダのAcceptやContext-typeが不正な場合など。 |
| 409 |
Conflict |
例えば同じidのentityを格納しようとしたなど |
| Too Many Results |
更新の際のフィルタリングで、複数のEntityが選択された |
| 411 |
Length Required |
本文の長さが指定されていない |
| 413 |
No Resource Available |
空間インデックスの制限を超過しているなど |
| Request Entity Too Large |
Entityが大きすぎる |
| 415 |
Unsupported Media Type |
|
| 422 |
Unprocessable |
既に存在するAttributeを追加しようとした際など |
|
