Getting Started

2020/03/18

Piece の仕様書

どうも、こんにちは！JellyWareです。

Getting Started!! Riiiver tutorialの第11弾となります。

このシリーズは、Riiiverやプログラミングを学び、初心者の方でもEco-Drive Riiiverを活用したオリジナルアプリを理解して作れるようになることを目指します。

今回から Piece の作成を中心に解説していきます。

Piece は、「PieceJSON」と「PieceCore」の2つで構成されています。まずは、Piece構成要素の1つである「PieceJSON」について説明をします。

PieceJSON とは

Piece 構成要素の1つです。

Piece の仕様書となる部分で、「Piece名」「Pieceが扱う設定値の情報」「次のPieceへ受け渡すデータ形式」などをまとめたものとなります。

名前の通り、JSONで記述されています。(JSONが何か分からない方は、第9弾をご参照ください。)

サンプル

以下、Riiiverのドキュメントに掲載されているサンプルのPieceJSONです。

{
  "title": {
    "en": "Current Temperature (celsius)",
    "ja": "現在の気温 (摂氏)"
  },
  "version": "1.0.0",
  "sdkVersion": "1.0.0",
  "deviceId": "none",
  "vendorId": "none",
  "description": {
    "en": "Current temperature in the setting area",
    "ja": "指定した地域の現在の気温を取得します。うまく取得できなかった場合は値が -1 となります。"
  },
  "blockType": "service",
  "executor": "RBCCommonWebServiceExecutor",
  "serviceProxy" : {
    "service": "citizenSample_OpenWeatherMap"
  },
  "preferences": {
    "type": "object",
    "properties": {
      "cityName": {
        "type": "string",
        "x-description": {
          "en": "set the area from which to get the temperature.",
          "ja": "気温を取得する地域を指定します。"
        },
        "enum": [
          "Sapporo-shi",
          "Tokyo",
          "Osaka",
          "Fukuoka-ken",
          "Okinawa-ken"
        ],
        "x-input-type": "drumroll",
        "default": "Tokyo",
        "x-title": {
          "ja": "地域",
          "en": "Area setting"
        },
        "x-enum-titles": {
          "Sapporo-shi": {
            "ja": "札幌市",
            "en": "Sapporo"
          },
          "Tokyo": {
            "ja": "東京都",
            "en": "Tokyo"
          },
          "Osaka": {
            "ja": "大阪府",
            "en": "Osaka"
          },
          "Fukuoka-ken": {
            "ja": "福岡県",
            "en": "Fukuoka"
          },
          "Okinawa-ken": {
            "ja": "沖縄県",
            "en": "Okinawa"
          }
        }
      }
    }
  },
  "output": {
    "type": "object",
    "properties": {
      "celsiusTemperature": {
        "type": "number"
      }
    }
  },
  "osType":"none",
  "categoryIds": ["cat_0007"]
}

Piece の仕様書として作成する PieceJSON は、Riiiver が定めたフォーマットに従って記述する必要があります。

フォーマット

それでは、PieceJSON のフォーマットについて解説します。今回は必要最低限の内容に留めます。

その他に関しては、今後適宜解説していきます。(気になる方は、公式のリファレンスをご参照ください。)

以下、最低限必要となるkeyとそれに対するvalueについて、1つずつ解説します。

title

Piece の名前を定義します。

Riiiver アプリに表示されることになるため、分かりやすい名前にしましょう。

また、言語毎に名前をつけることができます。「英語の Piece名」は必須なので注意しましょう。(対応している言語の種類はこちらを参照してください。)

"title": {
  "en": "the name of a Piece",
  "ja": "Piece の名前"
}

"title"の型はオブジェクトです。
各言語("en"や"ja")の型は文字列です。

version

Piece のバージョンを定義します。

アプリのアップデートのように、Piece もアップデートすることができます。その際には、同様にPiece のバージョンを上げる必要があります。(バージョン数値の増やし方は、特に指定はありません。)

初めて Piece を作成する場合は、1.0.0を指定します。

"version": "1.0.0"

"version"の型は文字列です。

sdkVersion

Riiiver SDKのバージョンを定義します^※。

Node.js を使用して Piece を開発する場合は、1.0.0を指定すれば問題ありません。

"sdkVersion": "1.0.0"

"sdkVersion"の型は文字列です。

deviceId

Riiiver SDK を利用して自社アプリをRiiiverに対応させる場合、もしくは、固有のデバイス専用の Piece の場合にはデバイスIDを指定します^※。

デバイス固有ではない、汎用的な Piece を作成する場合は指定する必要がないため、"none"とします。

"deviceId": "none"

"deviceId"の型は文字列です。

vendorId

Riiiver SDK を利用して自社アプリをRiiiver対応させる場合、ベンダーIDを指定します。ベンダーIDは、Riiiverに企業アカウントを登録する際に発行されます。^※。

Lambda を使用する場合は"none"とします。

"vendorId": "none"

"vendorID"の型は文字列です。

description

Piece の説明文を定義します。

Riiiver アプリに表示されることになるため、ユーザーに Piece の使い方が伝わるよう分かりやすく説明しましょう。

また、言語毎に説明をつけることができます。「英語の説明文」は必須なので注意しましょう。(対応している言語の種類はこちらを参照してください。)

"description": {
  "en": "the description of a Piece",
  "ja": "ピースの説明"
}

"description"の型はオブジェクトです。
各言語("en"や"ja")の型は文字列です。

blockType

Piece の種類を定義します。

自分の作る Piece に合わせて、"trigger"、"service"、"action"のうちから1つを指定します。

"blockType": "service"

"blockType"の型は文字列です。

