# 端云数据同步云侧环境部署指导

## 场景介绍

通过数据云同步功能，可将数据自动、及时存储至华为云空间，并在登录同一华为账号的设备间保持同步。该功能常用于满足以下体验诉求：

* 数据安全备份：不会因应用卸载或设备丢失、设备损坏导致数据永久丢失，重新安装应用数据即可自动恢复。
* 数据多端一致：登录同一华为账号的设备间数据自动、及时保持一致，多设备协同效率高，体验一致。

> 说明
>
> 用户需在"设置-云空间"内打开同步功能开关，并确保华为云空间存储空间充足。

## 服务优势

* **极简集成**

  简化开发：开发者通过使用[端云同步](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/data-cloud-sync-of-rdb-store)为应用快速添加云同步功能。

  专注核心：开发者只需关注应用的核心业务逻辑，数据同步的复杂性由ArkData和云空间处理。

  节省成本：免除基础设施负担，无需自行搭建和管理服务器、数据库、存储或带宽资源。
* **无缝全场景同步**

  覆盖广泛：支持同步的设备范围包含手机、平板、PC等。

  及时一致：用户数据在这些设备间自动、及时同步，确保体验一致。

  离线可用：即使用户设备暂时断网，也能正常访问和使用本地数据。网络恢复后，更改会自动同步到云端和其他设备。
* **安全隐私**

  安全存储：用户数据以多副本的形式在华为云空间存储，具备更高的可靠性。

  隐私保护：支持通过端侧加密等技术对用户数据进行加密后存储至云空间，确保用户数据仅本人可访问。
* **简单易用**

  功能启用方便：用户只需登录华为账号，打开同步开关，服务即自动启用。

  数据管理简单：华为云空间提供统一、易用的设置和数据管理界面，用户可在"设置-云空间"里管理同步功能和存储在云空间的数据。

## 约束限制

* 同步触发频率过高可能会被云端限流，建议开发者仅对用户操作触发变更的用户数据项启用该功能。不推荐后台定时任务或其他变更频繁、不离散的场景使用。
* 当前仅支持中国大陆地区，设备系统版本需不低于HarmonyOS 6.1.0，云空间版本需不低于6.3.0。
* 支持的设备类型涵盖手机、Tablet、2in1/PC等安装有云空间服务的设备。

## 基本概念

* **Container（容器）**：应用使用称为容器的逻辑空间来存储和管理数据，通常情况下一个应用对应一个容器，每一个容器代表应用在云空间内的储存空间，与其他应用的数据保持隔离。
* **Record Type（数据项类型）**：应用定义的数据项名称，由一个或多个字段组成，需要根据业务模型进行定义，例如数据项名称可以叫Todo。一个Container可以包含多个Record Type。一旦部署到生产环境，数据类型和字段不允许删除或修改。
* **Record Field（数据记录字段）**：Record Type中的具体列，用于存储特定的数据。例如，Todo中可能包含Title、Time、Comment等字段。
* **Record（数据记录）**：存储在Record Type中的具体数据条目。每个记录对应一行数据，并包含一个或多个字段。
* **开发环境**：用于调测目的，开发者拥有完全的配置、数据管理权利，可以增、删、改、查数据类型配置和调测数据记录；开发环境配置需要开发者谨慎部署到生产环境，一旦部署后续无法更改。
* **生产环境**：开发者可以查看或增加数据类型配置，但不允许修改和删除。

## 接入步骤

接入需要同时在云侧和端侧完成配置。云侧主要是创建容器及配置数据类型，用于确定应用在云空间内的数据存储空间和上云字段；端侧主要是声明接入字段及连接对应环境，用于云空间端侧展示同步开关及调测同步功能。

### 前置条件

