DropBox Datastore API 翻译

# DropBox Datastore API
## 关于

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

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

**应用实例**
1. [lists](https://github.com/dropbox/Lists-js)
2. [click the box](https://github.com/dropbox/ClickTheBox-js)

总结而言， 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**

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

**监听 record 变化**

``` javascript
datastore.recordsChanged.addListener(function (event) {
// affectedRecordsForTable 判断哪些记录变化了
console.log('records changed:', event.affectedRecordsForTable('tasks'));
});
```
### 定制冲突解决方案

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

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

``` javascript
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

``` javascript
// 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()
```