データフォーマット

「さくらのモノプラットフォーム」で提供されるデータフォーマットについて説明します。

[更新: 2022年10月06日]

上り通信（プラットフォームからクラウドアプリケーション）

さくらのモノプラットフォームでは、サービスアダプタとクラウドアプリケーション間で所定のデータフォーマットを使ってやりとりが行われます。なお、アプリケーションに送られるデータはJSON形式であり、エンコード方式はUTF-8です。また、1バイトは1オクテットです。

さくらのモノプラットフォームのデータフォーマット（本ページで記載しているJSONの値は仮のものです）

{
    "id": "abcdef12-3456-abcd-1234-abcde1234567",
    "device_id": "1234567890",
    "timestamp_src": "2022-03-24T00:00:00.000Z",
    "timestamp_platform_from_src": "2022-03-24T00:00:00.000Z",
    "timestamp_platform_to_dst": "2022-03-24T00:00:00.000Z",
    "type": "object",
    "payload": [
        {
            "type": "uint8",
            "tag": "00",
            "value": 60
        },
        {
            "type": "float32",
            "tag": "01",
            "value": 20.5
        },
        {
            "type": "binary",
            "tag": "fe",
            "value": "bW9ub3BsYXRmb3Jt"
        },
        {
            "type": "string.utf8",
            "tag": "ff",
            "value": "サンプル_monoplatform"
        }
    ]
}

さくらのモノプラットフォーム上り通信データ項目
フィールド名	型	意味
id	string	デバイスから転送された一連のデータに対して付与される一意の転送ID（UUID）です。このIDはデバイス側にも通知されます。
device_id	string	送信元を一意に識別するためのIDです。
timestamp_src	string	デバイス側でユーザが設定したデータ送信時の時刻です。 RFC 3339 （ISO 8601）に準拠した文字列形式（ミリ秒精度）なので、PHPやJavaScript等の各種言語で簡単に読み込めます。時刻はUTCで送信されます。
timestamp_platform_from_src	string	デバイスから送信されたデータをモノプラットフォームが受信した時点のプラットフォーム側の時刻です。 RFC 3339 に準拠した文字列形式（ミリ秒精度）です。時刻はUTCで送信されます。
timestamp_platform_to_dst	string	モノプラットフォームからアプリケーション側に向けてデータが送信された時点のプラットフォーム側の時刻です。 RFC 3339 に準拠した文字列形式（ミリ秒精度）です。時刻はUTCで送信されます。
type	string	データの種類を表す文字列です。詳細は別表を参照ください。
payload	Array	デバイスから送信されたデータ（バイナリ表現）の解析結果が入った配列です。配列内に格納される連想配列を「オブジェクト」と呼びます。
payload[].type	string	データの形式を表す文字列です。詳細は Payload詳細を参照ください。
payload[].tag	string	データの種類を表す文字列表現です。現時点ではデバイスから送信されたタグの数値（1バイト）を16進文字列にしたものです。
payload[].value	※	データの値です。typeによって型が異なります。 valueの最大サイズはオブジェクトごとに255バイトです。

さくらのモノプラットフォームtype詳細
type	意味
object	デバイスから送られたデータ
keepalive	接続維持のためにWebSocketサーバから定期的に送られるデータ（読み捨てても問題ありません）

下り通信（クラウドアプリケーションからプラットフォーム）

クラウドアプリケーションからプラットフォームに対する通信も上り通信と同じフォーマットで行います。なお、JSONデータはコンパクトなバイナリデータに変換されてデバイス側に送信されますが、このバイナリデータ全体の長さが1024バイト以下でなければいけません。

バイナリデータについては SIPF Object protocol コマンド構造を参照ください。

{
    "device_id": "1234567890",
    "type": "object",
    "timestamp_src": "2022-03-24T00:00:00.000Z",
    "payload": [
        {
            "type": "uint8",
            "tag": "00",
            "value": 60
        },
        {
            "type": "float32",
            "tag": "01",
            "value": 20.5
        },
        {
            "type": "binary",
            "tag": "fe",
            "value": "bW9ub3BsYXRmb3Jt"
        },
        {
            "type": "string.utf8",
            "tag": "ff",
            "value": "サンプル_monoplatform"
        }
    ]
}

