数据操作 | 开发文档

本篇文档介绍如何进行数据操作，分为写入，更新和删除数据。

数据操作包含以下七种方法：

方法	说明
setValue:	向指定节点写入数据。若此节点已存在数据，会覆盖原有数据。
setPriority:	设置节点优先级。
setValue:andPriority:	向指定节点写入数据并且设置该节点优先级。
childByAutoId	向指定节点添加子节点。子节点的 key 由 Wilddog Sync 自动生成并保证唯一。
removeValue	删除指定节点。
updateChildValues:	更新指定子节点。
runTransactionBlock:	并发操作时保证数据一致性。

写入数据

setValue: 方法用于向指定节点写入数据。此方法会先清空指定节点，再写入数据。

setValue: 方法可设置回调方法来获取操作的结果。

例如，向 Jobs 节点下写入 full_name 和 gender：

Objective-C
Swift

// 初始化 
WDGOptions *option = [[WDGOptions alloc] initWithSyncURL:@"https://<SyncAppID>.wilddogio.com"];
[WDGApp configureWithOptions:option];
// 获取一个 WDGSyncReference 实例
WDGSyncReference *ref = [[WDGSync sync] referenceWithPath:@"/web/saving-data/wildblog/users"];
NSDictionary *jobs = @{
                          @"full_name" : @"Steve Jobs",
                          @"gender" : @"male"
                      };

// child 用来定位到某个节点。                           
WDGSyncReference *usersRef = [ref childWithPath: @"Jobs"];
[usersRef setValue:jobs];

//初始化
let options = WDGOptions.init(syncURL: "https://<SyncAppID>.wilddogio.com")
WDGApp.configure(with: options)
// 获取一个 WDGSyncReference 实例
let ref = WDGSync.sync().reference(withPath: "/web/saving-data/wildblog/users")
let jobs = ["full_name": "Steve Jobs", "gender": "male"]

// child 用来定位到某个节点。
let usersRef = ref.child("jobs")
usersRef.setValue(jobs)

设置回调方法：

Objective-C
Swift

NSDictionary *jobs = @{
                          @"full_name" : @"Steve Jobs",
                          @"gender" : @"male"
                      };
[[ref child:@"Jobs"] setValue:jobs withCompletionBlock:^(NSError * _Nullable error, WDGSyncReference * _Nonnull ref) {
    if (error == nil) {
        // 数据同步到野狗云端成功完成
    }
}];

let jobs = ["full_name" : "Steve Jobs",
            "gender" : "male"]
ref.child("Jobs").setValue(jobs, withCompletionBlock: { error, ref in
    if error == nil {
        // 数据同步到野狗云端成功完成
    }
})

设置节点优先级

setPriority: 方法用于设置节点的优先级。

Wilddog Sync 支持为每个节点设置优先级(priority)，用于实现节点按优先级排序。优先级是节点的隐藏属性，默认为 null。

例如，设置 user 节点的优先级为100：

Objective-C
Swift

WDGSyncReference *ref = [[WDGSync sync] referenceWithPath:@"user"];
[ref setPriority:@(100) withCompletionBlock:^(NSError * _Nullable error, WDGSyncReference * _Nonnull ref) {
    if (error) {
        NSLog(@"set priority failed'");
        return;
    }
    NSLog(@"set priority success.");
 }];

let ref = WDGSync.sync().reference(withPath: "user")
ref.setPriority(100) { (error, ref) in
            if error == nil {
                // set priority success.
            }
        }

更多使用，请参考 setPriority()。

写入数据并设置节点优先级

setValue:andPriority: 方法用于指定节点写入数据并且设置该节点优先级。

例如，写入 jack 的姓名并且设置优先级为100：

Objective-C
Swift

WDGSyncReference *ref = [[WDGSync sync] referenceWithPath:@"full_name"];
[ref setValue:@"jack"
  andPriority:@100
withCompletionBlock:^(NSError * _Nullable error, WDGSyncReference * _Nonnull ref) {
     if (!error) {
         // set data success.
     }
}];

let ref = WDGSync.sync().reference(withPath: "full_name")
ref.setValue("jack", andPriority: 100) { (error, ref) in
    if error == nil {
         // set data success.
    }
}

更多使用，请参考 setValue:andPriority:。

追加子节点

childByAutoId 方法向指定节点添加子节点。新增子节点的 key 由 Wilddog Sync 自动生成并保证唯一。新增子节点的 key 基于时间戳和随机算法生成，并可以按照添加时间进行排序。

例如，追加子节点到 messages 节点：

Objective-C
Swift

WDGSyncReference *messageRef = [ref child: @"messages"];
NSDictionary *message1 = @{
    @"full_name": @"Steve Jobs",
    @"message": @"Think difference"
};
[[messageRef childByAutoId] setValue:message1];

