连接到 Atlas App Services - Kotlin SDK
在此页面上
本页介绍如何初始化应用客户端并使用Kotlin SDK连接到Atlas App Services后端。
应用客户端是App Services后端的客户端接口。 它允许您与App Services App交互，并提供对App Services功能的访问权限，包括：
每个应用程序客户端都与一个 App ID相关联。 要学习；了解如何在App Services用户界面中查找 App ID ，请参阅App Services文档中的查找 App ID 。
先决条件
在连接到 Atlas App Services 之前，您需要一个带有 App ID 的 App Services App。
要开始使用，请参阅App Services文档中的创建应用。
初始化应用客户端
Kotlin SDK 使用App接口访问 App客户端。
每个App客户端都与一个 App ID相关联。 您可以有多个连接到多个应用的应用客户客户端实例，但股票同一 App ID的所有应用客户端实例都使用相同的根本的连接。
您可以通过调用以下方法之一来初始化应用客户端：
.create()：使用默认配置值初始化应用.build()：使用通过AppConfiguration对象传递的自定义配置值初始化应用
初始化应用后，您可以使用App实例访问权限App Services功能。
默认应用程序客户端
要使用默认配置值初始化应用，请将App Services App的 App ID传递给App.create()方法：
// Creates an App with default configuration values val app = App.create(YOUR_APP_ID) // Replace with your App ID
已配置的应用程序客户端
AppConfiguration接口允许您使用可选参数配置应用客户端，以便更精细地控制应用连接详细信息，例如自定义请求标头和用于本地加密的密钥。
要控制配置选项，请使用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 会为单个Atlas App Services用户打开的所有同步 Realm 共享与服务器的连接。 跨多个会话共享连接可减少资源占用并提高性能。
默认情况下，多路复用处于禁用状态。 您可以使用.enableSessionMultiplexing()在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后端和客户端应用之间同步数据时使用的默认超时设置。
您可以使用.syncTimeups()在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 参考。
加密应用元数据
当您连接到App Services时， Realm会在设备上创建额外的元数据文件。 有关这些元数据文件的更多信息，请参阅适用于Kotlin的Atlas Device SDK 。
您可以对Atlas App Services在客户端设备上存储的元数据进行加密，这与加密同步Realm的方式类似。
要加密应用元数据，请在初始化应用时将加密密钥传递给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的每个请求，包括函数调用。
初始化应用时，可以传递：
自定义授权标头名称
String值String标头键和值的映射中的任何customRequest header（SDK 接受空值，但不接受空键）
AppConfiguration.Builder(YOUR_APP_ID) .authorizationHeaderName("MyApp-Authorization") .customRequestHeaders { put("X-MyApp-Version", "1.0.0") } .build()
启用平台网络
1.14.0版本新增。
Atlas Device SDK 的平台网络允许您使用平台的网络堆栈而不是默认的 WebSocket客户端来处理Device Sync流量。
启用后，您可以将在 Android 和Java虚拟机 (Java虚拟机（JVM） ) 平台上运行的应用程序配置为使用基于 OkHttp 的托管WebSocket{ 。托管 WebSocket 为需要身份验证的代理和防火墙提供高级配置支持。
默认，平台网络功能处于禁用状态。 您可以使用AppConfiguration.usePlatformNetworking()在AppConfiguration上启用 方法，它接受一个布尔值。
val config = AppConfiguration.Builder(YOUR_APP_ID) .usePlatformNetworking(true) .build()
注意
仅限 Android 和 JVM 平台
此功能目前仅适用于 Android 和Java虚拟机 (Java虚拟机（JVM）) 平台。
连接到特定MongoDB Server
默认情况下，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()
在运行时连接到不同的MongoDB Server
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()
如果未手动关闭，则在对 App实例进行垃圾收集时会释放资源。