Amazon Cognito
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

同步数据

注意

如果您是 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

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

  2. 导入 Amazon Cognito 程序包:import com.amazonaws.mobileconnectors.cognito.*;

  3. 初始化 Amazon Cognito Sync,传入 Android 应用程序上下文、身份池 ID、AWS 区域和已初始化的 Amazon Cognito 凭证提供程序:

    CognitoSyncManager client = new CognitoSyncManager( getApplicationContext(), Regions.YOUR_REGION, credentialsProvider);

iOS - Objective-C

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

  2. 导入 AWSCoreCognito,并初始化 AWSCognito

    #import <AWSiOSSDKv2/AWSCore.h> #import <AWSCognitoSync/Cognito.h> AWSCognito *syncClient = [AWSCognito defaultCognito];
  3. 如果您使用的是 CocoaPods,则将 <AWSiOSSDKv2/AWSCore.h> 替换为 AWSCore.h,然后遵循 Amazon Cognito 导入的同一语法。

iOS - Swift

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

  2. 导入并初始化 AWSCognito

    import AWSCognito let syncClient = AWSCognito.default()!

JavaScript

  1. 下载适用于 JavaScript 的 Amazon Cognito Sync Manager

  2. 在您的项目中添加 Sync Manager 库。

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

  4. 初始化 Sync Manager:

    var syncManager = new AWS.CognitoSyncManager();

Unity

  1. 您首先需要按照CognitoAWSCredentials中的说明创建 获取凭证 的实例。

  2. 创建 CognitoSyncManager 的实例,将 CognitoAwsCredentials 对象和 AmazonCognitoSyncConfig 至少传递到区域集:

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

Xamarin

  1. 您首先需要按照CognitoAWSCredentials中的说明创建 获取凭证 的实例。

  2. 创建 CognitoSyncManager 的实例,将 CognitoAwsCredentials 对象和 AmazonCognitoSyncConfig 至少传递到区域集:

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

了解数据集

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

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 数据集用作字典,值可以通过键进行访问。数据集的键和值可以读取、添加或修改,就像数据集是字典一样。下面显示了一个示例。

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

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

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

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

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

dataset.synchronize();

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

Unity

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

dataset.Synchronize();

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

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

Xamarin

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

dataset.SynchronizeAsync();

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