データバケット利用ガイド(ファイル受信タイプ)

Data Bucket Guide: File-Receiving Type

データバケット利用ガイド

はじめに

IoT をビジネスに活用するにあたって課題となるのが、IoT デバイスが収集したデータをどうやってサーバーやクラウドに保存するかということです。サーバーやクラウドの構築には専門知識が必要です。また、それにかかる費用や期間も気になるところです。

データバケットでは、クラウドにデータを保存する仕組みを提供します。利用するクラウドには、セキュアで大規模データを高速に処理できる Google Cloud Platform を採用しています。

このデータバケットを使えば、IoT デバイスからのデータを収集・蓄積する仕組みが、サーバーやクラウドに関する専門的な知識を必要とせず、簡単かつスピーディに構築できます。

データバケットとは何か

データバケットは、IoT デバイス(「デバイス」)から送られてくるデータを受け取り、ストレージに保存するクラウド型のシステムを提供します。

データバケット概略図

このシステムは、お客さまの Google Cloud Platform (「GCP」) プロジェクト上に、BLOCKS が自動で構築します。システムの構築(データバケットの作成)に、GCP に関する専門的な知識は不要です。

データバケットのシステムは、お客さまの GCP プロジェクト上に構築するため、BLOCKS の料金とは別に「 GCP サービスの利用料金」が発生します。

データバケットには、データの種類(「タイプ」)に応じて、2 つのタイプあります。

タイプ 説明
メッセージ受信タイプ
  • デバイスから加速度・温度・湿度などの比較的小さなデータ(「メッセージ」)を受け取り、BigQuery のテーブルにデータを保存します。
メッセージ受信タイプ概略図
ファイル受信タイプ
  • デバイスから画像ファイルや音声ファイルなどのファイル形式のデータを受け取り、Google Cloud Storage にファイルを保存します。
  • ログ(ファイル名や保存日時など)を保存できます(オプション)。
  • ファイルの保存を契機に、フローデザイナーのフローを実行します(オプション)。
ファイル受信タイプ概略図

データバケットの作り方

このドキュメントでは、ファイル受信タイプのデータバケットについて解説しています。

メッセージ受信タイプのデータバケットについては、「データバケット利用ガイド(メッセージ受信タイプ)」で解説しています。

<セルフサービスプラン(無料トライアル)の場合>

  • GCP サービスアカウントの役割にオーナー権限が付与されている必要があります。

    GCP サービスアカウントの役割にオーナー権限がない場合は、GCP コンソールの IAM のページにアクセスして、該当する GCP サービスアカウントの役割にオーナー権限を付与してください(図の 1 → 2 → 3 の順)。

    GCP コンソールの IAM 画面

データバケットを作る大まかな流れ

データバケットは、「データバケットとは?」の画面の[利用開始]ボタンをクリックするか、データバケット一覧画面の[追加]ボタンをクリックして、表示される案内に沿って操作するだけで簡単に作れます。

データバケットを作る大まかな流れは、以下のとおりです。

  1. データバケット作成
    データバケットの種類を選択して、名前を設定します。
  2. GCP サービスアカウント設定(セルフサービスプランのみ)
    データバケットで使用する GCP サービスアカウントを設定します。
  3. エントリーポイント設定
    デバイスがデータバケットへデータを送るときの送り先の設定をします。
  4. ストレージ設定
    データバケットが受け取って処理したデータをどう保存するかを設定します。
  5. フローデザイナー連携設定
    データバケットが受け取ったデータをストレージへ保存したときに、実行するフローデザイナーのフローを設定します。
  6. 入力内容の確認
    これまでの設定内容を確認します。

それぞれについて、以降で詳しく解説します。

データバケット作成

初めてデータバケットを作成する場合は、「データバケットとは?」の画面の[利用開始]ボタンをクリックします。

データバケットとは?画面

データバケットがひとつ以上ある場合は、、データバケットの一覧画面左上の[追加]ボタンをクリックします。

データバケット一覧画面

info_outline ライセンス不足の場合は、その旨のメッセージが表示されます(管理者の場合は、ライセンス購入画面を表示)。メッセージが表示された場合は、組織の管理者に問い合わせてください(管理者の場合は、ラインセンスを購入してください)。

続いて、データバケットのタイプを選択して、「次へ」ボタンをクリックします。

