本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 跨用戶端同步資料
<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 服務與最終使用者的裝置之間同步此資料，請呼叫同步方法。每個資料集的大小上限為 1 MB。一個身分最多可以與 20 個資料集相關聯。

Amazon Cognito Sync 用戶端會為身分資料建立本機快取。當您的應用程式讀取和寫入索引鍵時，會與此本機快取進行通訊。此通訊可確保您在裝置上進行的所有變更都可立即用在裝置上，即使在您離線時也一樣。呼叫同步方法時，會將服務的變更提取到裝置，而任何本機變更都會推播到服務。此時，變更即可供其他裝置進行同步。

## 初始化 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，請以 `AWSCore.h` 取代 `<AWSiOSSDKv2/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 Sync Manager for JavaScript](https://github.com/aws/amazon-cognito-js)。

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. 建立 `CognitoAWSCredentials` 的執行個體，請遵循 [取得憑證](getting-credentials.md) 中的指示操作。

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. 建立 `CognitoAWSCredentials` 的執行個體，請遵循 [取得憑證](getting-credentials.md) 中的指示操作。

1. 建立 `CognitoSyncManager` 的執行個體。傳遞 `CognitoAwsCredentials` 物件和 `AmazonCognitoSyncConfig`，並且至少包括區域設定，如下所示：

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

## 了解資料集
<a name="understanding-datasets"></a>



Amazon Cognito 將使用者描述檔資料整理成資料集。每個資料集最多可包含 1 MB 鍵值組形式的資料。資料集是您可以同步的最精細實體。在叫用同步方法之前，對資料集執行的讀取和寫入操作只會影響本機存放區。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` 和 nil 結果。排定的同步只在資料集物件的生命週期內有效。如果在恢復連線之前，應用程式已結束，則不會同步資料。如果您希望在排定同步期間發生事件時收到通知，您必須新增 `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` 物件和 nil 結果。排定的同步只在資料集物件的生命週期內有效。如果在恢復連線之前，應用程式已結束，則不會同步資料。如果您希望在排定同步期間發生事件時收到通知，您必須新增 `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)。