Riiiverの仕組み
Riiiverの仕組みについて詳しくご紹介します。下の図は「時計のボタンを押すと、現在の気温が時計に表示される」iiideaの仕組みを表したものです。
「時計のボタンを押す→現在の気温をWeb上のサービスから取得→結果を時計の針で示す」という仕組みですが、この実行例では以下の要素が登場します。
iiidea – ユーザーがRiiiver App(iOS/Android)で作成することができる機能のこと。3つのPieceを組み合わせることで作られます。
Piece – iiideaを構成する最小単位の機能パーツ。「Trigger Piece」「Service Piece」「Action Piece」の３種類のPieceがあります。現在の気温を時計で示す仕組みでいうと
- Trigger Piece : 時計のボタンを押す
- Service Piece : 現在の気温をweb上のサービスから取得する
- Action Piece : 気温を時計の針で示す
にそれぞれ分類されます。またiiideaは、Trigger ⇒ Service ⇒ Actionの順番で動作していくため、各Pieceは、前後のPieceとの接続情報等を含みます。
PieceJSON – Pieceの仕様書
PieceCore – Pieceの処理を行う動作部。スマートフォン内にネイティブコードで実装します。
Riiiver SDK – Riiiverを利用する上で必要なライブラリも含むフレームワーク。iiideaに含まれる3つのPieceを順番に処理する実行機能を持ちます（皆さまのiOS/Androidアプリ上でiiideaを実行させる場合に利用します）。
Lambda (AWS) – REST APIのクライアントとしてAWSのLambdaを採用しており、開発者は、Piece実行時にRiiiverが用意したLambda環境を利用することができます（この環境を利用することで、開発者はWeb上のサービスに接続するためのサーバーを各自で準備する必要がなくなります)。 スマートフォンのアプリ開発をしなくてもPieceが開発できるように準備した仕組みであり、利用は任意です(アプリにSDKを組み込んでPiece開発を行う場合は、Lambdaは使用しません)。
PieceJSON
Pieceを作る際には、「前のPieceから何を受け取り、次のPieceに何を出力するのか?」などの定義を行う必要があります。これら定義を定めたPieceの仕様書をPieceJSONと呼びます。
Piece JSONでは、ユーザーがRiiiverアプリでiiideaを作るときに表示される内容を定義しています。
- Pieceの名前 – 上図の「降水確率」にあたる部分。
- Pieceの説明
- Pieceのカテゴリ – Weather & Nature, Communication, Sports & Entertainmentなどのカテゴリごとにアプリ内に表示されます。
また、Pieceの動作まわりの定義も記述されています。
- 入力データ – あるPieceが前のPieceから受け付けることができるデータの型。
- 出力データ – あるPieceが次のPieceに渡すデータの型。
- 設定可能項目 – あるPieceを含むiiideaをユーザーが利用するとき、設定することができる項目の定義。
- 誰がロジックか – このPieceの順番になったら呼ぶべき実体は誰か？
「現在の気温を外部天気APIサービスから取得する」PieceのPieceJSONは以下のようなものになります。
{
"title": {
"en": "Current Temperature (celsius)",
"ja": "現在の気温 (摂氏)"
},
"version": "1.0.0",
"sdkVersion": "1.0.0",
"deviceId": "none",
"vendorId": "none",
"description": {
"en": "~~What is this Piece?~~\nGet the current temperature in degrees Celsius (°C).\n\n~~How do I use it?~~\nInclude this Piece in an iiidea to output a simple number representing the current temperature in °C.\nYou can choose in the iiidea settings for where to get information.\n\n~~Notes~~\nThe output value will be -50 if this Piece cannot get information due to network or a separate error.\n\nAbout Trademarks ( https://riiiver.com/en/trademark/ )",
"ja": "【どんなPiece？】\n現在の気温を摂氏で次のPieceに渡します。\n\n【どうやって使うの？】\n「地域」のドラムロールから、気温を知りたい場所を選択してください。\n\n【ご注意！】\n気温をうまく取得できなかった場合は値が -50 となります。\n\n商標について ( https://riiiver.com/trademark/ )"
},
"blockType": "service",
"executor": "RBCCommonWebServiceExecutor",
"serviceProxy" : {
"service": "pieceCore_sample"
},
"pieceCapability": "notUse",
"preferences": {
"type": "object",
"properties": {
"cityName": {
"type": "string",
"enum": [
"Sapporo-shi",
"Tokyo",
"Osaka",
"Fukuoka-ken",
"Okinawa-ken"
],
"default": "Tokyo",
"x-input-type": "drumroll",
"x-title": {
"ja": "地域",
"en": "Area setting"
},
"x-description": {
"en": "set the area from which to get the temperature.",
"ja": "気温を取得する地域を指定します。"
},
"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",
"minimum": -50,
"maximum": 50
}
}
},
"osType":"none",
"categoryIds": ["cat_0007"]
}上記のJSONに含まれるキーについてご説明します（JSONの各キーの意味については PieceJSON Keys ページをご参照ください）。
title
Pieceのタイトル（名称）を記入します。上記の例では英語、日本語を記入しています。ユーザーがRiiiverアプリを利用してPieceを探す際に、最初に目にする部分が、ここで定義するタイトルですので、分かりやすい名称にしていただくことを推奨しています。
version
Pieceのバージョンをつけます（最初は1.0.0など）。Versionは皆さまが各自で管理をし、Pieceを更新した場合は、バージョンを必ずインクリメントしたうえで公開してください。
sdkVersion
Pieceの実行に必要なSDKのバージョンを指定します（SDKによって実行できる／できないといった制約はまだありませんので、1.0.0としていただく形で問題ありません）。
description
Pieceの説明を書きます。タイトルと同じく、ユーザーがiiideaを作成する場合に目にする説明文です。「このPieceでどんなことができるのか?」「どんな値を入力して出力するのか?」「利用する際に制約事項はないか？（特定の時間帯は動作しないAPIを利用しているなど）」といった、iiideaを作る際にユーザーに説明するべき内容を記載してください。記載に関して、いくつかルールを設けていますのでこちらも併せてご確認ください。
blockType
このPieceがTrigger Pieceなのか、Service Pieceなのか、Action Pieceなのかを指定します。
executor
実際にPieceを動作させるPieceCoreのクラス（モジュール）名を指定します。（Webサービスに接続するServicePieceの場合、Lambdaを使うためのクラスRBCCommonWebServiceExecutorを指定してください。）
serviceProxy
Webサービスに接続するServicePieceの場合、Riiiverが用意したLambdaを利用する際に呼び出す関数名を指定してください。
preferences
ユーザーがこのPieceを含むiiideaを利用時する際に設定できる項目を定義します。上記の例では、「どの地域の現在気温を知りたいか?」ユーザーに地域を指定してもらうためにドラムロールを表示するように定義しています。どのようなUIを設定項目ユーザーに表示できるのかはPreference使用例をご参照ください。
output
Pieceが出力するデータの型を定義します。この例では温度を数字として出力します。他にどのような型が使えるのかはPieceの接続に関する規則をご参照ください。
osType
PieceがスマートフォンのOSに依存する場合、ここで指定できます。iOS/Androidに関わらず動作できるPieceの場合は「none」と指定します。
categoryIds
このPieceが属するカテゴリを指定します。ユーザーがRiiiverアプリでiiideaを作成する場合、Pieceのカテゴリを選択したうえで、Service Pieceを選択します。その際に、ここで指定されたカテゴリ内にPieceが表示されます。
実行時の動作とPieceCore
Pieceを実際に実行するのは、エンドユーザーのスマートフォン内で動作しているRiiiverアプリ内のRiiiver SDKです。ユーザーがiiideaをセットし、Trigger Pieceを作動させたときは、以下の図のような処理が走ります。
この図はiiideaを実行中、ちょうどService Pieceの順番になったときに処理を開始したタイミングのものです。
SDKはService Pieceを実行するときPieceJSONの"exceutor"キーで定義するクラス(インスタンス)を呼び出すことになっています。このクラス内にコードを実装すれば、必要なタイミングでPieceJSONで定義した型の入力データ、ユーザーが設定画面で指定した設定値とともに実行してくれます。
Pieceで行いたい処理が終了したら、クラスから出力データに沿った値を返せば、その値がそのまま次のPieceへと伝えられる仕組みです。この皆さまが記述するコード部分(クラス)をPieceCoreと呼びます。
PieceCoreの実装方法
PieceCoreはスマートフォン内にあります。PieceCoreの実装はAndroidの場合はJavaかKotrin、iOSの場合はSwiftなどのネイティブ環境でのコーディングが必要です。ただし、ほとんどのPieceでは、スマートフォン上の処理だけでは完結せず、コンテキストを取りにWeb上で動作するものが多数になるはずです。RiiiverではPieceを作成する方法を大きく以下の2種類ご用意しております。
（準備中）Riiiver SDKを利用して、スマートフォンのネイティブ開発環境でPieceCoreを作成し、Pieceを完成させる。
PieceCoreの開発はせずに、RiiiverのAWS Lambda環境上にコーディングし、Pieceを完成させる。 （Riiiver SDKに標準搭載されているPieceCoreを利用する。）
またPieceを作る際には、開発者登録が必要です。