Webサービスを利用したpieceを作る

In piece

Webサービスを利用したpieceを作成するときは、ServiceProxyという機構を利用して構成します

ServiceProxyを利用したpieceの構成

  • Service proxyを利用するためのpiece coreとして、RBCCommonWebServiceExecutorがあります
  • RBCCommonWebServiceExecutorは、pieceJSONに記述された次のパラメータをService proxy routerに送ります
    • service
    • parameters
    • preference
  • Service proxy routerは、serviceとして記述されたService proxy coreを呼び出します
  • piece JSONでService proxyを利用するための記述をし、piece coreにRBCCommonWebServiceExecutorを指定します
  • 以下の説明では、RBCCommonWebServiceExecutorを前提とした記述としています

ServiceProxyCoreの作成

  • ServiceProxyCoreは、Amazon Web Services(AWS)が提供している、Lambda上で動作するモジュールです
  • ServiceProxyCoreは、Lambda上で動くように作成する必要があります
  • ServiceProxyCoreの開発言語は、Lambda上で動くものであれば、何でもよいですが、Riiiverとしては、Node.jsを推奨します
  • ServiceProxyCoreのメインルーチンを含むファイルの名称は、ServiceProxyCore名と同一にしてください
    • ServiceProxyCore名には、数字は使えません
    • すでに登録済みのService proxy core名は使用できません。登録時にエラーメッセージが表示された場合はService proxy core名を変更してください

スマホ側からのパラメータ受け取り

  • スマホから送られてくる各種パラメータは、ProxyCoreへは次のようなJSON形式で伝わります。
  • “parameters”フィールドは、PieceJsonのServiceProxy.parametersに指定された情報が送られます。
    以下の例は、PieceJsonのServiceProxy.parametersに”location”が入力されていた場合の例です。
{ 
 "userData": {    
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",    
"userAgent": "xxx" ,    
"credential": "Bearer xxxxxxxxxx"  
},  
"serviceProxy": "proxycorename",  
"properties": {    
"parameters": {      
"location": {        
"latitude": number,        
"longitude": number,        
"altitude": number,        
"verticalAccuracy": number,        
"horizontalAccuracy": number,        
"heading": number,        
"speed": number      
}    
},    
"preferences": {     
 "radius": 1000    
}  
}
}

 

key description
userData ユーザーユニークな情報が入ります
– uuid ユーザーが利用している端末を特定するためのIDただし、アプリのログイン・ログアウトが発生すると変わる場合があります
– userAgent ユーザーが利用している端末のOSとアプリのバージョンを特定するために使います
– credential ユーザーのcredentialです各種Riiiver Server(ここでは主にBlockServer)へのアクセスで必要となります
properties iiidea実行時のパラメータ群です
– parameters ServiceProxyCoreが要求する動的なパラメータ(現在は位置情報のみ)
+ – location iiidea実行時のユーザーの位置情報
– preferences ServiceProxyCore実行時の準静的パラメータpieceJSONに記述したpreferenceの項目

Service proxy coreで利用するRiiiver server API

  • 原則として、AWSのAPIは使用せずに構築してください
  • 以下のAPIを使って、各種情報の出し入れを行うようにしてください

APIリスト

GET /proxyBlockId

Service proxy coreを実行するときに、pieceのIDを取得するために利用します

Parameters(query)

name required type description
serviceProxy true string ServiceProxyCoreの名前。

Responses Example Value

{
  "blockId": "string"
}

POST /ProxyCoreLog

Service proxy core実行時のログは本APIを使って蓄積してください
蓄積したログは、 GET /ProxyCoreLogで取得可能です

Parameters(query)

name required type description
blockId true string blockId

Parameters(body)

name required type description
created true string 発生時刻(UTC)
message true string ログメッセージ

Responses Example Value

{
  "logs": [
    {
      "created": "string",
      "message": "string"
    }
  ]
}

DELETE /ProxyCoreLog

蓄積したログを削除するときに利用します

Parameters(query)

name required type description
blockId true string blockId
date false string 削除するログの日付(UTC)
例: 2018-12-31

GET /clientAuthInfo

ユーザーAuthが必要なWebAPIを利用するときに、ユーザーのAuth情報(access token等)を取得するときに利用します

Parameters(header)

name required type description
User-Agent true string User-Agent

Parameters(query)

name required type description
blockId true string blockId
uuid true string クライアントを識別するUUID。

Responses Example Value

{
  "apiKey": "string",
  "oauth2": {
    "access_token": "string",
    "expires_in": 0,
    "scope": "string",
    "refresh_token": "string"
  },
  "other": "string"
}

PUT /updateOAuthToken

ユーザーAuthがOAuth2.0であるときで、かつ、clientAuthInfoで取得した access token が期限切れになっていた場合に利用します

piece serverで、 refresh token を使って、 access token の更新を行います

本APIが失敗した時はエラー処理をするようにしてください

Parameters(header)

name required type description
User-Agent true string User-Agent

Parameters(query)

name required type description
blockId true string blockId
uuid true string クライアントを識別するUUID。

Parameters(body)

name required type description
refresh_token true string blockId
uuid true string リフレッシュトークン

Responses Example Value

{
  "access_token": "string",
  "expires_in": 0,
  "scope": "string",
  "refresh_token": "string"
}

HTTPステータスコード

ステータスコード description
200 取得成功
201 保存成功
204 削除成功
400 パラメータ不正
401 API認証失敗
404 情報が存在しないい

スマホへの実行結果返却

  • スマホへ返却する実行結果は、そのbody部分がそのままpieceのoutputにマッピングされます
  • 具体的なレスポンスボディは下記のように組み立ててください
{
  "status": HTTPステータスコード,
  "body":{
    "key": value
  }
}
  • keyはpiece JSONのoutputに記載したkey名を指定してください
  • 返却する実行結果がなかった場合は、下記のようにbodyの中身は空としてください
{
  "status": 200,
  "body":{
  }
}
  • エラーが発生した場合も、下記のようにbodyの中身は空としてください
{
  "status": 400,
  "body":{
  }
}

Service proxy coreの動作検証

  • Riiiverでは、開発途中のものを動作確認するための環境は準備しません
  • 以下のような環境で、動作を検証してください
    • 自前で構築したNode.js実行環境
    • 自前で契約したAWS Lambdaでの実行

Service proxy coreのパッケージング

  • ソースコードが固まったら、実行に必要なライブラリ群とメインソースをまとめて、ZIPで圧縮します
  • この際、パスワードはかけないでください
  • ZIPファイル直下に、メインソースが含まれるようにしてください
SampleProxyCore.ZIP
+ SampleProxyCore.js
+ node_modules
  + ...

 

ServiceProxyCore実装禁止事項

  • AWSのAPIは利用しないでください
  • 外部Webサービス接続時は、公序良俗に反するようなサービスは利用しないでください
  • 外部API等を利用する場合は、リダイレクトされるようなAPIは利用しないでください
  • 他のServiceProxyCoreと接続しないでください
  • ログ出力を通して、個人情報を取得しないようにしてください
  • 必要以上にログを出力しないようにしてください

ServiceProxyCoreの審査

  • ServiceProxyCoreは次のような観点で審査します
  • pieceJSONに記述したservice名と名称が一致しているか
  • AWSのAPIを呼び出している箇所がないか
  • 他のLambda関数を呼び出す箇所がないか
  • 外部サービスのURLが正当なものか
    • リダイレクトされるようになっていないか
  • OAuth等が必要な場合に、ServerのAPIを適切に呼び出しているか
  • 外部にユーザー情報を送信するような箇所がないか
  • ログ出力は適正化されているか