IoT Platform DRC(オンデマンドデータ収集) ユーザーガイド (14.0_0 版) |
<改版履歴>
版数 |
説明 |
日付 |
9.0_0 |
初版登録 |
2019/08/22 |
9.0_1 |
誤記訂正 |
2019/12/11 |
11.0_0 |
7.2 使用リソース一覧に関する誤記訂正 7.5 API汎用例に関する記載の注意書きを追加 7.5 登録データの汎用例に関する誤記訂正 7.5-7.9 API実行時のレスポンスを200 OK→200に修正 |
2021/1/16 |
14.0_0 |
機能エンハンス 変更なし |
2022/4/1 |
はじめに
このたびは「IoT Platform」をご検討いただき、誠にありがとうございます。
この「IoT Platform DRC(オンデマンドデータ収集) ユーザーガイド(以下、本書)」は、本サービスをご契約いただいたお客様、またはご採用いただくお客様のための資料です。下記につきましてご了承くださいますよう、よろしくお願いいたします。
1. ご検討中のお客様は、本書を本サービスご採用可否のご判断のためにのみ、ご参照願います。
2. 本書および本書の内容について、第三者へご開示、ご提供にはならないようにお願いいたします。
3. 発行元の許可なく、本書の記載内容を複写、転写することを禁止します。
本書には本サービスをご採用いただくための重要な情報を記載しています。
ご契約いただいたお客様は、ご利用前に本書をよくお読みの上、本サービスをご利用ください。なお、本書は大切に保管してください。
ご採用いただけないお客様は、お客様の責任で本書をすみやかに廃棄願います。
本書の作成にあたって、細心の注意を払い可能な限り分かりやすい記載に努めていますが、本書の記述に誤りや欠落があっても弊社はいかなる責任も負わないものとします。本書及びその記述内容は予定なく変更される場合があります。
本書の内容の一部または全部を無断で複製・転載・改編しないでください。
Android, Android Studioは、米国Google Inc.の米国およびその他の国における商標または登録商標です。
Eclipse Pahoは米国およびその他の国における Eclipse Foundation, Inc. の商標もしくは登録商標です。
PythonはPython Software Foundationの登録商標です。
UbuntuはCanonical Ltd.の登録商標です。
LinuxはLinus Torvalds氏の日本およびその他の国における登録商標または商標です。
Javaは、Oracle Corporation 、関連会社の米国およびその他の国における登録商標です。
免責事項について
・本サービスのマニュアルに記載されていない操作を行なったことで思わぬ誤動作や、予期せぬ課金が発生した場合であっても一切の責任を追いかねます。
・本サービスの利用、または利用できなかったことにより万が一損害(業務の中断・データの破損/損失・事故などによる損害や第三者からの賠償請求の可能性を含む)が生じたとしても、責任を一切負いかねます。
<用語>
用語 |
説明 |
備考 |
IoT |
Internet of Thingsの略 「モノのインターネット」と言われるが、「モノがインターネットプロトコル(インターネット言語)でネットワークされている状態」のこと。
|
|
REST |
REpresentational State Transfer の略 複数のソフトウェア連携に適した設計原則をWebに適用したソフトウェアの設計様式を示す。 ※特定のURLにパラメータを指定してHTTPでアクセスするとXMLで記述されたメッセージが送られてくるような、呼び出しインターフェース(「RESTful API」と呼ばれる)。 本サービスではXMLではなくJSON形式で返信する。
|
|
エッジ |
現場のデータを蓄積している様々な機器
|
|
DRC(オンデマンドデータ収集) |
エッジに蓄積された実データを効率よく利活用できる機能
|
|
リソース |
リソースデータの収集単位 |
|
リソースデータ |
1つのデータ |
|
アクセスコード |
リソースを対象に設定する認可情報 |
|
- 目次 -
3.2.1. エッジへの検索指示を絞り込めるGraceful機能
第8章 メタデータのパーティション分割(partition_id)について
本書はIoT Platform(以下:本サービス)に含まれるDRC(オンデマンドデータ収集)(以下:本機能)のご利用に際し、システムを設計する方向けの「DRC(オンデマンドデータ収集)ユーザーガイド」です。
サービスのご利用に際し、お客様を支援するための以下のマニュアルをご用意しております。
マニュアル名 |
説明 |
IoT Platform サービス詳細説明書 |
本サービスのサービス仕様を説明しています。 |
IoT Platform ユーザーガイド
|
本サービスを利用したシステムを設計するにあたって、具体的な例を交えて設計指針の説明を行うマニュアルです。 |
IoT Platform APIリファレンス
|
本サービスで提供するサービスを利用したアプリケーションを設計するためのAPIのリファレンスマニュアルです。 |
IoT Platform サービスポータル操作マニュアル |
Web インターフェース機能(以下:サービスポータル)に関するマニュアルです。 |
IoT Platform DRC(オンデマンドデータ収集)ユーザーガイド |
本機能を利用したシステムを設計するにあたって、具体的な例を交えて設計指針の説明を行うマニュアルです。(本書) |
IoT Platform DRC(オンデマンドデータ収集)インターフェースリファレンス |
本機能で提供するサービスを利用したアプリケーションを設計するためのインターフェースのリファレンスマニュアルです。 |
リソース、アクセスコードなど本サービス全般の定義・考え方については、サービスポータル操作マニュアル第3章をご参照ください。
|
本サービスは以下の特長を持っています。これらの特長により、過去に遡って必要なデータを効率よく取り出すことができるため、分散された大量のエッジに蓄積された大容量のデータ(実データ)から必要な情報を必要なときに素早く取り出すことができます。
・メタデータ登録機能
エッジにおいて発生したデータの特徴(メタデータ)を収集・蓄積し、あとから検索しやすいように分解・整理する機能です。これにより、実データをすべて上げるときと比較して、伝送量を低減できます。
・データ検索機能
エッジに分散されて蓄積された実データを検索し収集します。検索要求に基づき、事前に収集しておいたメタデータの中から実データを保有しているエッジを選別し指示することができます。
これにより、大容量のデータから必要な情報を必要なときに素早く取り出すことができます。
DRC(オンデマンドデータ収集)(以下、本機能)を利用することにより、エッジに蓄積された実データを効率よく利活用できます。
センサや動画像を多数のエッジより収集するIoTビジネスにおいて、予めエッジからデータの特徴のみを抽出したメタデータを登録しておくことにより、メタデータを元にエッジに対して実データを抽出することができます。これにより、エッジとクラウドの通信量を必要最小限にしつつ、エッジで生成された実データを効率よく収集することができます。
図 DRC(オンデマンドデータ収集)の利用イメージ
本サービスは以下の機能を有しています。
本機能はメタデータを収集し蓄積します。メタデータとは実データ(動画像、センサ、機器稼動ログなど)の特徴のみを抽出したデータ(時刻、位置情報、タグなど)を指します。収集されたメタデータは後から検索しやすいように再整理されます。また、整理内容について結果を確認することができます。
図 メタデータ収集機能のイメージ図
本機能はお客様が設計した検索クエリを元にエッジに蓄積されたデータを検索することができます。
以下に、データを検索し取得するまでの流れの例を示します
① データ検索クエリの登録
お客様がいつどこにあったどのようなデータが欲しいかを記載したメタデータのクエリを登録します。本サービスはこのクエリを元に検索を行います。
② メタデータの検索
本サービスが事前に集めたメタデータを元にその実データがどのエッジにあるか判断します。
③ 前処理の指示
本サービスが検索条件に該当するエッジに対して指示を行います。
④ 該当する実データのみ収集
エッジが本サービスに対して検索条件に該当する実データを送信します。
図 検索要求機能のイメージ図
本サービスは以下2つの特長を持っています。
本サービスは、エッジに蓄積されたデータを収集する際、収集されるエッジの数や量を調整することができます。
予め収集したメタデータによっては、検索指示を行った結果、対象となるエッジの数や量が膨大になってしまい、データを収集しきれない問題が生じます。これを解決するために、対象となるエッジの数や量が膨大になった場合、指定したエッジの数や量だけ収集するようエッジへの指示を絞りこむことができます。これにより、意図せず膨大な収集を行ってしまうことがなくなるため、短期間で効率よくデータを収集することができます。
図 Gracfulの利用イメージ
エッジに検索指示を出した場合、エッジに電源が入っていなかった場合などにおいて、データを収集することができなくなる場合があります。Verbose機能を有効にすると、詳細な経過ログを表示できるため、収集できなかった場合の原因を特定することができます。
インシデントが発生した際に原因分析/影響見極めを行うにあたって周辺に存在したセンサ群から効率よくデータを収集するケースです。例えば、点在する車載器におけるドライブレコーダーから過去に発生した事故の動画を収集することができます。
特定事象や特定行動に対する予測精度向上のために類似する関連データを収集することができます。これを使って、エッジAIなどエッジにある機械学習モデルの最適化を行ったり、渋滞状況や気象状況を判別したりすることができます。
本章では、本機能を使用するために必要なものについて説明します。
ご契約後弊社から通知する以下の情報が必要になります。
表 1:ご契約後の通知内容情報一覧
|
項目 |
1 |
テナントID |
2 |
ベースURI |
各種アプリを開発するにあたって、REST(HTTP)ライブラリが必要になります。詳細な動作環境については、開発対象となるOSやプログラミング言語の仕様をご確認ください。
本書では、LinuxOSにおけるcurlコマンドにて説明を行います。
Ubuntu上でcurlコマンドを導入する方法を以下に示します。(root権限にて実行)
# apt-get install curl |
本サービスでは、SSL/TLSサーバ証明書としてSSL通信のためのサーバ証明書としてDigiCert社の「DigiCert SHA2 High Assurance Server CA」を使用しています。
SSL/TLS通信を行う場合は同社の「DigiCert High Assurance EV Root CA」をルート証明書としてご利用下さい。
https://www.digicert.com/digicert-root-certificates.htm#roots
※ URLは2019年7月現在のものです。
以下のすべてをお客様にて自ら用意する必要があります。
① サーバ(活用システム)
② サーバ(活用システム)上でデータ活用するアプリ
③ ネットワーク回線
④ エッジ上で動作するアプリ
⑤ エッジ(エッジコンピュータ、ゲートウェイ装置、デバイス、センサ、他)
⑥ 本サービスのご契約
図 お客様に準備頂くもの
尚、本機能は本サービスのリソース_JSONを介して実現します。そのため、エッジ上で動作するアプリ、データを活用するアプリはネットワーク回線を介して本サービスに接続できる必要があります。
本サービスを用いて、システム構築をする流れを以下に示します。
システム全体の設計を行う |
↓
設計に基づきポータル画面より設定を行う |
↓
リソース、アクセスコードの作成を行う |
↓ ・本機能の有効化、エッジ情報の登録、メタデータを納するリソースの作成
アプリ(エッジ/活用システム)の開発を行う |
↓ ・メタデータ収集アプリの開発(エッジ側)
↓ ・検索指示読取・実データ送信を行うする前処理アプリの開発(エッジ側)
↓ ・活用システムアプリの開発(活用システム側)
アプリの配備、及び機器の接続を行う |
↓
利用を開始する |
システムを構築する上で性能やセキュリティを確保するためには、アプリの開発を行う前のシステム全体の設計が重要になります。設計にあたっての考え方については「IoT Platformユーザーガイド」第5章をご参照ください。
本章では、設計時に注意する必要がある項目について記載します。本章をよくお読みの上、リソース、アクセスコード、イベントの設計を行って下さい。
アプリ開発の流れを紹介するにあたり、今回活用するユースケースについて紹介します。
今回は宇宙に点在する人工衛星をエッジとして、人工衛星に蓄積された画像を効率よく利活用する例について紹介します。
(尚、本シナリオは仮想のユースケースであり、実際の人工衛星に適用した事例ではありません。ご了承願います。)
本シナリオにおいて、人工衛星が複数打ち上げられています。打ち上げられた人工衛星は地上の画像を撮影し人工衛星内に蓄積しています。しかしながら、地上と人工衛星の間の帯域が限られており、常に最新の画像をすべて取得することができません。そこで、本機能を活用し、撮影したメタデータのみを地上に送信し、人工衛星に蓄積された画像を検索できるようにしました。これにより、過去に遡って必要な画像データを効率よく収集することができるようになります。
今回、人工衛星は検索時のキーとなるメタデータとして撮影した日時情報と緯度経度情報(geo_lat,geo_lng)を送信するものとします。また利用者は今回蓄積されたメタデータを基に、2019年2月2日における北緯(geo_lat)が36~37度、東経(geo_lng)が138度~139度の画像を検索し取得するものとします。取得指示を出すエッジとデータ数は10台までで1時間経過しても収集できなかった場合は指示を打ち切るものとします。尚、エッジである人工衛星に蓄積できるデータは7日分とします。
本機能の構成は以下の図のようになっています。図中のアルファベットは本機能のリソース_JSONを表しています。
図 内部構成と開発するアプリの一覧
本機能を実現するためには以下3つのアプリ開発する必要があります。
1.エッジにおけるメタデータ収集アプリ
センサや動画像からメタデータを生成し本機能に登録する機能が必要です。あわせて、センサや動画像をエッジ側に蓄積する機能が必要です。開発に使用するリソース_JSONは以下のとおりです。
No |
リソースパス |
用途 |
詳細参照先 |
A |
<prefix>/meta/gws |
エッジ情報の登録、参照 |
エッジ情報取得 エッジ情報登録 |
B |
<prefix>/meta/publish |
メタデータの登録 |
メタデータ登録 |
C |
<prefix>/meta/keys/<key>/<partition_id> |
分解されたメタデータの検索・取得 |
分解されたメタデータ取得 |
D |
<prefix>/meta/confirm/<gw_id> |
メタデータ登録結果の参照 |
メタデータ登録確認 |
2.活用システムにおける活用システムアプリ
どのようなデータを検索・抽出したいか指示する機能が必要です。検索指示後は本機能が収集・蓄積したデータを収集することによって、可視化や機械学習などを行う機能が必要です。開発に使用するリソース_JSONは以下のとおりです。
No |
リソースパス |
用途 |
詳細参照先 |
E |
<prefix>/request/search |
検索要求/キャンセル要求の登録 |
検索・キャンセル要求 |
J |
<prefix>/response/search |
指示完了通知の登録 |
指示完了通知 |
H |
<prefix>/response/progress/<gw_id> |
指示進捗状況の登録、参照 |
進捗確認 進捗通知 |
K |
<prefix>/response/preprocessed |
検索結果(実データ)の登録、参照 |
データ取得 データ送信 |
3.エッジにおける前処理アプリ
エッジより、本機能が指示した要求を読み取る機能、および読み取り内容に従ってデータを抽出・加工し、本機能へデータを送信する機能が必要です。開発に使用するリソース_JSONは以下のとおりです。
No |
リソースパス |
用途 |
詳細参照先 |
G |
<prefix>/request/clients/<gw_id> |
検索指示/キャンセル指示の参照 |
検索指示・キャンセル指示取得 |
I |
<prefix>/response/sent_flags/<gw_id> |
検索結果の登録 |
送信完了通知 |
H |
<prefix>/response/progress/<gw_id> |
指示進捗状況の登録、参照 |
進捗確認 進捗通知 |
K |
<prefix>/response/preprocessed |
検索結果(実データ)の登録、参照 |
データ取得 データ送信 |
本章では具体的なAPI発行例を紹介しながら各アプリの役割について説明します。例を実行するにあたってご契約後の通知内容をご用意ください。本章では以下で説明しますが、必要に応じて読み替えて実行して下さい。
テナントID |
<テナントID> |
ベースURI |
http://<zone>.fujitsu.com/ |
本機能では、本サービスの内部処理にて従量サービスで提供しているAPI(データアクセス)を利用します
(以降:内部処理)。また、内部処理についてはお客様利用分として計上します。想定以上の利用料金となることを防ぐために、本機能利用時は内部処理を考慮されたうえでアプリケーションを設計してください。なお、内部処理で用いるAPI回数は以下のとおりです。
1.メタデータ登録時
本機能API回数=200×メタ数×(メタデータ登録回数+1分あたりにメタデータ登録するエッジ数)
2.検索要求登録時
本機能API回数=(検索要求時指定の検索対象メタ数×検索条件にヒットするGW台数)×2
3.各リソースのポーリング
エッジ情報リソース:5分に1回
メタデータリソース:1分に1回
検索要求リソース:1分に1回
送信完了リソース:1分に1回(エッジ数には依存しません)
具体例:
1.メタデータ登録時
メタ数:3
メタデータ登録回数:1回/秒
1分あたりにメタデータ登録するエッジ数:5台
の場合
秒間あたりの本機能API回数=200×1×(3+5÷60)=616(API)
※Bulk Insert機能を用いてデータ登録するため、費用計算時は200を乗算します。
2.メタデータ登録時
検索要求時指定の検索対象メタ数:2
検索条件にヒットするエッジ台数:2
の場合
1検索要求あたりの本機能API回数=(2×2)×2=8(API)
※従量料金 10,000APIあたり10円
特に1.ではBulk Insert機能を使って登録するため、「メタ数」「メタデータ登録負荷」「メタデータ登録するエッジ台数」の3つについて充分に考慮してアプリケーション設計いただくようお願いします。
ポータル画面より、本機能の初期設定を行います。
設定方法については、「サービスポータル操作マニュアル」を参照ください。
以降、以下のprefixリソース、アクセスコードを設定したものとして説明していきます。
prefixリソース |
drc |
アクセスコード |
drcaccesscode |
正しく登録できた場合、以下のリソースが作成されます。ポータル画面またはAPIより以下のリソースが作成されていることを確認してください。
drc/meta/gws drc/meta/publish drc/meta/request/search drc/meta/response/search drc/meta/response/preprocessed |
はじめに7.2節に記載のA「エッジ情報」に動作するエッジ情報を追加します。
ここではエッジのIDとして「gw-001」「gw-002」「gw-003」「gw-004」「gw-005」を登録するものとします。以下のリソースにエッジの情報を記載します。
以降7.5章から7.9章まで記載しているAPI実行時の凡例ですが、URIの$filter=以降において、非予約文字以外の文字はパーセントエンコードにより置き換える必要があります。「 」(半角スペース)は「%20」、「+」は「%2b」、「'」(シングルクォーテーション)は「%27」、「=」は「%3d」に置き換えてください。詳細は「IoT Platform APIリファレンス」を参照してください。
リソース種別 |
リソース_JSON |
リソースパス |
drc/meta/gws |
データ形式 |
JSON |
APIを呼び出すのに必要なパラメータは以下の通りです。
HTTPメソッド |
PUT |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/gws?$bulk=single_resource_path |
BODY |
[ |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X PUT -H
'Authorization:
Bearer drcaccesscode' -d '[ “gw_id” : “gw-001" }, “gw_id” : “gw-002" }, “gw_id” : “gw-003" }, “gw_id” : “gw-004" }, “gw_id” : “gw-005" } |
正しくAPIを発行できた場合、レスポンスとして「200」が返ります。
正しく登録できた場合、以下のリソースが作成されます。ポータル画面またはAPIより以下のリソースが作成されていることを確認してください。
drc/meta/confirm/gw-001 : drc/meta/confirm/gw-005 drc/response/progress/gw-001 : drc/response/progress/gw-005 drc/response/sent_flags/gw-001 : drc/response/sent_flags/gw-005 drc/request/clients/gw-001 : drc/request/clients/gw-005 |
次に7.2節に記載のC「分解されたメタデータ」のためのリソースを作成する必要があります。
今回の例では位置情報(緯度geo_lng、経度geo_lat)をメタデータのkeyとして登録するため以下のリソースを追加します。必要に応じて追加してください。ここでエッジは実データを7日分保存できるものとするため、メタデータの保持期間も7日とします。保持期間はエッジにおける実データの最大保存期間を指定することを推奨します。
geo_lng
リソース種別 |
リソース_JSON |
リソースパス |
drc/meta/keys/geo_lng |
データ形式 |
JSON |
geo_lat
リソース種別 |
リソース_JSON |
リソースパス |
drc/meta/keys/geo_lat |
データ形式 |
JSON |
APIを呼び出すのに必要なパラメータは以下の通りです。
geo_lng
HTTPメソッド |
POST |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/keys/geo_lng |
BODY |
{ "resource" : { "retention_period" : 7 } } |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X POST -H 'Authorization: Bearer drcaccesscode' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/keys/geo_lng' -d '{ "resource" : { "retention_period" : 7 } }' |
正しくAPIを発行できた場合、レスポンスとして「201」が返ります。
APIを呼び出すのに必要なパラメータは以下の通りです。
geo_lat
HTTPメソッド |
POST |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/keys/geo_lat |
BODY |
{ "resource" : { "retention_period" : 7 } } |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X POST -H 'Authorization: Bearer drcaccesscode' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/keys/geo_lat' -d '{ "resource" : { "retention_period" : 7 } }' |
正しくAPIを発行できた場合、レスポンスとして「201」が返ります。
本節ではエッジにおけるメタデータ収集アプリにおいて必要な開発手順について記載します。
エッジにおけるメタデータ収集アプリが実施すべき処理の流れについて説明します。
メタデータ登録(B) |
↓idx_idを使って一意に登録します。
メタデータ登録状況参照(D) |
登録した際のidx_idを使って検索し状況を確認します。
エッジにて収集したセンサ・動画像の情報からメタデータを抽出し、本機能へ送信します。また、センサ・動画像の情報をエッジにおいて蓄積します。
ここではエッジである人工衛星が撮影した画像から以下のメタデータを抽出した場合において、メタデータを本機能へ登録する方法を紹介します。
画像ファイル名 |
S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559.jpg |
時刻 |
2019-02-02T01:28:59.024Z |
緯度(geo_lat) |
36.12427601168043 |
経度(geo_lng) |
138.77760353347315 |
以下のリソース_JSONに対してメタデータを登録します。
リソース種別 |
リソース_JSON |
リソースパス |
drc/meta/publish |
データ形式 |
JSON |
アクセスコードは以下を使用します。
アクセスコード |
drcaccesscode |
リソースパス |
drc |
アクセス権限 |
「CDL」「P」「G」に権限を付与 |
APIを呼び出すのに必要なパラメータは以下の通りです。
HTTPメソッド |
PUT |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/publish |
BODY |
{ "idx_id":"S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559", "meta": { "_date" : "20190202T012859.024Z", "geo_lat" : 36.12427601168043, "geo_lng" : 138.77760353347315 } } |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X PUT -H 'Authorization: Bearer drcaccesscode' -d '{ "idx_id":"S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559", "gw_id":"gw-001", "_date" : "20190202T012859.024Z", "geo_lng" : 36.12427601168043, "geo_lat" : 138.77760353347315 } }' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/publish' |
正しくAPIを発行できた場合、レスポンスとして「200」が返ります。
登録されたメタデータは検索しやすいよう分解され整理されます。次に、この登録・分解が成功したか否かを確認します。以下のリソース_JSONに結果が格納されるため、以下のリソース_JSONに対してidx_idが「S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559」に該当する実データを検索・参照します。
リソース種別 |
リソース_JSON |
リソースパス |
drc/meta/confirm/gw-001 |
データ形式 |
JSON |
アクセスコードは以下を使用します。
アクセスコード |
drcaccesscode |
リソースパス |
drc |
アクセス権限 |
「CDL」「P」「G」に権限を付与 |
APIを呼び出すのに必要なパラメータは以下の通りです。
HTTPメソッド |
GET |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/confirm/gw-001/_past?$filter=idx_id eq S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559 |
BODY |
なし |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X GET -H 'Authorization: Bearer drcaccesscode' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/confirm/gw-001/_past?$filter=idx_id eq "S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559"' |
メタデータの分解に成功した場合、statusにsucceededが記載されます。以下の例の場合geo_lng、geo_lat両方共成功していることが確認できます。
{ "idx_id" : "S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559", "status": { "geo_lat": "succeeded", "geo_lng": "succeeded", "_date" : "20190202T013000.000Z" } |
本節では活用システムにおいて必要な開発手順について記載します。
活用システムにおける活用システムアプリが実施すべき処理の流れについて説明します。
検索要求(E) |
↓ システム全体で一意なreq_idを作成し、これを用いて検索します。
検索結果取得(J) 任意 |
↓ 検索要求が正しく本システムに要求されたかを確認します。
進捗状況の取得(H) 任意 |
↓ エッジの検索処理状況を知りたい場合に取得します。
検索要求のキャンセル(E) 任意 |
↓ 検索要求をキャンセルしたい場合に実行します。
検索結果取得(J) |
↓ 検索要求時に使用したreq_idを用い検索結果を確認します。
実データの取得 |
検索結果が正常に終わった場合、実データを取得します。
収集したメタデータを使って、エッジに対して検索要求を行います。Graceful機能を使って意図せずエッジに高負荷な指示を出さないよう条件を絞り込むことができます。
ここでは例として、2019年2月2日における北緯(geo_lng)が36~37度、東経(geo_lat)が138度~139度の画像を取得、ただし取得指示を出すエッジと実データ数は10台までで1時間経過しても収集できなかった場合は指示を打ち切りするケースについて紹介します。
以下のリソース_JSONに結果が格納されるため、以下のリソース_JSONに対して検索要求データを登録します。
リソース種別 |
リソース_JSON |
リソースパス |
drc/request/search |
データ形式 |
JSON |
アクセスコードは以下を使用します。
アクセスコード |
drcaccesscode |
リソースパス |
drc |
アクセス権限 |
「CDL」「P」「G」に権限を付与 |
APIを呼び出すのに必要なパラメータは以下の通りです。
geo_lngの$filter条件は「"_date gt 20190202T000000.000Z and _date lt 20190203T000000.000Z and value gt 36 and value lt 37"」、geo_latの$filter条件は「"_date gt 20190202T000000.000Z and _date lt 20190203T000000.000Z and value gt 138 and value lt 139"」であるものとします。
HTTPメソッド |
PUT |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/request/search |
BODY |
{ "req_id" : "request001", "preproc" : "returnJPG", "_date gt 20190202T000000.000Z and _date lt
20190203T000000.000Z and value gt 138 and value lt 139" "gw_limit" : 10 }, |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X PUT -H 'Authorization: Bearer drcaccesscode' -d '{ "req_id" : "request001", "preproc" : "returnJPG", "_date gt 20190202T000000.000Z and _date lt
20190203T000000.000Z and value gt 138 and value lt 139" "gw_limit" : 10 }, |
正しくAPIを発行できた場合、レスポンスとして「200」が返ります。
preprocはエッジにおいて行いたい処理の名前になります。 もしも、エッジにおいて、動画のエンコード方法や圧縮率など検索内容によって異なる前処理を用意したい場合、preprocを異なる名前にすることによって、エッジの前処理を変更することができます。 その場合、エッジはpreprocに応じた前処理を予め用意しておく必要があります。 |
エッジから活用システムに対して検索処理の途中状況通知がある場合に進捗状況を取得することがでできます。なお、進捗状況データの取得は必須ではありませんが、検索処理を円滑に利用したい場合等にご利用ください。
リソース種別 |
リソース_JSON |
リソースパス |
drc/response/progress/$all |
データ形式 |
JSON |
アクセスコードは以下を使用します。
アクセスコード |
drcaccesscode |
リソースパス |
drc |
アクセス権限 |
「CDL」「P」「G」に権限を付与 |
APIを呼び出すのに必要なパラメータは以下の通りです。
HTTPメソッド |
GET |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/response/progress/$all/_past?$filter=req_id eq 'request001' |
BODY |
なし |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X GET -H 'Authorization: Bearer drcaccesscode' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/response/progress/$all/_past?$filter=req_id eq 'request001' |
進捗状況データがあった場合、以下のようなJSON取得できます。
{ "req_id": " request001", "%complete": 50, "gw_id": "gw-001", "date": "20190305T123456.000Z", "num_tasks": 10, "preproc": "returnJPG" } |
検索要求がtimeoutする前に検索要求を中断したい場合は検索要求をキャンセル指定で発行することで中断できます。この場合、該当の検索要求処理は終了しますが、キャンセル時点の検索結果を取得できます。
検索要求をキャンセルしたい場合、以下のリソース_JSONに対して検索キャンセルデータを登録します。
リソース種別 |
リソース_JSON |
リソースパス |
drc/request/search |
データ形式 |
JSON |
アクセスコードは以下を使用します。
アクセスコード |
drcaccesscode |
リソースパス |
drc |
アクセス権限 |
「CDL」「P」「G」に権限を付与 |
APIを呼び出すのに必要なパラメータは以下の通りです。
HTTPメソッド |
PUT |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/request/search |
BODY |
{ "req_id" : "request001", } |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X PUT -H 'Authorization: Bearer drcaccesscode' -d '{ "req_id" : "request001", }' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/request/search' |
正しくAPIを発行できた場合、レスポンスとして「200」が返ります。
活用システムアプリにおいて、検索要求(req_id:request001)を行った結果を取得するケースについて紹介します。エッジは完了するまで5分に1回を目安に定期実行してください。
リソース種別 |
リソース_JSON |
リソースパス |
drc/response/search |
データ形式 |
JSON |
アクセスコードは以下を使用します。
アクセスコード |
drcaccesscode |
リソースパス |
drc |
アクセス権限 |
「CDL」「P」「G」に権限を付与 |
APIを呼び出すのに必要なパラメータは以下の通りです。
HTTPメソッド |
GET |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/response/search/_past?$filter=req_id eq 'request001' |
BODY |
なし |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X GET -H 'Authorization: Bearer drcaccesscode' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/response/search/_past?$filter=req_id eq 'request001' |
検索に成功した場合、data_status_summaryが全件succeededとなります。
7.9.4節にて送信した実データの格納先より実データを取得してください。
{ "req_id" : "request001", "_date gt '20190202T000000.000Z'and _date
lt '20190203T000000.000Z and value gt 138 and value lt 139" "gw_limit" : 10 }, "inprogress" : "false", "gws_status_summary" : { "processing" : 0, "succeeded" : 1, "failed" : 0,
"canceled" : 0 "processing" : 0, "succeeded" : 1, "failed" : 0,
"canceled" : 0 "gw-001" : {
"status" : "succeeded" } |
・verboseをtrue指定して検索要求を実行した場合、req_idによる検索時に複数件の検索結果データがhitします。最新の1件を取得したい場合はtop=1指定を追加してAPIを呼び出してください。 ・検索要求が異常終了した場合はgws_status.error_messageにエラー要因が格納されますので。要因に応じた対処実施をお願いします。要因についてはDRC(オンデマンドデータ収集)インターフェースリファレンスを参照願います。 |
最後に実データを取得します。
実データの送信先として今回は以下のリソースを使いますが、別のリソースや外部のファイルサーバなど自由に使っていただいて構いません。
リソース種別 |
リソース_Binary |
リソースパス |
_bin/jpg |
データ形式 |
バイナリ |
アクセスコードは以下を使用します。
アクセスコード |
JPGaccesscode |
リソースパス |
_bin/jpg |
アクセス権限 |
「U」「R」に権限を付与 |
HTTPメソッド |
GET |
ヘッダフィールド名1 |
Authorization |
ヘッダフィールド値1 |
Bearer JPGaccesscode |
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/_bin/jpg/_present |
BODY |
なし |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
URIの$filter=以降において、非予約文字以外の文字はパーセントエンコードにより置き換える必要があります。「 」(半角スペース)は「%20」、「+」は「%2b」、「'」(シングルクォーテーション)は「%27」、「=」は「%3d」に置き換えてください。
$ curl -i -X GET -H 'Authorization:Bearer JPGaccesscode' 'http://<zone>.fujitsu.com/v1/<テナントID>/_bin/jpg/_present' |
正常完了できた場合、レスポンスとして「200」が返り画像データを取得することができます。
エッジが本機能の指示を読み取り、前処理を行いその結果を本機能へ送信します。
エッジにおける前処理アプリが実施すべき処理の流れについて説明します。
検索指示取得(G) |
↓ 検索指示を定期的に取得し、前処理をすべきか判断します。
前処理の実施 |
↓ idx_ids、preproc、typeに基づき前処理を実施します。
進捗状況の登録(H) 任意 |
↓ 活用システムに対して検索処理状況を通知したい場合に登録します。
実データの送信 |
↓ 前処理した実データ(ここでは画像)を登録します。
送信完了通知(I) |
検索指示取得時に記載されたreq_idを使って実データ送信が終わったことを通知します。
7.9.1. 検索指示取得(G)
エッジが本機能の指示を読み取るAPIの例を紹介します。
エッジは5分に1回を目安に定期実行を行い、指示が更新された場合に7.9.4節の実データの送信を行ってください。なお、検索指示の刈り取り漏れを防ぐために前処理アプリは前回(最終)の検索指示を取得した時刻を覚えておくことを推奨します。
リソース種別 |
リソース_JSON |
リソースパス |
drc/request/clients/gw-001 |
データ形式 |
JSON |
アクセスコードは以下を使用します。
アクセスコード |
drcaccesscode |
リソースパス |
drc |
アクセス権限 |
「CDL」「P」「G」に権限を付与 |
APIを呼び出すのに必要なパラメータは以下の通りです。
HTTPメソッド |
GET |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/request/clients/gw-001/_past?$filter=_date ge <前回取得した指示の_dateの値> |
BODY |
なし |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X GET -H 'Authorization: Bearer drcaccesscode' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/request/clients/gw-001/_past?$filter=_date ge 20190203T013002.123Z ' |
検索指示があった場合、以下のようなJSON取得できます。idx_idsはメタデータ登録時に付与した文字列です。(今回のユースケースの場合はファイル名になっています。)対応する実データを7.9.4節にて送信します。なお、検索指示が2件以上登録されている可能性がありますので、対応する実データの送信についても複数件対処する必要があります。
{ “req_id” : “request001”, “type” : “search”, "preproc" : "returnJPG", “idx_ids” : [ "S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559" ] } |
なお、同じreq_idでも再取得時にtypeがcancelに更新される場合があります。その場合は前処理アプリにて該当req_idの検索処理をキャンセルする作りこみが必要となります。
前処理はお客様で開発されるアプリケーションにて実施ください。前処理として最低限必要な処理は以下のとおりとなります。
1.typeがcancelだった場合は、該当のreq_idで要求されている、idx_idsおよびpreprocに対応した実データ取得処理をキャンセルする。
2.typeがsearchだった場合は、該当のreq_idで要求されている、idx_idsおよびpreprocに対応した実データ取得処理を実行する。
エッジが活用システムに対して検索処理の途中状況を通知したい場合に進捗状況を登録することで通知することができます。なお、進捗状況データの登録は必須ではありませんが、検索処理状況をリアルタイムに通知したい場合等にご利用ください。
リソース種別 |
リソース_JSON |
リソースパス |
drc/response/progress/gw-001 |
データ形式 |
JSON |
アクセスコードは以下を使用します。
アクセスコード |
drcaccesscode |
リソースパス |
drc |
アクセス権限 |
「CDL」「P」「G」に権限を付与 |
APIを呼び出すのに必要なパラメータは以下の通りです。
HTTPメソッド |
PUT |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/response/progress/gw-001 |
BODY |
{ "req_id": " request001", "%complete": 50, "gw_id": "gw-001", "date": "20190305T123456.000Z", "num_tasks": 10, "preproc": "returnJPG" } |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。なお、お客様のご利用状況に応じて追加で他情報を通知したい場合はJSONのkeyを任意に追加して登録しても問題ありません。
$ curl -i -X PUT -H 'Authorization: Bearer drcaccesscode' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/response/progress/gw-001’-d '{ "req_id": " request001", "%complete": 50, "gw_id": "gw-001", "date": "20190305T123456.000Z", "num_tasks": 10, "preproc": "returnJPG" } ’ |
正しくAPIを発行できた場合、レスポンスとして「200」が返ります。
エッジが本機能へ実データを送信するAPIの例を紹介します。
実データの送信先として今回は以下のリソースを使いますが、別のリソースや外部のファイルサーバなど自由に使っていただいて構いません。
リソース種別 |
リソース_Binary |
リソースパス |
_bin/jpg |
データ形式 |
バイナリ |
アクセスコードは以下を使用します。
アクセスコード |
JPGaccesscode |
リソースパス |
_bin/jpg |
アクセス権限 |
「U」「R」に権限を付与 |
HTTPメソッド |
PUT |
ヘッダフィールド名1 |
Authorization |
ヘッダフィールド値1 |
Bearer JPGaccesscode |
ヘッダフィールド名2 |
x-iotpf-meta-data1 |
ヘッダフィールド値2 |
S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559 |
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/_bin/jpg |
BODY |
登録するJPEGファイル(S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559.jpg) |
例えば、LinuxOSの端末からcurlコマンドを用いてAPIを呼び出す場合は以下のように実行します。
$ curl -i -X PUT -H 'Authorization:Bearer JPGaccesscode' -H 'x-iotpf-meta-data1: S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559' --data-binary @./S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559.jpg 'http://<zone>.fujitsu.com/v1/<テナントID>/_bin/jpg' |
正常完了できた場合、レスポンスとして「200」が返ります。
エッジが7.9.4節の実データ送信が終了したことを通知するAPIの例を紹介します。
以下のリソース_JSONに対して送信完了通知データを登録します。
リソース種別 |
リソース_JSON |
リソースパス |
drc/response/sent_flags/gw-001 |
データ形式 |
JSON |
アクセスコードは以下を使用します。
アクセスコード |
drcaccesscode |
リソースパス |
drc |
アクセス権限 |
「CDL」「P」「G」に権限を付与 |
APIを呼び出すのに必要なパラメータは以下の通りです。req_idについては7.9.1節にて読み取ったものをそのまま使用してください。
HTTPメソッド |
PUT |
ヘッダ フィールド名 |
Authorization
|
ヘッダ フィールド値 |
Bearer drcaccesscode
|
URI |
http://<zone>.fujitsu.com/v1/<テナントID>/drc/response/sent_flags/gw-001 |
BODY |
{ "req_id" : "request001", "preproc" :
"returnJPG", } |
正常完了できた場合、レスポンスとして「200」が返ります。
本ドキュメントでは、すべてのメタデータをkey毎に集約し、そのメタデータを元に検索を行う例を説明しました。もしもサービスを利用するにあたって、エッジの規模が極端に大きくなる場合や拠点によって分割してメタデータを管理したい場合、partition_idによってパーティションをわけることにより、メタデータを分割して管理することができます。
本ドキュメントの例ではメタデータは以下のようにメタデータを作成していました。
リソースパス |
概要 |
drc/meta/keys/geo_lng |
経度情報のメタデータ |
drc/meta/keys/geo_lat |
緯度情報のメタデータ |
またメタデータを登録する際は、以下のようなコマンドによって送信されていました。
$ curl -i -X PUT -H 'Authorization: Bearer drcaccesscode' -d '{ "idx_id":"S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559", "gw_id":"gw-001", "_date" : "2019-02-02T01:28:59.024Z", "geo_lng" : 36.12427601168043, "geo_lat" : 138.77760353347315 } }' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/publish' |
もしも、メタデータが増大し、東日本(jp-west)と西日本(jp-east)に分割したい場合事前に以下のようなメタデータを作成します。この時すべてのメタデータに対してすべてのpartition_id(今回はjp-west jp-east)が記載されたリソースを作成してください。
リソースパス |
概要 |
drc/meta/keys/geo_lng |
経度情報のメタデータ |
drc/meta/keys/geo_lat |
緯度情報のメタデータ |
drc/meta/keys/geo_lng/jp-west |
経度情報のメタデータ(東日本用) |
drc/meta/keys/geo_lat/jp-west |
緯度情報のメタデータ(東日本用) |
drc/meta/keys/geo_lng/jp-east |
経度情報のメタデータ(西日本用) |
drc/meta/keys/geo_lat/jp-east |
緯度情報のメタデータ(西日本用) |
メタデータを登録する際は以下のようにpartition_idを追加して登録してください。
$ curl -i -X PUT -H 'Authorization: Bearer drcaccesscode' -d '{ "idx_id":"S2B_MSIL2A_20190202T012859_N0211_R074_T54SUE_20190202T034559", "gw_id":"gw-001", "_date" : "2019-02-02T01:28:59.024Z", "geo_lng" : 36.12427601168043, "geo_lat" : 138.77760353347315 }, }' 'http://<zone>.fujitsu.com/v1/<テナントID>/drc/meta/publish' |
この時、drc/meta/keys/geo_lng/jp-west、drc/meta/keys/geo_lat/jp-westにメタデータは分割・整理され格納されます。
本機能のサンプルプログラムを以下において公開しています。使い方については下記URLをご参照ください。
https://github.com/fjiotpf/drcfs-sample
本プログラムは7章で紹介した人工衛星のエッジに搭載することを想定したサンプルアプリです。本アプリはNode-RED上にて動作し、事前に以下の環境が必要になります。