データバケットファイル受信タイプ選択

タイプは、以下の説明を参考にして選択してください。

タイプ 説明
メッセージ受信タイプ
  • デバイスから加速度・温度・湿度などの比較的小さなデータ(「メッセージ」)を受け取り、BigQuery のテーブルにデータを保存します。
メッセージ受信タイプ概略図
ファイル受信タイプ
  • デバイスから画像ファイルや音声ファイルなどのファイル形式のデータを受け取り、Google Cloud Storage にファイルを保存します。
  • ログ(ファイル名や保存日時など)を保存できます(オプション)。
  • ファイルの保存を契機に、フローデザイナーのフローを実行します(オプション)。
ファイル受信タイプ概略図

データバケットに付ける名前には、わかりやすい名前をつけておくと、管理しやすくなります。

データバケット(ファイル受信)名前設定

設定が完了したら、「次へ」ボタンをクリックします。

GCP サービスアカウント設定

このステップはセルフサービスプランの場合のみです。

ここでは、GCP サービスアカウントの選択と GCP のサービスを利用するための API を有効にします。

データバケット(ファイル受信)GCP サービスアカウント設定
GCP サービスアカウント選択

使用する GCP サービスアカウントをリストから選択します。

API の有効化

「確認」ボタンの前にチェックマークが付いていない API がある場合は、以下の操作を行います。

  1. チェックマークが付いていない API のリンクをクリックします。
  2. 「Google API Console」画面上部の「有効にする」ボタンをクリックします。
  3. 「有効にする」ボタンが「無効にする」ボタンに切り替わったら、Google API Console の画面を閉じて、BLOCKS の画面に戻ります。

すべての API について、上記操作が終わったら、「確認」ボタンをクリックします。「確認」ボタンの前にチェックマークが付くことを確認してください。

もし、チェックマークが付かない場合は、しばらく時間をおいてから「確認」ボタンをクリックしてください。状況によっては、なかなかチェックが付かない場合もあります。その場合は、チェックマークが付くまで、しばらく時間をおく→「確認」ボタンをクリックする操作を繰り返してください。

が表示される原因としては、以下のことが考えられます。

  • 対象となる API が有効化されていない。
    API 名横の をクリックして、表示されるページで確認します。もし、有効となっていない場合は、有効にします。
  • GCP サービスアカウントの役割が「オーナー」となっていない。
    GCP コンソール メニュー(GCP コンソール左上の )の「IAM と管理」をクリックし、「IAM」で確認します。もし、役割が「オーナー」となっていない場合は、「オーナー」を選択します。
  • 対象となる GCP プロジェクトの課金が有効になっていない。
    GCP コンソール メニュー(GCP コンソール左上の )の「お支払い」で確認します。もし、課金が有効になっていない場合は、課金を有効にします。

設定が完了したら、「次へ」ボタンをクリックします。

エントリーポイント設定

ここでは、エントリーポイントの設定を行います。

データバケット(ファイル受信)エントリーポイント設定

エントリーポイントとは、デバイスがデータバケットへデータを送るときの送り先(データを受け取って処理する部分の受け取り口)のことです。エントリーポイントは、URL で示されます。デバイスは、このエントリーポイント URL に HTTP の POST メソッドでデータを送ります。

エントリーポイント説明図

エントリーポイント URL は、以下のように形式が決まっています。一部のみ自由に設定することができます。

https://magellan-file-<*****>-dot-<プロジェクト ID>.appspot.com

項目 説明
<*****>

このデータバケットのエントリーポイントを特定するための文字列です。自由に設定できます。デフォルトの値は、ランダムな 16 進数文字列です。

  • 使用できる文字は、英小文字(a 〜 z)、数字 (0 〜 9) およびハイフン (-) です。
  • 末尾の文字は、数字か英小文字でなければなりません。
  • 文字数は、プロジェクト ID の長さによって変わり、15 文字から 27 文字までです。

1 つの GCP プロジェクトで、複数のデータバケットを作成する場合は、文字列が重複しないように設定してください。

<プロジェクト ID> GCP プロジェクト のプロジェクト ID が自動で設定されます。変更できません。

設定が完了したら、「次へ」ボタンをクリックします。

ストレージ設定

