Object 存储

Object 存储允许你将数据作为 KiiObject 存入一个 Bucket。

本文将详解该功能。关于基础总览,请查阅 Kii Cloud SDK 总览

在一个 KiiObject 中,你可以存储一些 Key-Value 和一个 Object Body(文件)。KiiObject 的主要组件是 Key-Value。当你需要一个 Object Body 时,你需要使用 SDK 的上传和下载功能单独处理它。

一个 KiiObject 可以只含有若干 Key-Value 或只含有一个 Object Body。例如,一个表示配置设置的 Object 一般不需要 Object Body,所以你可以只创建一个含有 Key-Value 的 KiiObject。你也可以创建一个只有 Object Body 而没有 Key-Value 的 KiiObject(这种情况下,SDK 将在 Object 中插入一些预定义的 Key-Value,详见下节)。

Key-Value

Kii Cloud 中每个 Key-Value 和其他关联数组一样。每个 Object 可以拥有多个键名和键值对,且可以使用键名获取对应的键值。Kii Cloud 将 Key-Value 存储为 JSON 格式。

这里有两种键:预定义键和自定义键。

预定义键

预定义键是 Kii Cloud 存储用于内部使用的。所有预定义键都以 "_"(下划线)开头,且 Kii Cloud 不允许使用 "_" 开头的自定义键。

这类预定义键的一些例子:

  • 用于内部数据管理的键,例如 _id_version
  • 自动填充的键,例如 _created(创建时间)和 _modified(修改时间)。这些键值可以使用 SDK 的专用方法提取到。

关于预定义键的详情,请查阅详细文档 参考文档

自定义键

自定义键是你的应用程序可以自由使用的键。只要不以 "_"(下划线)开头,你可以在 Object 设置任意 Key-Value。

键值可以是如下任意 JSON 可编码类型:

  • String
  • Boolean
  • Int
  • Long
  • Double
  • Byte Array
  • JSON
  • JSON Array
  • GeoPoint (geolocation)

大部分情况下,设置和获取一个键值时你需要指定相同的数据类型。关于在不同平台传递键值或数据类型转换时 Kii Cloud 的处理方式,请参阅 Key-Value 数据转换

当 Key-Value 被保存到 Kii Cloud 时,相关的索引(对 Bucket、键名和键值的索引)将自动生成在服务器上。这些索引将用于查询 Object。

请注意,只有键名长度小于 250 个字符且其键值长度小于 190 个字符(仅限字符串型键值)时,才会生成索引。如果 Object 中包含了键名或键值的长度超出此限制的字段,则不会生成此 Object 的索引;使用此字段进行的查询,不会匹配到这个 Object。

Object Body

你可以通过将文件关联到 KiiObject 的方法管理文件(Object Body)。

例如,你可以将一部电影的元数据存在 KiiObject 的 Key-Value 中,而将电影的文件存在它的 Object Body 中。

由于 Object Body 通常都很大,SDK 将按如下方式处理:

  • 虽然 Key-Value 和 Object Body 是绑定到同一 KiiObject 的,但是处理他们的 API 是彼此独立的。

    • 当请求 Object Body 时,客户端 SDK 会把 Object Body 作为文件进行读取和写入。
    • 对于 REST API,我们为 Key-Value 和 Object Body 的处理提供了独立的 API。
  • 部分客户端 SDK 支持暂停和继续文件传输。你可以在传输的过程中暂停它,并在之后继续传输。

一个 KiiObject 只能存储一个 Object Body。无法在一个 Object 中存储多个 Object Body。

如需在一个 KiiObject 中存储多个图标,那么你可以将图标转换成 BASE64 数据并将转换后的数据存储为 Key-Value。在这种情况下,如果 Key-Value 在表示成 JSON 格式后的大小超过了 64 KB,则会报错。如果大小在允许范围内,那么使用这种方法的好处是你可以通过 KiiObject 的查询操作一次性获取 BASE64 数据以及其他数据。