* 已经在开发者联盟官网注册账号并通过实名认证，详细请参见[账号注册认证](https://developer.huawei.com/consumer/cn/doc/start/registration-and-verification-0000001053628148)。
* 已经在[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)网站上创建项目和应用，详细请参见[创建项目](https://developer.huawei.com/consumer/cn/doc/AppGallery-connect-Guides/agc-harmonyos-0000001139004974)。

### 云侧操作

1. 进入云同步服务页面。

   登录AppGallery Connect网站，点击"开发与服务"，选择"我的项目"。

   在项目列表页面中选择项目，单击项目下需要创建容器的应用。

   在API管理或开放能力管理启用"云空间"。

   点击"全部功能"（左侧导航树下方），选择"构建>云空间服务"，点击固定按钮，以将服务显示在左侧导航树中。
2. 创建容器。

   在云同步服务主页面，点击**创建容器** 按钮，填写**容器名称** ，点击**确定**。

   容器名称需要和ArkData本地数据库名称保持一致，例如：ArkData的数据库名称为note.db，容器名称则为note（大小写保持一致，不用填写后缀）。

   容器创建完成后才可进入数据类型配置页面。
3. 配置数据类型。

   在云同步服务主页面，选择"数据类型配置"，填写**数据类型名称** 和**自定义字段**，可以根据需要进行增、删、改、查。

   数据类型名称需要和ArkData本地表名称保持一致。

   云侧自定义字段名称及类型需要与本地数据接入云空间的字段名称及类型保持一致。对应关系如下表：

   |云侧字段类型|本地字段类型|说明|
   |:----------------------|:------|:-----------------------------------------------------|
   |Encrypted String/String|TEXT|-|
   |Integer|INTEGER|-|
   |Double|DOUBLE|-|
   |Bytes|BLOB|-|
   |Asset|ASSET|搭载云空间6.3.1及以上版本、HarmonyOS 6.1.0.135及以上版本的设备，支持新建此类型字段。|
   |AssetList|ASSETS|搭载云空间6.3.1及以上版本、HarmonyOS 6.1.0.135及以上版本的设备，支持新建此类型字段。|

   > 说明
   > * 设置自定义字段的类型时，如果为String类型，支持选择加密字段（添加前缀Encrypted），以保护用户的数据隐私。
   >
   > * 添加为加密字段后，可能影响端云同步的性能和效率，建议开发者根据数据的安全等级合理选择加密字段。
   >
   > * 云端所有配置字段默认允许为空，ArkData本地表所有字段定义不能设置NOT NULL属性。
   >
   > * ArkData本地表字段设置为主键(Primary Key)时，需在云侧进行以下配置操作：展开**高级设置** ，下拉**端侧去重主键**，勾选本地设置了主键属性的字段。

4. 调测多端同步。

   调测方案一：

   在云同步服务主页面，选择"数据记录调测"，在**数据类型** 和**字段** 下拉框选择要查看的数据类型和字段，点击**查询**按钮，可以查看云端个人数据。
   > 说明
   > * 该页面只能查询和修改开发者自身账号的数据，端侧调测如果使用其他账号，此处无法查询。如需使用该页面，客户端调测也请登录相同的开发者账号。
   >
   > * 无法在数据记录调测页面查看加密字段的具体内容，如需查看加密字段的具体内容请使用调测方案二。
   >
   > * 数据占用云存储空间，请确保空间充足。

   调测方案二：

   两台设备登录相同账号，在A设备上打开应用，新增数据；而后在B设备上打开应用，查看A设备上写入的数据是否同步至本端。
5. 重置开发环境。

   开发者可通过此操作快速清理调测期间产生的大量临时数据和配置。

   在云同步服务主页面，选择"重置开发环境"，勾选"我理解所有的数据将被删除且无法找回"，点击弹框中的**重置**按钮。

   所有的数据类型配置将会被重置（如果配置已经变更到生产环境，则与生产环境保持一致），所有的个人数据将被清空，操作无法撤销，请谨慎操作。
6. 部署生产环境。

   当使用开发环境完成多端同步调测后，明确配置已满足业务需要，开发者可自主将开发环境配置实施变更到生产环境，后续有新增配置重复此操作。

   在云同步服务主页面，选择"实施变更到生产环境"，点击弹框中的**实施**按钮。

   谨慎实施，实施后无法撤回，配置无法删除和修改，仅支持增加。

### 端侧操作

1. 应用声明。

   通过配置[app.json5](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-configuration-file)文件中app标签的cloudStructuredDataSyncEnabled字段来控制是否接入云同步能力，字段为true时，表示接入，在"设置-云空间"内即可看到应用开关。

   ```json
   {
     "app": {
       "cloudStructuredDataSyncEnabled": true
     }
   }
   ```

2. 环境连接。

   云空间识别接入应用的证书类型为debug则连接开发环境，应用证书类型为release则连接生产环境。
3. 开发流程具体请见[端云数据同步关系型数据库端侧开发指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/data-cloud-sync-of-rdb-store)。

4. 体验设计建议。

   当应用内设置同步开关时，请提示并引导用户跳转至云空间页面打开开关。

   用户数据是用户宝贵的数据资产，也是持续使用应用的重要原因之一，建议将同步状态显性化，让服务更透明，让用户使用更安心。

   同步受功能开启状态、网络条件、云存储空间等方面的影响，请参考[端云同步状态码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-data-relationalstore-e#progresscode10)设计同步状态提醒。例如：
   * 同步正在进行时增加提醒：正在与云空间同步。

   * 同步已完成，有明确完成状态码时，参考如下表格增加提醒：

     |完成状态码|建议提示|
     |:----|:----------------------|
     |0|已与云空间同步|
     |1|与云空间同步已暂停|
     |2|网络错误，与云空间同步已暂停|
     |3|未开启同步|
     |4|与云空间同步已暂停，稍后将自动重试|
     |5|超出数据上限，与云空间同步已暂停|
     |6|云空间存储空间不足，请前往"设置-云空间"管理|
     |7|未连接WLAN，与云空间同步已暂停|

     > 说明
     >
     > 前往"设置-云空间"管理，也可添加[Deeplink](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/deep-linking-startup)文字链，用户点击直接跳转至云空间首页，跳转uri为：hicloud://cloudDrive/getInfo?path=MainActivity。

## 个人数据处理说明

此处针对华为作为最终用户数据处理者，开发者作为最终用户数据控制者的数据处理进行说明，包括：

* 华为处理的个人数据清单
* 指导开发者如何帮助最终用户实现对数据的控制

### 华为处理的个人数据清单

|**个人数据清单**|**使用目的**|**存留期**|
|:---------|:--------------------------------------------------------------------------------------------------------|:----------------------------------|
|用户数据|数据备份与同步。由应用指定存储至云空间的数据范围，并由最终用户确认（在"设置-云空间"内打开/关闭同步功能开关），以避免应用卸载或设备丢失、设备损坏导致数据永久丢失，以及数据在登录同一华为账号的设备间保持一致。|存储在云空间的数据将保存至如下时刻：最终用户主动删除存储在云空间的数据|

### 指导开发者如何帮助用户实现对数据的控制

* 如何清除最终用户存储在云空间的数据

  最终用户主动删除存储在云空间的数据： 前往"设置-云空间-管理空间"，通过"停止同步并删除云端数据"功能删除存储在云空间的数据，不会删除存储在设备上的数据。
* 如何导出最终用户的数据

  建议应用提供端内导出功能。
* 如何确保用户知晓数据管理权利

  请在应用隐私声明中说明数据存储至云空间的目的和范围，可参考如下内容（开发者可自行调整）：为了{用户体验描述}，通过华为云空间在已登录华为账号的设备间同步{数据项名称}等数据。您可以在"设置-云空间"里管理同步功能和存储在云空间的数据。

## 常见问题

### AppGallery Connect网站找不到云空间服务

在"开发与服务"页面，点击左下角"全部功能"按钮展开所有菜单，找到"构建 > 云空间服务"，可将其锁定到左侧导航树，便于后续查找使用。

### 日志出现报错信息：{"schedule":2,"code":1,"details":{}}

可能原因及解决方案：

1. 本地表中数据类型不符合Sqlite基本数据类型，依次排查表中数据类型是否符合规范。
2. 云侧配置与端侧配置不一致，请检查：
   * 是否设置分布式表。
   * 表名与云侧配置是否匹配。
   * 表中字段属性与云侧配置是否匹配，字段约束请参考上文[云侧操作](#云侧操作)步骤3。

如果以上未解决，可尝试：

1. 退出华为账号再次登录。
2. 卸载开发应用重新安装。

### 云端修改数据类型的配置后，端侧同步失败

退出华为账号重新登录。