Kotlinコルーチンサポート

AmplifyはKotlinのコルーチンとフローの使用に完全に焦点を当てたオプションの独立したAPIサーフェスを提供しています。

これを使用するには、coreではなくcore-kotlinから**Amplify**ファサードをインポートします。詳細はインストール手順を参照してください。

Coroutines APIでは、ほとんどのAmplify関数はsuspend関数として表現されます。サスペンド関数は、Android Architectureコンポーネントのライフサイクル対応コルーチンスコープを使用して起動できます。

import com.amplifyframework.kotlin.core.Amplify
val post = Post.builder()
    .title("My First Post")
    .build()
lifecycleScope.launch {
        Amplify.DataStore.save(post) // This is suspending function!
        Log.i("AmplifyKotlinDemo", "Saved a post")
    } catch (failure: DataStoreException) {
        Log.e("AmplifyKotlinDemo", "Save failed", failure)

コルーチンは依存する非同期呼び出しの可読性を大幅に向上させることができます。さらに、スコープ、ディスパッチャー、およびその他のKotlinコルーチンプリミティブを使用して、実行コンテキストをより詳細に制御できます。

3つの依存操作がある場合を考えてみましょう。Postを保存してからEditorを保存し、最後にPostEditorを保存したいとします。Amplifyのコルーチンインターフェースを使用すれば、これらの操作を順序付けて記述できます。

lifecycleScope.launch {
        listOf(post, editor, postEditor)
            .forEach { Amplify.DataStore.save(it) }
        Log.i("AmplifyKotlinDemo", "Post, Editor, and PostEditor saved")
    } catch (failure: DataStoreException) {
        Log.e("AmplifyKotlinDemo", "An item failed to save", failure)

Amplifyのバニラ版APIでは、これによって3つのネストされたコールバックを持つ大きなコードブロックが作成されます。

インストール

Amplifyのコルーチンサポートはオプションのモジュールcore-kotlinに含まれています。

Gradle Scriptsの下で**build.gradle.kts (Module :app)**を開き、dependenciesに次の行を追加します。
app/build.gradle.kts
```
dependencies {
    // Add the below line in `dependencies`
    implementation("com.amplifyframework:core-kotlin:ANDROID_VERSION")
}
```
**Amplify**ファサードを使用する場所では、com.amplifyframework.core.Amplifyではなくcom.amplifyframework.kotlin.core.Amplifyをインポートします。
```
import com.amplifyframework.kotlin.core.Amplify
```

使用方法

Amplifyは、コールバックベースのAPIの動作をKotlinプリミティブに直感的な方法でマッピングしようとします。単一の値（またはエラー）を発行するコールバックを持つ関数は現在、サスペンド関数として表現され、値を代わりに返します。値のストリームを発行するコールバックを持つ関数は、代わりにKotlinFlowを返すようになります。

特殊なケース

一部のAPIはキャンセルできる操作を返します。例には、APIへのリアルタイムサブスクリプションやストレージからのオブジェクトのアップロード/ダウンロードが含まれます。

APIサブスクリプション

APIカテゴリのsubscribe()関数は、サスペンド関数と Flowの両方を使用します。この関数はAPIサブスクリプションが確立されるまでサスペンドします。その後、フロー上で値を発行し始めます。

lifecycleScope.async {
        Amplify.API.subscribe(request) // Suspends until subscription established
            .catch { Log.e("AmplifyKotlinDemo", "Error on subscription", it) }
            .collect { Log.i("AmplifyKotlinDemo", "Data on subscription = $it") }
    } catch (error: ApiException) {
        Log.e("AmplifyKotlinDemo", "Failed to establish subscription", error)

ストレージのアップロードおよびダウンロード操作

ストレージカテゴリのdownloadFile()およびuploadFile()関数はやや複雑です。これらのAPIを使用すると、転送進捗を観察し、結果も取得できます。進捗結果はprogress()関数から返されたフロー上で配信されます。完了イベントはサスペンドresult()関数によって配信されます。

// Download
val download = Amplify.Storage.downloadFile(StoragePath.fromString("public/example.txt"), localFile)
lifecycleScope.async {
    download
        .progress()
        .collect { Log.i("AmplifyKotlinDemo", "Download progress = $it") }
lifecycleScope.async {
        val result = download.result()
        Log.i("AmplifyKotlinDemo", "Download finished! ${result.file.path}")
    } catch (failure: StorageException) {
        Log.e("AmplifyKotlinDemo", "Download failed", failure)
val upload = Amplify.Storage.uploadFile(StoragePath.fromString("public/example.txt"), localFile)
lifecycleScope.async {
        .progress()
        .collect { Log.i("AmplifyKotlinDemo", "Upload progress = $it") }
lifecycleScope.async {
        val result = upload.result()
        Log.i("AmplifyKotlinDemo", "Upload finished! ${result.path}")
    } catch (failure: StorageException) {
        Log.e("AmplifyKotlinDemo", "Upload failed", failure)