数据存储开发指南 · Java
数据存储是云服务提供的核心功能之一,可用于存放和查询应用数据。下面的代码展示了如何创建一个对象并将其存入云端:
// 构建对象
LCObject todo = new LCObject("Todo");
// 为属性赋值
todo.put("title", "工程师周会");
todo.put("content", "周二两点,全体成员");
// 将对象保存到云端
todo.saveInBackground().subscribe(new Observer<LCObject>() {
public void onSubscribe(Disposable disposable) {}
public void onNext(LCObject todo) {
// 成功保存之后,执行其他逻辑
System.out.println("保存成功。objectId:" + todo.getObjectId());
}
public void onError(Throwable throwable) {
// 异常处理
}
public void onComplete() {}
});
我们为各个平台或者语言开发的 SDK 在底层都是通过 HTTPS 协议调用统一的 REST API,提供完整的接口对数据进行各类操作。
SDK 安装与初始化
对象
LCObject
LCObject
是云服务对复杂对象的封装,每个 LCObject
包含若干与 JSON 格式兼容的属性值对(也称键值对,key-value pairs)。这个数据是无模式化的(schema free),意味着你不需要提前标注每个 LCObject
上有哪些 key,你只需要随意设置键值对就可以,云端会保存它。
比如说,一个保存着单个 Todo 的 LCObject
可能包含如下数据:
title: "给小林发邮件确认会议时间",
isComplete: false,
priority: 2,
tags: ["工作", "销售"]
数据类型
LCObject
支持的数据类型包括 String
、Number
、Boolean
、Object
、Array
、Date
等等。你可以通过嵌套的方式在 Object
或 Array
里面存储更加结构化的数据。
LCObject
还支持两种特殊的数据类型 Pointer
和 File
,可以分别用来存储指向其他 LCObject
的指针以及二进制数据。
LCObject
同时支持 GeoPoint
,可以用来存储地理位置信息。参见 GeoPoint。
以下是一些示例:
// 基本类型
boolean bool = true;
int number = 2018;
String string = number + " 流行音乐榜单";
Date date = new Date();
byte[] data = "Hello world!".getBytes();
ArrayList<Object> arrayList = new ArrayList<>();
arrayList.add(number);
arrayList.add(string);
HashMap<Object, Object> hashMap = new HashMap<>();
hashMap.put("number", number);
hashMap.put("string", string);
// 构建对象
LCObject testObject = new LCObject("TestObject");
testObject.put("testBoolean", bool);
testObject.put("testInteger", number);
testObject.put("testDate", date);
testObject.put("testData", data);
testObject.put("testArrayList", arrayList);
testObject.put("testHashMap", hashMap);
testObject.save();
我们不推荐通过 byte[]
在 LCObject
里面存储图片、文档等大型二进制数据。每个 LCObject
的大小不应超过 128 KB。如需存储大型文件,可创建 LCFile
实例并将其关联到 LCObject
的某个属性上。参见 文件。
注意:时间类型在云端将会以 UTC 时间格式存储,但是客户端在读取之后会转化成 本地时间。
开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 数据存储 > 结构化数据 中展示的日期数据也会依据操作系统的时区进行转换。一个例外是当你通过 REST API 获得数据时,这些数据将以 UTC 呈现。你可以手动对它们进行转换。
若想了解云服务是如何保护应用数据的,请阅读数据和安全。
构建对象
下面的代码构建了一个 class 为 Todo
的 LCObject
:
LCObject todo = new LCObject("Todo");
在构建对象时,为了使云端知道对象属于哪个 class,需要将 class 的名字作为参数传入。你可以将云服务里面的 class 比作关系型数据库里面的表。一个 class 的名字必须以字母开头,且只能包含数字、字母和下划线。
保存对象
下面的代码将一个 class 为 Todo
的对象存入云端:
// 构建对象
LCObject todo = new LCObject("Todo");
// 为属性赋值
todo.put("title", "马拉松报名");
todo.put("priority", 2);
// 将对象保存到云端
todo.saveInBackground().subscribe(new Observer<LCObject>() {
public void onSubscribe(Disposable disposable) {}
public void onNext(LCObject todo) {
// 成功保存之后,执行其他逻辑
System.out.println("保存成功。objectId:" + todo.getObjectId());
}
public void onError(Throwable throwable) {
// 异常处理
}
public void onComplete() {}
});
为了确认对象已经保存成功,我们可以到 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 数据存储 > 结构化数据 > Todo
里面看一下,应该会有一行新的数据产生。点一下这个数据的 objectId
,应该能看到类似这样的内容:
{
"title": "马拉松报名",
"priority": 2,
"ACL": {
"*": {
"read": true,
"write": true
}
},
"objectId": "582570f38ac247004f39c24b",
"createdAt": "2017-11-11T07:19:15.549Z",
"updatedAt": "2017-11-11T07:19:15.549Z"
}
注意,无需在 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 数据存储 > 结构化数据 里面创建新的 Todo
class 即可运行前面的代码。如果 class 不存在,它将自动创建。
以下是一些对象的内置属性,会在对象保存时自动创建,无需手动指定:
内置属性 | 类型 | 描述 |
---|---|---|
objectId | String | 该对象唯一的 ID 标识。 |
ACL | LCACL | 该对象的权限控制,实际上是一个 JSON 对象,控制台做了展现优化。 |
createdAt | Date | 该对象被创建的时间。 |
updatedAt | Date | 该对象最后一次被修改的时间。 |
这些属性的值会在对象被存入云端时自动填入,代码中尚未保存的 LCObject
不存在这些属性。
属性名(keys)只能包含字母、数字和下划线。自定义属性不得以双下划线(__
)开头或与任何系统保留字段和内置属性(ACL
、className
、createdAt
、objectId
和 updatedAt
)重名,无论大小写。
属性值(values)可以是字符串、数字、布尔值、数组或字典(任何能以 JSON 编码的数据)。参见 数据类型。
我们推荐使用驼 峰式命名法(CamelCase)为类和属性来取名。类,采用大驼峰法,如 CustomData
。属性,采用小驼峰法,如 imageUrl
。
获取对象
对于已经保存到云端的 LCObject
,可以通过它的 objectId
将其取回:
LCQuery<LCObject> query = new LCQuery<>("Todo");
query.getInBackground("582570f38ac247004f39c24b").subscribe(new Observer<LCObject>() {
public void onSubscribe(Disposable disposable) {}
public void onNext(LCObject todo) {
// todo 就是 objectId 为 582570f38ac247004f39c24b 的 Todo 实例
String title = todo.getString("title");
int priority = todo.getInt("priority");
// 获取内置属性
String objectId = todo.getObjectId();
Date updatedAt = todo.getUpdatedAt();
Date createdAt = todo.getCreatedAt();
}
public void onError(Throwable throwable) {}
public void onComplete() {}
});
如果你试图获取一个不存在的属性,SDK 不会报错,而是会返回 null
。
同步对象
当云端数据发生更改时,你可以调用 fetchInBackground
方法来刷新对象,使之与云端数据同步:
LCObject todo = LCObject.createWithoutData("Todo", "582570f38ac247004f39c24b");
todo.fetchInBackground().subscribe(new Observer<LCObject>() {
public void onSubscribe(Disposable disposable) {}
public void onNext(LCObject todo) {
// todo 已刷新
}
public void onError(Throwable throwable) {}
public void onComplete() {}
});
刷新操作会强行使用云端的属性值覆盖本地的属性。因此如果本地有属性修改,fetchInBackground
操作会丢弃这些修改。为避免这种情况,你可以在刷新时指定 需要刷新的属性,这样只有指定的属性会被刷新(包括内置属性 objectId
、createdAt
和 updatedAt
),其他属性不受影响。
LCObject todo = LCObject.createWithoutData("Todo", "582570f38ac247004f39c24b");
String keys = "priority, location";
todo.fetchInBackground(keys).subscribe(new Observer<LCObject>() {
public void onSubscribe(Disposable disposable) {}
public void onNext(LCObject todo) {
// 只有 priority 和 location 会被获取和刷新
}
public void onError(Throwable throwable) {}
public void onComplete() {}
});
如果想要确保只刷新已经保存到云端的对象,那么可以用 fetchIfNeededInBackground
替换 fetchInBackground
。
调用 fetchIfNeededInBackground
方法时,如果是本地构造尚未保存的对象,那么不会访问云端,onNext 方法中传入的是本地对象。
更新对象
要更新一个对象,只需指定需要更新的属 性名和属性值,然后调用 saveInBackground
方法。例如:
LCObject todo = LCObject.createWithoutData("Todo", "582570f38ac247004f39c24b");
todo.put("content", "这周周会改到周三下午三点。");
todo.saveInBackground().subscribe(new Observer<LCObject>() {
public void onSubscribe(Disposable disposable) {}
public void onNext(LCObject savedTodo) {
System.out.println("保存成功");
}
public void onError(Throwable throwable) {
System.out.println("保存失败!");
}
public void onComplete() {}
});;
云服务会自动识别需要更新的属性并将对应的数据发往云端,未更新的属性会保持原样。
有条件更新对象
通过传入 query
选项,可以按照指定条件去更新对象——当条件满足时,执行更新;条件不满足时,不执行更新并返回 305
错误。
例如,用户的账户表 Account
有一个余额字段 balance
,同时有多个请求要修改该字段值。为避免余额出现负值,只有当金额小于或等于余额的时候才能接受请求:
LCObject account = LCObject.createWithoutData("Account", "5745557f71cfe40068c6abe0");
// 对 balance 原子减少 100
final int amount = -100;
account.increment("balance", amount);
// 设置条件
LCSaveOption option = new LCSaveOption();
option.query(new LCQuery<>("Account").whereGreaterThanOrEqualTo("balance", -amount));
// 操作结束后,返回最新数据。
// 如果是新对象,则所有属性都会被返回,
// 否则只有更新的属性会被返回。
option.setFetchWhenSave(true);
account.saveInBackground(option).subscribe(new Observer<LCObject>() {
public void onSubscribe(Disposable disposable) {}
public void onNext(LCObject account) {
System.out.println("当前余额为:" + account.get("balance"));
}
public void onError(Throwable throwable) {
System.out.println("余额不足,操作失败!");
}
public void onComplete() {}
});
query
选项只对已存在的对象有效,不适用于尚未存入云端的对象。
query
选项在有多个客户端需要更新同一属性的时候非常有用。相比于通过 LCQuery
查询 LCObject
再对其进行更新的方法,这样做更加简洁,并且能够避免出现差错。
更新计数器
设想我们正在开发一个微博,需要统计一条微博有多少个赞和多少次转发。由于赞和转发的操作可能由多个客户端同时进行,直接在本地更新数字并保存到云端的做法极有可能导致差错。为保证计数的准确性,可以通过 原子操作 来增加或减少一个属性内保存的数字:
post.increment("likes", 1);
可以指定需要增加或减少的值。若未指定,则默认使用 1
。
注意,虽然原子增减支持浮点数,但因为底层数据库的浮点数存储格式限制,会有舍入误差。
因此,需要原子增减的字段建议使用整数以避免误差,例如 3.14
可以存储为 314
,然后在客户端进行相应的转换。
否则,以比较大小为条件查询对象的时候,需要特殊处理,
< a
需改查 < a + e
,> a
需改查 > a - e
,== a
需改查 > a - e
且 < a + e
,其中 e
为误差范围,据所需精度取值,比如 0.0001
。