Miniviz クイックスタートガイド（AI用）

📋 このドキュメントについて

このドキュメントは、Miniviz（IoTシステム向けBIプラットフォーム）の使用方法に関する完全なガイドです。AIに質問する際に、このドキュメント全体を貼り付けて使用してください。

使用方法:

  1. このドキュメント全体をコピーしてAIに貼り付ける
  2. 「Minivizで〇〇を実装したい」「MinivizのAPIで△△を送信する方法は？」など、具体的な質問をする
  3. AIはこのドキュメントの内容を参照して回答します

このドキュメントに含まれる情報:

  • Minivizの基本的な使用方法（7ステップ）
  • データ送信APIの完全な仕様（エンドポイント、リクエスト形式、制約事項）
  • 画像送信APIの完全な仕様（Proプランのみ）
  • サンプルコード（curl、Python）
  • データ型の制約と制限事項

重要事項:

  • データ送信API: POST https://api.miniviz.net/api/project/{project_id}?token={token}
  • 画像送信API: POST https://api.miniviz.net/api/project/{project_id}/image?token={token} (Proプランのみ)
  • ペイロード制約: 最大8キー、400バイトまで、フラット構造のみ（ネスト不可）
  • 画像制約: 200KBまで、60秒/枚、JPEG/PNGのみ

全体の流れ

全体の流れ

  1. Minivizアカウント作成/ログイン
  2. プロジェクト作成
  3. (デバイス側)データ送信
  4. データの確認(データベース)
  5. グラフ作成
  6. 通知設定
  7. (Proプランのみ)画像送信

1. Minivizアカウント作成/ログイン

メールアドレス・パスワードを入力して新規登録するか、既存のアカウントでログインします。

2. プロジェクト作成

データを管理するためのプロジェクトを作成します。

プロジェクトID・トークンのコピー

次項で必要になるため、プロジェクトID・トークンをコピーしておきます。

  • プロジェクト画面の右側のトークンアイコンをクリック
  • プロジェクトIDとトークンが表示されるので、これらをコピー
  • ここでコピーしたトークンは、デバイス側で使用します

3. (デバイス側)データ送信

デバイス側でデータを送信します。 まずはcurlコマンドや簡易のPythonスクリプトでデータ送信できるか確認することをお勧めします。

APIエンドポイント 

POST https://api.miniviz.net/api/project/{project_id}?token={token}

リクエスト概要

Miniviz API へのデータ送信は POST メソッドを使用します。送信ボディは JSON 形式です。

リクエストボディ

フィールド名 型 必須 説明
timestamp number Yes 送信時刻（UNIX 時間ミリ秒）
label_key string Yes デバイス名や設置場所など、送信元を識別するラベル
payload object Yes 実際に送信する計測値。キーに任意の指標名、値に数値または文字列を指定

データ型の制約

受け入れ可能なデータ型

文字列型（str）

  • 制約なし（文字数制限はない）
  • 例: "device-001", "温度センサー", "Hello World"

数値型

  • 整数型（int）: 制約なし（範囲制限はない）
  • 浮動小数点数型（float）: 制約なし（範囲制限はない）
  • 例: 42, -10, 3.14, -99.9

受け入れ不可な型

以下の型は payload の値として使用できません：

  • 辞書（dict）: ネストされたオブジェクトは不可
  • 配列（list, tuple, set）: 配列型は不可
  • 真偽値（bool）: 不可（文字列の "true"/"false" または数値 1/0 を使用）
  • null/None: 不可

ペイロード全体の制約

  • キー数: 最大8個
  • サイズ: JSONエンコード後で最大400バイト
  • 構造: フラット（ネスト不可）

リクエスト例 

{
  "timestamp": 1731129600000,
  "label_key": "raspberry_pi_home",
  "payload": {
    "temperature": 25,
    "humidity": 55,
    "switch": "true",
    "system_status": "running"
  }
}

curlコマンド(Linux/MacOS) 

timestamp_ms=$(( $(date -u +%s) * 1000 ))

curl -X POST \
  "https://api.miniviz.net/api/project/{project_id}?token={token}" \
  -H "Content-Type: application/json" \
  -d "{
        \"timestamp\": ${timestamp_ms},
        \"label_key\": \"Local_PC\",
        \"payload\": {
          \"temperature\": 25,
          \"humidity\": 55,
          \"switch\": \"true\",
          \"system_status\": \"running\"
        }
      }"

Pythonサンプルコード

Pythonを使用する場合は、以下のようなコードでデータを送信できます：

import time
from datetime import datetime, timezone
import requests

PROJECT_ID = "MINIVIZ_PROJECT_ID"
TOKEN = "MINIVIZ_API_TOKEN"
API_URL = "https://api.miniviz.net"
LABEL_KEY = "Local_PC"
SEND_INTERVAL = 90  # seconds

def send_data():
    url = f"{API_URL}/api/project/{PROJECT_ID}?token={TOKEN}"
    timestamp_ms = int(datetime.now(timezone.utc).timestamp() * 1000)

    response = requests.post(url, json={
        "timestamp": timestamp_ms,
        "label_key": LABEL_KEY,
        "payload": {
            "temperature": 25,
            "humidity": 55,
            "switch": "true",
            "system_status": "running"
        }
    })

    if response.ok:
        data = response.json()
        print(f"Send successful (id={data.get('id')})")
    else:
        print(f"Send failed: {response.status_code} {response.text}")

