DropBox Datastore API 翻译

关于

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

Datastore 介绍

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

应用实例

1. lists

2. click the box

总结而言， 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 能够是基本数据，也能够是基本数据的数组， 基本数据

1. String (String)

2. Boolean (Boolean)

3. Integer (Dropbox.Datastore.int64)

4. 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.

5. Date (Date) – POSIX-like timestamp stored with millisecond precision.

6. 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.

7. 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个规则

1. remote – The remote value will be chosen. This is the default behavior for all fields.

2. local – The local value of the field will be chosen.

3. max – The greater of the two changes will be chosen.

4. min – The lesser of the two changes will be chosen.

5. 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()