本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 同步不同客户端的数据
<a name="synchronizing-data"></a>

****  
如果您是 Amazon Cognito Sync 的新用户，请使用 [AWS AppSync](https://aws.amazon.com/appsync/)。与 Amazon Cognito Sync 一样， AWS AppSync 它是一项用于跨设备同步应用程序数据的服务。  
它允许同步用户数据，如应用程序首选项或游戏状态。它还通过允许多个用户实时同步和协作处理共享的数据，来扩展这些功能。

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

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

## 初始化 Amazon Cognito Sync 客户端
<a name="initializing-client"></a>

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

### Android
<a name="initialize-cog-sync-1.android"></a>

1. 按照[获取凭证](getting-credentials.md)中的说明创建凭证提供程序。

1. 如下所示导入 Amazon Cognito 程序包：`import com.amazonaws.mobileconnectors.cognito.*;`

1. 初始化 Amazon Cognito Sync。传入 Android 应用程序上下文、身份池 ID、 AWS 区域和初始化的 Amazon Cognito 凭证提供程序，如下所示：

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

### iOS - Objective-C
<a name="initialize-cog-sync-1.ios-objc"></a>

1. 按照[获取凭证](getting-credentials.md)中的说明创建凭证提供程序。

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

   ```
   #import <AWSiOSSDKv2/AWSCore.h>
   #import <AWSCognitoSync/Cognito.h>
   
   AWSCognito *syncClient = [AWSCognito defaultCognito];
   ```

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

### iOS - Swift
<a name="initialize-cog-sync-1.ios-swift"></a>

1. 按照[获取凭证](getting-credentials.md)中的说明创建凭证提供程序。

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

   ```
   import AWSCognito
   let syncClient = AWSCognito.default()!
   ```

### JavaScript
<a name="initialize-cog-sync-1.javascript"></a>

1. 下载适用于 [Amazon Cognito 的同步管理器](https://github.com/aws/amazon-cognito-js)。 JavaScript

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

1. 按照[获取凭证](getting-credentials.md)中的说明创建凭证提供程序。

1. 如下所示初始化 Sync Manager：

   ```
   var syncManager = new AWS.CognitoSyncManager();
   ```

### Unity
<a name="initialize-cog-sync-1.unity"></a>

1. 按照[获取凭证](getting-credentials.md)中的说明创建 `CognitoAWSCredentials` 的实例。

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

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

### Xamarin
<a name="initialize-cog-sync-1.xamarin"></a>

1. 按照 [获取凭证](getting-credentials.md) 中的说明创建 `CognitoAWSCredentials` 的实例。

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

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

## 了解数据集
<a name="understanding-datasets"></a>



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

### Android
<a name="understanding-datasets-1.android"></a>

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

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

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

### iOS - Objective-C
<a name="understanding-datasets-1.ios-objc"></a>

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

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

```
[dataset clear];
[dataset synchronize];
```

### iOS - Swift
<a name="understanding-datasets-1.ios-swift"></a>

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

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

```
dataset.clear()
dataset.synchronize()
```

### JavaScript
<a name="understanding-datasets-1.javascript"></a>

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

### Unity
<a name="understanding-datasets-1.unity"></a>

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

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

```
dataset.Remove("myKey");
```

### Xamarin
<a name="understanding-datasets-1.xamarin"></a>

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

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

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

## 在数据集中读取并写入数据
<a name="reading-and-writing-data"></a>

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

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

### Android
<a name="reading-and-writing-data-1.android"></a>

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

### iOS - Objective-C
<a name="reading-and-writing-data-1.ios-objc"></a>

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

### iOS - Swift
<a name="reading-and-writing-data-1.ios-swift"></a>

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

### JavaScript
<a name="reading-and-writing-data-1.javascript"></a>



```
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
<a name="reading-and-writing-data-1.unity"></a>

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

### Xamarin
<a name="reading-and-writing-data-1.xamarin"></a>



```
//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
<a name="reading-and-writing-data-2.android"></a>

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

```
dataset.remove("myKey");
```

### iOS - Objective-C
<a name="reading-and-writing-data-2.ios-objc"></a>

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

```
[dataset removeObjectForKey:@"myKey"];
```

### iOS - Swift
<a name="reading-and-writing-data-2.ios-swift"></a>

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

```
dataset.removeObjectForKey("myKey")
```

### Unity
<a name="reading-and-writing-data-2.unity"></a>

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

```
dataset.Remove("myKey");
```

### Xamarin
<a name="reading-and-writing-data-2.xamarin"></a>

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

```
dataset.Remove("myKey");
```

## 使用同步存储同步本地数据
<a name="synchronizing-local-data"></a>



### Android
<a name="synchronizing-local-data-1.android"></a>

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

```
dataset.synchronize(syncCallback);
```

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

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

要了解有关数据集同步和不同回调的更多信息，请参阅[处理事件回调](handling-callbacks.md)。

### iOS - Objective-C
<a name="synchronizing-local-data-1.ios-objc"></a>

`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` 中找到的通知的观察者。

要了解有关数据集同步和不同回调的更多信息，请参阅[处理事件回调](handling-callbacks.md)。

### iOS - Swift
<a name="synchronizing-local-data-1.ios-swift"></a>

`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` 中找到的通知的观察者。

要了解有关数据集同步和不同回调的更多信息，请参阅[处理事件回调](handling-callbacks.md)。

### JavaScript
<a name="synchronizing-local-data-1.javascript"></a>

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

```
dataset.synchronize();
```

要了解有关数据集同步和不同回调的更多信息，请参阅[处理事件回调](handling-callbacks.md)。

### Unity
<a name="synchronizing-local-data-1.unity"></a>

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

```
dataset.Synchronize();
```

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

要了解有关数据集同步和不同回调的更多信息，请参阅[处理事件回调](handling-callbacks.md)。

### Xamarin
<a name="synchronizing-local-data-1.xamarin"></a>

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

```
dataset.SynchronizeAsync();
```

要了解有关数据集同步和不同回调的更多信息，请参阅[处理事件回调](handling-callbacks.md)。