ここでは、デバイスから送られてきたデータを Google Cloud Storage (「GCS」) のバケットへ保存する設定を行います。また、ファイルの保存履歴(「ログ」)を BigQuery に残すことができるため、その設定もここで行います。

データバケット(ファイル受信)ストレージ設定

「GCS (Google Cloud Storage) バケットの選択」では、GCS 上のどのバケットにファイルを保存するかを設定します。なお、バケットとは、ファイルを保存する GCS 上の領域のことです。バケットは、事前に作成してください。

「オプション設定」では、ログを BigQuery に保存する設定を行います。ログを保存したい場合は、「ログを BigQuery に保存する」をチェックして、ログの保存先とする BigQuery のデータセットとテーブルを指定します。

指定したデータセットやテーブルが存在しなければ、データバケット作成時に自動でデータセットやテーブルを作成します。作成するテーブルでは、gcs_url と timestamp というフィールドが必ず作成されます。

フィールド名 データ型 説明
gcs_url STRING 保存するファイルの GCS URL (gs://バケット名/ファイル名)
timestamp TIMESTAMP ファイルを保存した日時

このほかに、ログに追加で記録したい情報があれば、その情報を記録するスキーマを追加してください。ログに追加で記録したい情報は、データバケットへデータを送るときに、ログに追加で記録したい情報も一緒に送ります。ログに記録したい情報は、「スキーマで追加したフィールド名=記録する情報」という形式で送ります。

例えば、ファイルの所有者情報もログに記録したいとします。スキーマにファイルの所有者情報を記録する「author」フィールドを追加します。デバイスからデータバケットへデータを送るときに、「author=MAGELLAN」というパラメーターを付加します。データバケットは、ログの「author」フィールドに、「MAGELLAN」を記録します。

デーバイスからデータバケットへデータを送る様子の図

なお、テーブルに既存のテーブルが指定された場合は、これらのフィールドがあることを期待します。少なくとも gcs_url と timestamp フィールドがないと、ログ保存時にエラーが発生します。

設定が完了したら、「次へ」ボタンをクリックします。

フローデザイナー連携設定

ここでは、デバイスから送られたデータを GCS にファイルとして保存されたことをきっかけにして、特定のフローデザイナーのフローを実行する設定を行います。

データバケット(ファイル受信)フローデザイナー連携設定

GCS へのファイル保存を契機にフローデザイナーのフローを実行したい場合は、「フローデザイナー連携機能を使用する」をチェックして、実行したいフローを選択します。

フロー実行時には、以下のパラメーターが渡されます。

パラメーター名 説明
gcs_url 保存したファイルの GCS URL (gs://バケット名/ファイル名)
target_time ファイルを保存した UTC 時刻(2016-10-13 12:39:10.234)
filename 保存したファイル名

このほかに、デバイスがデータバケットへ送った上記以外のパラメーターもそのまま渡されます。

データバケットからフローへパラメーターが渡される様子の解説図

連携するフローデザイナーに、「API Token for IoT Board <データバケットの名前>」という説明内容で API トークンが追加されます。この API トークンは削除しないでください(連携できなくなります)。API トークンの説明内容は変更できます。

設定が完了したら、「次へ」ボタンをクリックします。

入力内容の確認

ここでは、これまで設定した内容が確認できます。

データバケット(ファイル受信)入力内容の確認

設定内容に間違いがないかを確認して、もし間違いがあれば「前へ」ボタンをクリックして、間違いを修正する設定画面まで戻ります。設定に間違いがなければ、「完了」ボタンをクリックします。

データバケットの作成には、しばらく時間がかかります。データバケットの作成が完了すると、データバケットの詳細画面に切り替わります。

データバケットへデータを送る方法

デバイスからデータバケットへデータを送るには、HTTP の POST メソッドで「エントリーポイント URL」へデータを送ります。送るデータは、application/x-www-form-urlencoded 形式でエンコードしてください。

デバイスからデータバケットへデータを送るときは、少なくとも以下のパラメーター(「パラメーター名=値」という形式)が必要です。

送る情報 パラメーター名
API トークン key データバケット詳細画面の「API トークン」の値
ファイル名 filename GCS に保存するときのファイル名
ファイルとして送るデータ content Base64 でエンコードしたデータ

このほかに、任意のパラメーターが送れます。フローデザイナーのフローと連携した場合は、データバケットに送る任意のパラメーターは、そままフローにも送られます。

ログに標準以外のフィールドを追加した場合は、フィールド名をパラメーター名としたパラメーターを送ると、ログにそのデータが保存されます。

例えば、以下の仕様でファイルを GCS に保存するとします。

  • テキストファイルを GCS へ保存します。
    • ファイル名は、「sample.txt」とします。
    • ファイルの中身は、「hello, world」という文字列のみとします。
  • ログに追加のフィールド「author」があります。
  • フローデザイナーのフローと連携します。
    • フローでは、外部からの情報を変数 foo で参照します。

デバイスからデータバケットへ送るデータは、以下のとおりです(HTTP ヘッダーは一部のみの例示です)。

POST /upload HTTP/1.1
Content-Type: application/x-www-form-urlencoded

key=d29b76ac16181816ac7bd678&filename=sample.txt&content=aGVsbG8sIHdvcmxkCg%3D%3D&author=MAGELLAN&foo=bar

このときの各パラメーターの意味は、以下のとおりです。

パラメーター 説明
key=d29b76ac16181816ac7bd678 API トークンです。
filename=sample.txt GCS にデータを保存するときのファイル名です。
content=aGVsbG8sIHdvcmxkCg%3D%3D GCS に保存するデータです。「hello, world」という文字列を Base64 でエンコード後、さらに application/x-www-form-urlencoded 形式でエンコードしています。
author=MAGELLAN 任意のパラメーターです。ログの追加フィールド「author」に、「MAGELLAN」という値を保存する目的で使用しています。連携するフローにも渡されます。フローでは、「MAGELLAN」という値を変数「author」で参照できます。
foo=bar 任意のパラメーターです。連携するフローに渡されます。フローでは、「bar」という値を変数「foo」で参照できます。

なお、連携するフローには、「gcs_url」・「target_time」・「filename」というパラメーターも渡されます。詳しくは、「フローデザイナー連携設定」を参照してください。

「エントリーポイント URL」と「API トークン」は、データバケット詳細画面で確認できます。データバケット詳細画面は、確認したいデータバケットの名前をクリックすると表示されます。

GCP サービスの利用料金

データバケットは、ユーザーの GCP プロジェクトに各種 GCP サービスを利用した環境を構築します。

このため、MAGELLAN BLOCKS の料金とは別に GCP の料金が発生します。適用される料金は、サービスごとに異なります。詳しくは、データバケットで使用する各サービスごとの料金ページを参照してください。

データバケットの使い方

ここでは、デバイスからデータバケットへ画像ファイルを送り、フローデザイナーのフローと連携し画像解析する方法を例示します。

作成するデータバケットの仕様

下図は、「データバケット」と「フローデザイナーのフロー」との連携の様子です。

サンプルの概略図
  • デバイスから画像ファイルをデータバケットへ送ります。このとき画像ファイルの所有者情報(「author=MAGELLAN」)も一緒に送ります。
  • データバケットでは、画像ファイルを GCS のバケットに保存し、所有者情報もログ(「author」フィールド)に記録します。
    また、画像ファイルの保存後、フローデザイナーのフローを実行します。
  • フローデザイナーのフローでは、保存された画像を「画像解析」ブロック使って色解析します。解析結果は、「ログへ出力」ブロックを使って、ログに出力します。

データバケットを作る

まず、フローデザイナーのフローを以下の内容で準備します。# 列は、ブロックを上から順につなげる順番を示します。ここでは、「フローの開始」ブロックと「フローの終了」ブロックの記述を割愛していますが必要です。

# ブロック ブロックの設定
1 画像解析
  • GCP サービスアカウント: 適切な GCP サービスアカウント
  • 画像のGCS上のURL: ${gcs_url}
  • 検知する情報: 色解析のみ
2 ログへ出力
  • ログへ出力する変数: _
3 ログへ出力
  • ログへ出力する変数: author

続いて、データバケットは、以下の内容で作ります。実際に試す場合は、バケットやテーブルなどの具体的な値を示しているところは、自由に変えて構いません。

画面 項目 内容
エントリーポイント設定 エントリーポイント URL デフォルトのままとします。
ストレージ設定 GCS バケット 「magellan-iot-sample」とします。
ログ

ログを BigQuery に保存します。

  • データセット: samples
  • テーブル: logs
  • 追加するフィールド: author (STRING 型)
フローデザイナー連携設定 連携 先に作っておいたフローと連携させるため、そのフローデザイナーとフローを選択します。

試してみる

以下のサンプル画像を色解析し、ドミナント・カラーを分析してみます。

ドミナント・カラー分析用サンプル画像

なお、このドキュメントでは、Unix 系の「curl」コマンドと「base64」コマンドをターミルで使って試しています。

まず、画像の準備をします。以下のコマンドを実行します。

curl https://storage.googleapis.com/blocks-docs/basic-guide/image_properties_sample.jpg | base64 -o sample.jpg

「curl」コマンドを使って、サンプル画像ファイルをダウンロードしています。また、「base64」コマンドを使って、Base64 形式にエンコードしています。ファイル名は、「sample.jpg」としています。

続いて、画像ファイルをデータバケットへ送ります。

以下のように「curl」コマンドを使います。API トークン(「key」パラメーター)は、作成するデータバケットごとに異なります。実際に試す場合は、お使いのデータバケットの API トークンに読み替えてください。

curl --data key=d29b76ac16181816ac7bd678 --data filename=sample.jpg --data-urlencode content@sample.jpg --data author=MAGELLAN https://magellan-iot-2edblhnt-dot-magellan-iot-sample.appspot.com/upload

これで、画像ファイルが GCS に保存され、フローデザイナーのフローでその画像が解析されます。以下は、フローの実行ログです。

[2016-10-20 14:01:17.513]  info : Job-37 start
[2016-10-20 14:01:17.535]  info : VersatileVisionApi step start
[2016-10-20 14:01:17.543]  info : VersatileVisionApi: annotate for file gs://magellan-iot-sample/sample.jpg start
[2016-10-20 14:01:19.231]  info : VersatileVisionApi: annotate for file gs://magellan-iot-sample/sample.jpg finished
[2016-10-20 14:01:19.240]  info : VersatileVisionApi step finished
[2016-10-20 14:01:19.273]  info : Print step start
[2016-10-20 14:01:19.284]  info : Variable: '_'
{
  "imagePropertiesAnnotation": {
    "dominantColors": {
      "colors": [
        {
          "pixelFraction": 0.14428461,
          "color": {
            "green": 18,
            "blue": 17,
            "red": 23
          },
          "score": 0.362649
        },
        {
          "pixelFraction": 0.24923818,
          "color": {
            "green": 161,
            "blue": 117,
            "red": 131
          },
          "score": 0.15836251
        },
        {
          "pixelFraction": 0.035149883,
          "color": {
            "green": 164,
            "blue": 95,
            "red": 116
          },
          "score": 0.065103777
        },
        {
          "pixelFraction": 0.0064488696,
          "color": {
            "green": 194,
            "blue": 208,
            "red": 196
          },
          "score": 0.0080435993
        },
        {
          "pixelFraction": 0.12600099,
          "color": {
            "green": 132,
            "blue": 90,
            "red": 104
          },
          "score": 0.094027691
        },
        {
          "pixelFraction": 0.026787613,
          "color": {
            "green": 47,
            "blue": 46,
            "red": 51
          },
          "score": 0.057900768
        },
        {
          "pixelFraction": 0.025795478,
          "color": {
            "green": 137,
            "blue": 71,
            "red": 90
          },
          "score": 0.036577545
        },
        {
          "pixelFraction": 0.027354546,
          "color": {
            "green": 160,
            "blue": 100,
            "red": 125
          },
          "score": 0.02605368
        },
        {
          "pixelFraction": 0.018850543,
          "color": {
            "green": 91,
            "blue": 58,
            "red": 72
          },
          "score": 0.0187341
        },
        {
          "pixelFraction": 0.03351995,
          "color": {
            "green": 136,
            "blue": 78,
            "red": 104
          },
          "score": 0.016537288
        }
      ]
    }
  },
  "gcs_url": "gs://magellan-iot-sample/sample.jpg",
  "timestamp": 1476939676.1383731
}
[2016-10-20 14:01:19.293]  info : Print step finished
[2016-10-20 14:01:19.324]  info : Print step start
[2016-10-20 14:01:19.333]  info : Variable: 'author'
"MAGELLAN"
[2016-10-20 14:01:19.341]  info : Print step finished
[2016-10-20 14:01:19.368]  info : Job-37 finished