Atlas App Services への接続 - Kotlin SDK
項目一覧
このページでは、App クライアントを初期化し、 Kotlin SDK を使用して Atlas App Services バックエンドに接続する方法について説明します。
App クライアントは、App Services バックエンドへのクライアント側のインターフェースです。 これにより、App Services App とやり取りし、次のような App Services 機能にアクセスできます。
各アプリ クライアントは、単一のアプリ ID に関連付けられます。 App Services UI でアプリ ID を見つける方法については、App Services ドキュメントの「 アプリ ID の検索 」を参照してください。
前提条件
Atlas App Services に接続する前に、アプリ ID を持つ App Services App が必要です。
開始するには、App Services ドキュメントの「 アプリの作成」を参照してください。
アプリ クライアントを初期化
Kotlin SDK は、アプリインターフェースを使用して App
クライアントにアクセスします。
各App
クライアントは、単一のアプリ ID に関連付けられています。 複数のアプリに接続する複数の App クライアント インスタンスを持つことができますが、同じアプリ ID を共有するすべての App クライアント インスタンスは同じ基礎の接続を使用します。
次のいずれかの方法を呼び出すことで、アプリ クライアントを初期化できます。
.create()
: デフォルト構成値でアプリを初期化します.build()
: は、AppConfiguration
オブジェクトを介して渡されるカスタム構成値でアプリを初期化します
アプリを初期化すると、 App
インスタンスを使用して App Services 機能にアクセスできるようになります。
デフォルトのアプリクライアント
デフォルトの構成値でアプリを初期化するには、次のように 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()
構成キャッシュ
バージョン1.14.0での変更: baseUrl
はAppConfiguration
にキャッシュされていません
App クライアントを初期化すると、構成は内部的にキャッシュされます。
同じプロセス内で変更された構成でアプリを閉じてから再度開かしようとしても効果はありません。 クライアントはキャッシュされた構成を引き続き使用します。
Kotlin SDK バージョン1.14.0以降、 baseUrl()はAppConfiguration
でキャッシュされなくなりました。 つまり、 baseUrl
を変更でき、アプリクライアントは更新された構成を使用します。 以前の SDK バージョンでは、キャッシュされたアプリ構成でbaseUrl
を変更しても効果はありません。
アプリ クライアントの構成
次のセクションでは、特定のプロパティを使用してAppConfiguration
クライアントを構築する方法について説明します。
同期接続の共有
注意
Atlas Device Sync に適用されます
この構成オプションは Atlas Device Sync を使用するアプリにのみ適用されます。 Kotlin SDK で Device Sync を使用する方法の詳細については、「 アプリへの Device Sync の追加 - Kotlin SDK 」を参照してください。
バージョン 1.13.0 の新機能。
デフォルトでは、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()
詳細については、このページの「同期タイムアウトの設定」セクションを参照してください。
同期タイムアウトの設定
注意
Atlas Device Sync に適用されます
この構成オプションは Atlas Device Sync を使用するアプリにのみ適用されます。 Kotlin SDK で Device Sync を使用する方法の詳細については、「 アプリへの Device Sync の追加 - Kotlin SDK 」を参照してください。
バージョン 1.13.0 の新機能。
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設定
バージョン 1.11.0 の新機能。
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()
プラットフォーム ネットワーキングを有効にする
バージョン1.14.0の新機能。
Atlas Device SDK のプラットフォーム ネットワークでは、Device Sync トラフィックのデフォルトの WebSocket クライアントの代わりに、プラットフォームのネットワーク スタックを使用できます。
有効にすると、Android およびJava仮想マシン(JVM )プラットフォームで実行中されているアプリケーションを、OkHtp 経由で管理対象の WebSocks が使用するように構成できます。 。マネージド WebSockts は、認証を必要とするプロキシとファイアウォールの高度な構成サポートを提供します。
プラットフォーム ネットワークはデフォルトで無効になっています。 AppConfiguration.usePlatformNetwork()を使用して、 AppConfiguration
で有効にすることができます ブール値を受け入れるメソッドです。
val config = AppConfiguration.Builder(YOUR_APP_ID) .usePlatformNetworking(true) .build()
注意
Android と JVM プラットフォームのみ
この機能は現在、Android および Java Virtual Machine(JVM)プラットフォームでのみ使用できます。
特定のサーバーへの接続
デフォルトでは、Atlas Device SDK はhttps://services.cloud.mongodb.com
のグローバルbaseUrl
を使用して Atlas に接続します。 場合によっては、別のサーバーに接続する必要があるかもしれません。
App Services Appはローカル配置を使用しており、リージョン内のローカル
baseUrl
に直接接続する場合があります。
詳しくは、「 App Services をローカル配置した場合 」のドキュメントを参照してください。
AppConfigurationでbaseUrl
を指定できます。
// Specify a baseUrl to connect to instead of the default val config = AppConfiguration.Builder(YOUR_APP_ID) .baseUrl("https://example.com") .build()
実行中に別のサーバーへの接続
バージョン1.16.0の新機能。
場合によっては、アプリが の実行中中にbaseUrl
を変更する必要があるかもしれません。
実行時に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)
ユーザーにログインして同期されたデータベースを開いた後にbaseUrl
を変更する場合、アプリはクライアント リセットを実行する必要があります。 詳細については、 「 クライアント リセット エラーの処理 」を参照してください。
コードで次の操作を実行します。
app.updateBaseUrl
メソッドを使用してbaseUrl
を更新する新しいものを使用してログインするよう、ユーザーを再認証する
baseUrl
同期されたデータベースを開き、新しいサーバーからデータをプルします
ユーザーが認証を行い、新しいサーバーに接続するには、サーバーとクライアントの両方がオンラインである必要があります。 サーバーがオンラインでない場合、またはクライアントにネットワーク接続がない場合、ユーザーは認証を行いデータベースを開くことができません。
アプリ クライアントを閉じる
App.close()メソッドを使用して、アプリ インスタンスを手動で閉じ、すべての基盤となるリソースをリリースできます。
app.close()
手動で閉じられていない場合、アプリ インスタンスがガベージされたときにリソースは解放されます。