さくらのモノプラットフォーム下り通信データ項目
フィールド名	型	意味	省略時の挙動
device_id	string	送信元を一意に識別するためのIDです。	省略不可
type	string	データの種類を表す文字列です。下りではobjectを指定します。	省略不可
timestamp_src	string	クラウドアプリケーションからデータ送信時の時刻を設定してデバイス側に伝えることができます(タイムゾーンはUTCのみ)。 RFC 3339 （ISO 8601）に準拠した文字列形式（ミリ秒精度）なので、簡単にセットできます。	"1970-01-01T00:00:00.000Z"
payload	Array	デバイスから送信されたデータ（バイナリ表現）の解析結果が入った配列です。配列内に格納される連想配列を「オブジェクト」と呼びます。	省略不可
payload[].type	string	データの形式を表す文字列です。詳細は Payload詳細を参照ください。	省略不可
payload[].tag	string	データの種類を表す文字列表現です。現時点ではデバイスから送信されたタグの数値（1バイト）を16進文字列にしたものです。	省略不可
payload[].value	※	データの値です。typeによって型が異なります。 valueの最大サイズはオブジェクトごとに255バイトです。	省略不可

Payload詳細について 

上り、下りのデータ形式を表す文字列で以下を示します。

さくらのモノプラットフォーム payload[].type詳細
type	valueの型	意味
uint8	number	8ビット符号なし整数
int8	number	8ビット符号つき整数
uint16	number	16ビット符号なし整数
int16	number	16ビット符号つき整数
uint32	number	32ビット符号なし整数
int32	number	32ビット符号つき整数
uint64	number	64ビット符号なし整数
int64	number	64ビット符号つき整数
float32	number	32ビット浮動小数点数（IEEE754 単精度）
float64	number	64ビット浮動小数点数（IEEE754 倍精度）
binary	string	可変長バイト列（バイト列をBase64でエンコードした文字列）
string.utf8	string	可変長文字列（UTF8文字列）

下り通信のレスポンスについて（クラウドアプリケーションからプラットフォーム）

クラウドアプリケーションからプラットフォームに対する通信のレスポンスについて記載します。正常に送信できた場合、下記のようなレスポンスが返ってきます

{
    "device_id": "1234567890",
    "type": "notify",
    "id": "abcdef12-3456-abcd-1234-abcde1234567"
}

さくらのモノプラットフォームレスポンス詳細
device_id	string	デバイスID
type	string	レスポンスタイプ
id	string	メッセージに対するuuid

クラウドアプリケーションからのフォーマットが間違っている場合、メッセージフォーマットの誤りが通知され、プラットフォームはメッセージの受信を行いません以下にレスポンスエラーの例を示します。

{
     "type": "error",
     "timestamp": "2022-01-01T00:00:00.000Z",
     "payload": {
          "error": "Validation Error",
          "detail": "Validation Error: invalid type \"string.utf\".\nPlease set correct type (ex. \"uint8\")."
     }
}

さくらのモノプラットフォームレスポンスエラー詳細
フィールド名	型	意味
type	string	メッセージの型
timestamp	string	プラットフォーム返信時刻
payload[].error	string	エラータイプ
payload[].detail	string	エラー詳細

現状実装しているレスポンスエラー一覧は以下です。

さくらのモノプラットフォームレスポンスエラー一覧
payload[].detail	原因と対策
message unmarshall failed, please set correct json value	メッセージの解釈に失敗しました。メッセージフォーマットを確認してください。
timestamp_src error, please set correct RFC3339 format (got "2022-01-01")	timestamp の解釈に失敗しました。 RFC3339 のフォーマットに従って時刻をセットしてください。（上記数値はサンプルです
payload unmarshall failed, please set correct json value	ペイロードの解釈に失敗しました。ペイロードフォーマットを確認してください。
invalid type..."SAMPLE_TYPE". please set correct type..ex) uint8..uint16	SAMPLE_TYPEは不正なペイロードの型です。データフォーマットを確認し、正しい型をセットしてください。
invalid encoded binary, please encode by base64	base64以外のバイナリフォーマットです。
this object has No Tag	メッセージにタグが含まれておりません。
invalid tag format...."SAMPLE_TAG" tag must be '00' ~ 'FF'	タグフォーマットが不正です。 '00' ~ 'FF' を指定してください。

下り通信のレートリミットについて（クラウドアプリケーションからプラットフォーム）

クラウドアプリケーションからプラットフォームに対しては、一定のリクエスト数を超えるとプラットフォームがメッセージの受信や接続を受け付けません。

さくらのモノプラットフォームレートリミット一覧
コンポーネント	対象	間隔と実行動作
WebSocket	デバイスIDごと	30秒ごとに300回メッセージ送信時初回送信時から30秒後にリミット解除
WebSocket	デバイスIDごと	30秒ごと10回アプリケーションからの接続要求時初回接続時から30秒後にリミット解除
Incoming Webhook	デバイスIDごと	30秒ごとに300回メッセージ送信時初回送信時から30秒後にリミット解除