初始化 Amazon Cognito Sync 用戶端了解資料集在資料集中讀取和寫入資料將本機資料與同步存放區同步化

同步資料

如果您第一次使用 Amazon Cognito Sync，請改用 AWS AppSync。像 Amazon Cognito Sync 一樣，AWS AppSync 是讓您在裝置間同步應用程式資料的服務。

可同步使用者資料，如應用程式偏好設定或遊戲狀態。也擴充這些功能，允許多個使用者在共用資料上即時同步及協作。

使用 Amazon Cognito 可讓您將包含鍵值組的使用者資料儲存在資料集中。Amazon Cognito 將此資料與身分集區中的身分建立關聯，因此應用程式可以跨登入和裝置進行存取。若要在 Amazon Cognito 服務與最終使用者的裝置之間同步此資料，請呼叫同步方法。每個資料集的大小上限為 1 MB。一個身分最多可以與 20 個資料集相關聯。

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

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

若要進一步了解資料集同步和不同的回呼，請參閱處理回呼。

JavaScript


dataset.synchronize();

若要進一步了解資料集同步和不同的回呼，請參閱處理回呼。

Unity

Synchronize 方法會比較本機快取資料與存放在 Amazon Cognito Sync 存放區中的資料。遠端變更會從 Amazon Cognito Sync 存放區提取出來；如果發生任何衝突，將會叫用衝突解決方案；而裝置上的更新值會推播至服務。若要同步資料集，請呼叫其 synchronize方法：


dataset.Synchronize();

同步會以非同步方式執行，且最後會呼叫您可以在資料集中指定的其中一個回呼。

若要進一步了解資料集同步和不同的回呼，請參閱處理回呼。

Xamarin


dataset.SynchronizeAsync();

若要進一步了解資料集同步和不同的回呼，請參閱處理回呼。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

Amazon Cognito Sync 入門

處理回呼