初始化 Amazon Cognito Sync 客户端了解数据集在数据集中读取并写入数据使用同步存储同步本地数据

同步数据

如果您是 Amazon Cognito Sync 的新用户，请使用 AWS AppSync。像 Amazon Cognito Sync 一样，AWS AppSync 是一种在设备之间同步应用程序数据的服务。

它允许同步用户数据，如应用程序首选项或游戏状态。它还通过允许多个用户实时同步和协作处理共享的数据，来扩展这些功能。

借助 Amazon Cognito，您可将用户数据保存在包含键/值对的数据集中。Amazon Cognito 将此数据与您身份池中的身份相关联，这样您的应用程序就可以跨登录和设备访问它。要在 Amazon Cognito 服务和终端用户设备之间同步此数据，请调用 synchronize 方法。每个数据集的最大大小为 1MB。您最多可以将 20 个数据集与一个身份关联。

Amazon Cognito Sync 客户端会为身份数据创建一个本地缓存。您的应用程序在读取和写入键时，它与此本地缓存通信。此通信保证您在设备上所做的所有更改都能在设备上立即可用，即使您处于离线状态也是如此。调用 synchronize 方法后，服务的更改将拉取到设备上，并且所有本地更改都会推送到该服务。此时，这些更改可供其他设备同步。

初始化 Amazon Cognito Sync 客户端

要初始化 Amazon Cognito Sync 客户端，您必须先创建凭证提供程序。凭证提供程序获取临时 AWS 凭证，以使应用程序能够访问 AWS 资源。您还必须导入必要的标头文件。使用以下步骤初始化 Amazon Cognito Sync 客户端。

Android

按照获取凭证中的说明创建凭证提供程序。
如下所示导入 Amazon Cognito 程序包：import com.amazonaws.mobileconnectors.cognito.*;
初始化 Amazon Cognito Sync。传入 Android 应用程序上下文、身份池 ID、AWS 区域和初始化的 Amazon Cognito 凭证提供程序，如下所示：
```
CognitoSyncManager client = new CognitoSyncManager(
    getApplicationContext(),
    Regions.YOUR_REGION,
    credentialsProvider);
```

iOS - Objective-C

按照获取凭证中的说明创建凭证提供程序。

导入 AWSCore 和 Cognito，并初始化 AWSCognito如下所示：


#import <AWSiOSSDKv2/AWSCore.h>
#import <AWSCognitoSync/Cognito.h>

AWSCognito *syncClient = [AWSCognito defaultCognito];

如果您正在使用 CocoaPods，请将 <AWSiOSSDKv2/AWSCore.h> 替换为 AWSCore.h。请遵循与 Amazon Cognito 导入相同的语法。

iOS - Swift

按照获取凭证中的说明创建凭证提供程序。

导入并初始化 AWSCognito，如下所示：


import AWSCognito
let syncClient = AWSCognito.default()!

JavaScript

下载 Amazon Cognito Sync Manager for JavaScript。
在您的项目中添加 Sync Manager 库。
按照获取凭证中的说明创建凭证提供程序。

如下所示初始化 Sync Manager：


var syncManager = new AWS.CognitoSyncManager();

Unity

按照获取凭证中的说明创建 CognitoAWSCredentials 的实例。

创建 CognitoSyncManager 的实例。传递 CognitoAwsCredentials 对象和 AmazonCognitoSyncConfig，并至少包括区域集，如下所示：


AmazonCognitoSyncConfig clientConfig = new AmazonCognitoSyncConfig { RegionEndpoint = REGION };
CognitoSyncManager syncManager = new CognitoSyncManager(credentials, clientConfig);

Xamarin

按照获取凭证中的说明创建 CognitoAWSCredentials 的实例。

创建 CognitoSyncManager 的实例。传递 CognitoAwsCredentials 对象和 AmazonCognitoSyncConfig，并至少包括区域集，如下所示：


AmazonCognitoSyncConfig clientConfig = new AmazonCognitoSyncConfig { RegionEndpoint = REGION };
CognitoSyncManager syncManager = new CognitoSyncManager(credentials, clientConfig);

