Atlas App Services への接続 - Kotlin SDK

デフォルトのアプリクライアント

デフォルトの構成値でアプリを初期化するには、次のように App Services App のアプリケーションID をApp.create()メソッドに渡します。

// Creates an App with default configuration values
val app = App.create(YOUR_APP_ID) // Replace with your App ID

構成済みアプリクライアント

AppConfigurationインターフェースを使用すると、カスタム リクエスト ヘッダーやローカル暗号化のキーなど、アプリ接続の詳細をより細かく制御するためのオプションの引数を使用して App クライアントを構成できます。

構成オプションを制御するには、 AppConfiguration.Builderを使用し、 .build()メソッドを呼び出して構成オブジェクトを渡します。

// Creates an App with custom configuration values
AppConfiguration.Builder(YOUR_APP_ID)
    // Specify your custom configuration values
    .appName("my-app-name")
    .appVersion("1.0.0")
    .baseUrl("http://localhost:9090")
    .build()

同期接続の共有

デフォルトでは、SDK は同期された Realm ごとにサーバーへの個別の接続を開きます。 Kotlin v 1.13.0以降では、セッションの複数形 を有効にできます。 有効にすると、SDK は、単一の App Services ユーザーによって開かれたすべての同期された Realm のサーバーへの接続を共有します。 複数のセッションで接続を共有すると、リソースが削減され、パフォーマンスが向上する可能性があります。

重複はデフォルトで無効になっています。 .enableSession Multipressing() メソッドを使用してAppConfigurationで有効にすることができます ブール値を受け入れるメソッドです。

val config = AppConfiguration.Builder(YOUR_APP_ID)
    .enableSessionMultiplexing(true)
    .build()

有効にすると、すべてのセッションが閉じられたときに共有接続はすぐに閉じられません。 代わりに、 connectionLingerTimeが開いたままになり、デフォルトでは30秒になります。 この期間は、 AppConfigurationのSyncTimeoutOptions. connectionLingerTime()に新しい値を渡すことで上書きできます。

val configCustomLingerTime = AppConfiguration.Builder(YOUR_APP_ID)
    .enableSessionMultiplexing(true)
    .syncTimeouts {
        connectionLingerTime = 10.seconds // Overrides default 30 secs
    }
    .build()

詳細については、このページの「同期タイムアウトの設定」セクションを参照してください。

同期タイムアウトの設定

Kotlin v 1.13.0以降では、Atlas バックエンドとクライアント アプリ間でデータを同期するときに使用されるデフォルトのタイムアウト設定を上書きできます。

.syncTimeouts() メソッドを使用して、 AppConfigurationでさまざまな同期タイムアウト設定を設定できます 使用して複数のドキュメントを挿入できます。 オーバーライドする特定のタイムアウト プロパティ値を渡します。 構成されたタイムアウトは、アプリ内のすべての同期セッションに適用されます。

val config = AppConfiguration.Builder(YOUR_APP_ID)
    .syncTimeouts {
        connectTimeout = 1.minutes
        connectionLingerTime = 15.seconds
        pingKeepalivePeriod = 30.seconds
        pongKeepalivePeriod = 1.minutes
        fastReconnectLimit = 30.seconds
    }
    .build()

使用可能なタイムアウト プロパティとその定義の完全なリストについては、 SyncTimeoutOptionsBuilder API リファレンス を参照してください。

アプリ メタデータの暗号化

Atlas App Services に接続すると、Realm はデバイス上に追加のメタデータ ファイルを作成します。 これらのメタデータ ファイルの詳細については、「 Atlas Device SDK for Kotlin 」を参照してください。

同期された Realm を暗号化する方法と同様に、App Services がクライアントデバイスに保存するメタデータを暗号化できます。

アプリのメタデータを暗号化するには、アプリを初期化するときに暗号化キーをencryptionKeyプロパティに渡します。

val config =
    AppConfiguration.Builder(YOUR_APP_ID)
        // Specify the encryption key
        .encryptionKey(myEncryptionKey)
        .build()

カスタムHTTP headers設定

App Services またはDevice Syncをプロキシ設定で使用する場合は、カスタムHTTP headersを設定する必要がある場合があります。 Kotlin SDKは、アプリでのカスタムHTTP headersの設定をサポートしています。 これらのヘッダーは、関数呼び出しを含む App Services App へのすべてのリクエストに追加されます。

アプリを初期化するときに、以下を渡すことができます。

• カスタムauthorization HeaderName String値

• Stringヘッダーのキーと値のマップ内のカスタムリクエストヘッダー（SDK は空の値を受け入れますが、空のキーは受け入れません）

AppConfiguration.Builder(YOUR_APP_ID)
    .authorizationHeaderName("MyApp-Authorization")
    .customRequestHeaders { put("X-MyApp-Version", "1.0.0") }
    .build()

プラットフォーム ネットワーキングを有効にする

Atlas Device SDK のプラットフォーム ネットワークでは、Device Sync トラフィックのデフォルトの WebSocket クライアントの代わりに、プラットフォームのネットワーク スタックを使用できます。

有効にすると、Android および Java Virtual Machine（JVM）プラットフォームで実行されているアプリケーションを、OkHtp 経由で管理対象の WebSocks が使用するように構成できます 。マネージド WebSockts は、認証を必要とするプロキシやファイアウォールの高度な構成のサポートを提供します。

プラットフォーム ネットワークはデフォルトで無効になっています。 AppConfiguration.usePlatformNetwork（）を使用して、 AppConfigurationで有効にすることができます ブール値を受け入れるメソッドです。

val config =
    AppConfiguration.Builder(YOUR_APP_ID)
        .usePlatformNetworking(true)
        .build()

実行中に別のサーバーへの接続

場合によっては、アプリの実行中にbaseUrlを変更する必要があるかもしれません。 たとえば、Edge Server 間でローテーションしたり、App Services 接続から Edge Server 接続に移行したりする場合があります。

実行時にbaseUrlを変更するには、実験的なapp.updateBaseUrlメソッドを呼び出します。 nullを渡すと、 baseUrlをデフォルト値にリセットできます。

// Specify a custom baseUrl to connect to.
// In this case, an Edge Server instance running on the device:
val config = AppConfiguration.Builder(EDGE_SERVER_APP_ID)
    .baseUrl("http://localhost:80")
    .build()
val app = App.create(config)
// ... log in a user and use the app ...
// Later, change the baseUrl.
// In this case, pass `null` to reset to default:
// https://services.cloud.mongodb.com
app.updateBaseUrl(null)

この API は実験的なものであり、 @ExperialEdgeServerApiアノテーションが必要です。

// Opt in to the experimental Edge Server API
@OptIn(ExperimentalEdgeServerApi::class)

ユーザーにログインして同期されたデータベースを開いた後にbaseUrlを変更する場合、アプリはクライアント リセットを実行する必要があります。 詳細については、 「 クライアント リセット エラーの処理 」を参照してください。

コードで次の操作を実行します。

1. 同期セッションを一時停止する

2. app.updateBaseUrlメソッドを使用してbaseUrlを更新する

3. 新しいものを使用してログインするよう、ユーザーを再認証する baseUrl

4. 同期されたデータベースを開き、新しいサーバーからデータをプルします

ユーザーが認証を行い、新しいサーバーに接続するには、サーバーとクライアントの両方がオンラインである必要があります。 サーバーがオンラインでない場合、またはクライアントにネットワーク接続がない場合、ユーザーは認証を行いデータベースを開くことができません。