NSDictionary *message2 = @{
    @"full_name": @"Bill Gates",
    @"message": @"Hello World"
};
[[messageRef childByAutoId] setValue:message2];

let messageRef = ref.child("messages")
messageRef.childByAutoId().setValue(["full_name" : "Steve Jobs","message" : "Think difference"])
messageRef.childByAutoId().setValue(["full_name" : "Bill Gates","message" : "Hello World"])

产生的数据如下：

{
  "messages": {
    "-JRHTHaIs-jNPLXOQivY": {
      "full_name": "Steve Jobs",
      "message": "Think difference"
     },
    "-JRHTHaKuITFIhnj02kE": {
      "full_name": "Bill Gates",
      "message": "Hello World"
    }
  }
}

更新数据

updateChildValues 方法用于更新指定子节点。

updateChildValues 方法支持多路径更新。可以只调用一次方法更新多个路径的数据。

例如，更新 Jobs 的个人信息：

//原数据如下
{
    "Jobs": {
        "full_name": "Steve Jobs",
        "gender": "male"
    }
}

Objective-C
Swift

WDGSyncReference *jobsRef = [usersRef child: @"Jobs"];
 
NSDictionary *fullname = @{
    @"full_name": @"Tim Cook",
};
//只更新 jobs 的 full_name
[jobsRef updateChildValues:fullname];


let jobsRef = usersRef.child("jobs")
let fullname = ["full_name": "Tim Cook"]
//只更新 jobs 的 full_name
jobsRef.updateChildValues(fullname)

例如，同时更新 b 节点下的 d 和 x 节点下的 z：

//原数据如下
{
    "a": {
        "b": {
            "c": "cc",
            "d": "dd"
        },
        "x": {
            "y": "yy",
            "z": "zz"
        }
    }
}

正确示例：

Objective-C
Swift

[newPostRef updateChildValues:@{@"b/d":@"updateD",@"x/z":@"updateZ"}];


newPostRef.updateChildValues(["b/d":"updateD","x/z":"updateZ"])

错误示例：

Objective-C
Swift

// 错误的多路径更新写法！！
[newPostRef updateChildValues:@{@"b":@{@"d":@"updateD"},@"x":@{@"z":@"updateZ"}}];

// 错误的多路径更新写法！！
newPostRef.updateChildValues(["b":["d":"updateD"],"x":["z":"updateZ"]])

删除数据

removeValue方法用于删除指定节点。

Objective-C
Swift

WDGSyncReference *ref = [[WDGSync sync] reference];
[ref setValue:@{@"name" : @"Jone", @"age" : @"23"}];

//删除上面写入的数据
[ref removeValue];

let ref = WDGSync.sync().reference()
[ref.setValue(["name" : "Jone", "age" : "23"])

//删除上面写入的数据
messagesRef.removeValue()

提示：

设置节点的 value 为 nil 等同于 removeValue 方法。

事务处理

runTransactionBlock 方法用于并发操作时保证数据一致性。

例如，在实现多人点赞功能时，多人同时写入评分会产生覆盖，导致最终结果不准确。使用 runTransactionBlock 方法可以避免这种情况：

Objective-C
Swift

// 初始化 
WDGOptions *option = [[WDGOptions alloc] initWithSyncURL:@"https://docs-examples.wilddogio.com"];
[WDGApp configureWithOptions:option];  

// 获取一个 WDGSyncReference 实例
WDGSyncReference *upvotesRef =[[WDGSync sync] referenceWithPath:@"/web/saving-data/wildblog/posts/-JRHTHaIs-jNPLXOQivY/upvotes"];
    
[upvotesRef runTransactionBlock:^WDGTransactionResult *(WDGMutableData *currentData) {
    NSNumber *value = currentData.value;
    if (currentData.value == [NSNull null]) {
        value = 0;
    }
    [currentData setValue:[NSNumber numberWithInt:(1 + [value intValue])]];
    return [WDGTransactionResult successWithValue:currentData];
}];

// 初始化 
let options = WDGOptions.init(syncURL: "https://docs-examples.wilddogio.com")
WDGApp.configure(with: options)

// 获取一个 WDGSyncReference 实例
let upvotesRef = WDGSync.sync().reference(withPath: "/web/saving-data/wildblog/posts/-JRHTHaIs-jNPLXOQivY/upvotes")
        
upvotesRef.runTransactionBlock({
     (currentData:WDGMutableData!) in
     var value = currentData.value as? Int
     if (value == nil) {
         value = 0
     }
     currentData.value = value! + 1
     return WDGTransactionResult.success(withValue: currentData)
})

注意：

回调方法的返回值可能为空，需要进行相应的处理。

更多使用，请参考 - runTransactionBlock:。

上次更新：2018-06-21