了解数据集

Amazon Cognito 将用户配置文件数据组织到数据集中。每个数据集可以包含高达 1MB 的键值对形式的数据。数据集是您可以同步的最细粒度实体。在调用 synchronize 方法之前，在数据集上执行的读取和写入操作只会对本地存储产生影响。Amazon Cognito 使用唯一字符串标识数据集。您可以创建新数据集或打开现有数据集，如下所示。

Android


Dataset dataset = client.openOrCreateDataset("datasetname");

要删除数据集，首先要调用方法以将其从本地存储中删除，然后调用 synchronize 方法从 Amazon Cognito 中删除数据集，如下所示：


dataset.delete();
dataset.synchronize(syncCallback);

iOS - Objective-C


AWSCognitoDataset *dataset = [syncClient openOrCreateDataset:@"myDataSet"];

要删除数据集，首先要调用方法以将其从本地存储中删除，然后调用 synchronize 方法从 Amazon Cognito 中删除数据集，如下所示：


[dataset clear];
[dataset synchronize];

iOS - Swift


let dataset = syncClient.openOrCreateDataset("myDataSet")!

要删除数据集，首先要调用方法以将其从本地存储中删除，然后调用 synchronize 方法如下所示以从 Amazon Cognito 中删除数据集：


dataset.clear()
dataset.synchronize()

JavaScript


syncManager.openOrCreateDataset('myDatasetName', function(err, dataset) {
   // ...
});

Unity


string myValue = dataset.Get("myKey");
dataset.Put("myKey", "newValue");

要从数据集中删除键，请如下所示使用 Remove：


dataset.Remove("myKey");

Xamarin


Dataset dataset = syncManager.OpenOrCreateDataset("myDatasetName");

要删除数据集，首先要调用方法以将其从本地存储中删除，然后调用 synchronize 方法从 Amazon Cognito 中删除数据集，如下所示：


dataset.Delete();
dataset.SynchronizeAsync();

在数据集中读取并写入数据

Amazon Cognito 数据集的功能与字典一样，包含可以通过键访问的值。您可以读取、添加或修改数据集的键和值，就像数据集是字典一样，如下所示。

请注意，在您调用同步方法之前，写入数据集的值仅对本地缓存的数据副本有影响。

Android


String value = dataset.get("myKey");
dataset.put("myKey", "my value");

iOS - Objective-C


[dataset setString:@"my value" forKey:@"myKey"];
NSString *value = [dataset stringForKey:@"myKey"];

iOS - Swift


dataset.setString("my value", forKey:"myKey")
let value = dataset.stringForKey("myKey")

JavaScript


dataset.get('myKey', function(err, value) {
  console.log('myRecord: ' + value);
});

dataset.put('newKey', 'newValue', function(err, record) {
  console.log(record);
});

dataset.remove('oldKey', function(err, record) {
  console.log(success);
});

Unity


string myValue = dataset.Get("myKey");
dataset.Put("myKey", "newValue");

Xamarin


//obtain a value
string myValue = dataset.Get("myKey");

// Create a record in a dataset and synchronize with the server
dataset.OnSyncSuccess += SyncSuccessCallback;
dataset.Put("myKey", "myValue");
dataset.SynchronizeAsync();

void SyncSuccessCallback(object sender, SyncSuccessEventArgs e) {
  // Your handler code here
}

Android

要从数据集中删除键，请如下所示使用 remove 方法：


dataset.remove("myKey");

iOS - Objective-C

要从数据集中删除键，请如下所示使用 removeObjectForKey：


[dataset removeObjectForKey:@"myKey"];

iOS - Swift

要从数据集中删除键，请如下所示使用 removeObjectForKey：


dataset.removeObjectForKey("myKey")

Unity

要从数据集中删除键，请如下所示使用 Remove：


dataset.Remove("myKey");

Xamarin

您可以使用 Remove 从数据集中删除键：


dataset.Remove("myKey");

使用同步存储同步本地数据

Android