if __name__ == "__main__":
    print("Starting miniviz data send test (press Ctrl+C to stop)")
    while True:
        send_data()
        time.sleep(SEND_INTERVAL)

4. データの確認(データベース)

Databaseメニューからデータを確認します。 送信されたデータはデータベースに保存されます。

注意: ここに表示されない場合はデータ送信が失敗しています。再度デバイス側のログなどを確認してください。

5. グラフ作成

Visualizeメニューからグラフを作成します。 グラフの種類やデータの表示形式などを設定できます。

  • グラフタイプを選択（ラインチャート、バーチャートなど）
  • データソースとして送信したデータを選択
  • グラフが正常に表示されることを確認

6. 通知設定

SlackやWebhookなどの通知先を設定します。 Rulesメニューから通知設定を行います。

Slack通知設定

  1. Rulesメニューから通知設定を行う
  2. SlackのWebhook URLを入力
  3. 閾値や条件を設定
  4. 設定した閾値を超えた場合に通知が行われる

7. 画像送信（Proプランのみ）

Proプランでは画像送信APIを用いて画像を送信することができます。

APIエンドポイント 

POST https://api.miniviz.net/api/project/{project_id}/image?token={token}

リクエスト概要

Miniviz API への画像送信は POST メソッドを使用します。送信ボディは JSON 形式です。画像データは base64 エンコードして送信します。

リクエストボディ（画像送信）

フィールド名 型 必須 説明
timestamp number Yes 送信時刻（UNIX 時間ミリ秒）
label_key string Yes デバイス名や設置場所など、送信元を識別するラベル（128文字以内、[A-Za-z0-9-_.:@/]のみ）
image_name string Yes 画像ファイル名（255文字以内）
image_base64 string Yes base64エンコードされた画像データ（200KBまで）

制限事項

画像サイズと形式

  • 画像サイズ: 1枚あたり200KBまで（base64エンコード後のサイズ）
  • 対応形式: JPEG、PNGのみ
  • 送信周期: 60秒/枚（ラベルキー別に管理）
  • 保存期間: 30日間

※エクスポート機能は2025年12月末頃に公開予定です。

プラン制限

  • 利用可能プラン: Proプランのみ（無料プランでは403エラー）

リクエスト例（画像送信） 

{
  "timestamp": 1717587812345,
  "label_key": "camera_1",
  "image_name": "image.jpg",
  "image_base64": "base64_encoded_image_data"
}

curlコマンド(Linux/MacOS) - 画像送信 

timestamp_ms=$(( $(date -u +%s) * 1000 ))

# 画像ファイルをbase64エンコード
image_base64=$(base64 -i image.jpg)

curl -X POST \
  "https://api.miniviz.net/api/project/{project_id}/image?token={token}" \
  -H "Content-Type: application/json" \
  -d "{
        \"timestamp\": ${timestamp_ms},
        \"label_key\": \"camera_1\",
        \"image_name\": \"image.jpg\",
        \"image_base64\": \"${image_base64}\"
      }"

Pythonサンプルコード - 画像送信 

import requests
import base64
import os
from datetime import datetime, timezone

PROJECT_ID = "PROJECT_ID"
TOKEN = "TOKEN"
API_URL = "https://api.miniviz.net"
IMAGE_PATH = "image.jpg"
LABEL_KEY = "camera_1"

# 画像をbase64エンコード
with open(IMAGE_PATH, "rb") as f:
    image_data = f.read()
image_base64 = base64.b64encode(image_data).decode('utf-8')

# リクエスト送信
url = f"{API_URL}/api/project/{PROJECT_ID}/image"
payload = {
    "timestamp": int(datetime.now(timezone.utc).timestamp() * 1000),
    "label_key": LABEL_KEY,
    "image_name": os.path.basename(IMAGE_PATH),
    "image_base64": image_base64
}

try:
    response = requests.post(url, json=payload, params={"token": TOKEN})
    response.raise_for_status()
    print("✅ Send successful")
    print(response.json())
except requests.exceptions.HTTPError as e:
    print(f"❌ Error: HTTP {e.response.status_code}")
    print(e.response.text)
except Exception as e:
    print(f"❌ Error: {e}")

画像の確認

  • データベースページから送信された画像をプレビューすることができます
  • グラフ作成ページから画像をグラフに表示することもできます
    • [新しいグラフ作成] -> [グラフの種類を選択] -> [image]を選択

まとめ

Minivizは以下の機能を提供します：

  1. データ送信: IoTデバイスからセンサーデータを送信
  2. データ可視化: データベースでデータを確認
  3. グラフ作成: 送信したデータをグラフで可視化
  4. 通知設定: 閾値を超えた場合にSlackやWebhookで通知
  5. 画像送信: Proプランで画像データを送信・可視化

APIエンドポイント:

  • データ送信: POST https://api.miniviz.net/api/project/{project_id}?token={token}
  • 画像送信: POST https://api.miniviz.net/api/project/{project_id}/image?token={token}

制約:

  • ペイロード: 最大8キー、400バイトまで
  • 画像: 200KBまで、60秒/枚、Proプランのみ
This site uses Just the Docs, a documentation theme for Jekyll.