DropBox Datastore API 翻译

关于

Datastore API 是 dropbox 已经废弃的功能，不过 dropbox 将 jssdk 开源，这样对于研究 A-CS 实现有很好的参考价值，这里将它翻译出来，既当备份也当对 datastore 的设计有个基本的了解

Datastore 介绍

官方的介绍是，应用不仅仅是存储和同步文件，通过 Datastore API , 结构化的数据如联系人列表，任务列表，游戏状态都可以像文件同步一样简单。并且 Datastore 支持多平台，离线访问，自动冲突解决。并且可以通过浏览器查看所有应用的数据 https://www.dropbox.com/developers-v1/br... 。

应用实例

总结而言， Datastore 就是结构化数据的 A-CS 的实现

Datastore API 基本概念

Client and datastore manager

用户在客户端通过 app_key 启动 dropbox 认证，认证通过后，就可以在客户端创建 datastore manager 实例, 通过 manager 可以获取 datastores 列表，监听 datastore 的变化，同步 datastore，更新 datastore

Datastores and tables

datastores 是应用结构化数据的容器，每一个 datastore 是一个 tables 的集合，每个 table 是一个 records 的集合。同数据库一样

datastore <-> 数据库
table <-> 数据库表
record <-> 数据记录

当一个 datastore 被打开过后就会被缓存到本地，这样就可以实现应用数据的离线访问，每个 datastore 是相互独立的，当一个 datastore 改变的时候，会自动同步数据到 dropbox，也可能会将 dropbox 的新数据（其他客户端的改变）同步到本地。

用户之间可以分享数据，分享的基本单元是 datastore ，

Records

records 是应用存储数据的基本单元，每个 record 有一个或任意多个 fields 组成，有一个 ID ，每个 field 是 {key: value} 的组合, value 可以是基本数据，也可以是基本数据的数组，基本数据

String (String)
Boolean (Boolean)
Integer (Dropbox.Datastore.int64)
Floating point (Number) – IEEE double. All native JavaScript numbers will be interpreted as floating-point numbers. To store integers, use the Dropbox.Datastore.int64 type.
Date (Date) – POSIX-like timestamp stored with millisecond precision.
Bytes (Uint8Array) – Arbitrary data, which is treated as binary, such as thumbnail images or compressed data. Individual records can be up to 100KB, which limits the size of the data.
List (Dropbox.Datastore.List) – A special value that can contain other values, though not other lists

和 SQL 不同的是， datastore 中的 table 不包含 schema ，所以每个 record 可以有任意数目的 field

查询 records

var results = taskTable.query({completed: false}); var firstResult = results[0];

监听 record 变化

datastore.recordsChanged.addListener(function (event) { 
    // affectedRecordsForTable 判断哪些记录变化了
    console.log('records changed:', event.affectedRecordsForTable('tasks')); 
});

定制冲突解决方案

datastore 会自动的以 field 为基本单位合并改变，举个例子，如果用户在一个客户端上修改了 taskname 和 complete 状态，在另外的一个设备上 datastore api 会没有冲突的自动合并这个改变。

如果同时的改变了相同 record 的相同 field，这就需要解决冲突了，可以自定义冲突解决规则

taskTable.setResolutionRule('completed', 'local');

总共有 5个规则

remote – The remote value will be chosen. This is the default behavior for all fields.
local – The local value of the field will be chosen.
max – The greater of the two changes will be chosen.
min – The lesser of the two changes will be chosen.
sum – Additions and subtractions to the value will be preserved and combined.

分享 datastore

// Shareable datastore
datastoreManager.createDatastore(function (error, datastore) {
    /**
     * 给一组用户设置角色 (principal)
     * 第一个参数是表示分享给谁
        Dropbox.Datastore.PUBLIC – The role will apply to all Dropbox users.
        Dropbox.Datastore.TEAM – The role will apply to everyone on the user's team (only applicable for Dropbox for Business 
     * 第二个参数表示分享模式
        Dropbox.Datastore.NONE – The principal has no access to this datastore.
        Dropbox.Datastore.VIEWER – The principal is able to view this datastore.
        Dropbox.Datastore.EDITOR – The principal is able to edit this datastore.
        Dropbox.Datastore.OWNER – The principal is the owner of this datastore. This role cannot be assigned directly. The user who created a datastore is always that datastore's owner.
     */
    datastore.setRole(Dropbox.Datastore.PUBLIC, Dropbox.Datastore.EDITOR);
});

// 接受分享的用户
datastoreManager.openDatastore(datastoreId, function (error, datastore) {
    // The datastore is now shared with this user.
});

// 列举 datastore的访问人列表
datastore.listRoles()

// 获取当前用户的 role 
datastore.getEffectiveRole()