貯蔵庫への永続化用のAPIを提供する

kujirahand commented 6 months ago

貯蔵庫APIとは、貯蔵庫へデータを保存できるAPIです。

概要 - 貯蔵庫APIとは？

ユーザー独自のデータを保存するuser_dbと、アプリ独自のデータを保存するapp_dbの二種類から構成される貯蔵庫のAPIです。

何に使えるの？

ユーザー毎に保存できるuser_dbを使えば、そのユーザーだけが見られるTODOアプリを作ったり、ユーザー専用のメモ帳を作ったりできます。
アプリに共通のapp_dbを使えば、WEB掲示板を作ったり、ゲームのスコア用ランキングを作ったりできます。

user_dbとは？

user_dbは、そのアプリ内でユーザー毎に割り振られた専用の永続化ストレージです。
- ただし、別のユーザーのストレージを見ることはできません。
- ただし、同じユーザーでも別のアプリのストレージを見ることはできません。
基本的な「キーと値のペア」と大量のデータの読み書きが可能な「アイテムDB」を使ってデータの出し入れが可能です。
ユーザーがAPIを利用するには、貯蔵庫へのログインが必要です。
内容はブラウザ上ではなくサーバーに保存されます。
なでしこ版クラウドストレージ(OneDrive/Google Driveなど)の文字列版と思うと分かりやすいかも。

app_dbとは？

app_dbは、アプリ独自の保存領域です。
- 別のアプリは、別のアプリのストレージを見ることはできません。
内容はサーバーに保存されます。
掲示板アプリやスコアデータの記録に使えます。（ただし、不正対策などは考慮していません）
基本的な「キーと値のペア」と大量のデータの読み書きが可能な「アイテムDB」を使ってデータの出し入れが可能です。
ユーザーがAPIを利用するには、貯蔵庫へのログインが必要です。

使い方は？

貯蔵庫APIのデモを作成しました。こちらのデモを確認してください。

最初に以下の宣言を記述すると、貯蔵庫APIが利用可能になります。

# 以下の宣言で便利なライブラリを取り込む
!「https://n3s.nadesi.com/plain/api.nako3」を取り込む。

まずはデモを確認してください。

使えるなでしこの命令

以下のような関数が利用できます。

# --- APPキー ---
●APPキー一覧取得
●(KEYの)APPキー取得
●(KEYにVALUEを)APPキー設定
●(KEYを|KEYの)APPキー削除
# --- APPアイテム ---
●(KEYにVALUEを)APPアイテム追加
●(KEYのOFFSETからLIMITだけ)APPアイテム取得
●(KEYのOFFSETからLIMITだけ)APPアイテム末尾取得
●(KEYのIDを)APPアイテム削除
●(KEYのIDをVALUEに|VALUEへ)APPアイテム更新
# --- USERキー ---
●USERキー一覧取得
●(KEYの)USERキー取得
●(KEYにVALUEを)USERキー設定
●(KEYを|KEYの)USERキー削除
●(KEYを|KEYの)USERキー全削除
# --- USERアイテム ---
●(KEYにVALUEを)USERアイテム追加
●(KEYのOFFSETからLIMITだけ)USERアイテム取得
●(KEYのOFFSETからLIMITだけ)USERアイテム末尾取得
●(KEYのIDを)USERアイテム削除
●(KEYのIDをVALUEに|VALUEへ)USERアイテム更新
# --- その他 ---
●ログイン確認
●ユーザー名取得
●ユーザーID取得
●(user_idの)指定ユーザー取得

利用上の注意

アプリ毎に保存領域が異なるため、最初にアプリを一度保存して、app_idが有効な状態にしておく必要があります。
新規作成状態だと、正しい保存領域が得られません。
そのため、最初に「ログイン確認」命令を使って、ユーザーにログインを促してください。

内部的な仕様

以下は、内部的な仕様なので、なでしこユーザーは見なくても大丈夫です。

内部の仕組み