executor

PieceCore の名前を定義します。

別途改めて解説をしますが"RBCCommonWebServiceExecutor"という PieceCore を指定することで、Lambda にアップロードしたファイルを実行することができます。

"executor": "RBCCommonWebServiceExecutor"

"executor"の型は文字列です。

serviveProxy

Service / Action Piece のオプションを定義します。

"service"には、Lambda で動作する JavaScript のファイル名を指定します。この key は必須です。

その他に位置情報の取得有無などを指定できます。(詳しくは、こちらを参照してください。)

"serviceProxy" : {
  "service": "serviceSample"
}

"serviceProxy"の型はオブジェクトです。
"service"の型は文字列です。

osType

Piece が依存しているOSを定義します。

"iOS","Android","none"のうちから1つを指定します。"none"は、iOS, Android のどちらにも対応していることを意味します。

"osType":"none"

"osType"の型は文字列です。

categoryIds

Piece のカテゴリーを定義します。

Riiiver アプリに表示されることになるため、適切なカテゴリーを選びましょう。また、各カテゴリーに対応するvalueはこちらを参照してください。

2つまでカテゴリーを選ぶことができます。

"categoryIds": ["cat_0001"]

"categoryIds"の型は配列です。

以上が必要最低限の PieceJSON の memberとなります。まとめると下記の通りになります。

{
	"title": {
		"en": "the name of a Piece",
		"ja": "Piece の名前"
	},
	"version": "1.0.0",
	"sdkVersion": "1.0.0",
	"deviceId": "none",
	"vendorId": "none",
	"description": {
		"en": "the description of a Piece",
		"ja": "ピースの説明"
	},
	"blockType": "service",
	"executor": "RBCCommonWebServiceExecutor",
	"serviceProxy": {
		"service": "serviceSample"
	},
	"osType": "none",
	"categoryIds": ["cat_0001"]
}

みなさんの作成したい Piece に合わせて、この JSON を変更 / 追記していくことになります。

また、現状だと前後の Piece とのやり取りや、ユーザーがアプリから入力するデータについて定義されていません。

そういった場合、どのように JSON を記述すればいいか確認しましょう。

input

前の Piece から受け取るデータやその型を定義します。

"input"を設定すると、PieceCore でデータを受け取ることができるようになります。








"input": {
  "type": "object",
  "properties": {
    "inputData": {
      "type": "number"
    }
  }
}

2行目の"type"は必ず"object"を定義します。

"properties"の型はオブジェクトで、好きな名前をkeyとすることができます。つまり、4行目のinputDataを別の名前に差し替えることができます。

また、5行目の"type"には、「文字列」「数値」「配列」「オブジェクト」「ブーリアン」で受け取るデータの型を指定できます。それぞれ、"string","number","array","object","boolean"を指定します。

"string"の場合、"format"で形式を指定する必要があります。"text","email","date-time","date","time"のうちから適切なのを選びましょう。"number"の場合、"minimum","maximum"で最小、最大値を決める必要があります。指定する範囲は、必ず -1,000,000~1,000,000以内です。

詳しくはこちらをご参照ください。

output

次の Piece に受け渡すデータやその型を定義します。

"output"を設定すると、PieceCore で処理したデータを次の Piece に受け渡せます。








"output": {
  "type": "object",
  "properties": {
    "outputData": {
      "type": "boolean"
    }
  }
}

2行目の"type"は必ず"object"を定義します。

"properties"の型はオブジェクトで、好きな名前をkeyとすることができます。つまり、4行目のoutputDataを別の名前に差し替えることができます。

詳しくはこちらをご参照ください。

preferences

ユーザーがアプリから入力する、Piece の実行に必要なデータを定義します。
例：天気情報を知りたい都道府県名

"preferences": {
  "type": "object",
  "properties": {
    "propertySample": {
      "x-input-type": "text",
      "type": "string",
      "x-title": {
        "ja": "タイトル"
      },
      "x-description": {
        "ja": "説明"
      }
    }
  }
}

"preferences"は長いので、分割して解説します。

まずは、"type"と"preferences"の2つを解説します。

"type": "object",
"properties": {
  ~
}

"type"は必ず"object"を指定します。

"properties"の型はオブジェクトで、アプリに表示させる説明文や入力フォームの種類などを指定します。

次に"properties"内のオブジェクトを解説します。

"propertySample": {
  ~
}

今回は"propertySample"としていますが、key名は自由につけることができます。

PieceCore と紐づく箇所となりますので分かりやすい名前にしましょう。

次に、"propertySample"内のオブジェクトを解説します。

{
  "x-input-type": "text",
  "type": "string",
  "x-title": {
    "ja": "タイトル"
  },
  "x-description": {
    "ja": "説明"
  }
}

この箇所で「入力フォームの種類」「入力データの型」「入力フォームのタイトル」「入力フォームの説明文」などを指定します。
順に"x-input-type","type","x-title","x-description"がkeyです。

タイトルと説明文は、型がオブジェクトで言語毎に設定することができます。

その他、使用できるkeyについてはこちらを参照してください。

入力フォームの種類やデザインについてはこちらを参照してください。

注釈

Riiiver SDK とは、Riiiver と連携するスマートフォンアプリを作成するために用いるツールとなります。
Lambda を経由して実行される Piece を作成する場合は、使用することはありません。

PieceJSON がどういったものをまとめているかイメージが付きましたでしょうか？

参照するものが多く戸惑った方もいるかと思いますが、JSON が間違えていないかチェックするツールもありますので安心してください。(ツールについては別途解説します。)

ご覧くださりありがとうございました。

学習コンテンツ一覧はこちら