[stacks 区块链中文开发文档] 使用 Gaia 分布式存储系统为用户存储和检索数据

数据存储

原英文文档链接： https://docs.stacks.co/build-apps/guides/data-storage

使用 Gaia 为用户存储和检索数据

介绍

本指南解释了如何通过执行 Stacks.js 的 connect 和 storage 包来为用户存储和检索数据。 Gaia 分布式存储系统使用户完全控制了自己的数据，用户可以在链下存储自己公有或者私有的数据。 把用户的数据脱离 Stacks 区块链，可以确保应用程序可以为用户提供高性能和高可用性的数据读取和写入，并且不需要损害用户的隐私，也不需要中心化的第三方的参与。 有关此功能的具体示例，请参考 To-dos 应用程序教程。

安装依赖

必须安装以下依赖项：

npm install @stacks/connect @stacks/storage

发起会话

用户必须先对应用程序进行身份验证，然后 storage 包才能代表他们存储或提取数据。在 userSession.isUserSignedIn() 返回 true 的情况下，在继续集成以下数据存储功能之前，请参阅身份授权指南。

存储会话用户的数据

Gaia 使用键值存储，其中数据会被作为文件，存储到用户拥有或管理的 Gaia hubs，也可以从用户拥有的 Gaia hubs 数据中检索出来。

用户的默认的 Gaia Hub （用户数据存储中心）是由 Hiro PBC 基金会，通过 https://gaia.blockstack.org/ 运行。使用 Stacks 钱包 对应用程序进行身份验证，它支持最大 25 兆字节的文件。

我们建议将大于 25MB 的数据实例分成多个文件，单独保存它们，并在检索时重新组合它们。

这些文件可以包含任何类型的数据，例如文本、图像、视频或二进制文件。文件通常保存为字符串，表示字符串化的 JSON 对象，并包含特定模型的各种属性。要存储文件，首先实例化 storage 对象，对经过身份验证的用户使用 userSession 对象。然后继续使用相关参数调用 putFile 方法：

import { AppConfig, UserSession } from '@stacks/connect';
import { Storage } from '@stacks/storage';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });
const storage = new Storage({ userSession });

let fileName = 'car.json';

let fileData = {
  color: 'blue',
  electric: true,
  purchaseDate: '2019-04-03',
};

const options = {
  encrypt: true,
};

let fileUrl = storage.putFile(fileName, JSON.stringify(fileData), options).then(() => {
  // Handle any execution after data has been saved
});

options 参数对象包含一个 encrypt 属性，当设置为 true 时，表示在将数据存储到用户的 Gaia Hub 之前，应该使用用户的应用程序私钥来加密用户的数据。如果完全省略 encrypt 属性或者 options 对象，则默认情况下所有数据都将被加密。

如果将 encrypt 属性设置为 false，则数据将未加密地保存，所有对该用户的 Gaia Hub 具有公共访问权限的人，都可以使用。

虽然可以使用 store_write 作用域为所有经过身份验证的应用程序保存私有加密的数据，但用户必须在身份验证期间之前授权过 publish_data 作用域，以便应用程序保存公开未加密的数据。putFile 方法可以从用户的 Gaia Hub 检索，并返回文件所在的 URL，可以设置成 fileUrl 值。

每次要更新记录时，都需要使用具有相同 fileName 对象，和 putFile 方法一起，来保存一个全新的修改过的数据字符串。除此之外，没有单独的更新方法。

获取会话用户的数据

要使用应用程序检索以前为用户保存的数据，请调用 storage 对象中可用的 getFile 方法：

import { AppConfig, UserSession } from '@stacks/connect';
import { Storage } from '@stacks/storage';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });
const storage = new Storage({ userSession });

let fileName = 'car.json';

const options = {
  decrypt: true,
};

storage.getFile(fileName, options).then(fileData => {
  // Handle any execution that uses decrypted fileData
});

请注意，这里的 options 对象中的 decrypt 属性，应该执行与使用 putFile 保存数据时，最初用于 encrypt 时相同的布尔值。如果省略，则 decrypt 属性将默认为 true 。

已经加密的文件需要将 decrypt 设置为 true，以便应用程序知道，fileData 在回调可用之前，可以使用用户的应用程序私钥来解密数据。

获取其他用户的数据

应用程序还可以检索除活动会话以外的用户保存的公共数据，前提是这些用户已经通过区块链命名系统注册了用户名。 只需在 options 对象中指明此类用户的用户名：

import { AppConfig, UserSession } from '@stacks/connect';
import { Storage } from '@stacks/storage';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });
const storage = new Storage({ userSession });

let fileName = 'car.json';

const options = {
  username: 'markmhendrickson.id.blockstack',
};

storage.getFile(fileName, options).then(fileData => {
  // Handle any execution that uses decrypted fileData
});

此 getFile 方法的调用，将从 Gaia Hub 的存储单元中，检索从指定的 fileName 路径中找到的数据，该数据映射到已经注册了这个 username 的用户和绑定在当前域名中的特定应用程序。

在 option 对象中设置附加的 app 属性，以便可以检索和单独域名绑定的应用程序所保存的用户数据：

const options = {
  app: 'https://example.org',
  username: 'markmhendrickson.id.blockstack',
};

这将导致 getFile 方法可以让用户 Gaia Hub 上指定的应用程序，调用并检索在单独存储单元中找到的数据。

删除会话用户的数据

在 storage 对象上，调用 deleteFile 方法，以删除在活动会话用户的特定文件路径中找到的数据：

import { AppConfig, UserSession } from '@stacks/connect';
import { Storage } from '@stacks/storage';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });
const storage = new Storage({ userSession });

let fileName = 'car.json';

storage.deleteFile(fileName).then(() => {
  // Handle any execution after file has been deleted
});

应用程序只能为活动会话用户存储和删除数据。