送信データについて

データを送信するには、JSON を https://gw.machinist.iij.jp/endpoint に POST します。
送信するリクエストの header、body、及びレスポンスの内容は以下の通りです。

リクエスト

name value 必須 概要
Content-Type application/json o 固定文字列
Authorization Bearer ${your_api_key} o "Bearer " + ユーザのAPI key

body

{
  "agent": "${your_agent_name}",
  "metrics": [
    {
      "name": "temperature",
      "namespace": "Environment Sensor",
      "tags": {
        "tag_name": "tag_value"
      },
      "data_point": {
        "timestamp": 1470276000,
        "value": 27.6,
        "meta": {
          "latitude": "35.7020235",
          "longitude": "139.7450879000004"
        }
      }
    }
  ]
}
body の JSON のプロパティについて
property type 必須 概要
agent string o Agent の名前
metrics array:object o 送信する Metric の配列(256件まで)
  • 上記表の type は JSON の型を示しています。
  • agent プロパティの代わりに、Agent の ID を指定する agent_id プロパティを指定することも可能です。Agent の ID は エージェント 画面の一覧にて確認してください。
    • Agent の名前を変更する可能性がある場合は agent_id を指定したデータ投稿を推奨します。そうすることで、Agent の名前を変更した後でも同じメトリックとして認識します。
metrics 内の各オブジェクトのプロパティについて
property type 必須 概要
name string o 送信する Metric 名
namespace string x 送信する Metric の Namespace 名
tags object x Metric に付与するタグ、文字列のキーと値のペア(8件まで)
data_point object o 送信するデータ情報
  • 上記表の type は JSON の型を示しています。
data_point 内の各オブジェクトのプロパティについて
property type 必須 概要
value number o 送信するデータの値
timestamp number x 送信するデータのタイムスタンプ、UNIX timestamp 形式
meta object x 送信するデータの付加情報、文字列のキーと値のペア(8件まで)
  • 上記表の type は JSON の型を示しています。
特殊な meta プロパティについて
key(文字列) value(文字列) 概要
latitude -90° ~ 90° 地図の表示 に用いる緯度の値
longitude -180° ~ 180° 地図の表示 に用いる経度の値

curl コマンドによるデータ投稿のサンプル

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${your_api_key}" https://gw.machinist.iij.jp/endpoint -d @${json_file}

レスポンス

結果 ステータスコード 概要
OK 200 データの送信に成功しました
Bad Request 400 リクエストのフォーマットが不正です
Unauthorized Access 401 認証に失敗しました
Conflict 409 リソース利用上限数に達しています
Unprocessable Entity 422 リクエストボディのパラメータに問題があります
Too Many Requests 429 単位時間あたりの送信回数が規定値を超えています
  • エージェント数、及びメトリック数はユーザ毎に作成可能上限数が存在します。
    これを超過した場合、データの投稿が拒否されます(ステータスコード: 409)。
    このリソースの利用状況は アカウント設定 ページにて確認できます。
    リソースを削除することで新たなエージェントやメトリックが投稿できるようになります。
  • 1エージェントあたりの1分間のデータの送信可能回数は120回です。
    これを超過するとデータの投稿が最大1分間拒否されます(ステータスコード: 429)。
  • 1メトリックあたりのデータの保存可能間隔は1分です。
    1分以内に同一メトリックのデータを複数回投稿すると、データが上書きされます。

body

データの送信に失敗した場合、errors プロパティにエラーメッセージが格納されます。

例1: 成功した場合

{
  "message": "Succeeded"
}

例2: APIキーが不正な場合

{
  "message": "Unauthorized Access",
  "errors": [
    {
      "detail":"Bad credentials."
    }
  ]
}