サーバー側でアプリのトークンを生成する
アプリのロード時、セッションにIDに対するトークンを保存する $_SESSION["TOKEN"] = app_id
アプリのロード時、不可視のDOM要素 [div id="api_token"]TOKEN[/div]を差し込むようにする。
アプリ側では、上記トークンをパラメータとして、token=TOKENを与える
サーバー側では、$_SESSION["TOKEN"]からapp_idを取り出して、それぞれのDBに対して読み書きをする

提供するAPIの種類(共通)

[request]
api.php?
  action=api&
  token=(トークン)&
  page=(メソッド名)&
  xxx=xxx

is_login --- なし --- ログインしているか？ --- value=true / false
get_user --- user_id=ddd --- ユーザー名を取得/user_id=0を指定するとログイン中のIDと名前を得る --- name=xxxx&user_id=ddd

astorage::user --- ユーザーごとの保存領域

KEY - キーバリューストア:

list_key_as_user --- なし --- 保存しているキーの一覧 --- keys=[a,b,c]
get_key_as_user --- key=xxx --- キーのデータを取得　--- value=xxx | value=null
set_key_as_user --- key=xxx&value=xxx --- キーに値を保存 --- true|false
delete_key_as_user --- key --- キーを削除 --- true|false
deleteall_key_as_user --- なし --- 全てのキーを削除 --- true|flase

ITEM - アイテムテーブル:

insert_item_as_user --- key=xxx&value=xxx --- item_id
select_items_as_user --- key=xxx&offset=dd&limit=ddd&sort=(asc|desc) --- {values: [{item_id:dd, value:xxx, mtime:ddd}...]}
delete_item_as_user --- key=xxx&item_id=ddd
update_item_as_user --- key=xxx&item_id=ddd&value=xxxx --- true|false

select_items_as_userのlimitは最大30件まで。

astorage::app --- アプリごとの保存領域

KEY - キーバリューストア:

list_key_as_app --- なし --- 保存しているキーの一覧 --- keys=[a,b,c]
get_key_as_app --- key=xxx --- キーのデータを取得　--- value=xxx | value=null
set_key_as_app --- key=xxx&value=xxx --- キーに値を保存 --- true|false
delete_key_as_app --- key=xxx --- キーを削除 --- true|flase

ITEM - アイテムテーブル:

insert_item_as_app --- key=xxx&value=xxx --- item_id
select_items_as_app --- key=xxx&offset=dd&limit=ddd&sort=(asc|desc) --- {values: [{item_id:dd, value:xxx, mtime:ddd}...]}
delete_item_as_app --- key=xxx&item_id=ddd
update_item_as_app --- key=xxx&item_id=ddd&value=xxxx --- true|false

select_items_as_appのlimitは最大30件まで。

kujirahand commented 6 months ago

とりあえず、ベータ版リリースということで、以下で動作を確認できます。 https://n3s.nadesi.com/index.php?page=2782&action=show

kujirahand commented 6 months ago

TODO

そもそも、n3s-sandboxオリジンには、ログインフォームがない！！！ログインフォームを表示する
- https://n3s-sandbox.nadesi.com/index.php?page=my&action=login&back=xxx
- 貯蔵庫APIを作り、そこにモーダルダイアログでログイン画面を出す機能を作る
保存できる最大サイズを決める（ユーザー毎、キー毎）
JSONではなく、SQLITEを使に変更する
ユーザー毎ではなく、アプリ共通の保存領域を作る→これにより、掲示板が作成できる
なでしこから簡単に使えるライブラリを作る
保存ファイル名が user_id だがゼロ埋めして、分かりやすくする。
念のため暗号化する？読めないから不要

kujirahand commented 5 months ago

APPアイテム取得が連続で呼べない問題がある😿

kujirahand commented 4 months ago

app_dbの方、読み取り専用であれば、他のユーザーもアクセスできるようにしたいです。

kujirahand / nako3storage