synchronize 方法将本地缓存的数据与存储在 Amazon Cognito Sync 存储空间中的数据进行比较。从 Amazon Cognito Sync 存储空间中拉取远程更改；如果出现任何冲突，则调用冲突解决方法；设备上的更新值将推送到该服务。要同步数据集，请调用其 synchronize 方法：


dataset.synchronize(syncCallback);

synchronize 方法收到 SyncCallback 接口的实现，如下所述。

synchronizeOnConnectivity() 方法尝试在连接可用时进行同步。如果连接立即可用，则 synchronizeOnConnectivity() 的行为类似于 synchronize()。否则，它会监控连接更改，并在连接可用时立即执行同步。如果多次调用 synchronizeOnConnectivity()，则只会保持最近一次同步请求，并只会触发最近一次回调。如果数据集或回调收集到垃圾，则此方法不会执行同步，且不会触发回调。

要了解有关数据集同步和不同回调的更多信息，请参阅处理回调。

iOS - Objective-C

synchronize 方法是异步的，它会返回 AWSTask 对象以处理响应：


[[dataset synchronize] continueWithBlock:^id(AWSTask *task) {
    if (task.isCancelled) {
        // Task cancelled.
    } else if (task.error) {
        // Error while executing task.
    } else {
        // Task succeeded. The data was saved in the sync store.
    }
    return nil;
}];

synchronizeOnConnectivity 方法尝试在设备具备连接时进行同步。首先，synchronizeOnConnectivity 将检查连接状态，如果设备处于在线状态，则立即调用 synchronize，并返回与此次尝试关联的 AWSTask 对象。

如果设备处于离线状态，synchronizeOnConnectivity 1) 计划在设备下次变为在线状态时进行同步；2) 返回一个无结果的 AWSTask。计划的同步仅在该数据集对象的生命周期内有效。如果在连接恢复之前退出应用程序，则数据不会进行同步。如果您希望在计划同步期间发生事件时收到通知，则必须添加在 AWSCognito 中找到的通知的观察者。

要了解有关数据集同步和不同回调的更多信息，请参阅处理回调。

iOS - Swift

synchronize 方法是异步的，它会返回 AWSTask 对象以处理响应：


dataset.synchronize().continueWith(block: { (task) -> AnyObject? in

            if task.isCancelled {
                // Task cancelled.
            } else if task.error != nil {
                // Error while executing task
            } else {
                // Task succeeded. The data was saved in the sync store.
            }
            return task
})

synchronizeOnConnectivity 方法尝试在设备具备连接时进行同步。首先，synchronizeOnConnectivity 将检查连接状态，如果设备处于在线状态，则立即调用 synchronize，并返回与此次尝试关联的 AWSTask 对象。

如果设备处于离线状态，synchronizeOnConnectivity 1) 计划在设备下次变为在线状态时进行同步；2) 返回一个无结果的 AWSTask 对象。计划的同步仅在该数据集对象的生命周期内有效。如果在连接恢复之前退出应用程序，则数据不会进行同步。如果您希望在计划同步期间发生事件时收到通知，则必须添加在 AWSCognito 中找到的通知的观察者。

要了解有关数据集同步和不同回调的更多信息，请参阅处理回调。

JavaScript


dataset.synchronize();

要了解有关数据集同步和不同回调的更多信息，请参阅处理回调。

Unity

synchronize 方法将本地缓存的数据与存储在 Amazon Cognito Sync 存储空间中的数据进行比较。从 Amazon Cognito Sync 存储空间中拉取远程更改；如果出现任何冲突，则调用冲突解决方法；设备上的更新值将推送到该服务。要同步数据集，请调用其 synchronize 方法：


dataset.Synchronize();

同步将以异步方式运行，最终会调用您可以在数据集中指定的几个回调之一。

要了解有关数据集同步和不同回调的更多信息，请参阅处理回调。

Xamarin


dataset.SynchronizeAsync();

要了解有关数据集同步和不同回调的更多信息，请参阅处理回调。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

Amazon Cognito Sync 入门

处理回调