HarmonyOS鸿蒙Next中APP如何集成AGC云数据库，实现数据实时同步？

HarmonyOS鸿蒙Next中APP如何集成AGC云数据库，实现数据实时同步？

问题描述

开发鸿蒙 APP 需要实现多设备数据同步，想使用 AGC 云数据库替代自建 Python 后端，但不知道如何集成 AGC 云数据库，如何实现数据的增删改查和实时监听？是否需要额外配置权限或安全规则？关键字：AGC 云数据库、鸿蒙集成、实时同步、数据 CRUD、安全规则

回答内容

原理解析

AGC 云数据库（CloudDB）是华为提供的云端数据库服务，支持 NoSQL 数据模型，鸿蒙 APP 通过 AGC SDK 集成后，可实现：

• 客户端与云端的数据实时同步；
• 基于细粒度的安全规则控制访问权限；
• 离线数据缓存与自动同步，核心依赖agconnect-cloud-db SDK，需先在 AGC 控制台创建数据库和对象类型。

实现步骤

步骤 1：AGC 控制台配置

1. 登录 AGC→我的项目→云数据库→创建数据库（选择 “开发环境”）；
2. 创建对象类型（如UserInfo）：
   • 字段：userId（String，主键）、userName（String）、age（Integer）；
3. 发布对象类型（生成objectTypes.json，后续导入项目）；
4. 配置安全规则（如允许认证用户读写，避免匿名访问）。

步骤 2：项目集成 AGC SDK

1. 在build.gradle中添加依赖：

dependencies {
  implementation 'com.huawei.agconnect:agconnect-cloud-db:1.9.0.300'
}

1. 将 AGC 控制台下载的agconnect-services.json放入entry/src/main/resources/目录；
2. 将发布的objectTypes.json放入entry/src/main/resources/rawfile/目录。

步骤 3：初始化云数据库

import agconnect from '@hw-agconnect/api';
import '@hw-agconnect/cloud-db';
import common from '@ohos.app.ability.common';

class CloudDBManager {
  private cloudDB: agconnect.cloudDB.CloudDBZone;
  private context = getContext(this) as common.UIAbilityContext;

  // 初始化
  async init() {
    // 初始化AGC
    if (!agconnect.instance().isInitialized()) {
      agconnect.instance().initialize(this.context);
    }

    // 初始化云数据库
    const config = new agconnect.cloudDB.CloudDBConfig();
    config.setObjectTypeFile('rawfile/objectTypes.json');
    await agconnect.cloudDB.initialize(config);

    // 打开数据库分区（默认分区）
    this.cloudDB = await agconnect.cloudDB.openCloudDBZone('default', true);
    console.log('云数据库初始化成功');
  }
}

步骤 4：实现数据增删改查

// 新增数据
async addUser(user: { userId: string, userName: string, age: number }) {
  const userInfo = new agconnect.cloudDB.UserInfo(); // 自动生成的实体类
  userInfo.setUserId(user.userId);
  userInfo.setUserName(user.userName);
  userInfo.setAge(user.age);
  
  const result = await this.cloudDB.insert(userInfo);
  console.log('新增成功，ID：', result.getSuccessCount());
}

// 查询数据
async queryUser(userId: string) {
  // 构建查询条件
  const query = agconnect.cloudDB.Query.where(agconnect.cloudDB.UserInfo.class)
    .equalTo('userId', userId);
  
  const result = await this.cloudDB.query(query);
  return result.getSnapshotObjects().map((obj) => obj.toObject());
}

// 更新数据
async updateUser(user: { userId: string, userName: string }) {
  const userInfo = new agconnect.cloudDB.UserInfo();
  userInfo.setUserId(user.userId);
  userInfo.setUserName(user.userName);
  
  const result = await this.cloudDB.update(userInfo);
  console.log('更新成功：', result.getSuccessCount());
}

// 删除数据
async deleteUser(userId: string) {
  const userInfo = new agconnect.cloudDB.UserInfo();
  userInfo.setUserId(userId);
  
  const result = await this.cloudDB.delete(userInfo);
  console.log('删除成功：', result.getSuccessCount());
}

步骤 5：实时监听数据变化

// 监听UserInfo表的变化
listenUserChanges() {
  const query = agconnect.cloudDB.Query.where(agconnect.cloudDB.UserInfo.class);
  this.cloudDB.subscribe(query, (snapshot) => {
    const changes = snapshot.getChanges();
    changes.forEach((change) => {
      switch (change.getType()) {
        case agconnect.cloudDB.ChangeEventType.INSERT:
          console.log('新增数据：', change.getObjects());
          break;
        case agconnect.cloudDB.ChangeEventType.UPDATE:
          console.log('更新数据：', change.getObjects());
          break;
        case agconnect.cloudDB.ChangeEventType.DELETE:
          console.log('删除数据：', change.getObjects());
          break;
      }
    });
  });
}

避坑提醒

• 实体类需与 AGC 控制台的对象类型完全一致，修改后需重新发布并替换objectTypes.json；
• 必须开启 AGC “认证服务”，安全规则建议设置为 “已认证用户” 可访问，避免匿名访问泄露数据；
• 离线状态下操作会缓存到本地，联网后自动同步，需处理冲突（如设置字段级冲突策略）；
• 初始化需在 UIAbility 的onStart中执行，确保上下文有效。